Guide

Game item pickup and loot collection systems explained

Harbor Siege's Vault of Tides finale was tuned for spectacle: the boss shattered into forty world drops across a cramped arena. Players won the fight in ninety seconds and spent four minutes walking loot crumbs, mashing the interact key, and arguing about who claimed the legendary trident. Two items despawned while a mage sorted his bag; a hunter's client predicted a pickup the server rejected, leaving a ghost beam on the floor. Combat felt great; collection felt like inventory admin.

Item pickup systems are the bridge between loot rolls and inventory grants. They decide when a world entity becomes yours: manual interact, walk-over collision, magnet radius, vacuum abilities, and the fly-to-player motion that sells satisfaction without blocking movement. This guide covers pickup mode taxonomy, entity lifecycle, proximity queries and priority, magnet curves, full-bag filtering, multiplayer authority, the Harbor Siege vault refactor, a technique decision table, pitfalls, and a production checklist.

Pickup mode taxonomy

Pickup mode is a per-item or per-category rule, not a global game setting. Mixing modes without clear visual language creates “why didn't that pick up?” tickets:

Mode	Trigger	Best for
Manual interact	Player presses use on highlighted drop	High-value gear, quest items, tactical choice
Walk-over	Feet overlap pickup collider	Currency shards, ammo, consumables
Magnet radius	Enter radius; item accelerates toward player	ARPGs, horde modes, dense loot showers
Auto vacuum	Ability or buff collects all in range instantly	Ultimates, post-wave cleanup, quality-of-life perks
Deferred queue	Items wait until combat ends or room clears	Boss arenas, extraction shooters, cutscenes

Harbor Siege standardized: currency and crafting mats use magnet plus walk-over; rare-and-above gear uses magnet with a 0.4s hover beat so rarity beams read before the item vanishes; quest uniques stay manual interact via the interaction system.

World drop entity lifecycle

Treat every drop as a state machine shared by client VFX and server authority:

Spawned — server creates instance ID, item def, quantity, owner scope (personal vs party), optional despawn timer.
Idle — physics settle, bob animation, beam VFX; claimable by eligible players.
Reserved — one player or party won distribution; others see greyed mesh or no collider.
Collecting — fly-to-player arc in progress; entity no longer claimable.
Granted — inventory mutation committed; UI toast and audio fire.
Despawned — entity removed; timer or cleanup after grant failure (bag full).

Never delete the world entity before the server confirms the inventory grant. Clients may hide the mesh early for juice, but the authoritative ID must survive until grant_ok or a logged failure reason.

Proximity detection and priority

Each tick (or fixed physics step), query nearby drops against the player capsule. Production patterns:

Spatial indexing

Grid or BVH bucket world drops so you do not scan every entity in the level. Rebuild buckets when drops spawn in bursts (boss death). Cap per-frame pickup evaluations to avoid spikes when forty items land at once.

Priority when crowded

If magnet radius overlaps many items, collect in priority order:

Quest and objective items first
Highest rarity or ilvl
Currency and stackables (cheap to grant)
Distance (nearest first) as tiebreaker

Stagger starts by 2–4 frames so fly arcs do not stack into one unreadable blob. Harbor Siege limits concurrent collecting animations to six per player.

Line of sight and height

Optional LOS ray from player chest to drop center prevents picking loot through walls unless you explicitly want wall-phasing magnets in arcade modes. Vertical offset matters in multi-floor arenas: use separate floor layers or Z-band filters.

Magnet radius and fly-to-player motion

Magnet collection is two phases: activation (enter radius) and homing (motion toward attach point, usually chest or hand socket).

Parameter	Typical range	Design effect
Base radius	1.5–4 m	Larger = less walking, less tactile grounding
Radius modifiers	+10–50% from perks	Build identity; cap to protect performance
Accel curve	Ease-in then snap	Slow start sells beam; fast finish clears floor
Max homing time	0.3–1.2 s	After timeout, teleport to player to prevent stuck loot
Attach offset	Chest or weapon hand	Consistent with first-person vs third-person camera

Audio layers: soft tick on magnet activate, pitch rise during homing, distinct chime on grant by rarity tier. Pair with brief juice (scale pop, particle streak) but keep motion readable in co-op where ten players each homing forty drops can saturate VFX budgets.

