AI Core

Intégrer votre propre script

Comment votre resource fonctionne avec AI Core - charger la lib, appeler les couches au lieu des autres scripts, ce qu'il ne faut jamais toucher, et la liste à vérifier avant publication.

Votre script n'a pas besoin d'être un script ai-* pour fonctionner avec AI Core. Ce que vous avez à faire dépend de ce que vous écrivez :

Ce que vous avezCe qu'il faut faire
Un script écrit pour ESX, QBCore, Qbox ou vRPRien. AI Core fournit es_extended, qb-core, qbx_core et vrp et répond à leur API, le script tourne sans modification. Voir Compatibilité.
Votre propre nouvelle resource (Lua, TypeScript ou JavaScript simple)Charger la lib et appeler AI Core à travers elle. C'est le sujet de cette page.
Un script qui fournit quelque chose dont d'autres scripts ont besoin (un inventaire, un téléphone, un système de clés, un garage, un script de carburant...)La même chose, plus un adaptateur dans cette couche pour que le reste du serveur l'atteigne. Voir Scripts recommandés.

Le but en une phrase : tout ce que votre script partage avec un autre script passe par la lib ou par ai-core, jamais par les exports de cet autre script. Le propriétaire peut alors remplacer l'inventaire, le système de clés ou le téléphone, et votre script continue de fonctionner.

Charger la lib

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> est ensuite disponible dans tous les fichiers de votre resource. L'installation complète, les appels qui attendent, et le passage des tables et vecteurs Lua vers TypeScript : La lib pour Lua.

TypeScript

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

@aifivem/lib vient de npm : une resource hors du workspace AI Core l'installe avec bun install @aifivem/lib @aifivem/shared. Une resource JavaScript simple, sans étape de build, charge @ai-lib/dist/server.js et utilise le même aiLib global.

Ordre de démarrage

ai-core et ai-lib démarrent avant votre resource :

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

Appelez AI Core, pas l'autre script

Chaque tâche partagée a une seule porte. L'appel de la lib et l'export d'ai-core font la même chose ; prenez celui qui correspond à votre langage.

Ce dont vous avez besoinLuaTypeScriptRéférence
Donner, retirer, compter des objetsaiLib.inventory.addIteminventory.addItemObjets, objets ai-core
Un objet utilisableaiLib.inventory.registerUsableIteminventory.registerUsableItemregisterUsableItem
Une réserve ou une boutiqueaiLib.inventory.registerStashinventory.registerStashObjets
Clés de véhiculeaiLib.vehicleKeys.give / .hasvehicleKeys.give / .hasVéhicules
Faire apparaître un véhicule (plaque, carburant, apparence, clés, sièges en un appel)aiLib.spawnVehiclespawnVehiclespawnVehicle
Garer ou mettre en fourrièreaiLib.garages.storegarages.storegarages.store
L'argent d'un joueurexports['ai-core']:AddMoney(src, 'cash', 50, 'reason')core.AddMoney(...)Argent
De l'argent entre deux comptes, en une transactionaiLib.money.transfermoney.transfermoney.transfer
Métiers, gangs, serviceexports['ai-core']:SetJob(src, 'police', 2)core.SetJob(...)Métiers et gangs
Qui est en ligne, son nom, son métieraiLib.online.nameonline.nameJoueurs
Une alerte policeaiLib.dispatch.alertdispatch.alertdispatch.alert
La prisonaiLib.prison.jailprison.jailprison.jail
Une fiche MDTaiLib.mdt.recordmdt.recordmdt.record
Réanimer, soigner, "est mort"aiLib.medical.revivemedical.revivemedical.revive
Le téléphone (numéro, mail, message, notification)aiLib.phone.numberphone.numberTéléphone
Une apparence, une tenueaiLib.appearance.applyappearance.applyappearance.apply
Météo et heureaiLib.world.setWeatherworld.setWeatherMonde
Verrouiller une porteaiLib.doors.setLockeddoors.setLockeddoors.setLocked
Notifications, barres de progression, menus, dialogues de saisieaiLib.notify, aiLib.progress, aiLib.menu.shownotify, progress, menuInterface commune
Une entrée du menu radialaiLib.radial.addradial.addradial.add
Une commande (listée dans le panneau admin, vérifiée par ACE)aiLib.addCommandaddCommandaddCommand
Une ligne de log dans les canaux du propriétaireaiLib.aiLogaiLogaiLog

Quel script répond à chacun de ces points sur ce serveur, et la liste des adaptateurs : Couches et le bridge. Chaque fonction avec sa signature, ses paramètres et son retour : Référence API.

