AI Core
Référence de l’APILib : serveur

Objets

inventory : donner, retirer et compter des objets, coffres, boutiques et objets utilisables, quel que soit l’inventaire que fait tourner le serveur.

TypeScript
import { inventory } from "@aicore-fivem/lib/server";

inventory fait passer chaque appel d’objet par la couche d’inventaire d’ai-core : c’est l’inventaire que fait tourner le serveur (ai-inventory, ou un autre que le propriétaire choisit dans le panneau d’ai-core) qui répond. Votre script n’appelle jamais les exports propres à un inventaire, il continue donc de fonctionner quand le propriétaire change d’inventaire.

L’argument d’inventaire (inv, type InventoryRef) est l’id serveur d’un joueur (un nombre) ou l’id d’un autre inventaire (une chaîne : un nom de coffre, une plaque).

Les quantités sont des nombres entiers de 1 ou plus ; une fraction est arrondie à l’inférieur, une quantité de 0 ou négative fait échouer l’appel.

Tant qu’aucun inventaire ne tourne, les appels échouent silencieusement : false, 0, une liste vide ou null. Les équivalents Lua sur aiLib.inventory ont les mêmes noms et le même ordre d’arguments.

inventory.addItem

Donne des objets à un inventaire.

Côté : serveur · Attend : non

Signature
inventory.addItem(inv: InventoryRef, item: string, count?: number, metadata?: ItemMetadata, slot?: number): boolean
Lua
local ok = aiLib.inventory.addItem(inv, item, count, metadata, slot)

Paramètres

Prop

Type

Retour

boolean : true quand ils ont été donnés. false quand ils ne rentrent pas, que l’objet n’existe pas, qu’un argument est incorrect ou qu’aucun inventaire ne tourne.

Exemple

import { inventory } from "@aicore-fivem/lib/server";
import { fail } from "@aicore-fivem/lib/shared";

if (!inventory.addItem(source, "phone", 1, { number: "555-0101" })) return fail("INVENTORY_FULL");

Vérifiez d’abord canCarryItem quand vous prenez quelque chose en échange (de l’argent, un autre objet) : prenez-le seulement après que addItem a répondu true, ou rendez-le.

inventory.removeItem

Retire des objets d’un inventaire.

Côté : serveur · Attend : non

Signature
inventory.removeItem(inv: InventoryRef, item: string, count?: number, metadata?: ItemMetadata, slot?: number): boolean
Lua
local ok = aiLib.inventory.removeItem(inv, item, count, metadata, slot)

Paramètres

Prop

Type

Retour

boolean : true quand ils ont été retirés. false quand il n’y en a pas assez, qu’un argument est incorrect ou qu’aucun inventaire ne tourne.

Exemple

if (!inventory.removeItem(source, "lockpick")) return fail("NO_LOCKPICK");

inventory.getItemCount

Combien d’exemplaires d’un objet contient un inventaire.

Côté : serveur · Attend : non

Signature
inventory.getItemCount(inv: InventoryRef, item: string, metadata?: ItemMetadata): number
Lua
local count = aiLib.inventory.getItemCount(inv, item, metadata)

Prop

Type

Retour

number : le total de toutes les piles, 0 quand il n’y en a aucune ou qu’aucun inventaire ne tourne.

Exemple

const bags = inventory.getItemCount(source, "weed_bag");
notify(source, `You have ${bags} bags`);

inventory.hasItem

Si un inventaire contient au moins count exemplaires d’un objet.

Côté : serveur · Attend : non

Signature
inventory.hasItem(inv: InventoryRef, item: string, count?: number): boolean
Lua
local has = aiLib.inventory.hasItem(inv, item, count)

Prop

Type

Retour

boolean.

Exemple

if (!inventory.hasItem(source, "scrap_metal", 10)) return fail("NEED_10_SCRAP");

hasItem est une vérification, pas une réservation : entre hasItem et removeItem (avec un await entre les deux), l’objet peut partir. Agissez selon la réponse de removeItem.

inventory.canCarryItem

Si les objets rentreraient (poids et place libre).

Côté : serveur · Attend : non

Signature
inventory.canCarryItem(inv: InventoryRef, item: string, count?: number, metadata?: ItemMetadata): boolean
Lua
local fits = aiLib.inventory.canCarryItem(inv, item, count, metadata)

Prop

Type

Retour

boolean : true quand ils rentrent.

Exemple

if (!inventory.canCarryItem(source, "fish", 5)) return fail("TOO_HEAVY");
inventory.addItem(source, "fish", 5);

inventory.getItems

Toutes les piles d’un inventaire.

Côté : serveur · Attend : non

Signature
inventory.getItems(inv: InventoryRef): InventoryStack[]
Lua
local stacks = aiLib.inventory.getItems(inv)

Retour

InventoryStack[] : un { name, label, count, slot, metadata } par pile. Vide quand l’inventaire est vide, inconnu ou qu’aucun inventaire ne tourne.

Exemple

const weapons = inventory.getItems(source).filter((stack) => stack.name.startsWith("weapon_"));

inventory.clearInventory

Vide un inventaire.

Côté : serveur · Attend : non

Signature
inventory.clearInventory(inv: InventoryRef): void
Lua
aiLib.inventory.clearInventory(inv)

Retour

void.

Exemple

inventory.clearInventory("evidence_locker_12");

inventory.registerStash

Enregistre un coffre (une caisse de rangement, un casier). ai-core s’en souvient et l’enregistre à nouveau auprès de tout inventaire qui démarre plus tard, appelez-la donc une seule fois au démarrage de votre script.

