Configuration

cold_inventory utiliza dos tipos principales de configuracion:

Convars en server.cfg para comportamiento general, seguridad, persistencia, administracion y webhooks.
Archivos Lua para catalogos, documentos, vehiculos y la oficina de duplicados.

Framework

setr cold_inventory:mode "auto"

Valores aceptados:

auto
qbox / qbx
qbcore / qb / qb-core
esx
solo / standalone

Con auto, el recurso detecta primero QBOX, despues QBCore, despues ESX y finalmente utiliza modo solo.

Inventario principal

setr cold_inventory:cells 48
setr cold_inventory:carry 30000
setr cold_inventory:max_context_cells 500
setr cold_inventory:max_item_count 1000000
setr cold_inventory:command "inv"
setr cold_inventory:keep_input 1

cells — numero de slots del inventario de jugador. Rango interno: 1-200.
carry — peso maximo del jugador. El catalogo usa los pesos definidos en cada item.
max_context_cells — limite global de slots para inventarios contextuales.
max_item_count — cantidad maxima aceptada en una operacion/item.
command — comando para abrir/cerrar el inventario. Por defecto /inv.
keep_input — controla el comportamiento de foco/entrada de la NUI.

Hotbar y teclas

setr cold_inventory:hotbar 1
setr cold_inventory:hotbar_slots 5
setr cold_inventory:hotbar_show_ms 2500
setr cold_inventory:hotbar_always_visible 0
setr cold_inventory:weapon_animations 1

Teclas por defecto:

TAB — abrir/cerrar inventario.
Z — mostrar hotbar temporalmente.
1-5 — usar slots de hotbar con la configuracion por defecto.

hotbar_slots admite de 1 a 9.

Las teclas se registran con RegisterKeyMapping, por lo que cada jugador puede remapearlas desde los ajustes de FiveM.

Limites de metadata

setr cold_inventory:metadata_max_depth 6
setr cold_inventory:metadata_max_entries 128
setr cold_inventory:metadata_max_string 2048
setr cold_inventory:metadata_max_bytes 16384

Estos limites protegen el servidor frente a metadata excesivamente profunda, grande, ciclica o no valida.

Comandos de items

setr cold_inventory:allow_give_command 1
setr cold_inventory:give_command "giveitem"
setr cold_inventory:give_command_ace "cold_inventory.give"
setr cold_inventory:list_command_ace "cold_inventory.give"

Permiso recomendado:

add_ace group.admin cold_inventory.give allow

Comandos:

/giveitem water 5
/giveitem 12 water 5
/colditems

Si el primer argumento de /giveitem es un server ID valido, el item se entrega a ese jugador. Si no, se entrega al propio ejecutor.

Drops del suelo

setr cold_inventory:drop_cells 20
setr cold_inventory:drop_interact_distance 2.2
setr cold_inventory:drop_render_distance 45.0
setr cold_inventory:drop_merge_distance 1.2
setr cold_inventory:drop_prop "prop_paper_bag_small"
setr cold_inventory:persist_drops 1
setr cold_inventory:drop_scope_interval_ms 1500
setr cold_inventory:drop_scope_cell_size 100.0

drop_cells — slots de un drop.
drop_interact_distance — distancia para interactuar.
drop_render_distance — distancia maxima para renderizarlo.
drop_merge_distance — distancia para agrupar drops cercanos.
drop_prop — prop usado cuando el drop no representa un arma.
persist_drops — guarda drops en SQL para sobrevivir reinicios.
drop_scope_* — controla el calculo de proximidad/scoping de drops.

Si se tira un arma, el sistema puede representar el drop con el prop real del arma en lugar de la bolsa generica.

Maleteros

setr cold_inventory:vehicle_trunks 1
setr cold_inventory:vehicle_trunk_search_distance 6.0
setr cold_inventory:vehicle_trunk_interact_distance 1.85
setr cold_inventory:vehicle_trunk_validate_distance 12.0
setr cold_inventory:vehicle_trunk_retry_ms 1500

Las capacidades se configuran en:

shared/settings.lua

Dentro de:

ColdInventory.settings.vehicleTrunks

La prioridad es:

modelo > marca > clase > default

Puedes definir cells, limit y la posicion de almacenamiento. Para modelos especiales se puede usar storage = 'none' o storage = 'front'.

Gloveboxes

setr cold_inventory:vehicle_gloveboxes 1
setr cold_inventory:vehicle_glovebox_search_distance 4.5
setr cold_inventory:vehicle_glovebox_interact_distance 1.6
setr cold_inventory:vehicle_glovebox_validate_distance 8.0
setr cold_inventory:vehicle_glovebox_retry_ms 1500

La configuracion de capacidad esta en:

ColdInventory.settings.vehicleGloveboxes

Tambien sigue la prioridad:

modelo > marca > clase > default

Persistencia

setr cold_inventory:save_interval_ms 30000
setr cold_inventory:save_batch_size 200
setr cold_inventory:save_on_disconnect 1

save_interval_ms — intervalo de guardado de inventarios modificados.
save_batch_size — tamaño de lote SQL; internamente se limita a 25-500.
save_on_disconnect — fuerza guardado al desconectar.

Los inventarios activos viven en memoria y solo se encolan para SQL cuando cambian. El recurso tambien intenta guardar antes de detenerse o reiniciarse.

Transacciones y sincronizacion

setr cold_inventory:delta_sync 1
setr cold_inventory:action_cache_ms 30000
setr cold_inventory:transaction_durable 1
setr cold_inventory:transaction_max_bags 8
setr cold_inventory:journal_retention_days 14
setr cold_inventory:max_context_viewers 3
setr cold_inventory:container_max_depth 2

delta_sync — sincroniza cambios por revision/deltas cuando es posible.
action_cache_ms — conserva identificadores de acciones para hacer operaciones NUI idempotentes.
transaction_durable — usa journal/transacciones SQL para operaciones economicas multi-inventario.
transaction_max_bags — maximo de bolsas implicadas en una transaccion.
journal_retention_days — dias de retencion del journal SQL.
max_context_viewers — numero maximo global de jugadores mirando el mismo contexto.
container_max_depth — profundidad maxima de contenedores anidados.

Seguridad

setr cold_inventory:security_window_ms 1500
setr cold_inventory:security_sync_burst 6
setr cold_inventory:security_context_burst 5
setr cold_inventory:security_action_burst 16
setr cold_inventory:security_drop_burst 8
setr cold_inventory:security_strike_window_ms 15000
setr cold_inventory:security_strike_limit 8
setr cold_inventory:security_log_suspicious 1
setr cold_inventory:security_drop_player 0
setr cold_inventory:security_drop_reason "Cold Inventory security violation."
setr cold_inventory:security_lock_timeout_ms 8000
setr cold_inventory:security_mutation_timeout_ms 30000

El servidor vuelve a validar acciones sensibles: distancias, routing bucket, permisos, revisiones, tokens, peso, cantidades, slots, payloads y acceso al segundo inventario.

warning

security_drop_player = 1 puede expulsar jugadores al superar las reglas de seguridad. Es mejor dejarlo en 0 durante la configuracion y activarlo solo despues de probar tus integraciones.

Perdida de items al morir

setr cold_inventory:lose_items_on_death 1
setr cold_inventory:death_loss_notify 1
setr cold_inventory:death_loss_retries 8
setr cold_inventory:death_loss_retry_ms 250

Desactiva lose_items_on_death si tu servidor no debe aplicar la logica de perdida configurada al morir.

Catalogo de items

Edita:

data/items.lua

Ejemplo de item:

['comida_especial'] = {
    label = 'Comida especial',
    weight = 250,
    degrade = 180,
}

Las imagenes se colocan en:

web/images/

Armas, municion y cargadores

El catalogo esta en:

data/weapons.lua

El sistema conserva en metadata datos como:

durability
ammo
components
serial
registered

Las armas compatibles utilizan items de cargador persistentes del tipo:

magazine_weapon_pistol

Puedes sobrescribir la capacidad de un arma:

['WEAPON_PISTOL'] = {
    -- resto de la definicion
    magazineCapacity = 17,
}

Para excluir un arma especial del sistema de cargadores:

magazine = false

Durabilidad, caducidad y reparacion

setr cold_inventory:lifecycle_enabled 1
setr cold_inventory:auto_food_expiry 1
setr cold_inventory:food_expire_minutes 4320
setr cold_inventory:expiry_bucket_seconds 60
setr cold_inventory:repair_kit "repairkit"
setr cold_inventory:repair_kit_count 1
setr cold_inventory:repair_restore 100.0
setr cold_inventory:repair_distance 7.5

Ejemplo de herramienta reparable:

['herramienta'] = {
    label = 'Herramienta',
    stack = false,
    condition = {
        type = 'tool',
        lossOnUse = 8,
        repairable = true,
        repairItem = 'repairkit',
        repairCount = 1,
        repairAmount = 100,
    },
}

Los talleres base estan definidos en shared/settings.lua. Otros recursos pueden registrar talleres adicionales mediante el export RegisterRepairWorkshop.

Documentos oficiales

setr cold_inventory:documents_enabled 1
setr cold_inventory:document_issue_command "emitirdoc"
setr cold_inventory:document_revoke_command "revocardoc"
setr cold_inventory:document_ace "cold_inventory.documents"
setr cold_inventory:document_show_distance 3.0
setr cold_inventory:document_display_ms 10000
setr cold_inventory:document_verify_cache_ms 30000

Permiso recomendado:

add_ace group.admin cold_inventory.documents allow

Comandos por defecto:

/emitirdoc [id] [tipo] [dias]
/revocardoc [serie] [motivo]

Tipos incluidos en el catalogo base:

id_card
driver_license
weapon_license
lawyer_pass
work_permit
residence_permit

Los documentos se registran en cold_inventory_documents. El item que lleva el jugador contiene una referencia; la informacion oficial se reconstruye y valida desde MySQL.

Oficina NPC de documentos

La oficina de duplicados se configura en config.lua:

ColdInventoryConfig.DocumentShop = {
    enabled = true,
    currency = 'cash',
    interactionDistance = 2.5,
    serverDistance = 4.0,
    onlyWhenMissing = true,
    replacementOnly = true,
    issuerLabel = 'Registro Civil de COLD STATE',

    offices = {
        city_hall = {
            enabled = true,
            label = 'Oficina de documentacion',
            model = 'a_m_m_business_01',
            coords = { x = -545.49, y = -204.08, z = 38.22, w = 208.0 },
            groundOffset = 1.0,
            scenario = 'WORLD_HUMAN_CLIPBOARD',
            documents = {
                {
                    type = 'id_card',
                    label = 'Duplicado del documento de identidad',
                    price = 250,
                    icon = 'fa-solid fa-id-card',
                },
                {
                    type = 'driver_license',
                    label = 'Duplicado del carnet de conducir',
                    price = 500,
                    icon = 'fa-solid fa-car',
                },
            },
        },
    },
}

onlyWhenMissing evita cobrar si el personaje aun tiene una copia valida.
replacementOnly impide comprar un documento que nunca fue expedido previamente.
Al emitir un duplicado se revocan las copias anteriores.
Precio, moneda, distancia e identidad se vuelven a validar en servidor.

Auditoria y metricas

setr cold_inventory:audit_enabled 1
setr cold_inventory:audit_flush_ms 5000
setr cold_inventory:audit_batch_size 100
setr cold_inventory:audit_retention_days 30
setr cold_inventory:metrics_enabled 1
setr cold_inventory:admin_ace "cold_inventory.admin"

ACE recomendado:

add_ace group.admin cold_inventory.admin allow

Comandos administrativos:

/coldinvhealth
/coldinvinspect [serverId]
/coldinvfreeze [serverId] [on|off] [motivo]
/coldinvrepair [serverId]
/coldinvaudit [ownerKey]

Webhooks de Discord

Los webhooks deben configurarse con set, no con setr.

