AI Core
API-ReferenzLib: Client

Der lokale Spieler

Der gecachte Ped, Fahrzeug, Sitz und Waffe, das player-Objekt (Position, Teleport, Animationen), Bildschirm-Überblendungen, die Peds anderer Spieler und der nächstgelegene Spieler.

Alles über den Spieler, der an diesem Computer sitzt. Lies Werte aus cache, statt PlayerPedId() in Schleifen aufzurufen: ai-core hält einen Watcher für jede Ressource und schickt Änderungen, daher fragt kein Skript sie ab.

cache

Die meistgelesenen Werte des lokalen Spielers, aktuell gehalten von dem einen Watcher von ai-core. Wie cache von ox_lib: Lies cache.ped, statt PlayerPedId() aufzurufen, und cache.vehicle, statt in jedem Frame GetVehiclePedIsIn. Einen Schlüssel zu lesen ist ein einfacher Speicherzugriff, sicher in Schleifen und Code pro Frame.

Seite: Client · Wartet: nein

Signatur
const cache: PlayerCache // nur lesen
Lua
local ped = aiLib.cache.ped

Schlüssel

Prop

Type

Der Typ ist PlayerCache.

Beispiel

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

// Geschwindigkeit beim Fahren, alle 200 ms aus dem Cache gelesen.
every(200, () => {
  if (cache.vehicle === false || cache.seat !== -1) return;
  const kmh = GetEntitySpeed(cache.vehicle) * 3.6;
  SendNUIMessage({ action: "speed", data: Math.round(kmh) });
});

cache.ped hinkt einem Modellwechsel bis zu 100 ms hinterher. Direkt nachdem du das Modell geändert hast (SetPlayerModel), rufe einmal PlayerPedId() auf. Die player-Aktionen unten lesen den Ped bereits frisch.

onCache

Führt einen Handler aus, sobald sich ein gecachter Wert ändert: Der Spieler ist in ein Fahrzeug ein- oder ausgestiegen, hat den Sitz gewechselt, eine Waffe gezogen oder weggesteckt oder einen neuen Ped bekommen. Nutze es, statt den Wert per Timer zu prüfen.

Seite: Client · Wartet: nein

Signatur
onCache<K extends keyof PlayerCache>(key: K, handler: (value: PlayerCache[K], old: PlayerCache[K]) => void): void
Lua
aiLib.cache.onChange(key, function(value, old) end)

Parameter

Prop

Type

Rückgabewert

void. Es gibt keine Möglichkeit, den Handler zu entfernen; halte einen pro Feature am Anfang der Datei.

Beispiel

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

const points = new Points();

// Punkte, deren canShow cache.vehicle liest, werden erneut geprüft.
onCache("vehicle", () => points.refresh());

// Das Waffen-Item in der Hand, nur gelesen, wenn sich die Waffe ändert.
onCache("weapon", (weapon) => {
  const item = weapon === false ? null : inventory.currentWeapon();
  SendNUIMessage({ action: "weapon", data: item });
});

readPlayerState

Liest Fahrzeug, Sitz und Waffe eines Peds genau jetzt, ohne den Cache. Der Watcher von ai-core nutzt es; du brauchst es nur für einen Ped, der nicht der lokale ist, oder um von Hand mit dem Cache zu vergleichen.

Seite: Client · Wartet: nein

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

Kein Lua-Zwilling.

Parameter

Prop

Type

Rückgabewert

Ein Objekt mit vehicle (das Fahrzeug-Handle, false zu Fuß), seat (-1 Fahrer und aufwärts, false zu Fuß) und weapon (der Hash in der Hand, false, wenn unbewaffnet).

Beispiel

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

readWeapon

Die Waffe in der Hand eines Peds genau jetzt, false, wenn unbewaffnet.

Seite: Client · Wartet: nein

Signatur
readWeapon(ped: number): number | false

Kein Lua-Zwilling.

Parameter

Prop

Type

Rückgabewert

number | false: der Waffen-Hash, oder false, wenn der Ped WEAPON_UNARMED hält.

Beispiel

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

player

Ein Objekt für den lokalen Ped: wo er ist, ihn bewegen, Animationen. Lesezugriffe nutzen cache.ped; Aktionen lesen den Ped frisch, daher funktionieren sie auch direkt nach einem Modellwechsel.

player.ped

Das Handle des lokalen Peds (derselbe Wert wie cache.ped).

Seite: Client · Wartet: nein

Signatur
player.ped: number // schreibgeschützte Eigenschaft

Kein Lua-Zwilling: Nutze aiLib.cache.ped.

Rückgabewert

number: das Ped-Handle.

