Skip to content

🎁 Using the Pickups System

The Pickups system is a modular, decorator-driven, netcode-agnostic pipeline for collectible items and interactables. It scales from simple world pickups (health, currency, VFX) to fully authored interactables with decorators, authority binders, and UX feedback — all without hard-coupling to Inventory, Health, Currency, or any other system.

✔ Modular & decoupled
✔ Works standalone or integrated
✔ Designer-friendly ScriptableObject authoring
✔ Netcode-agnostic, with sample binders for NGO/Mirror/Fusion
✔ Fully extensible via effects, decorators, and authority rules

📦 Overview

Pickups are built from the following layers:

  1. Effects → what actually happens (heal, VFX, give item, give currency, teleport, etc.)
  2. Decorators → wrappers that add behaviour (SFX, VFX, conditions, debug, cooldown logic)
  3. Definitions → ScriptableObjects that author effects + decorator configuration
  4. Runtime Components → world pickups, interactables, triggers
  5. Authority Binders → optional SP/MP mutation-gating
  6. Feedback Hooks → VFX/SFX/flash for success and failure states

Everything flows through a unified effect pipeline:

Authority → Effect → Decorators (inner → outer) → Feedback

Authority is resolved before the effect pipeline executes.
Decorators wrap the effect itself and may block, extend, or augment behaviour.

🚀 Quickstart (60 Seconds)

1️⃣ Create a Definition

Project → Create → RevFramework → Pickups → Definitions → Instant Heal

Configure: - Heal amount - Optional decorators (VFX, SFX, conditions, debug) - Optional sprite/icon metadata

Definitions are authoring assets — they are converted into runtime effects by the factory/tooling.

2️⃣ Add Decorators

Decorators wrap the core effect with additional behaviour.

Decorator ordering rules (important):

  • Decorators are applied in ascending priority order
  • Lower priority values wrap first (inner)
  • Higher priority values wrap later (outer)

Decorators can: - Cancel execution - Add side effects (VFX/SFX) - Gate execution (conditions, RNG) - Add debug or telemetry behaviour

3️⃣ Create a World Pickup

Add a prefab with EffectPickupCore:

  • Assign a PickupEffect (typically created from a Definition via tooling)
  • Configure trigger filters (layers, tags)
  • Enable destroy-on-use or re-arm behaviour

For interactables:

  • Derive from PickupInteractableCoreBase
  • Supports Auto / Press / Hold interaction modes
  • Ideal for chests, terminals, levers, diegetic pickups

Make sure the prefab includes the appropriate TriggerRelay2D or TriggerRelay3D.

4️⃣ Apply an Effect (Code)

Minimal runtime invocation:

var dmg = actor.GetComponentInParent<IDamageable>();

// Unified apply path (handles cooldowns, decorators, null-damageable rules)
PickupEffectRunner.Apply(effect, dmg, actor);

This path automatically: - Enforces cooldown policy - Applies decorator chains - Respects null-damageable rules

📂 Module Structure

Folder Purpose
Core/ Effect pipeline, cooldowns, decorator execution, and context handling.
Definitions/ ScriptableObject authoring layer.
Effects/ Built-in gameplay effect implementations.
Decorators/ Behaviour wrappers (VFX, Sound, Conditions, Debug, etc.).
Authority/ SP/MP authority resolution and binders.
Feedback/ UX hooks for success/fail feedback.
Unity/ Unity-facing MonoBehaviour integration: world pickups, interactables, triggers, prompts, helpers.
Utilities/ Lightweight helper components.
Samples/ Demo scenes and netcode integration examples.

⚙️ Scripting Define Symbols

The Pickups runtime does not use any scripting define symbols.

All netcode integrations live entirely in Samples assemblies.

Netcode Define Symbol
NGO REV_USE_NGO
Mirror REV_USE_MIRROR
Fusion REV_USE_FUSION

These defines: - Do not affect runtime behaviour - Are only required for sample binders + proxies - Are completely optional

The core Pickups system remains fully netcode-agnostic.

🧩 Extension Points

Safe, supported extension surfaces:

  • PickupEffect → New runtime gameplay effects
  • PickupEffectDecorator → Pre/post behaviour wrappers
  • IPickupDecoratorCreator → Register new decorator types
  • IPickupAuthority → Define who may mutate pickups (SP/MP)
  • IPickupFeedback / IPickupFailFeedback → Custom UX responses
  • PickupEffectFactory.SetRegistry(...) → Override or extend decorator registries

The system encourages explicit composition and avoids hidden magic.

🌐 Authority (Multiplayer)

Pickups are netcode-agnostic, but support authoritative mutation via binders.

Typical flow:

Client collides (no authority)
        ↓
Client routes request to server
        ↓
Server resolves IPickupAuthority
        ↓
Server applies effect + despawns pickup
        ↓
Netcode replicates removal / feedback
  • If no authority binder is present → consumption is allowed (single-player safe)
  • If a binder denies authority → local consume is rejected

See Samples/NetcodeSamples for NGO, Mirror, and Fusion patterns.

⚠️ Gotchas

  • Cooldown owner defaults to IDamageable, otherwise the context GameObject
  • Null-damageable execution is only allowed when the effect implements IEffectAllowsNullDamageable
  • Effects should not directly spawn VFX/SFX — use decorators
  • Interactables require the correct TriggerRelay2D / TriggerRelay3D
  • Authority rules are opt-in, never implicit
  • Decorators execute inner → outer and may block execution
  • Cooldowns are per-owner unless customised

🧠 Effect Cheat Sheet — Requires IDamageable?

Effect Needs Damageable?
InstantHealEffect ✅ Yes
RegenOverTimeEffect ✅ Yes
ShieldEffect ❌ No
TeleportEffect ❌ No
AnimatorTriggerEffect ❌ No
VfxBurstEffect ❌ No
GiveItemEffect ❌ No
GiveCurrencyEffect ❌ No
CompositeEffect Depends on child effects

❌ What Pickups Is Not

  • Not a full interaction framework (it provides hooks, not UI)
  • Not a mandatory inventory system
  • Not tied to any specific netcode solution
  • Not responsible for replication or prediction
  • Not a prefab kit — runtime logic only

📘 See Also

  • Core — effect & decorator pipeline
  • Definitions — ScriptableObject authoring
  • Decorators — wrapping & extending effects
  • Effects — built-in behaviours
  • Unity — triggers & interactables
  • Authority — mutation gating for SP/MP
  • Feedback — UX responses
  • Samples — demos & netcode integrations