Le joueur local

Tout ce qui concerne le joueur assis devant cet ordinateur. Lisez les valeurs dans cache au lieu d’appeler PlayerPedId() dans des boucles : ai-core garde un seul observateur pour toutes les ressources et pousse les changements, si bien qu’aucun script ne les interroge en boucle.

cacheCopy Anchor Link

Les valeurs du joueur local les plus lues, tenues à jour par l’observateur unique d’ai-core. Comme le cache d’ox_lib : lisez cache.ped au lieu d’appeler PlayerPedId(), et cache.vehicle au lieu de GetVehiclePedIsIn à chaque frame. Lire une clé est une simple lecture en mémoire, sûre dans les boucles et dans le code exécuté à chaque frame.

Côté : client · Attend : non

const cache: PlayerCache // lecture seule

local ped = aiLib.cache.ped

ClésCopy Anchor Link

Le type est PlayerCache.

ExempleCopy Anchor Link

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

// Vitesse affichée pendant la conduite, lue dans le cache toutes les 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

Exécute un gestionnaire chaque fois qu’une valeur en cache change : le joueur est monté dans un véhicule ou en est descendu, a changé de siège, a sorti ou rangé une arme, ou a reçu un nouveau ped. Utilisez-le au lieu de vérifier la valeur avec un minuteur.

Côté : client · Attend : non

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

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

ParamètresCopy Anchor Link

RetourCopy Anchor Link

void. Il n’y a aucun moyen de retirer le gestionnaire ; gardez-en un par fonctionnalité en haut du fichier.

ExempleCopy Anchor Link

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

const points = new Points();

// Les points dont canShow lit cache.vehicle sont vérifiés à nouveau.
onCache("vehicle", () => points.refresh());

// L’objet arme en main, lu seulement quand l’arme change.
onCache("weapon", (weapon) => {
  const item = weapon === false ? null : inventory.currentWeapon();
  SendNUIMessage({ action: "weapon", data: item });
});

readPlayerStateCopy Anchor Link

Lit le véhicule, le siège et l’arme d’un ped à l’instant, sans le cache. L’observateur d’ai-core l’utilise ; vous n’en avez besoin que pour un ped qui n’est pas le ped local, ou pour comparer avec le cache à la main.

Côté : client · Attend : non

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

Pas d’équivalent Lua.

ParamètresCopy Anchor Link

RetourCopy Anchor Link

Un objet avec vehicle (le handle du véhicule, false à pied), seat (-1 conducteur et plus, false à pied) et weapon (le hash en main, false quand il est désarmé).

ExempleCopy 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

L’arme dans la main d’un ped à l’instant, false quand il est désarmé.

Côté : client · Attend : non

readWeapon(ped: number): number | false

Pas d’équivalent Lua.

ParamètresCopy Anchor Link

RetourCopy Anchor Link

number | false : le hash de l’arme, ou false quand le ped tient WEAPON_UNARMED.

ExempleCopy 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

Un seul objet pour le ped local : où il se trouve, le déplacer, les animations. Les lectures utilisent cache.ped ; les actions lisent le ped à jour, elles fonctionnent donc aussi juste après un changement de modèle.

player.pedCopy Anchor Link

Le handle du ped local (la même valeur que cache.ped).

Côté : client · Attend : non

player.ped: number // propriété en lecture seule

Pas d’équivalent Lua : utilisez aiLib.cache.ped.

RetourCopy Anchor Link

number : le handle du ped.

ExempleCopy Anchor Link

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

SetPedArmour(player.ped, 100);

player.coordsCopy Anchor Link

La position actuelle du ped.

Côté : client · Attend : non

player.coords(): Vec3

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

RetourCopy Anchor Link

Un Vec3 { x, y, z } en TypeScript (z est la racine du ped, environ 1 m au-dessus du sol). Lua renvoie un vector3.

ExempleCopy 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

La direction vers laquelle le ped est tourné, en degrés (0-360, 0 = nord).

Côté : client · Attend : non

player.heading(): number

local heading = aiLib.player.heading()

RetourCopy Anchor Link

number : le cap en degrés.

ExempleCopy Anchor Link

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

// Enregistre l’emplacement et la direction pour un enregistrement du panneau.
const spot = { ...player.coords(), heading: player.heading() };

player.distanceToCopy Anchor Link

La distance en ligne droite entre le ped et un point, en mètres.

Côté : client · Attend : non

player.distanceTo(point: Vec3): number

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

ParamètresCopy Anchor Link

RetourCopy Anchor Link

number : des mètres, mesurés en 3D.

ExempleCopy 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

Fige le ped sur place, ou le laisse bouger à nouveau.

Côté : client · Attend : non

player.freeze(state: boolean): void

aiLib.player.freeze(frozen)

ParamètresCopy Anchor Link

RetourCopy Anchor Link

void.

ExempleCopy Anchor Link

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

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

