El jugador local

Todo sobre el jugador sentado frente a este ordenador. Lee los valores de cache en lugar de llamar a PlayerPedId() en bucles: ai-core mantiene un único observador para todos los recursos y envía los cambios, así que ningún script los sondea.

cacheCopy Anchor Link

Los valores más leídos del jugador local, mantenidos al día por el único observador de ai-core. Como el cache de ox_lib: lee cache.ped en lugar de llamar a PlayerPedId(), y cache.vehicle en lugar de GetVehiclePedIsIn en cada frame. Leer una clave es una simple lectura en memoria, segura en bucles y en código por frame.

Lado: Cliente · Espera: no

const cache: PlayerCache // solo lectura

local ped = aiLib.cache.ped

ClavesCopy Anchor Link

El tipo es PlayerCache.

EjemploCopy Anchor Link

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

// Velocidad mostrada mientras conduce, leída de la caché 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

Ejecuta un handler cada vez que cambia un valor en caché: el jugador se subió o bajó de un vehículo, cambió de asiento, sacó o guardó un arma, o recibió un ped nuevo. Úsalo en lugar de comprobar el valor con un temporizador.

Lado: Cliente · Espera: no

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

DevuelveCopy Anchor Link

void. No hay forma de quitar el handler; mantén uno por funcionalidad al principio del archivo.

EjemploCopy Anchor Link

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

const points = new Points();

// Los puntos cuyo canShow lee cache.vehicle se comprueban de nuevo.
onCache("vehicle", () => points.refresh());

// El objeto de arma en la mano, leído solo cuando cambia el arma.
onCache("weapon", (weapon) => {
  const item = weapon === false ? null : inventory.currentWeapon();
  SendNUIMessage({ action: "weapon", data: item });
});

readPlayerStateCopy Anchor Link

Lee ahora mismo el vehículo, el asiento y el arma de un ped, sin la caché. El observador de ai-core lo usa; solo lo necesitas para un ped que no es el local, o para comparar con la caché a mano.

Lado: Cliente · Espera: no

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

Sin equivalente en Lua.

ParámetrosCopy Anchor Link

DevuelveCopy Anchor Link

Un objeto con vehicle (el handle del vehículo, false a pie), seat (-1 conductor y siguientes, false a pie) y weapon (el hash en la mano, false cuando va desarmado).

EjemploCopy 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

El arma en la mano de un ped ahora mismo, false cuando va desarmado.

Lado: Cliente · Espera: no

readWeapon(ped: number): number | false

Sin equivalente en Lua.

ParámetrosCopy Anchor Link

DevuelveCopy Anchor Link

number | false: el hash del arma, o false cuando el ped tiene WEAPON_UNARMED.

EjemploCopy 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 objeto para el ped local: dónde está, moverlo, animaciones. Las lecturas usan cache.ped; las acciones leen el ped al momento, así que también funcionan justo después de un cambio de modelo.

player.pedCopy Anchor Link

El handle del ped local (el mismo valor que cache.ped).

Lado: Cliente · Espera: no

player.ped: number // propiedad de solo lectura

Sin equivalente en Lua: usa aiLib.cache.ped.

DevuelveCopy Anchor Link

number: el handle del ped.

EjemploCopy Anchor Link

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

SetPedArmour(player.ped, 100);

player.coordsCopy Anchor Link

La posición actual del ped.

Lado: Cliente · Espera: no

player.coords(): Vec3

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

DevuelveCopy Anchor Link

Un Vec3 { x, y, z } en TypeScript (z es la raíz del ped, aproximadamente 1 m por encima del suelo). Lua devuelve un vector3.

EjemploCopy 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 dirección hacia la que mira el ped, en grados (0-360, 0 = norte).

Lado: Cliente · Espera: no

player.heading(): number

local heading = aiLib.player.heading()

DevuelveCopy Anchor Link

number: el heading en grados.

EjemploCopy Anchor Link

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

// Guarda el sitio y la dirección para un registro del panel.
const spot = { ...player.coords(), heading: player.heading() };

player.distanceToCopy Anchor Link

Distancia en línea recta del ped a un punto, en metros.

Lado: Cliente · Espera: no

player.distanceTo(point: Vec3): number

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

ParámetrosCopy Anchor Link

DevuelveCopy Anchor Link

number: metros, medidos en 3D.

EjemploCopy 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 el ped en el sitio, o le deja moverse de nuevo.

Lado: Cliente · Espera: no

player.freeze(state: boolean): void

aiLib.player.freeze(frozen)

ParámetrosCopy Anchor Link

DevuelveCopy Anchor Link

void.

EjemploCopy Anchor Link

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

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

player.teleportCopy Anchor Link

