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 avez | Ce qu'il faut faire |
|---|---|
| Un script écrit pour ESX, QBCore, Qbox ou vRP | Rien. 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
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
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 :
ensure ai-core
ensure ai-lib
ensure my-resourceAppelez 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 besoin | Lua | TypeScript | Référence |
|---|---|---|---|
| Donner, retirer, compter des objets | aiLib.inventory.addItem | inventory.addItem | Objets, objets ai-core |
| Un objet utilisable | aiLib.inventory.registerUsableItem | inventory.registerUsableItem | registerUsableItem |
| Une réserve ou une boutique | aiLib.inventory.registerStash | inventory.registerStash | Objets |
| Clés de véhicule | aiLib.vehicleKeys.give / .has | vehicleKeys.give / .has | Véhicules |
| Faire apparaître un véhicule (plaque, carburant, apparence, clés, sièges en un appel) | aiLib.spawnVehicle | spawnVehicle | spawnVehicle |
| Garer ou mettre en fourrière | aiLib.garages.store | garages.store | garages.store |
| L'argent d'un joueur | exports['ai-core']:AddMoney(src, 'cash', 50, 'reason') | core.AddMoney(...) | Argent |
| De l'argent entre deux comptes, en une transaction | aiLib.money.transfer | money.transfer | money.transfer |
| Métiers, gangs, service | exports['ai-core']:SetJob(src, 'police', 2) | core.SetJob(...) | Métiers et gangs |
| Qui est en ligne, son nom, son métier | aiLib.online.name | online.name | Joueurs |
| Une alerte police | aiLib.dispatch.alert | dispatch.alert | dispatch.alert |
| La prison | aiLib.prison.jail | prison.jail | prison.jail |
| Une fiche MDT | aiLib.mdt.record | mdt.record | mdt.record |
| Réanimer, soigner, "est mort" | aiLib.medical.revive | medical.revive | medical.revive |
| Le téléphone (numéro, mail, message, notification) | aiLib.phone.number | phone.number | Téléphone |
| Une apparence, une tenue | aiLib.appearance.apply | appearance.apply | appearance.apply |
| Météo et heure | aiLib.world.setWeather | world.setWeather | Monde |
| Verrouiller une porte | aiLib.doors.setLocked | doors.setLocked | doors.setLocked |
| Notifications, barres de progression, menus, dialogues de saisie | aiLib.notify, aiLib.progress, aiLib.menu.show | notify, progress, menu | Interface commune |
| Une entrée du menu radial | aiLib.radial.add | radial.add | radial.add |
| Une commande (listée dans le panneau admin, vérifiée par ACE) | aiLib.addCommand | addCommand | addCommand |
| Une ligne de log dans les canaux du propriétaire | aiLib.aiLog | aiLog | aiLog |
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
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.
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 :
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 :
add_convar_permission my-resource read mysql_connection_stringVoir 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 dudata/*.jsond'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).
Référence API
Chaque export, événement et fonction de la lib avec sa signature, ses paramètres et son retour.
La lib pour Lua
aiLib : installation, les appels qui attendent, tables et vecteurs Lua à travers la frontière des resources.
Couches et le bridge
Quel script répond à chaque couche, et comment fonctionne le bridge ESX / QB / Qbox.
Scripts recommandés
Faire lister un script gratuit dans le panneau et écrire l'adaptateur de sa couche.