Weapons & Vehicle Storage

Overview · Weapons & Vehicle Storage
Weapon System Overview
Magazine Ammunition · Server Authority
Manual & Automatic Reload Modes
Empty Magazine & Equip Behavior
Throwable Weapons
Weapon Durability & Back Display
Vehicle Storage Overview
Vehicle Registry & Capacity Resolution
Trunk & Glovebox Interaction
Live Trunk Session Security
Front Trunks / Frunks
Addon Vehicle Trunk Placement
NPC Vehicle Trunk Loot
Vehicle Storage Exports

Overview · Weapons & Vehicle Storage

5 · Weapons & Vehicle Storage

Weapon magazine authority, throwables, lifecycle and secure trunk/glovebox storage.

Weapon System Overview

Weapons as inventory item instances with server-owned ammunition/lifecycle state.

Applies to: Nord Inventory v2.0.0

Weapons are inventory items. The server owns item identity and metadata; the game weapon entity is a presentation/control surface synchronized to that inventory instance.

Reserve ammunition remains inventory items until a reload transaction removes exactly the rounds that fit into the magazine.

Magazine Ammunition · Server Authority

Current magazine model and reload transaction rules.

Applies to: Nord Inventory v2.0.0

Weapon ammunition persistence

Nord Inventory stores the rounds currently loaded in a firearm in the weapon instance metadata (metadata.ammo).

When a firearm is holstered through the inventory, the final magazine count is now sent to the server in the same CompleteUseItem transaction. This avoids an event-order race where the player could reload, holster, and re-equip the same weapon but receive an empty magazine.

If holstering happens while the native reload animation/transaction is still active, Nord uses the server-approved loaded value already held in equippedWeapon.ammo instead of GTA's temporary clip staging value.

The server never trusts this path to add ammunition. UpdateWeaponAmmo can only reduce the current server magazine count. Actual increases still require LoadWeaponAmmo, which removes matching ammunition items first.

-- Nord Inventory - inventory limits, weapon ammo and runtime rules

Config = Config or {}

Config.DefaultPlayerSlots = 40
Config.DefaultPlayerWeight = 80000 -- grams
Config.DefaultStashSlots = 60
Config.DefaultStashWeight = 150000
Config.TrunkSlots = 50
Config.TrunkWeight = 120000
Config.GloveboxSlots = 10
Config.GloveboxWeight = 15000

-- Weapon magazine handling. Nord keeps ONLY the currently loaded magazine on the
-- weapon metadata; reserve ammunition always remains as inventory items until a
-- reload transaction removes exactly the rounds that fit in the magazine.
Config.WeaponAmmo = {
    Enabled = true,
    DefaultMagazineSize = 30, -- used only until a weapon instance has magazineSize metadata
    MaxMagazineSize = 999,
    DetectMagazineFromGame = true, -- first equip can seed metadata.magazineSize from GTA's native clip size

    -- Keep the weapon physically equipped when the magazine reaches 0.
    -- GTA may try to switch the ped to WEAPON_UNARMED when the last round is
    -- fired; Nord immediately restores the empty weapon. The weapon is only
    -- holstered when the player uses/clicks that same inventory item again.
    KeepEquippedWhenEmpty = true,

    -- Automatic mode is intentionally slower than pressing R manually.
    -- First Nord waits before requesting the reload, then it keeps the weapon
    -- empty for an additional preparation period before the native reload starts.
    AutoReloadDelay = 1400, -- ms after the magazine reaches zero before automatic reload is requested
    AutomaticReloadPrepareTime = 900, -- extra ms before the automatic reload animation / rounds enter the weapon

    ReloadCooldown = 650, -- protects against duplicate reload requests
    ManualReloadControl = 45, -- INPUT_RELOAD (R)
}

Config.InventorySessionSeconds = 300
Config.SaveIntervalSeconds = 30
Config.MaxTransferAmount = 100000
Config.MaxContainerDepth = 3

Config.EnableWeight = true
Config.EnableVolume = false
Config.EnableDurability = true
Config.EnableItemHistory = true
Config.TransactionLogRetentionDays = 14

Manual & Automatic Reload Modes

R vs automatic reload timing in the current config.

Applies to: Nord Inventory v2.0.0

Current defaults:

AutoReloadDelay: 1400 ms
AutomaticReloadPrepareTime: 900 ms
ReloadCooldown: 650 ms
ManualReloadControl: 45 (R)

Automatic reload intentionally adds delay. Manual R remains the faster deliberate player action. Duplicate requests are protected by cooldown/server transaction rules.

Empty Magazine & Equip Behavior

Keep the actual weapon equipped when the last round is fired.

Applies to: Nord Inventory v2.0.0

KeepEquippedWhenEmpty = true prevents GTA's automatic unarmed switch from becoming the inventory authority. Nord restores the empty equipped weapon; clicking/using the same inventory item is what holsters it.

Throwable Weapons

Consume inventory only after a projectile is actually thrown.

Applies to: Nord Inventory v2.0.0

Throwable weapons

Throwable GTA weapons use one real native projectile when equipped.

Definitions use:

weapon = { name = 'WEAPON_GRENADE' },
unique = true,
metadataDefaults = {
    throwable = true
}

The item is not consumed when merely equipped. Nord waits for GTA's ammo to transition from 1 to 0, which indicates that the projectile was actually released, and only then removes the exact inventory instance by UID.

This applies to grenades, sticky bombs, pipe bombs, Molotovs, proximity mines, gas/smoke/tear gas, flares, snowballs and balls.