Beispiel

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

SetPedArmour(player.ped, 100);

player.coords

Die aktuelle Position des Peds.

Seite: Client · Wartet: nein

Signatur
player.coords(): Vec3
Lua
local coords = aiLib.player.coords() -- vector3

Rückgabewert

Ein Vec3 { x, y, z } in TypeScript (z ist der Ursprung des Peds, etwa 1 m über dem Boden). Lua gibt einen vector3 zurück.

Beispiel

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.heading

Die Richtung, in die der Ped schaut, in Grad (0-360, 0 = Norden).

Seite: Client · Wartet: nein

Signatur
player.heading(): number
Lua
local heading = aiLib.player.heading()

Rückgabewert

number: das Heading in Grad.

Beispiel

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

// Den Ort und die Richtung für einen Panel-Eintrag speichern.
const spot = { ...player.coords(), heading: player.heading() };

player.distanceTo

Gerade Entfernung vom Ped zu einem Punkt, in Metern.

Seite: Client · Wartet: nein

Signatur
player.distanceTo(point: Vec3): number
Lua
local metres = aiLib.player.distanceTo(point) -- vector3 oder { x, y, z }

Parameter

Prop

Type

Rückgabewert

number: Meter, gemessen in 3D.

Beispiel

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.freeze

Friert den Ped an Ort und Stelle ein oder lässt ihn sich wieder bewegen.

Seite: Client · Wartet: nein

Signatur
player.freeze(state: boolean): void
Lua
aiLib.player.freeze(frozen)

Parameter

Prop

Type

Rückgabewert

void.

Beispiel

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

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

player.teleport

Bewegt den Spieler und wartet hinter einer schwarzen Überblendung, bis die Welt um den neuen Ort geladen ist. Ohne z (oder mit ground: "find") sucht es den Boden unter x und y: Nutze das für den Kartenwegpunkt.

Seite: Client · Wartet: ja (Promise in TypeScript, hält in Lua den Thread an)

Signatur
player.teleport(to: { x: number; y: number; z?: number }, options?: TeleportOptions): Promise<void>
Lua
aiLib.player.teleport(to, options) -- innerhalb eines Threads aufrufen

Parameter

Prop

Type

TeleportOptions

Prop

Type

Rückgabewert

Promise<void>, das erfüllt wird, sobald der Spieler am neuen Ort steht und die Kollision dort geladen ist (oder nach 5 Sekunden ohne sie). Lua gibt nichts zurück.

Beispiel

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 }); // kein z: landet auf dem Boden
  },
  false,
);

Die TypeScript-Bodensuche stellt den eingefrorenen Ped auf steigende Höhen, wartet auf jeder auf die Kollision und überspringt Oberflächen in MLO- oder IPL-Interieurs, sodass er nie auf einem Dach oder in einem Gebäude über der Straße landet. Die Lua-Version nimmt den ersten Boden, den sie findet, und wartet höchstens 3 Sekunden auf die Kollision.

player.playAnim

Spielt eine Animation auf dem Ped ab. Es lädt zuerst das Animations-Dictionary.

Seite: Client · Wartet: ja in TypeScript (wird erfüllt, wenn die Animation gestartet ist); hält in Lua an, während das Dictionary lädt

Signatur
player.playAnim(dict: string, clip: string, options?: AnimOptions): Promise<void>
Lua
aiLib.player.playAnim(dict, clip, options) -- innerhalb eines Threads aufrufen

Parameter

Prop

Type

AnimOptions

Prop

Type

Rückgabewert

Promise<void>, das erfüllt wird, wenn die Animation gestartet ist. Es wird abgelehnt, wenn das Dictionary nicht existiert oder nicht innerhalb von 10 Sekunden lädt. Lua gibt nichts zurück und tut nichts, wenn das Dictionary nicht lädt.

Beispiel

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.stopAnim

Stoppt, was auch immer der Ped tut (ClearPedTasks): Animationen und Szenarien.

Seite: Client · Wartet: nein

Signatur
player.stopAnim(): void
Lua
aiLib.player.stopAnim()

Rückgabewert

void.

Beispiel

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.holdAnim

Hält eine Animation am Laufen, bis du sie stoppst, und nimmt sie wieder auf, wenn ein Sturz oder Stoß sie unterbricht. Dokumentiert bei den Props unter Peds, Blips und Props.

Überblendungen und andere Spieler

fadeOut

Blendet den Bildschirm schwarz aus und wartet, bis er ganz schwarz ist. Nutze es, um einen Teleport, einen Modellwechsel oder einen Szenenwechsel zu verbergen.

