AI Core

Dein eigenes Script einbinden

Wie deine eigene Resource mit AI Core arbeitet - die Lib laden, die Layer statt anderer Scripts aufrufen, was du nie anfassen darfst, und die Checkliste vor der Veröffentlichung.

Dein Script muss kein ai-* Script sein, um mit AI Core zu arbeiten. Was zu tun ist, hängt davon ab, was du schreibst:

Was du hastWas zu tun ist
Ein Script für ESX, QBCore, Qbox oder vRPNichts. AI Core stellt es_extended, qb-core, qbx_core und vrp bereit und antwortet auf deren API, das Script läuft unverändert. Siehe Kompatibilität.
Deine eigene neue Resource (Lua, TypeScript oder einfaches JavaScript)Die Lib laden und AI Core über sie aufrufen. Darum geht es auf dieser Seite.
Ein Script, das etwas bereitstellt, das andere Scripts brauchen (ein Inventar, ein Handy, ein Schlüsselsystem, eine Garage, ein Tank-Script...)Dasselbe wie oben, plus ein Adapter in diesem Layer, damit der Rest des Servers es erreicht. Siehe Empfohlene Scripts.

Das Ziel in einem Satz: alles, was dein Script mit einem anderen Script teilt, geht über die Lib oder ai-core, niemals über die Exports dieses Scripts. Der Besitzer kann dann das Inventar, das Schlüsselsystem oder das Handy austauschen, und dein Script läuft weiter.

Die Lib laden

Lua

fxmanifest.lua
fx_version 'cerulean'
game 'gta5'
lua54 'yes'

dependency 'ai-lib'
shared_script '@ai-lib/init.lua'

client_script 'client.lua'
server_script 'server.lua'

aiLib.<name> steht danach in jeder Datei deiner Resource bereit. Das ganze Setup, welche Aufrufe warten, und wie Lua-Tabellen und Vektoren nach TypeScript übergehen: Lib für Lua.

TypeScript

server.ts
import { inventory, onClientCallback } from "@aifivem/lib/server";

@aifivem/lib kommt von npm; eine Resource außerhalb des AI-Core-Workspace installiert sie mit bun install @aifivem/lib @aifivem/shared. Eine einfache JavaScript-Resource ohne Build-Schritt lädt @ai-lib/dist/server.js und nutzt dasselbe globale aiLib.

Startreihenfolge

ai-core und ai-lib starten vor deiner Resource:

server.cfg
ensure ai-core
ensure ai-lib
ensure my-resource

Rufe AI Core, nicht das andere Script

Jede gemeinsame Aufgabe hat eine Tür. Der Lib-Aufruf und der ai-core-Export machen dasselbe; nimm, was zu deiner Sprache passt.

Was du brauchstLuaTypeScriptReferenz
Items geben, nehmen, zählenaiLib.inventory.addIteminventory.addItemItems, ai-core Items
Ein benutzbares ItemaiLib.inventory.registerUsableIteminventory.registerUsableItemregisterUsableItem
Ein Lager oder ein ShopaiLib.inventory.registerStashinventory.registerStashItems
FahrzeugschlüsselaiLib.vehicleKeys.give / .hasvehicleKeys.give / .hasFahrzeuge
Ein Fahrzeug spawnen (Kennzeichen, Tank, Aussehen, Schlüssel, Sitze in einem Aufruf)aiLib.spawnVehiclespawnVehiclespawnVehicle
Ein Fahrzeug einparken oder abschleppenaiLib.garages.storegarages.storegarages.store
Geld eines Spielersexports['ai-core']:AddMoney(src, 'cash', 50, 'reason')core.AddMoney(...)Geld
Geld zwischen zwei Konten, in einer TransaktionaiLib.money.transfermoney.transfermoney.transfer
Jobs, Gangs, Dienstexports['ai-core']:SetJob(src, 'police', 2)core.SetJob(...)Jobs und Gangs
Wer online ist, Name, JobaiLib.online.nameonline.nameSpieler
Ein PolizeialarmaiLib.dispatch.alertdispatch.alertdispatch.alert
GefängnisaiLib.prison.jailprison.jailprison.jail
Ein MDT-EintragaiLib.mdt.recordmdt.recordmdt.record
Beleben, heilen, "ist tot"aiLib.medical.revivemedical.revivemedical.revive
Das Handy (Nummer, Mail, Nachricht, Benachrichtigung)aiLib.phone.numberphone.numberHandy
Ein Aussehen, ein OutfitaiLib.appearance.applyappearance.applyappearance.apply
Wetter und ZeitaiLib.world.setWeatherworld.setWeatherWelt
Eine Tür schließenaiLib.doors.setLockeddoors.setLockeddoors.setLocked
Benachrichtigungen, Fortschrittsbalken, Menüs, EingabedialogeaiLib.notify, aiLib.progress, aiLib.menu.shownotify, progress, menuGemeinsame UI
Ein Eintrag im RadialmenüaiLib.radial.addradial.addradial.add
Ein Befehl (im Adminpanel gelistet, ACE geprüft)aiLib.addCommandaddCommandaddCommand
Eine Logzeile in den Kanälen des BesitzersaiLib.aiLogaiLogaiLog

Welches Script davon auf diesem Server antwortet, und die Liste der Adapter: Layer und die Bridge. Jede Funktion mit Signatur, Parametern und Rückgabe: API-Referenz.