Putting the throwable away before throwing keeps the item in the inventory. Throwables do not use firearm reload logic, magazine persistence, or the empty-firearm auto-restore behavior.

Weapon Durability & Back Display

Lifecycle remains authoritative while back props remain cosmetic.

Applies to: Nord Inventory v2.0.0

Weapon durability uses the same server lifecycle system as supported items. Back weapon props do not prove ownership and are not used to calculate ammo, condition or permissions.

Vehicle Storage Overview

Trunk/glovebox sessions with model/category capacity resolution.

Applies to: Nord Inventory v2.0.0

Default fallback capacities:

Trunk: 50 slots / 120000 g
Glovebox: 10 slots / 15000 g

The vehicle registry can override these by category/model. Framework vehicle catalogs and GTA model scans can feed Admin Studio.

Vehicle Registry & Capacity Resolution

Category/model data, framework import and unlimited/custom capacity patterns.

Applies to: Nord Inventory v2.0.0

The current vehicle registry is enabled, imports supported framework vehicles automatically and scans GTA models. Capacity resolution prefers model/category-specific rules before global defaults.

Use Admin Studio to manage realistic capacities instead of editing runtime inventory rows.

Trunk & Glovebox Interaction

Access mode, distance checks and interior TAB behavior.

Applies to: Nord Inventory v2.0.0

Current vehicle interaction behavior includes:

TAB inside a vehicle opens the glovebox path;
trunk access uses configured TextUI/Target bridge behavior;
lock state is rechecked through the configured provider;
session identity binds to the actual vehicle/net identity/plate data rather than a UI-only selection.

Live Trunk Session Security

Why an already-open trunk closes when access becomes invalid.

Applies to: Nord Inventory v2.0.0

Vehicle Trunk Access & Live Session Guard

Nord Inventory validates trunk access both before opening and while the inventory remains open.

Locked vehicles

A locked vehicle cannot open its trunk inventory. The client checks both the normal GTA lock status and per-player door locks. The server revalidates the lock state whenever the artifact exposes the native, and also receives the normal-client preflight status for compatibility.

Live trunk session

Once a trunk is open, Nord continuously validates the same live vehicle context. The inventory closes automatically when:

the vehicle becomes locked;
the vehicle moves away from its opening position;
the vehicle starts moving above the configured threshold;
the player is no longer close enough to the physical trunk/frunk interaction point;
the vehicle despawns;
the network id is recycled to another entity;
the plate no longer matches the opened vehicle.

This is especially important for ambient/NPC vehicles: an NPC cannot drive away while the player keeps the old trunk inventory open.

Configuration

Config.VehicleInteraction.Trunk.SessionGuard = {
    Enabled = true,
    ClientCheckInterval = 150,
    ServerCheckInterval = 750,
    DistanceTolerance = 1.60,
    VehicleMoveDistance = 1.00,
    VehicleMoveSpeed = 0.65,
    CloseWhenLocked = true,
    CloseWhenVehicleMoves = true,
}

The client guard is for immediate UX. The server guard protects the inventory session and rejects further inventory actions once the vehicle context becomes invalid.

Player-owned vehicles and vehicle-key resources

Player-owned/personal vehicles must obey the same trunk lock rule as every other vehicle.

Nord Inventory now has a dedicated open lock bridge:

client/bridge/vehiclelocks.lua
server/bridge/vehiclelocks.lua

With the default configuration:

LockIntegration = {
    Provider = 'auto'
}

auto detects nord_vehiclekeys.

When nord_vehiclekeys is running, Nord Inventory reads its synchronized:

nordkeys:locked

state on the client and validates the server state through:

exports.nord_vehiclekeys:GetLockState(netId)

A locked = true result always blocks the trunk, even if GTA's native GetVehicleDoorLockStatus is briefly stale/unlocked for the owner.

The provider and native checks are intentionally combined: if either reliable source says the vehicle is locked, trunk access is denied.

Other vehicle-key resources

Use:

LockIntegration = {
    Provider = 'custom'
}

and implement the resolver in the open bridge files, or set the provider to a resource exposing an IsVehicleLocked export.

Front Trunks / Frunks

Front-compartment detection for vehicles whose storage is at the front.

Applies to: Nord Inventory v2.0.0

Nord can infer front storage using model/engine/bone/flag data and vehicle overrides. Keep model-specific exceptions in the vehicle configuration/registry rather than special-casing an integration's UI.

Addon Vehicle Trunk Placement

Placement assistance and model overrides for non-standard vehicles.

Applies to: Nord Inventory v2.0.0

Addon vehicles can have unusual dimensions, trunk geometry or storage location. Use the placement/vehicle registry tools to define the correct access position and capacity instead of increasing global interaction distance.

NPC Vehicle Trunk Loot

Optional randomized loot for eligible NPC vehicle trunks.

Applies to: Nord Inventory v2.0.0

Current config permits NPC trunk robbery and enables randomized loot. Default rolls range from 1 to 4 with an empty chance of 15%. Weighted sample loot includes basic consumables/tools and configured items.

Treat the server as the loot authority. Do not decide reward rolls only in the client.

Vehicle Storage Exports

Capacity queries for other vehicle/garage resources.

Applies to: Nord Inventory v2.0.0

GetVehicleStorageCapacity(invType, modelHash, vehicleClass)
GetVehicleTrunkWeight(modelHash, vehicleClass)
GetVehicleTrunkSlots(modelHash, vehicleClass)
GetVehicleGloveboxWeight(modelHash, vehicleClass)
GetVehicleGloveboxSlots(modelHash, vehicleClass)

These exports let garages/dealerships/admin tools show the same capacities Nord Inventory will actually enforce.