Skip to content

RevFramework – Pickups System

Overview

What Pickups is

The Pickups module is a modular, netcode-agnostic pickup and effect pipeline for Unity. It lets you create collectibles and trigger effects — from simple interactions to fully decorated, authority-aware pickups — all using a unified system.

Key Design Goals

  • Unified pipeline: World pickups and interactables all execute through the same PickupEffect model.
  • Extensible by design: Add decorators, feedback, or authority rules without modifying core logic.
  • Deterministic behaviour: Consistent execution through effect chains, cooldowns, and optional authority checks.
  • Zero lock-in: Works standalone or alongside systems like Inventory, Currency, or Health.

What’s Included

Category Purpose
PickupEffect Base class for all runtime effects.
PickupEffectFactory Builds decorated effect chains from definitions.
PickupEffectDecorator Wraps effects with additional behaviour (VFX, SFX, conditions).
TriggerPickup Trigger-based world pickup component.
InteractablePickupBase Interactable pickup component (Auto / Press / Hold).
PickupAuthority Authority resolver for validating pickup consumption.
Feedback Components Play sounds, VFX, or visual feedback on success/failure.
ShieldSystem Runtime helper used by shield-based pickups.
Teaching Panels Runtime panels for testing and learning the system.
Demo Scenes Example scenes demonstrating pickups, decorators, and interaction flows.

Hook-Up Summary

1. Create a Definition

Project ▸ Create ▸ RevFramework ▸ Pickups ▸ Definitions Configure behaviour and optional decorator settings.

2. Create a Pickup Prefab

Add one of:

  • TriggerPickup — world trigger (auto-consume)
  • InteractablePickupBase — interactable (Press, Hold, Auto)

Assign a PickupEffect (often built via a Definition).

3. Test It

Press Play and interact with the pickup.

The system will:

  • validate the actor
  • apply the effect
  • execute decorators
  • trigger feedback
  • destroy or respawn the pickup

Integration with Other Modules

Pickups does not depend on other systems directly.

Instead, integrations are implemented through:

  • custom PickupEffect logic
  • decorators that wrap behaviour
  • optional bridges or adapters

Examples include:

  • granting items
  • awarding currency
  • applying health changes
  • triggering gameplay systems

Multiplayer Note

Pickups is netcode-agnostic.

It provides:

  • authority checks (IPickupAuthority)
  • resolution logic (PickupAuthority)

It does not provide

  • replication
  • RPC handling
  • spawning/despawning

Your networking solution is responsible for those concerns.

Quote

🗝️ Pickups decides “can this be consumed?” — your netcode decides “who owns the world.”

Extension Points

  • Subclass PickupEffect to create new gameplay behaviour.
  • Use PickupEffectDecorator to wrap behaviour around effects.
  • Implement IPickupDecoratorCreator to extend the decorator pipeline.
  • Extend InteractablePickupBase for custom interaction logic.
  • Implement IPickupAuthority for custom permission rules.
  • Implement IPickupFeedback / IPickupFailFeedback for UX behaviour.

Typical Usage

bool delivered = PickupEffectRunner.TryApply(effect, damageable, actor);

This handles:

  • reporting, context-aware and standard dispatch
  • decorator execution
  • cooldown enforcement
  • null-damageable handling

…and returns whether the payload actually reached the actor.

Prefer TryApply over Apply

PickupEffectRunner.Apply(...) and PickupEffect.ApplyTo(...) return void. They still run the same gating, but they discard its answer — so a live cooldown, a decorator that cancelled and a clean delivery are indistinguishable to the caller.

That matters wherever something is consumed on apply. TriggerPickup uses TryApply and does not destroy itself over a refused payload. Use Apply only for an effect that cannot be refused, where there is nothing to read.

Authority and trigger logic are handled by the runtime pickup components.

Learning Resources

  • Demo Scenes Example pickup setups and interaction flows

  • Teaching Panels Runtime panels for inspecting behaviour

  • MkDocs Site /pickups/

  • Videos Quickstart, decorators, and authority breakdowns

Summary

TL;DR

Pickups is a modular effect-delivery pipeline.

It separates:

  • when something is consumed (runtime components)
  • what happens (effects)
  • how it is wrapped (decorators)
  • who is allowed (authority)

That separation is what makes the system:

  • extensible
  • testable
  • integration-friendly