Côté : serveur · Attend : non

Signature
inventory.registerStash(name: string, label: string, slots: number, maxWeight: number, jobs?: string[]): void
Lua
aiLib.inventory.registerStash(name, label, slots, maxWeight, jobs)

Paramètres

Prop

Type

Retour

void.

Exemple

inventory.registerStash("police_armory", "Armory", 50, 200_000, ["police"]);

inventory.openInventory

Ouvre un coffre ou l’inventaire d’un autre joueur sur l’écran d’un joueur.

Côté : serveur · Attend : non

Signature
inventory.openInventory(source: number, inv: InventoryRef): boolean
Lua
local ok = aiLib.inventory.openInventory(source, inv)

Prop

Type

Retour

boolean : true quand l’inventaire l’a ouvert.

Exemple

import { onClientCallback, near, online, inventory } from "@aicore-fivem/lib/server";
import { fail } from "@aicore-fivem/lib/shared";

const ARMORY = { x: 452.3, y: -980.0, z: 30.7 };

onClientCallback(
  "my-police:armory",
  (source) => {
    if (!online.onDutyIn(source, ["police"])) return fail("NOT_ON_DUTY");
    return { ok: inventory.openInventory(source, "police_armory") };
  },
  { guards: [near(ARMORY, 3)] },
);

Aucun contrôle de distance ni d’accès n’a lieu ici : vérifiez la distance, le métier et la propriété avant de l’appeler.

inventory.registerUsableItem

Exécute votre gestionnaire quand un joueur utilise un objet. ai-core conserve le gestionnaire pour les inventaires qui démarrent plus tard et à travers les redémarrages d’inventaire, enregistrez-le donc une seule fois au démarrage de votre script.

Côté : serveur · Attend : non

Signature
inventory.registerUsableItem(name: string, handler: UsableItemHandler): void
Lua
aiLib.inventory.registerUsableItem(name, handler) -- handler(source, item)

Paramètres

Prop

Type

La pile utilisée est un UsedItem.

Les inventaires qui retirent eux-mêmes un objet utilisé (ai-inventory) le retirent dès que le gestionnaire renvoie autre chose que false. Quand votre gestionnaire attend (une barre de progression) et retire l’objet lui-même, renvoyez false tout de suite, sinon l’objet est retiré deux fois.

Retour

void.

Exemple

import { inventory, progressFor, medical, createLocale } from "@aicore-fivem/lib/server";

const Locale = createLocale();

async function bandage(source: number) {
  const done = await progressFor(source, { label: Locale("BANDAGING"), duration: 4000, canCancel: true });
  if (done && inventory.removeItem(source, "bandage")) medical.heal(source);
}

inventory.registerUsableItem("bandage", (source) => {
  void bandage(source);
  return false; // garder l'objet pour l'instant : bandage() le retire après la barre
});

inventory.getItemDefinition

Le libellé, le poids et les options d’un objet.

Côté : serveur · Attend : non

Signature
inventory.getItemDefinition(name: string): ItemDefinition | null
Lua
local def = aiLib.inventory.getItemDefinition(name)

Retour

ItemDefinition (name, label, weight, unique, close, description, image?), ou null quand l’inventaire ne connaît pas l’objet.

Exemple

const label = inventory.getItemDefinition("water")?.label ?? "water";
notify(source, `You bought ${label}`, "success");

inventory.registerShop

Enregistre une boutique que le serveur ouvre pour un joueur (elle n’a pas d’emplacement propre). ai-core l’enregistre à nouveau auprès de tout inventaire qui démarre plus tard ; appelez-la une seule fois au démarrage.

Côté : serveur · Attend : non

Signature
inventory.registerShop(name: string, label: string, items: ShopProduct[]): void
Lua
aiLib.inventory.registerShop(name, label, items)

Prop

Type

Retour

void.

Exemple

inventory.registerShop("police_shop", "Police supplies", [
  { name: "handcuffs", price: 0 },
  { name: "radio", price: 50 },
]);

inventory.openShop

Ouvre une boutique enregistrée sur l’écran d’un joueur.

Côté : serveur · Attend : non

Signature
inventory.openShop(source: number, name: string): boolean
Lua
local ok = aiLib.inventory.openShop(source, name)

Retour

boolean : true quand elle s’est ouverte.

Exemple

onClientCallback("my-police:shop", (source) => {
  if (!online.onDutyIn(source, ["police"])) return fail("NOT_ON_DUTY");
  return { ok: inventory.openShop(source, "police_shop") };
});

Aucun contrôle de distance ni d’accès n’a lieu ici : faites-les avant de l’appeler.

Joueurs et personnages

online, onCharacter, notify, joueurs proches, positions et stockages par joueur : PlayerMap, Cooldowns, KeyedCooldowns, SourceLock, RateLimit, KeyWatchers.

Véhicules

spawnVehicle, vehicleType, randomPlate, véhicules les plus proches, entités depuis les net ids du client, vehicleKeys, carburant et garages.

Sur cette page

inventory.addItemParamètresRetourExempleinventory.removeItemParamètresRetourExempleinventory.getItemCountRetourExempleinventory.hasItemRetourExempleinventory.canCarryItemRetourExempleinventory.getItemsRetourExempleinventory.clearInventoryRetourExempleinventory.registerStashParamètresRetourExempleinventory.openInventoryRetourExempleinventory.registerUsableItemParamètresRetourExempleinventory.getItemDefinitionRetourExempleinventory.registerShopRetourExempleinventory.openShopRetourExemple