Frage niemals die Tabellen von AI Core ab. ai_core_characters, ai_core_accounts, ai_core_character_jobs, ai_vehicles_owned und die anderen ai_* Tabellen sind intern: Charaktere, Geld, Jobs und Fahrzeuge liegen im Speicher und werden nach ai-cores eigenem Plan geschrieben, ein direktes SELECT kann also veraltet sein, und eine Spalte kann sich in jedem Release ändern. Frage stattdessen ai-core - es antwortet für einen geladenen Spieler wie für einen gespeicherten Charakter (Charaktere, Geld, Jobs). Dasselbe gilt für die Datendateien eines anderen ai-* Scripts (data/*.json seines Adminpanels): sie sind der Inhalt des Panels, keine Schnittstelle.

Eine citizenid ist keine Charakter-ID. Es gibt zwei IDs: die Charakter-ID (charId, eine Zahl) und die citizenid (Text), die Scripts anderer Frameworks nutzen. Rechne die eine nie selbst in die andere um - frage ai-core (GetCharIdByCitizenId, GetSourceByCitizenId, GetSourceByCharId): Charaktere.

AI Core erkennen

Lua
local onAiCore = GetResourceState('ai-core') == 'started'

In TypeScript macht es die Lib für dich: isResourceStarted("ai-core"), oder optionalExport("ai-core"), das null ist, solange die Resource gestoppt ist (Exports).

Ein Script, das mehrere Frameworks unterstützt, findet auch qbx_core, qb-core und es_extended gestartet, weil ai-core sie bereitstellt. Dieser Weg funktioniert, erreicht aber nur, was diese APIs sagen können. Prüfe ai-core vor den Framework-Namen und nimm den AI-Core-Weg, wenn er da ist; behalte den Framework-Code als Rückfall für andere Server.

Die Regeln, an denen dein Script gemessen wird

Es sind dieselben Regeln, denen jedes ai-* Script folgt (Überblick), und worauf ein Review schaut:

Der Server entscheidet

Jede Client-Anfrage geht durch das Tor der Lib: ein Ratenlimit, ein Aufruf zur Zeit (lock), eine ACE-Prüfung, und in TypeScript zusätzlich Guards (Admin, hat einen Charakter, nahe an einem Punkt) und ein Argument-Parser. Geld, Items und Rechte ändern sich nie auf dem Client, und ein Client-Wert wird nie so genutzt, wie er ankommt - in Lua prüfst du jedes Argument selbst.

server.lua
aiLib.onClientCallback('myshop:buy', function(source, item)
    if type(item) ~= 'string' or #item > 32 then return aiLib.fail('CORE_ERR_ARGS') end
    if not aiLib.inventory.canCarryItem(source, item, 1) then return aiLib.fail('INVENTORY_FULL') end
    -- hier, auf dem Server, das Geld nehmen und das Item geben
    return { ok = true }
end, { rate = { count = 5, windowMs = 10000 }, lock = true })

Client-Eingaben, die strengen Leser von TypeScript (readText, oneArg) und Ablehnungen (fail, ActionResult).

Snapshot, dann Deltas

Lebende Daten gehen einmal vollständig an einen Client, danach nur noch das Geänderte, und nur an die Spieler, die es brauchen. Kein Polling, kein "etwas hat sich geändert, hol es neu" Signal, kein Verkehr pro Tick. State Bags für Werte pro Entity und pro Spieler, AreaStream für Weltobjekte, State Bags für den Rest.

Einstellungen im Adminpanel

Ein Serverbesitzer sollte kein Lua bearbeiten. Der eigene Einstellungsbildschirm deines Scripts bekommt mit einem Aufruf eine Karte auf dem Dashboard des ai-core-Panels, damit der Besitzer die Einstellungen aller Scripts an einem Ort findet:

server.lua
exports['ai-core']:RegisterExternalPanel({
    label = 'My script',
    icon = 'gear',
    description = 'Shops, prices and rewards',
    command = 'myscriptconfig',
})

Ein Script, das du nicht ändern kannst, wird stattdessen mit den Zeilen ai_admin_label / ai_admin_command in seiner fxmanifest.lua gelistet: RegisterExternalPanel. Mit aiLib.addCommand registrierte Befehle und mit aiLib.Keybind erstellte Tasten erscheinen von selbst in den Befehls- und Tastenlisten des Panels.

Deine eigenen Daten sind deine

Die Tabellen deiner eigenen Resource sind deine Sache: benenne sie nach deiner Resource (myscript_*) und erstelle sie beim Start. Lua-Resourcen nutzen ai-mysql, das für oxmysql, mysql-async und ghmattimysql einsteht (MySQL.query.await, MySQL.single.await), deine vorhandenen Queries laufen also weiter. Eine Resource, die den Connection String selbst liest, braucht zusätzlich eine Zeile in env.cfg:

env.cfg
add_convar_permission my-resource read mysql_connection_string

Siehe Die Datenbank.

Vor der Veröffentlichung

  • ai-lib (oder @aifivem/lib) geladen, dependency 'ai-lib' im Manifest.
  • Keine Exports eines anderen Scripts für Items, Schlüssel, Geld, Jobs, Handy, Alarme, Kleidung, Tank, Türen, Garagen oder Gefängnis.
  • Keine Query gegen eine ai_* Tabelle von AI Core, und kein Lesen der data/*.json eines anderen Scripts.
  • Jede Client-Anfrage mit Ratenlimit und auf dem Server geprüft.
  • Lebende Daten als Snapshot und Deltas.
  • Einstellungen im Panel, Texte in deinen eigenen Sprachdateien (locale).
  • Getestet mit den ai-* Scripts, die die Funktion berührt, und bei einem Layer auch mit getauschter Wahl des Servers (ein anderes Inventar, ein anderes Schlüsselsystem).

Auf dieser Seite