🛡 Pickups System — System Guarantees Matrix¶

This page defines the runtime guarantees provided by the RevFramework Pickups system.

A guarantee means the system always behaves this way when used through its supported APIs and runtime components.

If something is not listed here, it should not be relied upon as a system invariant.

📌 Purpose¶

The guarantees matrix answers the question:

“What behaviour can gameplay code safely depend on?”

This is different from:

Document	Purpose
Overview	What the system does
Mental Model	How the system is structured
Public API	What developers can call
Guarantees Matrix	What behaviour is guaranteed

Area	Guarantee	Notes
Consumption	A pickup can only be consumed once per physics step	Prevents duplicate triggers from multi-collider actors
Effect execution	A successful pickup produces a single effect execution chain	Decorators wrap the effect into one deterministic chain
Destroy behaviour	A pickup either destroys or re-arms, never both	Controlled by `destroyOnUse` or respawn configuration
Trigger routing	Trigger events are routed through `IPickupTriggerReceiver` when using relay components	Relays normalize physics callbacks
Actor resolution	Actor GameObject passed to the pickup is resolved consistently from the trigger source	Rigidbody root is preferred when present

Area	Guarantee	Notes
Application routing	When using built-in runtime components, effects are applied via `PickupEffectRunner`	Ensures correct dispatch between standard and context-aware paths
Context routing	Context-aware effects receive `ItemUseContext` when provided	Runner selects the correct entrypoint automatically
Null target safety	Effects that do not implement `IEffectAllowsNullDamageable` will not run without an `IDamageable`	Enforced by `PickupEffect`
Context optionality	`ItemUseContext` values may be null or unset	Effects must tolerate missing data
Composite effects	Composite effects execute child effects in declared order	Each child enforces its own gating and cooldown rules

Area	Guarantee	Notes
Order	Decorators execute in deterministic priority order	Lower priority wraps first
Wrapping	Decorators form a single nested execution chain around the core effect	Built by `PickupEffectFactory`
Cancellation	A decorator may cancel execution of the wrapped effect chain	Cancelling skips the wrapped effect and any inner decorators
Chain stability	Decorator structure is fixed after factory construction	Runtime does not mutate the chain

Area	Guarantee	Notes
Authority check	Pickups do not execute effects when authority explicitly denies the action	Checked through `PickupAuthority`
Optional authority	If no authority implementation is resolved, pickups proceed normally	Authority is optional
Resolver consistency	Authority resolution follows a consistent lookup path (context → scene → global fallback)	Ensures predictable behaviour

Area	Guarantee	Notes
Success feedback	Success feedback executes after a successful pickup	Triggered by runtime components
Failure feedback	Failure feedback executes when pickup conditions fail	Effect is not applied in this case
Feedback isolation	Feedback components do not affect effect execution logic	Purely presentation/UX

Area	Guarantee	Notes
Interaction modes	Interactable pickups support Auto, Press, and Hold modes	Defined by `PickupMode`
Prompt behaviour	Prompt UI is shown only when interaction requires input	Hidden for Auto mode
Facing checks	Facing requirements are optional and configurable	Controlled by dot threshold
Respawn behaviour	Respawn restores visibility and interaction state without duplicating objects	Same instance reused
Duplicate prevention	Trigger-based pickups guard against multi-collider double-consume within the same physics step	Internal latch mechanism

Area	Guarantee	Notes
System independence	Pickups does not require other gameplay systems to function	Fully standalone
Integration model	External systems integrate through effects or decorators	No hard dependencies
Determinism	Integration behaviour runs within the same effect chain	Preserves execution order

The system intentionally does not guarantee:

These responsibilities belong to other systems or the host project.

The Pickups system guarantees:

Everything else is intentionally delegated to integrations or higher-level gameplay systems.