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 hast | Was zu tun ist |
|---|---|
| Ein Script für ESX, QBCore, Qbox oder vRP | Nichts. 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
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
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:
ensure ai-core
ensure ai-lib
ensure my-resourceRufe 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 brauchst | Lua | TypeScript | Referenz |
|---|---|---|---|
| Items geben, nehmen, zählen | aiLib.inventory.addItem | inventory.addItem | Items, ai-core Items |
| Ein benutzbares Item | aiLib.inventory.registerUsableItem | inventory.registerUsableItem | registerUsableItem |
| Ein Lager oder ein Shop | aiLib.inventory.registerStash | inventory.registerStash | Items |
| Fahrzeugschlüssel | aiLib.vehicleKeys.give / .has | vehicleKeys.give / .has | Fahrzeuge |
| Ein Fahrzeug spawnen (Kennzeichen, Tank, Aussehen, Schlüssel, Sitze in einem Aufruf) | aiLib.spawnVehicle | spawnVehicle | spawnVehicle |
| Ein Fahrzeug einparken oder abschleppen | aiLib.garages.store | garages.store | garages.store |
| Geld eines Spielers | exports['ai-core']:AddMoney(src, 'cash', 50, 'reason') | core.AddMoney(...) | Geld |
| Geld zwischen zwei Konten, in einer Transaktion | aiLib.money.transfer | money.transfer | money.transfer |
| Jobs, Gangs, Dienst | exports['ai-core']:SetJob(src, 'police', 2) | core.SetJob(...) | Jobs und Gangs |
| Wer online ist, Name, Job | aiLib.online.name | online.name | Spieler |
| Ein Polizeialarm | aiLib.dispatch.alert | dispatch.alert | dispatch.alert |
| Gefängnis | aiLib.prison.jail | prison.jail | prison.jail |
| Ein MDT-Eintrag | aiLib.mdt.record | mdt.record | mdt.record |
| Beleben, heilen, "ist tot" | aiLib.medical.revive | medical.revive | medical.revive |
| Das Handy (Nummer, Mail, Nachricht, Benachrichtigung) | aiLib.phone.number | phone.number | Handy |
| Ein Aussehen, ein Outfit | aiLib.appearance.apply | appearance.apply | appearance.apply |
| Wetter und Zeit | aiLib.world.setWeather | world.setWeather | Welt |
| Eine Tür schließen | aiLib.doors.setLocked | doors.setLocked | doors.setLocked |
| Benachrichtigungen, Fortschrittsbalken, Menüs, Eingabedialoge | aiLib.notify, aiLib.progress, aiLib.menu.show | notify, progress, menu | Gemeinsame UI |
| Ein Eintrag im Radialmenü | aiLib.radial.add | radial.add | radial.add |
| Ein Befehl (im Adminpanel gelistet, ACE geprüft) | aiLib.addCommand | addCommand | addCommand |
| Eine Logzeile in den Kanälen des Besitzers | aiLib.aiLog | aiLog | aiLog |
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
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.
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:
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:
add_convar_permission my-resource read mysql_connection_stringSiehe 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 derdata/*.jsoneines 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).
API-Referenz
Jeder Export, jedes Event und jede Lib-Funktion mit Signatur, Parametern und Rückgabe.
Lib für Lua
aiLib: Setup, die Aufrufe die warten, Lua-Tabellen und Vektoren über die Resource-Grenze.
Layer und die Bridge
Welches Script jeden Layer antwortet, und wie die ESX / QB / Qbox Bridge arbeitet.
Empfohlene Scripts
Ein kostenloses Script im Panel listen lassen und den Adapter für seinen Layer schreiben.