Server loot and ground drops

Ground loot is server-authoritative. Native containers and drops display the server's items; Take and Take All send pickup requests checked against the drop, routing bucket and player distance. The local inventory changes only after authorization.

The official open77_loot resource must stay started. Its manifest asks for network.events and world.loot, and its client is distributed with the server's resource set.

Vanilla loot suppression is a client session policy, independent of this resource. A server without open77_loot, or one that stops it, does not enable solo loot: unmanaged choices and local pickup/consume callbacks remain blocked. Managed drops keep their native presentation and server pickup requests. Outside multiplayer, normal solo behavior remains the fallback unless loot authority has been explicitly enabled for a local test.

Use this guide to place items in the world from a server resource, and to credit them to a player's inventory when they are picked up.

Server API#

Server resources that declare world.loot get Open77.loot:

permissions { "network.events", "world.loot" }

local dropId, reason = Open77.loot.create({
    item = "Items.money",             -- TweakDB record
    quantity = 250,
    position = { x = -1450.2, y = 117.8, z = 12.4 },
    bucket = 0,                        -- routing bucket
    radius = 2.0,                      -- 0.5 to 10 metres
    label = "Eurodollars",
    visualItem = "Items.MoneyShard",  -- record used only for the 3D entity
    ttlMs = 300000                     -- optional, seven days maximum
})

assert(dropId, reason)

Open77.loot.update(dropId, {
    quantity = 300,
    position = { x = -1450.0, y = 118.1, z = 12.4 },
    radius = 2.5
})

local drop = Open77.loot.get(dropId)
local bucketDrops = Open77.loot.all(0)
Open77.loot.remove(dropId)

A player's authoritative position is available server-side too:

local position = Open77.players.position(playerId)
-- { x, y, z, bucket }, or nil when the player or snapshot is unavailable.

A drop belongs to the resource that created it. Another resource can neither change nor delete it, and stopping the owning resource cleans up its drops. The registry is capped at 4,096 entries, quantities at 1,000,000, and positions at the world bounds the protocol accepts.

item and visualItem play distinct roles. item is the authoritative content actually granted once the pickup is validated. visualItem is a TweakDB record that owns a dropObject and serves only to create the physical gameItemDropObject. For a weapon, leaving visualItem empty uses the weapon's own record directly. Since Items.money is abstract currency, Open77 automatically picks Items.MoneyShard (smallItemDrop, entity money) when no override is supplied.

After an accepted pickup, every server VM receives:

AddEventHandler("onLootPickup", function(playerId, dropId, item, quantity, ownerResource)
    if ownerResource ~= GetCurrentResourceName() then return end

    -- Write the authoritative persistent inventory here (database, weight,
    -- transaction log, and so on). The client never decides the outcome.
    print(playerId, dropId, item, quantity)
end)

The pickup is atomic within the registry: two players cannot consume the same id. Validation uses a PlayerSnapshot received less than two seconds ago, requires the same routing bucket, and accepts at most radius + 0.75 m to absorb network latency.

Server events#

AddEventHandler("onLootCreated", function(id, resource, item) end)
AddEventHandler("onLootRemoved", function(id, reason, resource) end)

Both require world.loot — the same string reading one costs, because a lifecycle event that announced a loot to a resource that cannot list one would route around that capability. reason is removed, expired, resource_stopped, picked_up, moved_bucket, or the free text (at most 64 characters) the caller passed to the remove call.

The same two transitions also reach the generic onEntityCreated(kind, id, resource) and onEntityRemoved(kind, id, reason) with kind = "loot", for a resource that additionally declares world.entities.observe. The mirror is raised by the same statement, so the two feeds cannot disagree; see entity lifecycle events for the authority rule and for why there is no Updated counterpart.

Testing from the Open77 terminal#

These commands are genuinely declared in open77_loot/server/main.lua with RegisterCommand, just as in a FiveM resource:

