ai-inventory para desarrolladores

Referencias de inventarioCopy Anchor Link

Cada export de servidor que recibe inv acepta:

Exports de servidorCopy Anchor Link

Tipados como AiInventoryServerExports en @aicore-fivem/shared: resourceExport("ai-inventory") en TypeScript.

AddItemCopy Anchor Link

Añade objetos a un inventario. Los montones con el mismo nombre y metadata se unen hasta el tamaño de montón del objeto; el resto va a celdas libres.

Lado: Servidor · Espera: no

AddItem(inv: number | string, item: string, count: number, metadata?: Record<string, unknown>, slot?: number): boolean

local ok = exports['ai-inventory']:AddItem(source, 'water', 2)

ParámetrosCopy Anchor Link

DevuelveCopy Anchor Link

boolean: true cuando se añadieron todas las unidades. false cuando el inventario o el objeto son desconocidos, count no es válido o no cabe (celdas o peso). No se añade nada cuando responde false.

EjemploCopy Anchor Link

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

const inv = resourceExport("ai-inventory");

onClientCallback("myscript:buyWater", (source) => {
  if (!inv.CanCarryItem(source, "water", 1)) return fail("NO_SPACE");
  if (!inv.AddItem(source, "water", 1)) return fail("NO_SPACE");
  return { ok: true };
});

RemoveItemCopy Anchor Link

Quita objetos de un inventario.

Lado: Servidor · Espera: no

RemoveItem(inv: number | string, item: string, count: number, metadata?: Record<string, unknown>, slot?: number): boolean

DevuelveCopy Anchor Link

boolean: true cuando se quitaron todas las unidades. false cuando no hay suficientes (entonces no se quita nada). Un arma quitada a un jugador también se le quita de las manos.

GetItemCountCopy Anchor Link

GetItemCount(inv: number | string, item: string, metadata?: Record<string, unknown>): number

Cuántas unidades de item (que coincidan con metadata si se da) tiene el inventario. 0 para un inventario u objeto desconocido. Lado: Servidor · Espera: no.

CanCarryItemCopy Anchor Link

CanCarryItem(inv: number | string, item: string, count: number, metadata?: Record<string, unknown>): boolean

Si cabrían count unidades (celdas y peso), sin añadirlas. Lado: Servidor · Espera: no.

GetItemsCopy Anchor Link

GetItems(inv: number | string): Array<{ name, label, weight, slot, count, amount, metadata, info, stack, unique, close, description, type, image }>

Cada montón del inventario. count / metadata (nombres de ox) y amount / info (nombres de qb) tienen los mismos valores; weight es el total del montón en gramos. Una lista vacía para un inventario desconocido. Lado: Servidor · Espera: no.

GetWeightCopy Anchor Link

GetWeight(inv: number | string): { weight: number; maxWeight: number } | null

Peso cargado y límite en gramos (maxWeight 0 = sin límite). null cuando el inventario no está cargado. Lado: Servidor · Espera: no.

RegisterUsableItemCopy Anchor Link

Ejecuta tu función cuando un jugador usa un objeto. Primero se reproduce la animación del objeto (si tiene); tu función se ejecuta cuando termina.

Lado: Servidor · Espera: no

RegisterUsableItem(name: string, handler: (source: number, item: { name: string; slot: number; count: number; metadata: Record<string, unknown> }) => unknown): void

EjemploCopy Anchor Link

import { resourceExport, notify } from "@aicore-fivem/lib/server";

const inv = resourceExport("ai-inventory");

inv.RegisterUsableItem("repairkit", (source, item) => {
  const ped = GetPlayerPed(String(source));
  const vehicle = GetVehiclePedIsIn(ped, false);
  if (vehicle === 0) {
    notify(source, "Sit in a vehicle first", "error");
    return false; // conservar el objeto
  }
  emitNet("myscript:repair", source, NetworkGetNetworkIdFromEntity(vehicle));
});

RegisterStashCopy Anchor Link

Registra un alijo desde un script (una casa, una taquilla de banda). Los alijos compartidos se cargan al momento y se quedan cargados.

Lado: Servidor · Espera: no

RegisterStash(name: string, label: string, slots: number, maxWeight: number, jobs?: string[], personal?: boolean): void

Un alijo de script no tiene sitio en el mundo: ábrelo con OpenInventory.

OpenInventoryCopy Anchor Link

Abre un inventario en la pantalla de un jugador, junto al suyo.

Lado: Servidor · Espera: no

OpenInventory(source: number, inv: number | string): boolean

DevuelveCopy Anchor Link

boolean: true cuando se abrió. false cuando el jugador no tiene inventario cargado, el inventario es desconocido o no está cargado, o es el propio del jugador.

