Peds, blips y props

Cosas que solo ve este cliente: un NPC detrás de un mostrador, blips del mapa, un prop en la mano del jugador, un coche de exposición. Ninguno está en red, así que nunca chocan con el bloqueo de entidades y no le cuestan nada al servidor. Un punto ya crea su propio NPC y su blip (ped y blip de points.add); usa estas clases para los que no tienen un punto.

Peds localesCopy Anchor Link

new LocalPedCopy Anchor Link

Un ped que solo ve este cliente (un tendero, un NPC de trabajo). Se crea cuando el jugador se acerca a menos de distance de coords y se elimina cuando se aleja, así que mil NPC en el mapa no cuestan nada hasta que alguien se acerca. Está quieto y congelado, no puede recibir daño e ignora los eventos (disparos, empujones).

Lado: Cliente · Espera: no (el modelo se carga en segundo plano cuando el jugador se acerca)

new LocalPed(options: LocalPedOptions)

local ped = aiLib.LocalPed.new(options)

ParámetrosCopy Anchor Link

LocalPedOptionsCopy Anchor Link

MiembrosCopy Anchor Link

EjemploCopy Anchor Link

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

const guard = new LocalPed({
  model: "s_m_m_security_01",
  coords: { x: -1037.6, y: -2737.8, z: 20.2, heading: 330 },
  scenario: "WORLD_HUMAN_GUARD_STAND",
  distance: 80,
  onSpawn: (ped) => SetPedComponentVariation(ped, 0, 1, 0, 0),
});

// Más tarde, cuando termina el trabajo:
guard.remove();

BlipsCopy Anchor Link

createBlipCopy Anchor Link

Crea un blip con nombre en el mapa y devuelve su handle. Lo quitas tú mismo con RemoveBlip(handle); para los blips que reconstruyes cuando cambia el panel, usa un grupo Blips.

Lado: Cliente · Espera: no

createBlip(options: BlipOptions): number

local blip = aiLib.Blips.create(options)

ParámetrosCopy Anchor Link

BlipOptionsCopy Anchor Link

Un estilo de blip elegido en tu panel de administración (el widget blip, leído con readBlipStyle) se expande directamente en estas opciones: createBlip({ ...style, coords, label }).

DevuelveCopy Anchor Link

number: el handle del blip.

EjemploCopy Anchor Link

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

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

// Un destino de entrega con ruta GPS; se quita al entregar.
const target = createBlip({
  coords: { x: 1197.4, y: -3253.6, z: 7.1 },
  sprite: 478,
  color: 5,
  label: Locale("DELIVERY"),
  shortRange: false,
  route: true,
});
// ... al entregar:
RemoveBlip(target);

new BlipsCopy Anchor Link

Un grupo de blips por id: add reemplaza un blip con el mismo id y clear los quita todos. Usa un grupo por funcionalidad.

Lado: Cliente · Espera: no

new Blips()

local blips = aiLib.Blips.new()

MétodosCopy Anchor Link

En Lua llama a los métodos con dos puntos: blips:add(id, options).

EjemploCopy Anchor Link

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

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

const GARAGES = [
  { id: "legion", coords: { x: 215.8, y: -810.1, z: 30.7 } },
  { id: "airport", coords: { x: -796.5, y: -2023.3, z: 9.2 } },
];

for (const garage of GARAGES)
  blips.add(garage.id, { coords: garage.coords, sprite: 357, color: 3, label: Locale("GARAGE") });

// Se cerró un garaje:
blips.remove("airport");

Props y animaciones mantenidasCopy Anchor Link

attachPropCopy Anchor Link

Crea un prop local y lo une a un hueso de un ped (un teléfono en la mano, una caja llevada delante). El prop no tiene colisión salvo que la pidas.

Lado: Cliente · Espera: sí (Promise: primero carga el modelo)

attachProp(model: string | number, options: AttachPropOptions): Promise<number>

Sin equivalente en Lua: crea el objeto y llama tú mismo a AttachEntityToEntity.

ParámetrosCopy Anchor Link

AttachPropOptionsCopy Anchor Link

DevuelveCopy Anchor Link

Promise<number>: la entidad del prop, o 0 cuando el modelo no carga o el ped ya no existe. Nunca se rechaza.

EjemploCopy Anchor Link

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

export async function readNewspaper(): Promise<void> {
  const paper = await attachProp("prop_cliff_paper", {
    bone: 18905,
    offset: { x: 0.12, y: 0.03, z: 0.02 },
    rotation: { x: 10, y: 0, z: 0 },
  });
  const hold = player.holdAnim("amb@world_human_tourist_map@male@base", "base");
  setTimeout(() => {
    hold.stop();
    if (paper) DeleteEntity(paper);
  }, 10_000);
}

player.holdAnimCopy Anchor Link

Mantiene una animación en reproducción hasta que la detienes. Cuando una caída, un golpe o un ragdoll la interrumpe, se vuelve a poner en medio segundo. Úsalo para cargar algo, sostener un teléfono o un bucle de trabajo. Una animación mantenida por recurso: una nueva reemplaza la anterior.

Lado: Cliente · Espera: no

player.holdAnim(dict: string, clip: string, options?: HoldAnimOptions): { stop(): void }

Sin equivalente en Lua: reproduce la animación con aiLib.player.playAnim y compruébala con una tarea aiLib.every.

ParámetrosCopy Anchor Link

HoldAnimOptionsCopy Anchor Link

DevuelveCopy Anchor Link

{ stop(): void }: llama a stop() para terminar la animación mantenida y limpiar las tareas del ped. Llamar a stop() en una animación mantenida que ya fue reemplazada no hace nada.

EjemploCopy Anchor Link

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

export async function carryBox(): Promise<void> {
  const box = await attachProp("hei_prop_heist_box", {
    bone: 60309,
    offset: { x: 0.025, y: 0.08, z: 0.255 },
    rotation: { x: -145, y: 290, z: 0 },
  });
  // Termina sola cuando el jugador se sube a un vehículo.
  player.holdAnim("anim@heists@box_carry@", "idle", {
    while: () => cache.vehicle === false,
  });
  setTimeout(() => box && DeleteEntity(box), 60_000);
}

Vehículos de exposiciónCopy Anchor Link

new PreviewVehicleCopy Anchor Link

Un vehículo local de vista previa para exposiciones y tiendas: congelado, no se puede dañar, cerrado y limpio. Mostrar un modelo nuevo reemplaza el anterior, y la última llamada siempre gana (una llamada anterior que aún carga su modelo no hace nada). Se elimina con clear() y cuando tu recurso se detiene. Nada está en red.

Lado: Cliente · Espera: show sí (Promise)

new PreviewVehicle()

Sin equivalente en Lua.

MiembrosCopy Anchor Link

EjemploCopy Anchor Link

import { PreviewVehicle, setVehicleSetup } from "@aicore-fivem/lib/client";

const preview = new PreviewVehicle();
const STAGE = { x: -44.4, y: -1097.1, z: 26.4, heading: 120 };

export async function showCar(model: string, color: number): Promise<void> {
  const vehicle = await preview.show(model, STAGE, (v) => setVehicleSetup(v, { colors: [color, color] }));
  if (vehicle) SetVehicleNumberPlateText(vehicle, "SHOWROOM");
}

export function leaveShowroom(): void {
  preview.clear();
}