Sondeos y carga

Preguntas al juego sobre el mundo (qué hay delante del jugador, a qué altura está el suelo, cómo se llama esta calle) y los cargadores que necesita cada modelo, animación y efecto antes de usarse.

SondeosCopy Anchor Link

raycastCopy Anchor Link

Un sondeo de línea respondido en el mismo frame: qué toca primero la línea de from a to. Úsalo para "qué está mirando el jugador", colocar objetos en el suelo o la línea de visión.

Lado: Cliente · Espera: no (bloquea el frame hasta que termina la prueba)

raycast(from: Vec3, to: Vec3, options?: RaycastOptions): RayHit | null

local hit = aiLib.raycast(from, to, options) -- table o nil; from / to son vector3

ParámetrosCopy Anchor Link

RaycastOptionsCopy Anchor Link

DevuelveCopy Anchor Link

RayHit | null: { coords, normal, entity } del primer impacto, o null (nil) cuando la línea no toca nada.

EjemploCopy Anchor Link

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

/** What the camera looks at within 10 m. */
export function lookedAt(): number {
  const [cx = 0, cy = 0, cz = 0] = GetGameplayCamCoord();
  const [rx = 0, , rz = 0] = GetGameplayCamRot(2);
  const pitch = (rx * Math.PI) / 180;
  const yaw = (rz * Math.PI) / 180;
  const dir = { x: -Math.sin(yaw) * Math.cos(pitch), y: Math.cos(yaw) * Math.cos(pitch), z: Math.sin(pitch) };
  const hit = raycast(
    { x: cx, y: cy, z: cz },
    { x: cx + dir.x * 10, y: cy + dir.y * 10, z: cz + dir.z * 10 },
    { flags: 2 | 4 | 16 },
  );
  return hit?.entity ?? 0;
}

groundZCopy Anchor Link

La altura del suelo bajo un punto, sondeando hacia abajo desde z.

Lado: Cliente · Espera: no

groundZ(x: number, y: number, z?: number): number | null

local ground = aiLib.groundZ(x, y, z) -- number o nil

ParámetrosCopy Anchor Link

DevuelveCopy Anchor Link

number | null: la altura del suelo, o null (nil) mientras la colisión de ahí no está cargada (el área está lejos del jugador).

EjemploCopy Anchor Link

import { groundZ, player } from "@aicore-fivem/lib/client";

const { x, y, z } = player.coords();
const ground = groundZ(x, y, z + 2);
if (ground !== null) console.log(`ground is ${(z - ground).toFixed(2)} m below`);

locationNameCopy Anchor Link

Los nombres de la calle, la calle que se cruza y el área en un punto. Úsalo en alertas de dispatch, mensajes de teléfono y HUD.

Lado: Cliente · Espera: no

locationName(coords?: Vec3): LocationName

local where = aiLib.locationName(coords) -- coords es un vector3, opcional

ParámetrosCopy Anchor Link

DevuelveCopy Anchor Link

LocationName:

EjemploCopy Anchor Link

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

const { street, crossing, zone } = locationName();
const text = crossing ? `${street} / ${crossing}, ${zone}` : `${street}, ${zone}`;

vehicleLabelCopy Anchor Link

El nombre visible de un vehículo (Sultan RS) a partir de un nombre de modelo, un hash de modelo o una entidad de vehículo.

Lado: Cliente · Espera: no

vehicleLabel(vehicle: string | number): string

local name = aiLib.vehicleLabel(vehicle)

ParámetrosCopy Anchor Link

DevuelveCopy Anchor Link

string: la etiqueta del juego para el modelo; el nombre visible del modelo cuando el juego no tiene texto para él (vehículos add-on sin entrada de texto); el nombre o el hash del modelo como texto cuando incluso eso falta.

EjemploCopy Anchor Link

import { cache, notify, onCache, vehicleLabel } from "@aicore-fivem/lib/client";

onCache("vehicle", (vehicle) => {
  if (vehicle !== false && cache.seat === -1) notify(vehicleLabel(vehicle), "info", 2000);
});

waypointCopy Anchor Link

El waypoint que el jugador marcó en el mapa.

Lado: Cliente · Espera: no

waypoint(): { x: number; y: number } | null

local target = aiLib.waypoint() -- { x, y } o nil

DevuelveCopy Anchor Link