Full bag, filters, and grant failures

Pickup must consult inventory capacity before starting homing, not after the item reaches the player:

Stackables — grant partial stacks; leave remainder on ground with updated quantity label.
Unique gear — if no slot, leave drop idle and show “inventory full” once per second max (no spam).
Currency — usually bypasses bag limits; grant to wallet directly.
Auto-loot filters — “ignore common below ilvl X” keeps magnets from refilling junk; unfiltered drops stay on ground for manual salvage.

Failed grants should log reason codes (BAG_FULL, NOT_ELIGIBLE, DISTRIBUTION_PENDING) for QA and live ops. Harbor Siege added a post-encounter stash vacuum that only collects items passing the player's loot filter after the boss door locks.

Multiplayer authority

The server owns eligibility and grants. Clients predict homing for responsiveness:

Client detects overlap, sends pickup_request(drop_id).
Server validates distance, ownership, distribution rules, bag space.
On success: broadcast collecting to observers; apply inventory delta; ack initiating client.
On failure: reject with reason; client snaps drop back to idle position.

Rate-limit requests per player (e.g. 20/s) to block pickup spam macros. Personal loot instances never share one world entity ID across players; each eligible player gets a distinct drop clone or a personal-only collider to prevent steal-by-latency arguments.

Harbor Siege vault refactor (worked example)

Vault of Tides shipped with manual interact on all boss loot. Refactor goals: zero despawn losses, under thirty seconds post-boss cleanup, readable rarity.

Changes shipped:

Unified PickupComponent on all drops — mode, radius, priority tier, despawn timer from data table.
Staggered magnet wave — on boss death, drops spawn with 50 ms index offset; magnet activates after physics settle (300 ms).
Grant-before-hide — server grants inventory, then signals VFX; removed client-only deletion that caused ghost items.
Concurrent fly cap — six active homing arcs; queue rest with visible “+N loot incoming” UI chip.
Party scope hook — integrated with need/greed resolution before magnet activates on rare drops.
Telemetry — time-to-clear-floor, grant failures by reason, despawn without grant (target zero).

Median post-boss loot time fell from 3m 50s to 28s; despawn-without-grant incidents went from 12 per thousand runs to zero over two weeks.

Technique decision table

Approach	Use when	Avoid when
Manual interact only	Sparse loot, strong identity per item	Horde drops, currency fountains
Walk-over only	Simple mobile runners, clear paths	Dense 3D arenas with verticality
Magnet radius	ARPG pacing, frequent small drops	Simulation games selling physical looting
Deferred queue	Boss spectacle, narrative beats	Open-world always-on exploration
Auto vacuum ability	Build reward, end-of-wave cleanup	Every player has it from minute one
Interact via prompt system	Quest items, containers, NPC handoffs	Thirty identical commons on the floor

Common pitfalls

Grant after VFX — crash mid-flight loses items; commit inventory first.
One global magnet radius — currency and legendaries need different feel and priority.
No stagger on boss bursts — forty simultaneous physics bodies tank frame time.
Client-authoritative pickup — dupes and steal disputes; server must validate.
Ignoring distribution state — magnet collects before need/greed resolves.
Despawn timer shorter than loot phase — Harbor's original 60 s timer during 4 m cleanup.
Full bag silent fail — players think magnets are broken; surface one clear message.

Production checklist

Pickup mode defined per item category in data, not hard-coded per prefab.
Entity lifecycle states logged from spawn through despawn.
Spatial query budget capped; boss drops use staggered spawn.
Priority order documented for overlapping magnet activations.
Grant validated before homing starts; partial stack math tested.
Full-bag and filter-fail UX with rate-limited player feedback.
Server-authoritative requests with client prediction and reject snapback.
Personal loot uses non-shared drop IDs per eligible player.
Despawn only after grant or explicit abandon with telemetry.
Rarity VFX readable during hover beat before collection.
Co-op VFX budget: concurrent homing cap per player.
Integration tests: boss burst, bag full, latency reject, party scope.

Key takeaways

Pickup is a pipeline, not a collider on a prefab.
Match mode to item role: magnets for flow, interact for meaning.
Grant inventory before you hide the world entity.
Stagger dense drops for performance and readability.
Server eligibility prevents dupes and co-op arguments.