EjemploCopy Anchor Link

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

const inv = resourceExport("ai-inventory");
inv.RegisterStash("gang_ballas", "Ballas locker", 60, 200_000);

onClientCallback("myscript:openLocker", (source) => {
  return inv.OpenInventory(source, "gang_ballas") ? { ok: true } : fail("CANNOT_OPEN");
});

ClearInventoryCopy Anchor Link

ClearInventory(inv: number | string): void

Vacía un inventario. Lado: Servidor · Espera: no.

RegisterShop and OpenShopCopy Anchor Link

Una tienda sin lugar, abierta por tu script (una app de teléfono, un menú de NPC). Solo se puede comprar mientras ese jugador la tiene abierta, pagando con efectivo y después con banco. Una tienda del panel con el mismo id tiene prioridad.

Lado: Servidor · Espera: no

RegisterShop(name: string, label: string, items: Array<{ name: string; price: number }>): void
OpenShop(source: number, name: string): boolean

OpenShop devuelve false cuando la tienda es desconocida o el jugador no tiene inventario.

ItemsCopy Anchor Link

Items(name?: string): { name, label, weight, stack, unique, close, description, type, image, useable } | Record<string, ...> | null

Una definición de objeto (forma de ox), todas las definiciones por nombre cuando se omite name, o null para un nombre desconocido. stack es true cuando el tamaño de montón es mayor que 1; unique cuando es 1. Lado: Servidor · Espera: no.

Exports de clienteCopy Anchor Link

OpenSelf y HasItem están tipados como AiInventoryClientExports.

EventosCopy Anchor Link

ai-inventory:usedItemCopy Anchor Link

Se dispara en el servidor después de cada uso de un objeto.

Lado: Servidor (evento local)

on("ai-inventory:usedItem", (source: number, name: string) => {
  if (name === "joint") emitNet("myscript:highEffect", source);
});

AI Core lo convierte en su propio evento ai-core:itemUsed (source, name, status), el que debes escuchar si tu script debe funcionar con cualquier inventario.

API de ox_inventoryCopy Anchor Link

ai-inventory hace provide de ox_inventory y responde a sus exports (escritos sobre ox_inventory 2.44). Los inventarios se nombran como en ox: un source de jugador, un nombre de alijo, { id, owner } para alijos personales, una matrícula para maleteros.

• Servidor: AddItem (devuelve success, response, llama a cb), RemoveItem, GetItem, GetItemCount, Search (count / slots), CanCarryItem, CanCarryWeight, CanCarryAmount, GetInventory, GetInventoryItems, GetSlot, GetSlotWithItem, GetSlotsWithItem, GetSlotIdWithItem, GetSlotIdsWithItem, GetEmptySlot, SetMetadata, SetDurability, SetMaxWeight, RegisterStash, ClearInventory, Items, ItemList, forceOpenInventory (alijo, jugador, tienda), CreateTemporaryStash, CustomDrop, RemoveInventory, SwapSlots.
• Cliente: openInventory, closeInventory, Search, GetItemCount, GetPlayerItems, GetPlayerWeight, GetPlayerMaxWeight, Items, useSlot, getCurrentWeapon / GetCurrentWeapon. displayMetadata, weaponWheel y setStashTarget se aceptan y no hacen nada.
• No se responden: hooks (registerHook, removeHooks), UpdateVehicle, ConfiscateInventory / ReturnInventory, GetContainerFromSlot, RegisterShop (las tiendas vienen del panel o del RegisterShop propio de ai-inventory).

API de qb-inventoryCopy Anchor Link

ai-inventory hace provide de qb-inventory (API 2.0). Los objetos devueltos llevan las dos formas: count / metadata y amount / info.

• Servidor: AddItem(identifier, item, amount, slot, info), RemoveItem, HasItem (un nombre, una lista o { name = amount }), GetItemCount, GetItemByName, GetItemsByName, GetItemBySlot, CanAddItem, GetFreeWeight, GetSlots, ClearInventory, SetItemData, CreateInventory, OpenInventory, OpenInventoryById, RemoveInventory, CloseInventory.
• Cliente: HasItem, CloseInventory.
• No se responden: hooks y listeners, CreateShop / OpenShop, SetInventory, GetInventory, SaveInventory, LoadInventory, UseItem, GetFirstSlotByItem, GetSlotsByItem, GetTotalWeight.

Base de datos y logsCopy Anchor Link

Tabla ai_inventory_inventories: una fila por inventario guardado (id, JSON items). Solo ai-inventory la escribe; los cambios se guardan cada 30 segundos, al descargar y al detener. Canales de logs: moves (desactivado por defecto), drops, gives, purchases, crafting.