Screens and controls

Helpers for scripts with their own NUI page or tool mode: open a full-screen page with focus and hidden HUDs, list the keys of a tool on the HUD, and block controls without writing a per-frame loop.

NuiScreenCopy Anchor Link

new NuiScreenCopy Anchor Link

Your resource's full-screen NUI page in one object. open takes the focus, hides every HUD (through hud) and sends the open message; close gives the focus back, shows the HUDs, sends { action: "close" } to the page and runs your onClose. The page's own close NUI callback closes it too. Create one per resource, at the top of the file.

Side: Client · Waits: no

new NuiScreen<M extends NuiPageMessage = NuiPageMessage>(name: string, options?: NuiScreenOptions)

No Lua twin: Lua resources call SetNuiFocus, aiLib.hud.hide / show and RegisterNUICallback('close', ...) themselves.

ParametersCopy Anchor Link

NuiScreenOptionsCopy Anchor Link

NuiPageMessageCopy Anchor Link

What open and send take: { action: string; data?: unknown }. Pass your own union type as M to type every message.

MembersCopy Anchor Link

ExampleCopy Anchor Link

import { callAction, NuiScreen, ScriptCamera } from "@aicore-fivem/lib/client";
import { readText } from "@aicore-fivem/lib/shared";

type Message =
  | { action: "open"; data: { items: string[] } }
  | { action: "result"; data: boolean };

const camera = new ScriptCamera();
const screen = new NuiScreen<Message>("shop", {
  onClose: () => camera.stop(500),
});

export function openShop(items: string[]): void {
  camera.start({ x: 26.5, y: -1345.0, z: 30.2 }, { pointAt: { x: 25.7, y: -1347.3, z: 29.5 } }, 500);
  screen.open({ action: "open", data: { items } });
}

// The page calls fetch(`https://${GetParentResourceName()}/buy`, { body: JSON.stringify("water") }).
screen.on(
  "buy",
  (data) => readText(data, 32),
  async (item) => {
    const reply = await callAction("myshop:buy", [item], { fallback: "BUY_FAILED" });
    return { ok: reply !== null };
  },
);

hudCopy Anchor Link

HUDs (ai-hud and the other HUD scripts ai-core supports) through ai-core. A full-screen UI hides them on open and shows them on close. Reasons are counted per resource, so two screens open at once keep the HUDs hidden until both close. While any reason holds, ai-core hides every HUD and the minimap.

hud.hideCopy Anchor Link

Hides every HUD for a reason, until hud.show with the same reason.

Side: Client · Waits: no

hud.hide(reason: string): void

aiLib.hud.hide(reason)

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

void.

ExampleCopy Anchor Link

import { hud } from "@aicore-fivem/lib/client";

RegisterCommand(
  "cinema",
  () => {
    if (hud.visible) hud.hide("cinema");
    else hud.show("cinema");
  },
  false,
);

hud.showCopy Anchor Link

Removes one hide reason. The HUDs come back when no reason of any resource is left.

Side: Client · Waits: no

hud.show(reason: string): void

aiLib.hud.show(reason)

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

void. See the hud.hide example.

hud.visibleCopy Anchor Link

Whether HUDs show now (no full-screen UI open).

Side: Client · Waits: no

hud.visible: boolean // read-only property

local visible = aiLib.hud.visible() -- a function in Lua

ReturnsCopy Anchor Link

boolean: true when no hide reason of any resource holds.

hud.onChangeCopy Anchor Link

Runs a handler whenever HUDs show or hide. A HUD script uses it to hide itself.

Side: Client · Waits: no

hud.onChange(fn: (visible: boolean) => void): void

No Lua twin: listen to the local event ai-core:client:hudVisible (visible).

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

void.

ExampleCopy Anchor Link

import { hud } from "@aicore-fivem/lib/client";

hud.onChange((visible) => SendNUIMessage({ action: "visible", data: visible }));

keyHintsCopy Anchor Link

Key help lines a script shows for a while (an admin noclip's keys, a minigame's controls), listed by the HUD on the left next to the ones keybinds declare with hint. Hints of a stopped resource disappear by themselves.

keyHints.showCopy Anchor Link

Shows a key hint, or changes the one with the same id.

Side: Client · Waits: no

keyHints.show(id: string, hint: KeyHintRequest): void

aiLib.keyHints.show(id, hint)

ParametersCopy Anchor Link

KeyHintRequestCopy Anchor Link

The type is KeyHintRequest.

ReturnsCopy Anchor Link

void.

ExampleCopy Anchor Link

import { createLocale, keyHints } from "@aicore-fivem/lib/client";

const Locale = createLocale<typeof import("../../locales/en.json")>();

export function startPlacing(): void {
  keyHints.show("rotate", { label: Locale("ROTATE"), key: "Q / E", icon: "rotate" });
  keyHints.show("place", { label: Locale("PLACE"), keybind: "myscript_place", icon: "check" });
}

export function stopPlacing(): void {
  keyHints.hide("rotate");
  keyHints.hide("place");
}

keyHints.hideCopy Anchor Link

Removes one of your key hints. An unknown id does nothing.

Side: Client · Waits: no

keyHints.hide(id: string): void

aiLib.keyHints.hide(id)

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

void. See the keyHints.show example.

controlsCopy Anchor Link

Disabled controls of your resource, with one per-frame job for all of them. Each reason (cuffed, menu, placing) adds its controls and removes them when it ends; the job runs only while any reason is active. Never write your own setTick with DisableControlAction.

controls.disableCopy Anchor Link

Disables a list of controls every frame until controls.enable(reason). Calling it again with the same reason replaces that reason's list.

Side: Client · Waits: no

controls.disable(reason: string, controls: readonly number[], group?: number): void

aiLib.controls.disable(reason, controls, group)

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

void.

ExampleCopy Anchor Link

import { controls, onServerEvent } from "@aicore-fivem/lib/client";

const CUFFED = [21, 22, 23, 24, 25, 37, 44, 140, 141, 142, 143, 257, 263, 264];

onServerEvent(
  "mypolice:cuffed",
  { args: ([on]) => (typeof on === "boolean" ? [on] : null) },
  (on) => (on ? controls.disable("cuffed", CUFFED) : controls.enable("cuffed")),
);

controls.disableAllCopy Anchor Link

Disables every control (input groups 0, 1 and 2) every frame until controls.enable(reason), except the ones you keep. Use it for a noclip or a free camera, and read the disabled keys with IsDisabledControlPressed.

Side: Client · Waits: no

controls.disableAll(reason: string, except?: readonly number[]): void

aiLib.controls.disableAll(reason, except)

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

void.

ExampleCopy Anchor Link

import { controls, every } from "@aicore-fivem/lib/client";

const fly = every(0, () => {
  if (IsDisabledControlPressed(0, 32)) console.log("forward");
}, { active: false, name: "noclip" });

export function noclip(on: boolean): void {
  if (on) controls.disableAll("noclip", [1, 2, 249]);
  else controls.enable("noclip");
  fly.set(on);
}

controls.enableCopy Anchor Link

Ends one reason: its controls work again unless another reason still disables them. An unknown reason does nothing.

Side: Client · Waits: no

controls.enable(reason: string): void

aiLib.controls.enable(reason)

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

void. See the examples above.

controls.isDisabledCopy Anchor Link

Whether a reason of your resource is active now.

Side: Client · Waits: no

controls.isDisabled(reason: string): boolean

No Lua twin.

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

boolean: true while that reason holds.

ExampleCopy Anchor Link

import { controls } from "@aicore-fivem/lib/client";

if (controls.isDisabled("cuffed")) console.log("the player is cuffed");