O jogador local

Tudo sobre o jogador sentado neste computador. Leia valores de cache em vez de chamar PlayerPedId() em loops: o ai-core mantém um único observador para todos os recursos e envia as mudanças, então nenhum script fica consultando por elas.

cacheCopy Anchor Link

Os valores mais lidos do jogador local, mantidos atualizados pelo único observador do ai-core. Como o cache do ox_lib: leia cache.ped em vez de chamar PlayerPedId(), e cache.vehicle em vez de GetVehiclePedIsIn a cada frame. Ler uma chave é uma simples leitura em memória, segura em loops e em código por frame.

Lado: Cliente · Espera: não

const cache: PlayerCache // somente leitura

local ped = aiLib.cache.ped

ChavesCopy Anchor Link

O tipo é PlayerCache.

ExemploCopy Anchor Link

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

// Velocidade mostrada enquanto dirige, lida do cache a cada 200 ms.
every(200, () => {
  if (cache.vehicle === false || cache.seat !== -1) return;
  const kmh = GetEntitySpeed(cache.vehicle) * 3.6;
  SendNUIMessage({ action: "speed", data: Math.round(kmh) });
});

onCacheCopy Anchor Link

Roda um handler sempre que um valor em cache muda: o jogador entrou ou saiu de um veículo, trocou de assento, sacou ou guardou uma arma, ou recebeu um novo ped. Use em vez de verificar o valor em um timer.

Lado: Cliente · Espera: não

onCache<K extends keyof PlayerCache>(key: K, handler: (value: PlayerCache[K], old: PlayerCache[K]) => void): void

aiLib.cache.onChange(key, function(value, old) end)

ParâmetrosCopy Anchor Link

RetornoCopy Anchor Link

void. Não há como remover o handler; mantenha um por funcionalidade no topo do arquivo.

ExemploCopy Anchor Link

import { onCache, inventory, Points } from "@aicore-fivem/lib/client";

const points = new Points();

// Os pontos cujo canShow lê cache.vehicle são verificados de novo.
onCache("vehicle", () => points.refresh());

// O item da arma na mão, lido só quando a arma muda.
onCache("weapon", (weapon) => {
  const item = weapon === false ? null : inventory.currentWeapon();
  SendNUIMessage({ action: "weapon", data: item });
});

readPlayerStateCopy Anchor Link

Lê o veículo, o assento e a arma de um ped agora mesmo, sem o cache. O observador do ai-core o usa; você só precisa dele para um ped que não é o local, ou para comparar com o cache à mão.

Lado: Cliente · Espera: não

readPlayerState(ped: number): { vehicle: number | false; seat: number | false; weapon: number | false }

Sem equivalente em Lua.

ParâmetrosCopy Anchor Link

RetornoCopy Anchor Link

Um objeto com vehicle (o handle do veículo, false a pé), seat (-1 motorista em diante, false a pé) e weapon (o hash na mão, false quando desarmado).

ExemploCopy Anchor Link

import { playerPed, readPlayerState } from "@aicore-fivem/lib/client";

const ped = playerPed(12);
if (ped !== 0 && readPlayerState(ped).seat === -1) console.log("player 12 is driving");

readWeaponCopy Anchor Link

A arma na mão de um ped agora mesmo, false quando desarmado.

Lado: Cliente · Espera: não

readWeapon(ped: number): number | false

Sem equivalente em Lua.

ParâmetrosCopy Anchor Link

RetornoCopy Anchor Link

number | false: o hash da arma, ou false quando o ped segura WEAPON_UNARMED.

ExemploCopy Anchor Link

import { nearestPlayer, playerPed, readWeapon } from "@aicore-fivem/lib/client";

const id = nearestPlayer(5);
if (id !== null && readWeapon(playerPed(id)) !== false) console.log("the player next to you is armed");

playerCopy Anchor Link

Um objeto para o ped local: onde ele está, movê-lo, animações. As leituras usam cache.ped; as ações leem o ped atualizado, então também funcionam logo depois de uma troca de modelo.

player.pedCopy Anchor Link

O handle do ped local (o mesmo valor de cache.ped).

Lado: Cliente · Espera: não

player.ped: number // propriedade somente leitura

Sem equivalente em Lua: use aiLib.cache.ped.

RetornoCopy Anchor Link

number: o handle do ped.

