AI Core
Referência da APILib: servidor

Itens

inventory: dê, tire e conte itens, baús, lojas e itens usáveis pelo inventário que o servidor estiver rodando.

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

inventory envia toda chamada de item pela camada de inventário do ai-core: o inventário que o servidor roda (ai-inventory, ou outro que o dono escolhe no painel do ai-core) responde. Seu script nunca chama os exports próprios de um inventário, então continua funcionando quando o dono troca de inventário.

O argumento de inventário (inv, tipo InventoryRef) é o id de servidor de um jogador (um número) ou o id de outro inventário (uma string: o nome de um baú, uma placa).

Quantidades são números inteiros de 1 ou mais; uma fração é arredondada para baixo, e 0 ou uma quantidade negativa faz a chamada falhar.

Enquanto nenhum inventário está rodando, as chamadas falham em silêncio: false, 0, uma lista vazia ou null. Os equivalentes em Lua em aiLib.inventory têm os mesmos nomes e a mesma ordem de argumentos.

inventory.addItem

Dá itens a um inventário.

Lado: Servidor · Espera: não

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)

Parâmetros

Prop

Type

Retorno

boolean: true quando dados. false quando não cabem, o item não existe, um argumento está errado ou nenhum inventário está rodando.

Exemplo

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");

Verifique canCarryItem antes quando você recebe algo em troca (dinheiro, outro item): tire-o só depois que addItem respondeu true, ou devolva-o.

inventory.removeItem

Tira itens de um inventário.

Lado: Servidor · Espera: não

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)

Parâmetros

Prop

Type

Retorno

boolean: true quando tirados. false quando não há o suficiente, um argumento está errado ou nenhum inventário está rodando.

Exemplo

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

inventory.getItemCount

Quantos de um item um inventário tem.

Lado: Servidor · Espera: não

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

Prop

Type

Retorno

number: o total somando todas as pilhas, 0 quando não há nenhum ou nenhum inventário está rodando.

Exemplo

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

inventory.hasItem

Se um inventário tem pelo menos count de um item.

Lado: Servidor · Espera: não

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

Prop

Type

Retorno

boolean.

Exemplo

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

hasItem é uma verificação, não uma reserva: entre hasItem e removeItem (um await no meio) o item pode sair. Aja com base na resposta de removeItem.

inventory.canCarryItem

Se os itens caberiam (peso e espaço livre).

Lado: Servidor · Espera: não

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

Prop

Type

Retorno

boolean: true quando cabem.

Exemplo

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

inventory.getItems

Todas as pilhas de um inventário.

Lado: Servidor · Espera: não

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

Retorno

InventoryStack[]: um { name, label, count, slot, metadata } por pilha. Vazio quando o inventário está vazio, é desconhecido ou nenhum inventário está rodando.

Exemplo

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

inventory.clearInventory

Esvazia um inventário.

Lado: Servidor · Espera: não

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

Retorno

void.

Exemplo

inventory.clearInventory("evidence_locker_12");

inventory.registerStash

Registra um baú (uma caixa de armazenamento, um armário). O ai-core se lembra dele e o registra de novo em qualquer inventário que iniciar depois, então chame uma vez quando o script iniciar.

Lado: Servidor · Espera: não

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

Parâmetros

Prop

Type

Retorno

void.

Exemplo

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

inventory.openInventory

Abre um baú ou o inventário de outro jogador na tela de um jogador.

Lado: Servidor · Espera: não

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

Prop

Type

Retorno

boolean: true quando o inventário o abriu.

Exemplo

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)] },
);

Nenhuma verificação de distância ou de acesso acontece aqui: verifique distância, emprego e posse antes de chamá-lo.

inventory.registerUsableItem

Roda o seu handler quando um jogador usa um item. O ai-core guarda o handler para inventários que iniciarem depois e entre reinícios do inventário, então registre uma vez quando o script iniciar.

Lado: Servidor · Espera: não

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

Parâmetros

Prop

Type

A pilha usada é um UsedItem.

Inventários que tiram o item usado por conta própria (ai-inventory) o tiram assim que o handler retorna qualquer coisa diferente de false. Quando o seu handler espera (uma barra de progresso) e remove o item ele mesmo, retorne false na hora, senão o item é tirado duas vezes.

Retorno

void.

Exemplo

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; // mantém o item agora: bandage() o tira depois da barra
});

inventory.getItemDefinition

O rótulo, o peso e as flags de um item.

Lado: Servidor · Espera: não

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

Retorno

ItemDefinition (name, label, weight, unique, close, description, image?), ou null quando o inventário não conhece o item.

Exemplo

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

inventory.registerShop

Registra uma loja que o servidor abre para um jogador (ela não tem um lugar próprio). O ai-core a registra de novo em qualquer inventário que iniciar depois; chame uma vez na inicialização.

Lado: Servidor · Espera: não

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

Prop

Type

Retorno

void.

Exemplo

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

inventory.openShop

Abre uma loja registrada na tela de um jogador.

Lado: Servidor · Espera: não

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

Retorno

boolean: true quando abriu.

Exemplo

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

Nenhuma verificação de distância ou de acesso acontece aqui: verifique-as antes de chamá-lo.

Jogadores e personagens

online, onCharacter, notify, jogadores próximos, posições e stores por jogador: PlayerMap, Cooldowns, KeyedCooldowns, SourceLock, RateLimit, KeyWatchers.

Veículos

spawnVehicle, vehicleType, randomPlate, veículos mais próximos, entidades a partir de net ids do cliente, vehicleKeys, combustível e garagens.

Nesta página

inventory.addItemParâmetrosRetornoExemploinventory.removeItemParâmetrosRetornoExemploinventory.getItemCountRetornoExemploinventory.hasItemRetornoExemploinventory.canCarryItemRetornoExemploinventory.getItemsRetornoExemploinventory.clearInventoryRetornoExemploinventory.registerStashParâmetrosRetornoExemploinventory.openInventoryRetornoExemploinventory.registerUsableItemParâmetrosRetornoExemploinventory.getItemDefinitionRetornoExemploinventory.registerShopRetornoExemploinventory.openShopRetornoExemplo