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.

This integration is built and supported for RevFramework systems only. It is not intended as a general integration layer for third-party pickup or item-use systems.

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, providing a consistent execution path for Inventory-driven PickupEffect usage.

4. PickupEffectInvoker

(internal helper for full-context execution)

PickupEffectInvoker is the primary internal helper used by Inventory.

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 centralizes execution, making future extensions easier if needed.

🧩 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.

🌍 Third-Party / Custom System Use

This integration is built for RevFramework Inventory and Pickups systems only.

If you are using a different pickup or item-use system:

  • Treat this as a reference example
  • Implement your own bridge or resolver
  • Use the public APIs of each system

👉 Custom or third-party integrations are not supported by this layer.

📎 See Also

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