ExemploCopy Anchor Link

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

SetPedArmour(player.ped, 100);

player.coordsCopy Anchor Link

A posição do ped agora.

Lado: Cliente · Espera: não

player.coords(): Vec3

local coords = aiLib.player.coords() -- vector3

RetornoCopy Anchor Link

Um Vec3 { x, y, z } em TypeScript (z é a raiz do ped, cerca de 1 m acima do chão). Lua retorna um vector3.

ExemploCopy Anchor Link

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

const here = player.coords();
console.log(`${locationName(here).street} at ${here.x.toFixed(1)}, ${here.y.toFixed(1)}`);

player.headingCopy Anchor Link

A direção para onde o ped olha, em graus (0-360, 0 = norte).

Lado: Cliente · Espera: não

player.heading(): number

local heading = aiLib.player.heading()

RetornoCopy Anchor Link

number: o heading em graus.

ExemploCopy Anchor Link

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

// Salva o lugar e a direção para um registro do painel.
const spot = { ...player.coords(), heading: player.heading() };

player.distanceToCopy Anchor Link

Distância em linha reta do ped até um ponto, em metros.

Lado: Cliente · Espera: não

player.distanceTo(point: Vec3): number

local metres = aiLib.player.distanceTo(point) -- vector3 ou { x, y, z }

ParâmetrosCopy Anchor Link

RetornoCopy Anchor Link

number: metros, medidos em 3D.

ExemploCopy Anchor Link

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

const counter = { x: 25.7, y: -1347.3, z: 29.5 };
if (player.distanceTo(counter) > 3) notify("Walk to the counter first", "error");

player.freezeCopy Anchor Link

Congela o ped no lugar, ou o deixa se mover de novo.

Lado: Cliente · Espera: não

player.freeze(state: boolean): void

aiLib.player.freeze(frozen)

ParâmetrosCopy Anchor Link

RetornoCopy Anchor Link

void.

ExemploCopy Anchor Link

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

player.freeze(true);
setTimeout(() => player.freeze(false), 5000);

player.teleportCopy Anchor Link

Move o jogador e espera até o mundo ao redor do novo lugar carregar, atrás de um fade para preto. Sem z (ou com ground: "find"), ele procura o chão sob x e y: use isso para o waypoint do mapa.

Lado: Cliente · Espera: sim (Promise em TypeScript, pausa a thread em Lua)

player.teleport(to: { x: number; y: number; z?: number }, options?: TeleportOptions): Promise<void>

aiLib.player.teleport(to, options) -- chame dentro de uma thread

ParâmetrosCopy Anchor Link

TeleportOptionsCopy Anchor Link

RetornoCopy Anchor Link

Promise<void> que resolve assim que o jogador está no novo lugar e a colisão ali carregou (ou depois de 5 segundos sem ela). Lua não retorna nada.

ExemploCopy Anchor Link

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

RegisterCommand(
  "tpm",
  async () => {
    const target = waypoint();
    if (!target) return notify("Set a waypoint first", "error");
    await player.teleport(target, { keepVehicle: true }); // sem z: cai no chão
  },
  false,
);

player.playAnimCopy Anchor Link

Toca uma animação no ped. Carrega o dicionário da animação primeiro.

Lado: Cliente · Espera: sim em TypeScript (resolve quando a animação começou); em Lua pausa enquanto o dicionário carrega

player.playAnim(dict: string, clip: string, options?: AnimOptions): Promise<void>

aiLib.player.playAnim(dict, clip, options) -- chame dentro de uma thread

ParâmetrosCopy Anchor Link

AnimOptionsCopy Anchor Link

RetornoCopy Anchor Link

Promise<void> que resolve quando a animação começou. Ela rejeita quando o dicionário não existe ou não carrega em 10 segundos. Lua não retorna nada e não faz nada quando o dicionário não carrega.

ExemploCopy Anchor Link

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

export async function handOver(): Promise<void> {
  await player.playAnim("mp_common", "givetake1_a", { flag: 48, duration: 1500 });
}

player.stopAnimCopy Anchor Link

Para o que quer que o ped esteja fazendo (ClearPedTasks): animações e cenários.

Lado: Cliente · Espera: não

player.stopAnim(): void

aiLib.player.stopAnim()

RetornoCopy Anchor Link

void.

