Skip to content

🧠 Pickups System — Mental Model

This page explains how to think about the RevFramework Pickups system.

It is not a code reference and it is not a step-by-step setup guide.

Its job is to help you understand:

  • what Pickups is responsible for
  • what the main moving parts are
  • how those parts connect
  • where to extend the system safely
  • where Pickups stops and another system begins

🎯 Core Idea

A Pickup is not “an item on the ground.”

A Pickup is:

a trigger or interactable that decides whether an actor may consume something, then applies an effect if allowed.

That effect may be:

  • pure Pickups logic
  • a gameplay-side utility effect
  • a decorator-enhanced effect chain
  • an optional cross-system integration effect

So the mental model is:

Actor enters or interacts
→ pickup checks filters / mode / authority
→ pickup holds or resolves an effect
→ effect is applied
→ optional decorators wrap that effect
→ optional feedback / destroy / respawn flow happens

Pickups is therefore best understood as a consumption pipeline, not as a loot database or item economy.

🧱 The System in One Sentence

Pickups turns a world interaction into effect application.

It handles:

  • world pickup entry
  • interaction flow
  • authority checks
  • trigger forwarding
  • effect application
  • decorator composition
  • success/failure feedback hooks

It does not own broader game systems like:

  • inventory progression
  • economy rules
  • health rules
  • status stacking policy
  • save systems
  • quest progression

Those systems may integrate with Pickups, but Pickups does not define them.

🧭 The Main Layers

Think about Pickups in five layers.

1. Definitions

Definitions are the authoring layer.

They describe what kind of pickup effect should be built and what decorator data should be applied.

Examples:

  • PickupEffectDefinitionBase
  • TeleportPickupDefinition
  • AnimatorTriggerPickupDefinition

A definition is data, not the thing that runs in the world.

2. Effects

Effects are the runtime payload.

They are the actual logic that runs when a pickup is consumed.

Examples:

  • PickupEffect
  • TeleportEffect
  • AnimatorTriggerEffect
  • CompositeEffect

If a definition is the blueprint, the effect is the thing that actually executes.

3. Decorators

Decorators are wrappers around effects.

They let you add behaviour around a core effect without changing the core effect itself.

Typical built-in examples:

  • sound
  • VFX
  • persistent VFX
  • conditional gates
  • debug logging

Mental model:

core effect
wrapped by decorator
wrapped by another decorator
wrapped by another decorator

So the pickup does not run separate systems — it runs one effect chain.

4. Runtime Pickup Components

These are the Unity-facing world behaviours.

They decide when something should try to consume the pickup.

Examples:

  • TriggerPickup
  • InteractablePickupBase
  • TriggerRelay2D
  • TriggerRelay3D

These are the bridge between world interaction and effect application.

5. Integration Seams

These are the seams where Pickups can cooperate with other systems without becoming tightly coupled.

Examples:

  • IPickupAuthority
  • PickupAuthority
  • custom effects calling into other systems (Health, Inventory, etc.)

This is where Pickups stays modular: it can work alone, or participate in larger gameplay flows.

🔁 End-to-End Flow

World Pickup Flow

World pickup exists
→ actor enters trigger
→ relay forwards trigger
→ pickup validates actor
→ pickup checks authority
→ pickup applies effect (via runner)
→ decorators run around the effect
→ success path finishes
→ pickup destroys or re-arms

Interactable Pickup Flow

Actor enters interactable range
→ interactable tracks actor
→ prompt / input / hold flow runs
→ pickup attempts DoPickup(actor)
→ success or failure path resolves
→ feedback hooks fire
→ pickup destroys or respawns

🧠 The Three Questions Pickups Answers

Whenever you are working inside this system, think in terms of three questions.

1. Can this actor consume this pickup?

Handled by:

  • trigger presence
  • filters (layer/tag)
  • facing checks
  • interaction mode
  • optional authority
  • custom interactable logic

2. What should happen if they do?

This is the effect layer:

  • apply an effect
  • apply a composed chain
  • optionally route with context
  • optionally call external systems

3. What should wrap the experience?

This is everything around the effect:

  • decorators
  • VFX / SFX
  • conditional gates
  • prompt UI
  • feedback
  • destroy / respawn

🪓 What Pickups Is Not

This matters because it prevents misuse.

Pickups is not:

Not an inventory system

Pickups may grant items, but does not manage storage or slots.

Not a health system

Pickups may heal, but does not own health rules.

Not a status system

Pickups may apply effects, but does not manage stacking/lifetimes.

Not a save/load system

Persistence is handled elsewhere.

Not a full interaction framework

Only pickup-style interactions are supported.

🧩 Where To Extend the System

Ask:

Which layer owns this concern?

Add a new runtime effect

Use:

  • PickupEffect
  • optionally IEffectAllowsNullDamageable
  • optionally IPickupEffectWithContext

Add wrapping behaviour

Use:

  • PickupEffectDecorator
  • IPickupDecoratorCreator
  • IPickupDecoratorRegistry

Add a new authoring type

Use:

  • PickupEffectDefinitionBase

Change how pickups are consumed

Use:

  • TriggerPickup
  • InteractablePickupBase
  • IPickupTriggerReceiver

Add authority rules

Use:

  • IPickupAuthority

Add feedback

Use:

  • IPickupFeedback
  • IPickupFailFeedback

🏗 Definition → Effect → Decorator Relationship

Definition (data)
→ builds Effect (logic)
→ wrapped by Decorators (behaviour layers)
→ applied by runtime component

🌍 World Pickup Mental Model

A world pickup is just a delivery mechanism.

TriggerPickup does NOT know gameplay logic.

It only:

  • detects entry
  • validates actor
  • checks authority
  • applies effect
  • handles lifecycle

Delivery ≠ Payload

🎮 Interactable Pickup Mental Model

InteractablePickupBase adds richer entry rules:

  • input
  • hold timing
  • prompts
  • UX hooks

Interactables are pickups with more complex entry conditions.

🔒 Authority Mental Model

Authority is optional.

  • No authority → pickup works normally
  • Authority present → pickup must pass permission

Think of IPickupAuthority as:

a permission layer, not gameplay logic

🧪 Debugging Mental Model

When something breaks:

  1. Runtime trigger
  2. Effect chain
  3. Effect logic
  4. UX/lifecycle

🪜 Learning Order

  1. PickupEffect
  2. PickupEffectDefinitionBase
  3. PickupEffectFactory
  4. PickupEffectDecorator
  5. TriggerPickup
  6. InteractablePickupBase
  7. authority / feedback

📌 Practical Rule of Thumb

  • What happens → Effect
  • How it’s wrapped → Decorator
  • How it’s authored → Definition
  • When it triggers → Runtime component
  • Who can use it → Authority

TL;DR

Pickups is:

a modular effect-delivery pipeline for world and interactable consumption

Built from:

  • definitions
  • effects
  • decorators
  • runtime components
  • integration seams

Keep those boundaries clear and the system stays predictable, extensible, and easy to reason about.