Vínculos e dados do jogador

O ai-core envia os dados do próprio jogador local para o cliente dele: um snapshot quando o personagem carrega, depois só os valores que mudam. Estes helpers leem essa cópia, então uma verificação custa uma leitura em memória e nunca pergunta ao servidor.

Use-os para o que o jogador vê (o canShow de um ponto, um item do radial, uma linha de menu). O servidor decide o que o jogador pode fazer com os mesmos dados (online em Jogadores e personagens): uma verificação no cliente nunca é prova.

Dados do jogadorCopy Anchor Link

Os valores que o ai-core guarda, por chave (AiPlayerData):

Os tipos dos membros são CharacterInfo, JobMembership e GangMembership.

getPlayerDataCopy Anchor Link

O último valor de uma chave. No primeiro uso no seu recurso também lê tudo o que o ai-core já enviou (pelo export GetPlayerData do ai-core), então um recurso reiniciado depois que o jogador carregou tem os valores na hora.

Lado: Cliente · Espera: não

getPlayerData<K extends keyof AiPlayerData>(key: K): AiPlayerData[K] | undefined

local value = aiLib.playerData.get(key)

ParâmetrosCopy Anchor Link

RetornoCopy Anchor Link

AiPlayerData[K] | undefined: o valor, ou undefined (nil em Lua) quando nada chegou ainda (nenhum personagem carregado, ai-core não iniciado).

ExemploCopy Anchor Link

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

RegisterCommand(
  "whoami",
  () => {
    const character = getPlayerData("character");
    const job = getPlayerData("job");
    const cash = getPlayerData("money")?.cash ?? 0;
    if (!character) return notify("No character loaded", "error");
    notify(`${job?.job ?? "unemployed"} (${job?.grade ?? 0}), $${cash}`, "info");
  },
  false,
);

onPlayerDataCopy Anchor Link

Roda um handler toda vez que o ai-core envia uma chave para este jogador.

Lado: Cliente · Espera: não

onPlayerData<K extends keyof AiPlayerData>(key: K, handler: (value: AiPlayerData[K]) => void): () => void

aiLib.playerData.onChange(key, function(value) end)

ParâmetrosCopy Anchor Link

RetornoCopy Anchor Link

TypeScript: () => void, uma função que remove o handler. Lua não retorna nada.

ExemploCopy Anchor Link

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

const stop = onPlayerData("money", (money) => {
  SendNUIMessage({ action: "money", data: { cash: money.cash ?? 0, bank: money.bank ?? 0 } });
});
// stop() quando o HUD fecha de vez

seedPlayerDataCopy Anchor Link

Preenche valores à mão. Chaves que já têm valor são mantidas. Você não precisa disto: a lib se preenche sozinha a partir do ai-core no primeiro uso.

Lado: Cliente · Espera: não

seedPlayerData(data: Partial<AiPlayerData>): void

Sem equivalente em Lua.

ParâmetrosCopy Anchor Link

RetornoCopy Anchor Link

void.

ExemploCopy Anchor Link

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

// Um ambiente de teste sem o ai-core.
seedPlayerData({ jobs: [{ job: "police", grade: 3 }], duty: "police" });

Verificações de vínculoCopy Anchor Link

hasJobCopy Anchor Link

Se o jogador tem um dos empregos em um cargo mínimo, em serviço ou não.

Lado: Cliente · Espera: não

hasJob(jobs: readonly string[], minGrade?: number): boolean

Sem equivalente em Lua: percorra aiLib.playerData.get('jobs') (veja o exemplo Lua de points.add).

ParâmetrosCopy Anchor Link

RetornoCopy Anchor Link

boolean: true quando a lista está vazia, ou o jogador tem um dos jobs no minGrade ou acima.

ExemploCopy Anchor Link

import { hasJob, onMembershipChange, Points } from "@aicore-fivem/lib/client";

const points = new Points();
points.add("armory", {
  coords: { x: 482.6, y: -995.2, z: 30.7 },
  label: "Armory",
  canShow: () => hasJob(["police", "sheriff"], 1),
  onPressed: () => emitNet("mypolice:armory"),
});
onMembershipChange(() => points.refresh());

