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
A definition carrying a health-percent condition is built through the Health-aware factory when Health is installed, so the same asset gates identically whether it is collected from the world or used from a bag

All resolved effects execute through PickupEffectRunner, which is also what a world pickup uses — so an effect behaves the same on both routes and reports refusals on both.

4. PickupEffectInvoker — removed¶

It was never the execution path, despite what this section used to say

This section described PickupEffectInvoker as "the primary internal helper used by Inventory" and stated that all resolved effects executed through it. Neither was true: the type was internal with zero callers, unreachable by the framework and by buyers alike, and the safe stub it described for the Pickups-absent case had already been removed as unreachable.

It could not be wired in either. The live path is PickupEffectRunner.TryApply, called from the bridge's own adapter, and it is used for a concrete reason: it returns whether the payload was delivered, and ItemUseSystem needs that answer to decide whether to consume the item. The invoker returned void, so routing through it would have restored the defect where a potion drunk at full health was consumed for nothing. Unwireable and unreached, it has been deleted.

ItemUseContext still reaches effects that implement IPickupEffectWithContext — through the resolver, which was always where it came from.

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