Seite: Client · Wartet: ja (Promise in TypeScript, hält in Lua den Thread an)

Signatur
fadeOut(ms?: number): Promise<void>
Lua
aiLib.fadeOut(ms) -- innerhalb eines Threads aufrufen

Parameter

Prop

Type

Rückgabewert

Promise<void>, das erfüllt wird, wenn der Bildschirm schwarz ist, oder spätestens nach ms + 2 Sekunden. Es wird nie abgelehnt.

Beispiel

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

fadeIn

Blendet den Bildschirm wieder ein und wartet, bis er klar ist. Das Gegenstück zu fadeOut.

Seite: Client · Wartet: ja (Promise in TypeScript, hält in Lua den Thread an)

Signatur
fadeIn(ms?: number): Promise<void>
Lua
aiLib.fadeIn(ms) -- innerhalb eines Threads aufrufen

Parameter

Prop

Type

Rückgabewert

Promise<void>, das erfüllt wird, wenn der Bildschirm klar ist, oder spätestens nach ms + 2 Sekunden. Es wird nie abgelehnt.

Beispiel

Siehe fadeOut: Die beiden werden immer zusammen genutzt.

playerPed

Der Ped eines Spielers nach Server-ID. Für den lokalen Spieler gibt es cache.ped zurück; für einen anderen Spieler 0, wenn dieser Spieler nicht nah genug ist, um zu diesem Client gestreamt zu werden.

Seite: Client · Wartet: nein

Signatur
playerPed(serverId: number): number
Lua
local ped = aiLib.playerPed(serverId)

Parameter

Prop

Type

Rückgabewert

number: das Ped-Handle, oder 0, wenn der Spieler auf diesem Client nicht in Reichweite ist.

Beispiel

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

// Der Server teilt allen in der Nähe mit, dass ein Spieler gefesselt wurde.
onServerEvent(
  "myscript:cuffed",
  { args: ([id]) => (typeof id === "number" ? [id] : null) },
  (id) => {
    const ped = playerPed(id);
    if (ped !== 0) SetEnableHandcuffs(ped, true);
  },
);

Nutze nie GetPlayerPed(-1) oder GetPlayerPed(GetPlayerFromServerId(id)) von Hand: Eine unbekannte ID ergibt -1, und GetPlayerPed(-1) ist der lokale Ped, sodass die Aktion den falschen Spieler trifft.

nearestPlayer

Der nächstgelegene andere Spieler innerhalb einer Entfernung, als Server-ID. Geht nur die Spieler durch, die zu diesem Client gestreamt werden. Nutze es, um das Ziel von Geben-, Durchsuchen-, Fesseln- oder Tackle-Aktionen zu wählen, und sende dann diese ID an den Server, der die Entfernung erneut prüft.

Seite: Client · Wartet: nein

Signatur
nearestPlayer(metres: number, options?: { from?: Vec3; filter?: (serverId: number, ped: number) => boolean }): number | null
Lua
local serverId = aiLib.nearestPlayer(metres, options) -- integer oder nil

Parameter

Prop

Type

Optionen

Prop

Type

Rückgabewert

number | null: die Server-ID des nächsten Spielers, der filter bestanden hat, oder null (nil in Lua), wenn niemand innerhalb von metres ist. Der lokale Spieler wird nie zurückgegeben.

Beispiel

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

Mit dem Server sprechen

Den Server fragen und auf seine Antwort warten, Server-Aktionen mit übersetzten Ablehnungen ausführen, auf Server-Events hören und Server-Callbacks beantworten.

Interaktionspunkte

Points - jeder Ort, den ein Spieler nutzt (Theken, Shops, Türen, NPCs, Geldautomaten, Kofferräume), als Prompt oder Target-Option, mit Peds, Blips und Punkten aus Panel-Einträgen.

Auf dieser Seite

cacheSchlüsselBeispielonCacheParameterRückgabewertBeispielreadPlayerStateParameterRückgabewertBeispielreadWeaponParameterRückgabewertBeispielplayerplayer.pedRückgabewertBeispielplayer.coordsRückgabewertBeispielplayer.headingRückgabewertBeispielplayer.distanceToParameterRückgabewertBeispielplayer.freezeParameterRückgabewertBeispielplayer.teleportParameterTeleportOptionsRückgabewertBeispielplayer.playAnimParameterAnimOptionsRückgabewertBeispielplayer.stopAnimRückgabewertBeispielplayer.holdAnimÜberblendungen und andere SpielerfadeOutParameterRückgabewertBeispielfadeInParameterRückgabewertBeispielplayerPedParameterRückgabewertBeispielnearestPlayerParameterOptionenRückgabewertBeispiel