Telas e controles

Helpers para scripts com a própria página NUI ou modo de ferramenta: abrir uma página de tela cheia com foco e HUDs escondidos, listar as teclas de uma ferramenta no HUD e bloquear controles sem escrever um loop por frame.

NuiScreenCopy Anchor Link

new NuiScreenCopy Anchor Link

A página NUI de tela cheia do seu recurso em um objeto. open pega o foco, esconde todos os HUDs (por hud) e envia a mensagem de abertura; close devolve o foco, mostra os HUDs, envia { action: "close" } para a página e roda o seu onClose. O callback NUI close da própria página também a fecha. Crie uma por recurso, no topo do arquivo.

Lado: Cliente · Espera: não

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

Sem equivalente em Lua: recursos Lua chamam SetNuiFocus, aiLib.hud.hide / show e RegisterNUICallback('close', ...) eles mesmos.

ParâmetrosCopy Anchor Link

NuiScreenOptionsCopy Anchor Link

NuiPageMessageCopy Anchor Link

O que open e send recebem: { action: string; data?: unknown }. Passe o seu próprio tipo união como M para tipar todas as mensagens.

MembrosCopy Anchor Link

ExemploCopy 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 } });
}

// A página chama 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 e os outros scripts de HUD que o ai-core suporta) pelo ai-core. Uma UI de tela cheia os esconde ao abrir e os mostra ao fechar. Os motivos são contados por recurso, então duas telas abertas ao mesmo tempo mantêm os HUDs escondidos até as duas fecharem. Enquanto qualquer motivo vale, o ai-core esconde todos os HUDs e o minimapa.

hud.hideCopy Anchor Link

Esconde todos os HUDs por um motivo, até hud.show com o mesmo motivo.

Lado: Cliente · Espera: não

hud.hide(reason: string): void

aiLib.hud.hide(reason)

ParâmetrosCopy Anchor Link

RetornoCopy Anchor Link

void.

ExemploCopy 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

Remove um motivo de esconder. Os HUDs voltam quando não sobra motivo de nenhum recurso.

Lado: Cliente · Espera: não

hud.show(reason: string): void

aiLib.hud.show(reason)

ParâmetrosCopy Anchor Link

RetornoCopy Anchor Link

void. Veja o exemplo de hud.hide.

hud.visibleCopy Anchor Link

Se os HUDs aparecem agora (nenhuma UI de tela cheia aberta).

Lado: Cliente · Espera: não

hud.visible: boolean // propriedade somente leitura

local visible = aiLib.hud.visible() -- uma função em Lua

RetornoCopy Anchor Link

boolean: true quando nenhum motivo de esconder de nenhum recurso vale.

hud.onChangeCopy Anchor Link

Roda um handler sempre que os HUDs aparecem ou se escondem. Um script de HUD usa isto para se esconder.

Lado: Cliente · Espera: não

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

Sem equivalente em Lua: escute o evento local ai-core:client:hudVisible (visible).

ParâmetrosCopy Anchor Link

RetornoCopy Anchor Link

void.

ExemploCopy Anchor Link

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

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

keyHintsCopy Anchor Link

Linhas de ajuda de teclas que um script mostra por um tempo (as teclas do noclip de um admin, os controles de um minigame), listadas pelo HUD à esquerda ao lado das que os keybinds declaram com hint. As ajudas de um recurso parado somem sozinhas.

keyHints.showCopy Anchor Link

Mostra uma ajuda de tecla, ou altera a que tem o mesmo id.

Lado: Cliente · Espera: não

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

aiLib.keyHints.show(id, hint)

ParâmetrosCopy Anchor Link

KeyHintRequestCopy Anchor Link

O tipo é KeyHintRequest.

RetornoCopy Anchor Link

void.

ExemploCopy 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

Remove uma das suas ajudas de teclas. Um id desconhecido não faz nada.

Lado: Cliente · Espera: não

keyHints.hide(id: string): void

aiLib.keyHints.hide(id)

ParâmetrosCopy Anchor Link

RetornoCopy Anchor Link

void. Veja o exemplo de keyHints.show.

controlsCopy Anchor Link

Controles desativados do seu recurso, com um único job por frame para todos eles. Cada motivo (cuffed, menu, placing) adiciona os seus controles e os remove quando termina; o job só roda enquanto algum motivo está ativo. Nunca escreva o seu próprio setTick com DisableControlAction.

controls.disableCopy Anchor Link

Desativa uma lista de controles a cada frame até controls.enable(reason). Chamá-la de novo com o mesmo motivo substitui a lista desse motivo.

Lado: Cliente · Espera: não

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

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

ParâmetrosCopy Anchor Link

RetornoCopy Anchor Link

void.

ExemploCopy 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

Desativa todos os controles (grupos de entrada 0, 1 e 2) a cada frame até controls.enable(reason), exceto os que você mantém. Use para um noclip ou uma câmera livre, e leia as teclas desativadas com IsDisabledControlPressed.

Lado: Cliente · Espera: não

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

aiLib.controls.disableAll(reason, except)

ParâmetrosCopy Anchor Link

RetornoCopy Anchor Link

void.

ExemploCopy 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

Encerra um motivo: os controles dele voltam a funcionar, a menos que outro motivo ainda os desative. Um motivo desconhecido não faz nada.

Lado: Cliente · Espera: não

controls.enable(reason: string): void

aiLib.controls.enable(reason)

ParâmetrosCopy Anchor Link

RetornoCopy Anchor Link

void. Veja os exemplos acima.

controls.isDisabledCopy Anchor Link

Se um motivo do seu recurso está ativo agora.

Lado: Cliente · Espera: não

controls.isDisabled(reason: string): boolean

Sem equivalente em Lua.

ParâmetrosCopy Anchor Link

RetornoCopy Anchor Link

boolean: true enquanto esse motivo vale.

ExemploCopy Anchor Link

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

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