loot.create.player 1 Items.money 250 1.0 2.0 Items.MoneyShard
loot.create Items.money 250 -1450.2 117.8 12.4 0 2.0
loot.create.player 1 Items.Preset_Lexington_Default 1
loot.list 0
loot.remove 1

Type these lines into the developer terminal opened with ² in Cyberpunk. loot.list is public. The mutations loot.create, loot.create.player, and loot.remove are registered with restricted=true and require the ACL permissions command.loot.create, command.loot.create.player, and command.loot.remove respectively (or a suitable wildcard).

loot.create expects <item> <quantity> <x> <y> <z> [bucket] [radius] [visualItem]. Decimal numbers use a dot. The drop is replicated to the bucket's players immediately; its prompt should disappear on every client as soon as a pickup is accepted.

loot.create.player uses the player's latest fresh snapshot and adds one metre in Z by default, so the item falls in front of them. Its full form is loot.create.player <playerId> <item> <quantity> [offsetZ] [radius] [visualItem].

The representation is a real native entity produced by LootManager.SpawnItemDrop: the record's mesh, a gameItemDropObject wrapper, placement, physics, highlight, and REDengine UI. Open77 binds the native EntityID to the server id when the child object appears, then fills the native inventory with item and quantity. There is no separate Open77 anchor or prompt any more.

Client API#

Gameplay clients read the projection through open77_loot's exports:

CreateThread(function()
    local promise, err = Open77.exports.call("open77_loot", "all")
    if not promise then return print(err) end
    local drops = assert(promise:await())
    for _, drop in ipairs(drops) do
        print(drop.id, drop.item, drop.quantity)
    end
end)

-- The native prompt already performs this. Useful for a custom UI.
CreateThread(function()
    local promise = Open77.exports.call("open77_loot", "requestPickup", 42)
    if promise then print(promise:await()) end
end)

Available exports:

• get(id) — returns the local drop, or nil;
• all() — snapshot sorted by id;
• requestPickup(id) — sends the request to the server.

This local event lets you show feedback without touching authority:

AddEventHandler("open77:loot:result", function(id, accepted, reason, item, quantity)
    if not accepted then
        print("Pickup refused: " .. tostring(reason))
    end
end)

Do not call Open77.loot.upsert, acceptPickup, or setAuthorityEnabled directly from a gameplay resource. Those are the internal primitives of the distributed projection, guarded by world.loot.

The boundary between native UI and server authority#

• Inventory choices stay visible only for entities bound to a server drop;
• Inventory.OnInteractionUsed is intercepted before its local RemoveItem and becomes a open77:loot:pickup request;
• the native pickup condition is re-enabled only for bound gameItemDropObjects;
• legacy placed pickups (HealthConsumable, VirtualItem_TEMP) and the Loot choices of inspectable objects;
• the container role of bodies, bags, ground items, and static containers;
• the vanilla backpack's "drop" action;
• the normal held-weapon drop path when an NPC dies;
• drops already present when authority activates, purged before the server projection.

The global purge runs only when authority activates. After that, a pickup, a removal, or an update empties only the inventory of the entity concerned. Cyberpunk then receives its normal OnInventoryEmptyEvent and cleanly removes the HUD, the interaction, and the visual without recreating the other ground items.

Open77 items therefore use the same presentation as vanilla: the physical mesh resolved by the TweakDB record falls with the game's physics, and the Inventory component builds the list and the item card. That entity holds no authority though: removal and granting only happen after the server answers positively.

Scope#

A drop holds one stack — one item and one quantity. Containers holding several stacks, and corpses carrying an authoritative inventory, belong to the container API and are not part of this one.

Persistent inventory is yours to write. This subsystem decides who may take what, and stops there. onLootPickup is where you credit an account, apply weight, or write a transaction log.

Quest collectibles that bypass Inventory are not intercepted. A handful of highly specialised pickups take neither the Inventory path nor the standard loot conditions; those still grant locally. If you meet one, its class can be identified with the Open77 inspector.