Peds, blips e props

Coisas que só este cliente vê: um NPC atrás de um balcão, blips no mapa, um prop na mão do jogador, um carro de vitrine. Nenhum deles está em rede, então nunca brigam com o lockdown de entidades e não custam nada ao servidor. Um ponto já cria o próprio NPC e blip (ped e blip de points.add); use estas classes para os que não têm ponto.

Peds locaisCopy Anchor Link

new LocalPedCopy Anchor Link

Um ped que só este cliente vê (um lojista, um NPC de emprego). Ele é criado quando o jogador chega a até distance de coords e apagado quando ele sai, então mil NPCs no mapa não custam nada até alguém se aproximar. Ele fica congelado, não pode ser ferido e ignora eventos (tiros, empurrões).

Lado: Cliente · Espera: não (o modelo carrega em segundo plano quando o jogador se aproxima)

new LocalPed(options: LocalPedOptions)

local ped = aiLib.LocalPed.new(options)

ParâmetrosCopy Anchor Link

LocalPedOptionsCopy Anchor Link

MembrosCopy Anchor Link

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

// Depois, quando o emprego termina:
guard.remove();

BlipsCopy Anchor Link

createBlipCopy Anchor Link

Cria um blip nomeado no mapa e retorna o handle dele. Você mesmo o remove com RemoveBlip(handle); para blips que você reconstrói quando o painel muda, use um grupo Blips.

Lado: Cliente · Espera: não

createBlip(options: BlipOptions): number

local blip = aiLib.Blips.create(options)

ParâmetrosCopy Anchor Link

BlipOptionsCopy Anchor Link

Um estilo de blip escolhido no seu painel de administração (o widget blip, lido com readBlipStyle) se espalha direto nestas opções: createBlip({ ...style, coords, label }).

RetornoCopy Anchor Link

number: o handle do blip.

ExemploCopy Anchor Link

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

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

// Um destino de entrega com rota de GPS; removido ao 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,
});
// ... na entrega:
RemoveBlip(target);

new BlipsCopy Anchor Link

Um grupo de blips por id: add substitui um blip com o mesmo id e clear remove todos. Use um grupo por funcionalidade.

Lado: Cliente · Espera: não

new Blips()

local blips = aiLib.Blips.new()

MétodosCopy Anchor Link

Em Lua chame os métodos com dois-pontos: blips:add(id, options).

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

// Uma garagem foi fechada:
blips.remove("airport");

Props e animações mantidasCopy Anchor Link

attachPropCopy Anchor Link

Cria um prop local e o prende a um bone do ped (um celular na mão, uma caixa carregada na frente). O prop não tem colisão, a menos que você peça.

Lado: Cliente · Espera: sim (Promise: carrega o modelo primeiro)

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

Sem equivalente em Lua: crie o objeto e chame AttachEntityToEntity você mesmo.

ParâmetrosCopy Anchor Link

AttachPropOptionsCopy Anchor Link

RetornoCopy Anchor Link

Promise<number>: a entidade do prop, ou 0 quando o modelo não carrega ou o ped não existe mais. Nunca rejeita.

ExemploCopy 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

Mantém uma animação tocando até você pará-la. Quando uma queda, um esbarrão ou um ragdoll a interrompe, ela é retomada em meio segundo. Use para carregar coisas, segurar um celular ou um loop de trabalho. Uma por recurso: uma nova substitui a antiga.

Lado: Cliente · Espera: não

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

Sem equivalente em Lua: toque a animação com aiLib.player.playAnim e verifique-a com um job aiLib.every.

ParâmetrosCopy Anchor Link

HoldAnimOptionsCopy Anchor Link

RetornoCopy Anchor Link

{ stop(): void }: chame stop() para encerrar a animação mantida e limpar as tarefas do ped. Chamar stop() em uma que já foi substituída não faz nada.

ExemploCopy 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 sozinha quando o jogador entra em um veículo.
  player.holdAnim("anim@heists@box_carry@", "idle", {
    while: () => cache.vehicle === false,
  });
  setTimeout(() => box && DeleteEntity(box), 60_000);
}

Veículos de vitrineCopy Anchor Link

new PreviewVehicleCopy Anchor Link

Um veículo local de prévia para vitrines e lojas: congelado, não pode ser danificado, trancado e limpo. Mostrar um novo modelo substitui o antigo, e a última chamada sempre vence (uma chamada mais antiga ainda carregando o modelo não faz nada). Apagado em clear() e quando o seu recurso para. Nada em rede.

Lado: Cliente · Espera: show sim (Promise)

new PreviewVehicle()

Sem equivalente em Lua.

MembrosCopy Anchor Link

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