set cold_inventory:webhooks_enabled 1
set cold_inventory:webhook "https://discord.com/api/webhooks/ID/TOKEN"
set cold_inventory:webhook_security ""
set cold_inventory:webhook_admin ""
set cold_inventory:webhook_transactions ""
set cold_inventory:webhook_log_all 0
set cold_inventory:webhook_actions "transfer,give_nearby,discard,trade,craft,purchase,death_loss,document_issue,document_revoke,document_purchase,snapshot_restore,repair"
set cold_inventory:webhook_flush_ms 1500
set cold_inventory:webhook_batch_size 10
set cold_inventory:webhook_queue_limit 1000
set cold_inventory:webhook_retry_limit 3
set cold_inventory:webhook_retry_ms 1500
set cold_inventory:webhook_aggregate_ms 5000
set cold_inventory:webhook_username "COLD INVENTORY"
set cold_inventory:webhook_avatar ""

Las URLs especializadas son opcionales. Si no defines una URL para seguridad, administracion o transacciones, esa categoria usa cold_inventory:webhook como fallback.

danger

Nunca uses setr para una URL de webhook. Una convar replicada puede exponer el webhook y su token a los clientes.

Stashes y contextos desde otros recursos

Ejemplo de stash persistente:

exports.cold_inventory:RegisterStash(
    'police_armory',
    'POLICE ARMORY',
    60,
    350000,
    false,
    { police = 0 },
    vec3(441.2, -981.9, 30.7)
)

Abrirlo:

exports.cold_inventory:OpenInventory(source, 'stash', 'police_armory')

Stash temporal:

local tempId = exports.cold_inventory:CreateTemporaryStash({
    label = 'RAID CACHE',
    slots = 24,
    maxWeight = 180000,
    owner = false,
    items = {
        { name = 'water', count = 4 },
        { name = 'bread', count = 2 },
    },
    durationMs = 600000,
})

OpenInventory respeta permisos, distancia e instancia. ForceOpenInventory ignora esas validaciones y debe reservarse para flujos administrativos o scripts internos de confianza.

Contenedores

Ejemplo:

exports.cold_inventory:RegisterContainer('paperbag', {
    label = 'Bolsa de papel',
    cells = 8,
    limit = 12000,
    allowNested = false,
})

La profundidad maxima global se controla con:

setr cold_inventory:container_max_depth 2

Compatibilidad `ox_inventory`

El manifest contiene:

provide 'ox_inventory'

La capa de compatibilidad expone numerosos contratos publicos habituales, incluyendo items, slots, peso, metadata, stashes, shops, drops, hooks, inventarios temporales y apertura de vehiculos.

Ejemplos compatibles:

exports.cold_inventory:AddItem(source, 'water', 1)
exports.cold_inventory:RemoveItem(source, 'water', 1)
exports.cold_inventory:GetItemCount(source, 'water')
exports.cold_inventory:CanCarryItem(source, 'water', 5)

Cuando un recurso externo espera ox_inventory, el provide permite que FiveM resuelva esa dependencia contra cold_inventory siempre que el recurso consumidor use contratos compatibles.

API propia

Entre los exports propios disponibles estan:

GetMode
DeclareItem
FetchBag
CountItem
GiveItem
TakeItem
SetCount
WipeBag
RegisterContext
RegisterStash
CreateTemporaryStash
OpenContext
OpenInventory
ForceOpenInventory
TransferItem
BindItemAction
UseItem
RegisterContainer
RegisterStashPolicy
GetHealth
InspectInventory
FreezeInventory
RepairInventory
CreateSnapshot
RestoreSnapshot
QueryAudit
IssueDocument
RevokeDocument
VerifyDocument
ShowDocument
LogWebhook

Consulta el propio recurso si necesitas la firma exacta de un export avanzado antes de integrarlo en otro script.

Framework​

Inventario principal​

Hotbar y teclas​

Limites de metadata​

Comandos de items​

Drops del suelo​

Maleteros​

Gloveboxes​

Persistencia​

Transacciones y sincronizacion​

Seguridad​

Perdida de items al morir​

Catalogo de items​

Armas, municion y cargadores​

Durabilidad, caducidad y reparacion​

Documentos oficiales​

Oficina NPC de documentos​

Auditoria y metricas​

Webhooks de Discord​

Stashes y contextos desde otros recursos​

Contenedores​

Compatibilidad ox_inventory​

API propia​