Pantallas y controles

Utilidades para scripts con su propia página NUI o modo de herramienta: abrir una página a pantalla completa con foco y HUD ocultos, mostrar las teclas de una herramienta en el HUD y bloquear controles sin escribir un bucle por frame.

NuiScreenCopy Anchor Link

new NuiScreenCopy Anchor Link

La página NUI a pantalla completa de tu recurso en un solo objeto. open toma el foco, oculta todos los HUD (mediante hud) y envía el mensaje de apertura; close devuelve el foco, muestra los HUD, envía { action: "close" } a la página y ejecuta tu onClose. El callback NUI close propio de la página también la cierra. Crea uno por recurso, al principio del archivo.

Lado: Cliente · Espera: no

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

Sin equivalente en Lua: los recursos Lua llaman ellos mismos a SetNuiFocus, aiLib.hud.hide / show y RegisterNUICallback('close', ...).

ParámetrosCopy Anchor Link

NuiScreenOptionsCopy Anchor Link

NuiPageMessageCopy Anchor Link

Lo que aceptan open y send: { action: string; data?: unknown }. Pasa tu propio tipo unión como M para tipar cada mensaje.

MiembrosCopy Anchor Link

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

// La página llama a 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

Los HUD (ai-hud y los demás scripts de HUD que admite ai-core) a través de ai-core. Una interfaz a pantalla completa los oculta al abrirse y los muestra al cerrarse. Los motivos se cuentan por recurso, así que dos pantallas abiertas a la vez mantienen los HUD ocultos hasta que ambas se cierran. Mientras haya algún motivo activo, ai-core oculta todos los HUD y el minimapa.

hud.hideCopy Anchor Link

Oculta todos los HUD por un motivo, hasta hud.show con el mismo motivo.

Lado: Cliente · Espera: no

hud.hide(reason: string): void

aiLib.hud.hide(reason)

ParámetrosCopy Anchor Link

DevuelveCopy Anchor Link

void.

EjemploCopy 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

Quita un motivo de ocultación. Los HUD vuelven cuando no queda ningún motivo de ningún recurso.

Lado: Cliente · Espera: no

hud.show(reason: string): void

aiLib.hud.show(reason)

ParámetrosCopy Anchor Link

DevuelveCopy Anchor Link

void. Consulta el ejemplo de hud.hide.

hud.visibleCopy Anchor Link

Si los HUD se muestran ahora (ninguna interfaz a pantalla completa abierta).

Lado: Cliente · Espera: no

hud.visible: boolean // propiedad de solo lectura

local visible = aiLib.hud.visible() -- una función en Lua

DevuelveCopy Anchor Link

boolean: true cuando no hay ningún motivo de ocultación activo de ningún recurso.

hud.onChangeCopy Anchor Link

Ejecuta un handler cada vez que los HUD se muestran o se ocultan. Un script de HUD lo usa para ocultarse.

Lado: Cliente · Espera: no

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

Sin equivalente en Lua: escucha el evento local ai-core:client:hudVisible (visible).

ParámetrosCopy Anchor Link

DevuelveCopy Anchor Link

void.

EjemploCopy Anchor Link

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

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

keyHintsCopy Anchor Link

Líneas de ayuda de teclas que un script muestra durante un rato (las teclas de un noclip de admin, los controles de un minijuego), listadas por el HUD a la izquierda junto a las que declaran los keybinds con hint. Las ayudas de un recurso detenido desaparecen solas.

keyHints.showCopy Anchor Link

Muestra una ayuda de tecla, o cambia la que tiene el mismo id.

Lado: Cliente · Espera: no

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

aiLib.keyHints.show(id, hint)

ParámetrosCopy Anchor Link

KeyHintRequestCopy Anchor Link

El tipo es KeyHintRequest.

DevuelveCopy Anchor Link

void.

EjemploCopy 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

Quita una de tus ayudas de teclas. Un id desconocido no hace nada.

Lado: Cliente · Espera: no

keyHints.hide(id: string): void

aiLib.keyHints.hide(id)

ParámetrosCopy Anchor Link

DevuelveCopy Anchor Link

void. Consulta el ejemplo de keyHints.show.

controlsCopy Anchor Link

Controles desactivados de tu recurso, con una sola tarea por frame para todos ellos. Cada motivo (cuffed, menu, placing) añade sus controles y los quita cuando termina; la tarea solo se ejecuta mientras algún motivo está activo. Nunca escribas tu propio setTick con DisableControlAction.

controls.disableCopy Anchor Link

Desactiva una lista de controles en cada frame hasta controls.enable(reason). Llamarlo otra vez con el mismo motivo reemplaza la lista de ese motivo.

Lado: Cliente · Espera: no

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

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

ParámetrosCopy Anchor Link

DevuelveCopy Anchor Link

void.

EjemploCopy 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

Desactiva todos los controles (grupos de entrada 0, 1 y 2) en cada frame hasta controls.enable(reason), salvo los que conserves. Úsalo para un noclip o una cámara libre, y lee las teclas desactivadas con IsDisabledControlPressed.

Lado: Cliente · Espera: no

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

aiLib.controls.disableAll(reason, except)

ParámetrosCopy Anchor Link

DevuelveCopy Anchor Link

void.

EjemploCopy 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

Termina un motivo: sus controles vuelven a funcionar salvo que otro motivo aún los desactive. Un motivo desconocido no hace nada.

Lado: Cliente · Espera: no

controls.enable(reason: string): void

aiLib.controls.enable(reason)

ParámetrosCopy Anchor Link

DevuelveCopy Anchor Link

void. Consulta los ejemplos de arriba.

controls.isDisabledCopy Anchor Link

Si un motivo de tu recurso está activo ahora.

Lado: Cliente · Espera: no

controls.isDisabled(reason: string): boolean

Sin equivalente en Lua.

ParámetrosCopy Anchor Link

DevuelveCopy Anchor Link

boolean: true mientras ese motivo está activo.

EjemploCopy Anchor Link

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

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