ExemploCopy Anchor Link

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

export async function readClipboard(): Promise<void> {
  await player.playAnim("amb@world_human_clipboard@male@idle_a", "idle_c");
  setTimeout(() => player.stopAnim(), 4000);
}

player.holdAnimCopy Anchor Link

Mantém uma animação tocando até você pará-la, retomando-a quando uma queda ou um esbarrão a interrompe. Documentado junto com os props em Peds, blips e props.

Fades e outros jogadoresCopy Anchor Link

fadeOutCopy Anchor Link

Escurece a tela até o preto e espera até ela ficar totalmente preta. Use para esconder um teleporte, uma troca de modelo ou uma mudança de cena.

Lado: Cliente · Espera: sim (Promise em TypeScript, pausa a thread em Lua)

fadeOut(ms?: number): Promise<void>

aiLib.fadeOut(ms) -- chame dentro de uma thread

ParâmetrosCopy Anchor Link

RetornoCopy Anchor Link

Promise<void> que resolve quando a tela está preta, ou depois de ms + 2 segundos no máximo. Nunca rejeita.

ExemploCopy Anchor Link

import { fadeIn, fadeOut } from "@aicore-fivem/lib/client";

export async function moveToSquare(): Promise<void> {
  await fadeOut();
  SetEntityCoords(PlayerPedId(), -269.4, -955.3, 31.2, false, false, false, false);
  await fadeIn();
}

fadeInCopy Anchor Link

Clareia a tela de novo e espera até ela ficar limpa. O par de fadeOut.

Lado: Cliente · Espera: sim (Promise em TypeScript, pausa a thread em Lua)

fadeIn(ms?: number): Promise<void>

aiLib.fadeIn(ms) -- chame dentro de uma thread

ParâmetrosCopy Anchor Link

RetornoCopy Anchor Link

Promise<void> que resolve quando a tela está limpa, ou depois de ms + 2 segundos no máximo. Nunca rejeita.

ExemploCopy Anchor Link

Veja fadeOut: os dois são sempre usados juntos.

playerPedCopy Anchor Link

O ped de um jogador pelo id de servidor. Para o jogador local retorna cache.ped; para outro jogador retorna 0 quando esse jogador não está perto o bastante para ser transmitido a este cliente.

Lado: Cliente · Espera: não

playerPed(serverId: number): number

local ped = aiLib.playerPed(serverId)

ParâmetrosCopy Anchor Link

RetornoCopy Anchor Link

number: o handle do ped, ou 0 quando o jogador não está no escopo deste cliente.

ExemploCopy Anchor Link

import { onServerEvent, playerPed } from "@aicore-fivem/lib/client";

// O servidor avisa todos por perto que um jogador foi algemado.
onServerEvent(
  "myscript:cuffed",
  { args: ([id]) => (typeof id === "number" ? [id] : null) },
  (id) => {
    const ped = playerPed(id);
    if (ped !== 0) SetEnableHandcuffs(ped, true);
  },
);

nearestPlayerCopy Anchor Link

O outro jogador mais próximo dentro de uma distância, como id de servidor. Percorre só os jogadores transmitidos a este cliente. Use para escolher o alvo de ações de dar, revistar, algemar ou derrubar, e depois envie esse id ao servidor, que verifica a distância de novo.

Lado: Cliente · Espera: não

nearestPlayer(metres: number, options?: { from?: Vec3; filter?: (serverId: number, ped: number) => boolean }): number | null

local serverId = aiLib.nearestPlayer(metres, options) -- integer ou nil

ParâmetrosCopy Anchor Link

OpçõesCopy Anchor Link

RetornoCopy Anchor Link

number | null: o id de servidor do jogador mais próximo que passou em filter, ou null (nil em Lua) quando ninguém está a até metres. O jogador local nunca é retornado.

ExemploCopy Anchor Link

import { callAction, nearestPlayer, notify } from "@aicore-fivem/lib/client";

RegisterCommand(
  "givecash",
  async (_src: number, args: string[]) => {
    const target = nearestPlayer(3, { filter: (_id, ped) => !IsPedInAnyVehicle(ped, false) });
    if (target === null) return notify("Nobody is close enough", "error");
    await callAction("myscript:give", [target, Number(args[0])], { fallback: "GIVE_FAILED" });
  },
  false,
);