ai-inventory para desenvolvedores

Referências de inventárioCopy Anchor Link

Todo export do servidor que recebe inv aceita:

Exports do servidorCopy Anchor Link

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

AddItemCopy Anchor Link

Adiciona itens a um inventário. Pilhas com o mesmo nome e metadata se juntam até o tamanho de pilha do item; o resto vai para células livres.

Lado: Servidor · Espera: não

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

RetornoCopy Anchor Link

boolean: true quando todas as unidades foram adicionadas. false quando o inventário ou o item é desconhecido, count não é válido, ou não cabe (células ou peso). Nada é adicionado quando responde false.

ExemploCopy 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

Tira itens de um inventário.

Lado: Servidor · Espera: não

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

RetornoCopy Anchor Link

boolean: true quando todas as unidades foram retiradas. false quando não há o suficiente (nada é retirado nesse caso). Uma arma retirada de um jogador também é tirada das mãos dele.

GetItemCountCopy Anchor Link

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

Quantas unidades de item (correspondendo a metadata quando informada) o inventário tem. 0 para um inventário ou item desconhecido. Lado: Servidor · Espera: não.

CanCarryItemCopy Anchor Link

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

Se count unidades caberiam (células e peso), sem adicioná-las. Lado: Servidor · Espera: não.

GetItemsCopy Anchor Link

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

Todas as pilhas do inventário. count / metadata (nomes do ox) e amount / info (nomes do qb) guardam os mesmos valores; weight é o total da pilha em gramas. Uma lista vazia para um inventário desconhecido. Lado: Servidor · Espera: não.

GetWeightCopy Anchor Link

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

Peso carregado e limite em gramas (maxWeight 0 = sem limite). null quando o inventário não está carregado. Lado: Servidor · Espera: não.

RegisterUsableItemCopy Anchor Link

Roda sua função quando um jogador usa um item. A animação do item (se houver) toca primeiro; sua função roda quando ela termina.

Lado: Servidor · Espera: não

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

ExemploCopy 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; // mantém o item
  }
  emitNet("myscript:repair", source, NetworkGetNetworkIdFromEntity(vehicle));
});

RegisterStashCopy Anchor Link

Registra um baú a partir de um script (uma casa, um armário de gangue). Baús compartilhados são carregados na hora e ficam carregados.

Lado: Servidor · Espera: não

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

Um baú de script não tem lugar no mundo: abra-o com OpenInventory.

OpenInventoryCopy Anchor Link

Abre um inventário na tela de um jogador, ao lado do próprio inventário dele.

Lado: Servidor · Espera: não

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

RetornoCopy Anchor Link

boolean: true quando aberto. false quando o jogador não tem um inventário carregado, o inventário é desconhecido ou não está carregado, ou é o próprio inventário do jogador.

ExemploCopy 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

Esvazia um inventário. Lado: Servidor · Espera: não.

RegisterShop and OpenShopCopy Anchor Link

Uma loja sem lugar, aberta pelo seu script (um app de celular, um menu de NPC). Comprar só é permitido enquanto aquele jogador a tem aberta, pago com dinheiro vivo e depois banco. Uma loja do painel com o mesmo id tem prioridade.

Lado: Servidor · Espera: não

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

OpenShop retorna false quando a loja é desconhecida ou o jogador não tem inventário.

ItemsCopy Anchor Link

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

Uma definição de item (formato do ox), todas as definições por nome quando name é omitido, ou null para um nome desconhecido. stack é true quando o tamanho de pilha está acima de 1; unique quando é 1. Lado: Servidor · Espera: não.

Exports do clienteCopy Anchor Link

OpenSelf e HasItem são tipados como AiInventoryClientExports.

EventosCopy Anchor Link

ai-inventory:usedItemCopy Anchor Link

Disparado no servidor depois de todo uso de um item.

Lado: Servidor (evento local)

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

O AI Core transforma isso no seu próprio evento ai-core:itemUsed (source, name, status), o que você deve escutar se o seu script tiver que funcionar com qualquer inventário.

ox_inventory APICopy Anchor Link

O ai-inventory faz provide de ox_inventory e responde aos exports dele (escrito com base no ox_inventory 2.44). Os inventários são nomeados como no ox: um source de jogador, um nome de baú, { id, owner } para baús pessoais, uma placa para porta-malas.

• Servidor: AddItem (retorna success, response, chama 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 (stash, player, shop), CreateTemporaryStash, CustomDrop, RemoveInventory, SwapSlots.
• Cliente: openInventory, closeInventory, Search, GetItemCount, GetPlayerItems, GetPlayerWeight, GetPlayerMaxWeight, Items, useSlot, getCurrentWeapon / GetCurrentWeapon. displayMetadata, weaponWheel e setStashTarget são aceitos e não fazem nada.
• Não respondidos: hooks (registerHook, removeHooks), UpdateVehicle, ConfiscateInventory / ReturnInventory, GetContainerFromSlot, RegisterShop (as lojas vêm do painel ou do próprio RegisterShop do ai-inventory).

qb-inventory APICopy Anchor Link

O ai-inventory faz provide de qb-inventory (API 2.0). Os itens retornados carregam os dois formatos: count / metadata e amount / info.

• Servidor: AddItem(identifier, item, amount, slot, info), RemoveItem, HasItem (um nome, uma lista ou { name = amount }), GetItemCount, GetItemByName, GetItemsByName, GetItemBySlot, CanAddItem, GetFreeWeight, GetSlots, ClearInventory, SetItemData, CreateInventory, OpenInventory, OpenInventoryById, RemoveInventory, CloseInventory.
• Cliente: HasItem, CloseInventory.
• Não respondidos: hooks e listeners, CreateShop / OpenShop, SetInventory, GetInventory, SaveInventory, LoadInventory, UseItem, GetFirstSlotByItem, GetSlotsByItem, GetTotalWeight.

Banco de dados e logsCopy Anchor Link

Tabela ai_inventory_inventories: uma linha por inventário guardado (id, items JSON). Só o ai-inventory a escreve; as mudanças são salvas a cada 30 segundos, ao descarregar e ao parar. Canais de log: moves (desligado por padrão), drops, gives, purchases, crafting.