N'interrogez jamais les tables d'AI Core. ai_core_characters, ai_core_accounts, ai_core_character_jobs, ai_vehicles_owned et les autres tables ai_* sont internes : les personnages, l'argent, les métiers et les véhicules vivent en mémoire et sont écrits selon le calendrier d'ai-core ; un SELECT direct peut donc être périmé, et une colonne peut changer à n'importe quelle version. Demandez à ai-core à la place - il répond aussi bien pour un joueur chargé que pour un personnage stocké (personnages, argent, métiers). Idem pour les fichiers de données d'un autre script ai-* (data/*.json de son panneau admin) : c'est le contenu du panneau, pas une interface.

Un citizenid n'est pas un id de personnage. Deux ids existent : l'id du personnage (charId, un nombre) et le citizenid (texte) que les scripts des autres frameworks utilisent. Ne convertissez jamais l'un en l'autre vous-même - demandez à ai-core (GetCharIdByCitizenId, GetSourceByCitizenId, GetSourceByCharId) : Personnages.

Détecter AI Core

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

En TypeScript la lib le fait pour vous : isResourceStarted("ai-core"), ou optionalExport("ai-core"), qui vaut null tant que la resource est arrêtée (exports).

Un script qui gère plusieurs frameworks trouve aussi qbx_core, qb-core et es_extended démarrés, parce qu'ai-core les fournit. Ce chemin fonctionne, mais il n'atteint que ce que ces API savent dire. Vérifiez ai-core avant les noms de frameworks et prenez le chemin AI Core quand il est là ; gardez le code framework comme repli pour les autres serveurs.

Les règles sur lesquelles votre script est jugé

Ce sont les règles que suit chaque script ai-* (Vue d'ensemble), et ce qu'une relecture regarde :

Le serveur décide

Chaque requête client passe par la porte de la lib : une limite de débit, un appel à la fois (lock), une vérification ACE, et en TypeScript aussi des gardes (admin, a un personnage, près d'un point) et un analyseur d'arguments. L'argent, les objets et les droits ne changent jamais sur le client, et une valeur du client n'est jamais utilisée telle quelle - en Lua, vous vérifiez chaque argument vous-même.

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
    -- prendre l'argent et donner l'objet ici, sur le serveur
    return { ok = true }
end, { rate = { count = 5, windowMs = 10000 }, lock = true })

Entrées client, les lecteurs stricts de TypeScript (readText, oneArg) et les refus (fail, ActionResult).

Snapshot, puis deltas

Les données vivantes partent une fois en entier vers un client, ensuite seulement ce qui a changé, et seulement aux joueurs concernés. Pas d'interrogation répétée, pas de signal "quelque chose a changé, recharge", pas de trafic à chaque tick. Des state bags pour les valeurs par entité et par joueur, AreaStream pour les objets du monde, les state bags pour le reste.

Les réglages dans le panneau admin

Un propriétaire de serveur ne devrait pas éditer du Lua. L'écran de réglages de votre script obtient une carte sur le tableau de bord du panneau d'ai-core en un appel, pour que le propriétaire trouve les réglages de tous les scripts au même endroit :

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

Un script que vous ne pouvez pas modifier est listé à la place par les lignes ai_admin_label / ai_admin_command de son fxmanifest.lua : RegisterExternalPanel. Les commandes enregistrées avec aiLib.addCommand et les touches créées avec aiLib.Keybind apparaissent d'elles-mêmes dans les listes de commandes et de touches du panneau.

Vos données sont à vous

Les tables de votre propre resource sont votre affaire : nommez-les d'après votre resource (myscript_*) et créez-les au démarrage. Les resources Lua utilisent ai-mysql, qui remplace oxmysql, mysql-async et ghmattimysql (MySQL.query.await, MySQL.single.await), vos requêtes existantes continuent donc de fonctionner. Une resource qui lit elle-même la chaîne de connexion a aussi besoin d'une ligne dans env.cfg :

env.cfg
add_convar_permission my-resource read mysql_connection_string

Voir La base de données.

Avant de publier

  • ai-lib (ou @aifivem/lib) chargé, dependency 'ai-lib' dans le manifest.
  • Aucun export d'un autre script pour les objets, les clés, l'argent, les métiers, le téléphone, les alertes, les vêtements, le carburant, les portes, les garages ou la prison.
  • Aucune requête sur une table ai_* d'AI Core, et aucune lecture du data/*.json d'un autre script.
  • Chaque requête client limitée en débit et vérifiée sur le serveur.
  • Données vivantes en snapshot et deltas.
  • Réglages dans le panneau, textes dans vos propres fichiers de langue (locale).
  • Testé avec les scripts ai-* que la fonctionnalité touche, et, quand une couche est en jeu, avec le choix du serveur remplacé (un autre inventaire, un autre système de clés).

Sur cette page