player.teleportCopy Anchor Link

Déplace le joueur et attend que le monde autour du nouvel emplacement soit chargé, derrière un fondu au noir. Sans z (ou avec ground: "find"), il cherche le sol sous x et y : utilisez cela pour le point de passage de la carte.

Côté : client · Attend : oui (Promise en TypeScript, cède la main (yield) du thread en Lua)

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

aiLib.player.teleport(to, options) -- à appeler dans un thread

ParamètresCopy Anchor Link

TeleportOptionsCopy Anchor Link

RetourCopy Anchor Link

Promise<void> qui se résout une fois que le joueur se tient au nouvel emplacement et que la collision y est chargée (ou après 5 secondes sans elle). Lua ne renvoie rien.

ExempleCopy 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 }); // pas de z : atterrit sur le sol
  },
  false,
);

player.playAnimCopy Anchor Link

Joue une animation sur le ped. Il charge d’abord le dictionnaire d’animations.

Côté : client · Attend : oui en TypeScript (se résout quand l’animation a démarré) ; cède la main (yield) en Lua pendant le chargement du dictionnaire

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

aiLib.player.playAnim(dict, clip, options) -- à appeler dans un thread

ParamètresCopy Anchor Link

AnimOptionsCopy Anchor Link

RetourCopy Anchor Link

Promise<void> qui se résout quand l’animation a démarré. Elle est rejetée quand le dictionnaire n’existe pas ou ne se charge pas en 10 secondes. Lua ne renvoie rien et ne fait rien quand le dictionnaire ne se charge pas.

ExempleCopy 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

Arrête tout ce que fait le ped (ClearPedTasks) : animations et scénarios.

Côté : client · Attend : non

player.stopAnim(): void

aiLib.player.stopAnim()

RetourCopy Anchor Link

void.

ExempleCopy 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

Maintient une animation jusqu’à ce que vous l’arrêtiez, en la relançant quand une chute ou un choc l’interrompt. Documenté avec les props sur Peds, blips et props.

Fondus et autres joueursCopy Anchor Link

fadeOutCopy Anchor Link

Fait un fondu de l’écran au noir et attend qu’il soit complètement noir. Utilisez-le pour cacher une téléportation, un changement de modèle ou un changement de scène.

Côté : client · Attend : oui (Promise en TypeScript, cède la main (yield) du thread en Lua)

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

aiLib.fadeOut(ms) -- à appeler dans un thread

ParamètresCopy Anchor Link

RetourCopy Anchor Link

Promise<void> qui se résout quand l’écran est noir, ou au plus tard après ms + 2 secondes. Elle n’est jamais rejetée.

ExempleCopy 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

Ramène l’image à l’écran par un fondu et attend qu’elle soit nette. Le pendant de fadeOut.

Côté : client · Attend : oui (Promise en TypeScript, cède la main (yield) du thread en Lua)

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

aiLib.fadeIn(ms) -- à appeler dans un thread

ParamètresCopy Anchor Link

RetourCopy Anchor Link

Promise<void> qui se résout quand l’écran est net, ou au plus tard après ms + 2 secondes. Elle n’est jamais rejetée.

ExempleCopy Anchor Link

Voir fadeOut : les deux s’utilisent toujours ensemble.

playerPedCopy Anchor Link

Le ped d’un joueur d’après son id serveur. Pour le joueur local, il renvoie cache.ped ; pour un autre joueur, il renvoie 0 quand ce joueur n’est pas assez proche pour être streamé vers ce client.

Côté : client · Attend : non

playerPed(serverId: number): number

local ped = aiLib.playerPed(serverId)

ParamètresCopy Anchor Link

RetourCopy Anchor Link

number : le handle du ped, ou 0 quand le joueur n’est pas à portée sur ce client.

ExempleCopy Anchor Link

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

// Le serveur prévient tous ceux qui sont proches qu’un joueur a été menotté.
onServerEvent(
  "myscript:cuffed",
  { args: ([id]) => (typeof id === "number" ? [id] : null) },
  (id) => {
    const ped = playerPed(id);
    if (ped !== 0) SetEnableHandcuffs(ped, true);
  },
);

nearestPlayerCopy Anchor Link

L’autre joueur le plus proche dans un rayon donné, sous forme d’id serveur. Ne parcourt que les joueurs streamés vers ce client. Utilisez-le pour choisir la cible des actions donner, fouiller, menotter ou plaquer, puis envoyez cet id au serveur, qui vérifie à nouveau la distance.

Côté : client · Attend : non

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

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

ParamètresCopy Anchor Link

OptionsCopy Anchor Link

RetourCopy Anchor Link

number | null : l’id serveur du joueur le plus proche ayant passé filter, ou null (nil en Lua) quand personne n’est dans le rayon metres. Le joueur local n’est jamais renvoyé.

ExempleCopy 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,
);