Mueve al jugador y espera hasta que el mundo alrededor del nuevo sitio se ha cargado, tras un fundido a negro. Sin z (o con ground: "find"), busca el suelo bajo x e y: úsalo para el waypoint del mapa.

Lado: Cliente · Espera: sí (Promise en TypeScript, cede el hilo en Lua)

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

aiLib.player.teleport(to, options) -- llamar dentro de un hilo

ParámetrosCopy Anchor Link

TeleportOptionsCopy Anchor Link

DevuelveCopy Anchor Link

Promise<void> que se resuelve en cuanto el jugador está en el nuevo sitio y la colisión de ahí se ha cargado (o tras 5 segundos sin ella). Lua no devuelve nada.

EjemploCopy 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 }); // sin z: aterriza en el suelo
  },
  false,
);

player.playAnimCopy Anchor Link

Reproduce una animación en el ped. Primero carga el diccionario de animaciones.

Lado: Cliente · Espera: sí en TypeScript (se resuelve cuando empezó la animación); en Lua cede mientras carga el diccionario

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

aiLib.player.playAnim(dict, clip, options) -- llamar dentro de un hilo

ParámetrosCopy Anchor Link

AnimOptionsCopy Anchor Link

DevuelveCopy Anchor Link

Promise<void> que se resuelve cuando empezó la animación. Se rechaza cuando el diccionario no existe o no carga en 10 segundos. Lua no devuelve nada y no hace nada cuando el diccionario no carga.

EjemploCopy 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

Detiene lo que esté haciendo el ped (ClearPedTasks): animaciones y escenarios.

Lado: Cliente · Espera: no

player.stopAnim(): void

aiLib.player.stopAnim()

DevuelveCopy Anchor Link

void.

EjemploCopy 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

Mantiene una animación en reproducción hasta que la detienes, y la vuelve a poner cuando una caída o un golpe la interrumpe. Documentado con los props en Peds, blips y props.

Fundidos y otros jugadoresCopy Anchor Link

fadeOutCopy Anchor Link

Funde la pantalla a negro y espera hasta que está completamente negra. Úsalo para ocultar un teletransporte, un cambio de modelo o un cambio de escena.

Lado: Cliente · Espera: sí (Promise en TypeScript, cede el hilo en Lua)

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

aiLib.fadeOut(ms) -- llamar dentro de un hilo

ParámetrosCopy Anchor Link

DevuelveCopy Anchor Link

Promise<void> que se resuelve cuando la pantalla está negra, o como muy tarde tras ms + 2 segundos. Nunca se rechaza.

EjemploCopy 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

Vuelve a mostrar la pantalla con un fundido y espera hasta que se ve con claridad. La pareja de fadeOut.

Lado: Cliente · Espera: sí (Promise en TypeScript, cede el hilo en Lua)

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

aiLib.fadeIn(ms) -- llamar dentro de un hilo

ParámetrosCopy Anchor Link

DevuelveCopy Anchor Link

Promise<void> que se resuelve cuando la pantalla se ve con claridad, o como muy tarde tras ms + 2 segundos. Nunca se rechaza.

EjemploCopy Anchor Link

Consulta fadeOut: los dos se usan siempre juntos.

playerPedCopy Anchor Link

El ped de un jugador por id de servidor. Para el jugador local devuelve cache.ped; para otro jugador devuelve 0 cuando ese jugador no está lo bastante cerca como para transmitirse a este cliente.

Lado: Cliente · Espera: no

playerPed(serverId: number): number

local ped = aiLib.playerPed(serverId)

ParámetrosCopy Anchor Link

DevuelveCopy Anchor Link

number: el handle del ped, o 0 cuando el jugador no está en el alcance de este cliente.

EjemploCopy Anchor Link

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

// El servidor avisa a todos los cercanos de que esposaron a un jugador.
onServerEvent(
  "myscript:cuffed",
  { args: ([id]) => (typeof id === "number" ? [id] : null) },
  (id) => {
    const ped = playerPed(id);
    if (ped !== 0) SetEnableHandcuffs(ped, true);
  },
);

nearestPlayerCopy Anchor Link

El otro jugador más cercano dentro de una distancia, como id de servidor. Recorre solo los jugadores transmitidos a este cliente. Úsalo para elegir el objetivo de las acciones de dar, registrar, esposar o placar, y luego envía ese id al servidor, que comprueba de nuevo la distancia.

Lado: Cliente · Espera: no

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

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

ParámetrosCopy Anchor Link

OpcionesCopy Anchor Link

DevuelveCopy Anchor Link

number | null: el id de servidor del jugador más cercano que pasó filter, o null (nil en Lua) cuando no hay nadie a menos de metres. Nunca se devuelve el jugador local.

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