Skip to content

📦 Inventory ↔ Pickups Integration

(Inventory/Bridges/Pickups)

Optional glue layer that allows Inventory items to trigger Pickups effects and vice‑versa.
This is not a hard dependency — the Inventory system works perfectly without Pickups installed.

If the Pickups module is NOT present:
Everything in this folder compiles out cleanly via #if REV_PICKUPS_PRESENT and safe stubs.
No errors. No missing references. No required setup.

Why this exists

Two major RevFramework modules often want to cooperate without coupling:

  • Inventory
    Stores item stacks, uses, equipment, and containers.

  • Pickups
    Handles world pickups, pickup effects, decorator chains, and item‑use context.

Common needs:

  • World pickup → add to inventory
  • Inventory item → run PickupEffect when used
  • Shared effect logic between physical pickups and inventory use

This folder provides those bridges, while keeping both systems fully optional and independent.

🔌 Contents

1. InventoryPickupInteractable

(world → inventory)

A world‑space pickup that adds an item into an inventory container when triggered.

svc.GiveExact(actor, new ItemStack { def = item, quantity = quantity }, container);
  • Compiled only when Pickups is installed
  • Acts like a normal world pickup
  • Accepts any Inventory owner (Player tag or CharacterInventory)

2. UnifiedPickup2D

(world → effect + inventory)

A 2D trigger pickup that can:

  • run a PickupEffect,
  • add an item to Inventory,
  • or both (EffectOnly / InventoryOnly / Both).

Inventory is resolved dynamically if present — no hard dependency.

3. UseEffectResolver → PickupEffect integration

(inventory item‑use → pickups effect)

This is the most important integration seam.

The bridge registers an external resolver:

UseEffectResolver.ExternalResolvers += ResolvePickupEffect;

This allows PickupEffect assets to be resolved dynamically when you call:

ItemUseSystem.TryUse(owner, slotIndex);

Key points:

  • Inventory never references Pickups directly
  • PickupEffect assets (and definition‑built effects) resolve at runtime
  • Effects implementing IPickupEffectWithContext receive full context

All resolved effects execute via PickupEffectInvoker, ensuring one consistent execution path.

4. PickupEffectInvoker

(internal choke point for full‑context execution)

PickupEffectInvoker is the only execution path used by Inventory when applying PickupEffect logic.

It guarantees full context:

ItemUseContext
{
    itemDef,
    owner,
    slotIndex
}

Behaviour:

  • Uses the rich path if IPickupEffectWithContext is implemented
  • Falls back to ApplyTo(IDamageable, GameObject) otherwise
  • Internal by design — not part of the public API
  • When Pickups is missing, a stub implementation safely no‑ops

This creates a single choke point for future extensions (telemetry, cooldowns, durability, audit, etc.).

🧩 Hard Dependencies?

No. Inventory never requires Pickups.

  • All bridge files are guarded by #if REV_PICKUPS_PRESENT
  • When the define is missing:
  • Bridges compile out
  • The invoker becomes a no‑op
  • UseEffectResolver does not resolve PickupEffect assets

Inventory remains fully functional.

🛠 When to Use These Bridges

Enable this folder when you want:

  • PickupEffect assets for consumables (healing, buffs, damage, etc.)
  • World pickups that drop directly into Inventory
  • Inventory item use to trigger the same effect system as physical pickups
  • Decorated effects via PickupEffectDefinitionBase

You do not need this folder if your project:

  • does not use Pickups
  • uses a custom item‑use system
  • handles pickups through different mechanics

❌ Not Included

This folder does not provide:

  • networking or replication of pickups
  • auto‑pickup radius logic
  • custom effect implementations
  • UI integration
  • stacking rules (handled by Inventory)
  • damage / health logic (handled by Common)

It is strictly integration glue, not gameplay.

🧪 Safe Behaviour When Pickups Is Missing

If Pickups is removed:

  • All bridges compile out
  • Inventory remains fully operational
  • Item use silently ignores PickupEffect assets
  • No editor or runtime errors occur

Zero lock‑in guaranteed.

📎 See Also

  • Inventory → Use — item‑use system
  • Pickups → Core — effect definitions & decorators
  • ItemUseSystem — where Inventory triggers effect resolution
  • UseEffectResolver — dynamic effect interface across modules