{ x: number; y: number } | null: la posición del waypoint (sin altura: los waypoints del mapa no tienen), o null (nil) cuando no hay ningún waypoint marcado.

EjemploCopy Anchor Link

Consulta player.teleport: teletransportarse al waypoint.

pedHeadshotCopy Anchor Link

Saca una foto de la cara de un ped y espera hasta que el juego la renderizó. Usa el nombre de la textura en una página NUI como https://nui-img/<txd>/<txd>.

Lado: Cliente · Espera: sí (Promise en TypeScript, cede el hilo en Lua)

pedHeadshot(ped: number, transparent?: boolean, timeoutMs?: number): Promise<{ handle: number; txd: string } | null>

local handle, txd = aiLib.pedHeadshot(ped, transparent, timeout) -- llamar dentro de un hilo

ParámetrosCopy Anchor Link

DevuelveCopy Anchor Link

Promise<{ handle: number; txd: string } | null>: el handle de la foto y el nombre de su textura; null cuando el ped no existe o el renderizado tardó más que el tiempo límite. Lua devuelve handle, txd, o nil.

EjemploCopy Anchor Link

import { cache, pedHeadshot } from "@aicore-fivem/lib/client";

export async function sendMugshot(): Promise<void> {
  const shot = await pedHeadshot(cache.ped, true);
  if (!shot) return;
  SendNUIMessage({ action: "photo", data: `https://nui-img/${shot.txd}/${shot.txd}` });
  setTimeout(() => UnregisterPedheadshot(shot.handle), 10_000);
}

onShotCopy Anchor Link

Ejecuta un handler en el frame en que el ped local dispara (estrés, alertas de disparos, casquillos). Una comprobación por frame para tu recurso, activa solo mientras hay un arma en la mano.

Lado: Cliente · Espera: no

onShot(handler: (weapon: number) => void): () => void

aiLib.onShot(function(weapon) end) -- no devuelve nada

ParámetrosCopy Anchor Link

DevuelveCopy Anchor Link

TypeScript: () => void, una función que quita el handler. Lua no devuelve nada (el handler se queda).

EjemploCopy Anchor Link

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

let lastAlert = 0;
onShot(() => {
  if (GetGameTimer() - lastAlert < 30_000) return; // una alerta cada 30 s
  lastAlert = GetGameTimer();
  emitNet("mypolice:shots");
});

Cargar recursos del juegoCopy Anchor Link

Los modelos, animaciones, efectos y texturas deben cargarse antes de usarse. Cada cargador solicita el recurso y espera hasta que está listo. Libéralo cuando termines, como indica cada entrada.

requestModelCopy Anchor Link

Carga un modelo (ped, vehículo, objeto) y da su hash.

Lado: Cliente · Espera: sí (Promise en TypeScript, cede el hilo en Lua)

requestModel(model: string | number, timeoutMs?: number): Promise<number>

local hash = aiLib.requestModel(model, timeout) -- integer o nil, llamar dentro de un hilo

ParámetrosCopy Anchor Link

DevuelveCopy Anchor Link

Promise<number>: el hash del modelo una vez cargado. Se rechaza cuando el modelo no existe en los archivos del juego o no carga a tiempo. Lua devuelve el hash, o nil en ambos casos.

EjemploCopy Anchor Link

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

export async function placeCone(x: number, y: number, z: number): Promise<number> {
  const hash = await requestModel("prop_roadcone02a");
  const cone = CreateObject(hash, x, y, z, false, false, false);
  SetModelAsNoLongerNeeded(hash);
  PlaceObjectOnGroundProperly(cone);
  return cone;
}

requestAnimDictCopy Anchor Link

Carga un diccionario de animaciones.

Lado: Cliente · Espera: sí (Promise en TypeScript, cede el hilo en Lua)

requestAnimDict(dict: string, timeoutMs?: number): Promise<string>

local dict = aiLib.requestAnimDict(dict, timeout) -- string o nil, llamar dentro de un hilo

ParámetrosCopy Anchor Link

DevuelveCopy Anchor Link

Promise<string>: el nombre del diccionario una vez cargado. Se rechaza cuando el diccionario no existe o no carga a tiempo. Lua devuelve el nombre, o nil.

EjemploCopy Anchor Link