inGangCopy Anchor Link

Se o jogador está em uma das gangues em um cargo mínimo.

Lado: Cliente · Espera: não

inGang(gangs: readonly string[], minGrade?: number): boolean

Sem equivalente em Lua: percorra aiLib.playerData.get('gangs').

ParâmetrosCopy Anchor Link

RetornoCopy Anchor Link

boolean: true quando a lista está vazia, ou o jogador está em uma das gangs no minGrade ou acima.

ExemploCopy Anchor Link

import { inGang, radial } from "@aicore-fivem/lib/client";

radial.add({
  id: "mygang:stash",
  label: "Gang stash",
  icon: "box",
  canShow: () => inGang(["ballas", "vagos"], 2),
  onPressed: () => emitNet("mygang:stash"),
});

onDutyInCopy Anchor Link

Se o jogador está em serviço em um dos empregos.

Lado: Cliente · Espera: não

onDutyIn(jobs: readonly string[]): boolean

Sem equivalente em Lua: aiLib.playerData.get('duty') é o emprego em serviço.

ParâmetrosCopy Anchor Link

RetornoCopy Anchor Link

boolean: true quando o emprego em serviço do jogador está em jobs.

ExemploCopy Anchor Link

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

const points = new Points();
points.addVehicle("mymech:repair", {
  label: "Repair",
  icon: "wrench",
  canShow: () => onDutyIn(["mechanic"]),
  onPressed: (vehicle) => emitNet("mymech:repair", NetworkGetNetworkIdFromEntity(vehicle)),
});

onMembershipChangeCopy Anchor Link

Roda uma função quando os empregos, o serviço ou as gangues do jogador mudam. Use para atualizar pontos e blips cujo canShow os lê.

Lado: Cliente · Espera: não

onMembershipChange(fn: () => void): void

Sem equivalente em Lua: aiLib.playerData.onChange para jobs, duty e gangs.

ParâmetrosCopy Anchor Link

RetornoCopy Anchor Link

void.

ExemploCopy Anchor Link

import { onMembershipChange, Points, radial } from "@aicore-fivem/lib/client";

const points = new Points();
onMembershipChange(() => {
  points.refresh();
  radial.refresh();
});

allowsCopy Anchor Link

Se o jogador local pode usar um lugar com uma regra de acesso. O online.allows(source, rule) do servidor decide com a mesma regra, então o que o jogador vê é exatamente o que o servidor o deixa usar. Leia a regra de um registro do painel com readAccess(record) (@aicore-fivem/lib/shared).

Lado: Cliente · Espera: não

allows(rule: AccessRule): boolean

Sem equivalente em Lua.

ParâmetrosCopy Anchor Link

AccessRuleCopy Anchor Link

O tipo é AccessRule.

RetornoCopy Anchor Link

boolean: true quando as duas listas estão vazias (todos); quando o jogador está em uma das gangs no cargo mínimo dela; ou quando o jogador tem um dos jobs no cargo mínimo dele (e está em serviço nele quando onDuty). Caso contrário false.

ExemploCopy Anchor Link

import { AdminWorld, allows, callAction, onMembershipChange, Points } from "@aicore-fivem/lib/client";
import { readAccess, readVec3, RecordObjects, type AccessRule } from "@aicore-fivem/lib/shared";

const world = new AdminWorld(["stashes"]);
const points = new Points();

interface Stash { coords: { x: number; y: number; z: number }; access: AccessRule }
const readStash = (_key: string, raw: Record<string, unknown>): Stash | null => {
  const coords = readVec3(raw.coords);
  return coords ? { coords, access: readAccess(raw) } : null;
};

new RecordObjects(world, "stashes", readStash, (id, stash) => {
  points.add(id, {
    coords: stash.coords,
    label: "Stash",
    canShow: () => allows(stash.access),
    onPressed: () => callAction("mystash:open", [id], { fallback: "STASH_FAILED" }),
  });
  return () => points.remove(id);
});

onMembershipChange(() => points.refresh());