import { cache, requestAnimDict } from "@aicore-fivem/lib/client";

export async function dance(): Promise<void> {
  const dict = await requestAnimDict("anim@amb@nightclub@dancers@crowddance_facedj@");
  TaskPlayAnim(cache.ped, dict, "hi_dance_facedj_09_v2_male^1", 8, -8, -1, 1, 0, false, false, false);
  RemoveAnimDict(dict);
}

requestAnimSetCopy Anchor Link

Carga un clipset de movimiento (andar agachado, andar herido).

Lado: Cliente · Espera: sí (Promise en TypeScript, cede el hilo en Lua)

requestAnimSet(set: string, timeoutMs?: number): Promise<string>

local set = aiLib.requestAnimSet(set, timeout) -- string o nil, llamar dentro de un hilo

ParámetrosCopy Anchor Link

DevuelveCopy Anchor Link

Promise<string>: el nombre del clipset una vez cargado. Se rechaza cuando no carga a tiempo. Lua devuelve el nombre, o nil.

EjemploCopy Anchor Link

import { cache, requestAnimSet } from "@aicore-fivem/lib/client";

export async function limp(): Promise<void> {
  const set = await requestAnimSet("move_m@injured");
  SetPedMovementClipset(cache.ped, set, 0.2);
}

requestPtfxAssetCopy Anchor Link

Carga un recurso de efectos de partículas.

Lado: Cliente · Espera: sí (Promise en TypeScript, cede el hilo en Lua)

requestPtfxAsset(asset: string, timeoutMs?: number): Promise<string>

local asset = aiLib.requestPtfxAsset(asset, timeout) -- string o nil, llamar dentro de un hilo

ParámetrosCopy Anchor Link

DevuelveCopy Anchor Link

Promise<string>: el nombre del recurso una vez cargado. Se rechaza cuando no carga a tiempo. Lua devuelve el nombre, o nil.

EjemploCopy Anchor Link

import { player, requestPtfxAsset } from "@aicore-fivem/lib/client";

export async function sparks(): Promise<void> {
  const asset = await requestPtfxAsset("core");
  const { x, y, z } = player.coords();
  UseParticleFxAsset(asset);
  StartParticleFxNonLoopedAtCoord("ent_sht_electrical_box", x, y, z, 0, 0, 0, 1, false, false, false);
  RemoveNamedPtfxAsset(asset);
}

requestTextureDictCopy Anchor Link

Carga un diccionario de texturas en streaming (para DrawSprite y similares).

Lado: Cliente · Espera: sí (Promise en TypeScript, cede el hilo en Lua)

requestTextureDict(dict: string, timeoutMs?: number): Promise<string>

local dict = aiLib.requestTextureDict(dict, timeout) -- string o nil, llamar dentro de un hilo

ParámetrosCopy Anchor Link

DevuelveCopy Anchor Link

Promise<string>: el nombre del diccionario una vez cargado. Se rechaza cuando no carga a tiempo. Lua devuelve el nombre, o nil.

EjemploCopy Anchor Link

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

export async function showCrosshair(): Promise<void> {
  const dict = await requestTextureDict("shared");
  every(0, () => DrawSprite(dict, "emptydot_32", 0.5, 0.5, 0.01, 0.018, 0, 255, 255, 255, 200));
}

requestWeaponAssetCopy Anchor Link

Carga el modelo y los recursos de un arma y da su hash.

Lado: Cliente · Espera: sí (Promise en TypeScript, cede el hilo en Lua)

requestWeaponAsset(weapon: string | number, timeoutMs?: number): Promise<number>

local hash = aiLib.requestWeaponAsset(weapon, timeout) -- integer o nil, llamar dentro de un hilo

ParámetrosCopy Anchor Link

DevuelveCopy Anchor Link

Promise<number>: el hash del arma una vez cargada. Se rechaza cuando no carga a tiempo. Lua devuelve el hash, o nil.

EjemploCopy Anchor Link

import { player, requestWeaponAsset } from "@aicore-fivem/lib/client";

export async function showcasePistol(): Promise<number> {
  const hash = await requestWeaponAsset("WEAPON_PISTOL");
  const { x, y, z } = player.coords();
  const object = CreateWeaponObject(hash, 0, x, y, z + 1, true, 1, 0);
  RemoveWeaponAsset(hash);
  return object;
}