Skip to content

🔌 Pickups System — Integration Surfaces

This page explains where new gameplay logic should integrate with the RevFramework Pickups system.

If you're adding new behaviour, start here.

The Pickups architecture is intentionally layered so that gameplay code can extend the system without modifying its internals. Each extension point exists for a specific responsibility.

Choosing the correct surface keeps systems predictable, maintainable, and compatible with the rest of RevFramework.

🧠 Integration Surfaces Overview

Goal Extension Surface Example
Add a new pickup behaviour PickupEffect teleport, spawn actor, apply buff
Wrap behaviour around an effect PickupEffectDecorator play VFX/SFX, conditional gate
Create a new pickup asset type PickupEffectDefinitionBase custom ScriptableObject definition
Customize decorator creation IPickupDecoratorCreator custom decorator pipeline
Replace decorator resolution IPickupDecoratorRegistry alternate decorator registry
Control multiplayer authority IPickupAuthority server authority, owner checks
Add success feedback IPickupFeedback play sound, spawn particles
Add failure feedback IPickupFailFeedback flash, deny sound
Create new world pickup behaviour TriggerPickup trigger-based pickup
Create custom interactable pickups InteractablePickupBase press / hold interaction
Integrate other gameplay systems Effects / decorators health, inventory, economy

🧱 Add a New Pickup Behaviour

Use:

PickupEffect

This is the core extension surface when the behaviour belongs to the payload of the pickup.

Examples:

  • teleport player
  • grant currency
  • apply status
  • spawn actor
  • trigger animation
PickupDefinition
→ builds PickupEffect
→ effect runs when pickup is consumed

🎨 Wrap Behaviour Around an Effect

Use:

PickupEffectDecorator

Decorators wrap another effect and run before or after it.

Examples:

  • spawn VFX
  • play sound
  • add random chance
  • add conditional gates
Decorator
→ runs before effect
→ runs effect
→ runs after effect

Decorators allow behaviour to be added without modifying the core effect.

🧩 Create a New Pickup Asset Type

Use:

PickupEffectDefinitionBase

Definitions are authoring assets used by designers and tools.

They describe:

  • what effect to build
  • what decorators to apply
  • configuration data

Definitions should not contain runtime logic.

🏗 Customize Decorator Creation

Use:

IPickupDecoratorCreator

This allows custom decorator construction logic.

Typical uses:

  • custom decorator categories
  • decorator pipelines
  • specialized effect wrapping

Decorators are resolved through the registry used by the factory.

🔐 Add Multiplayer Authority Rules

Use:

IPickupAuthority

This interface determines whether a pickup may be consumed by a given actor.

Typical implementations:

  • server-authoritative gameplay
  • ownership checks
  • permission systems

The system resolves authority through:

PickupAuthority.Resolve(...)

If no authority is present, pickups proceed without authority gating.

🔔 Add Feedback

Feedback should not modify gameplay logic.

Instead use:

IPickupFeedback
IPickupFailFeedback

Examples:

Success feedback:

  • play sound
  • spawn particles
  • UI confirmation

Failure feedback:

  • flash red
  • play error sound
  • UI message

🌍 Create New World Pickup Behaviour

Use:

TriggerPickup

This component handles:

  • trigger entry
  • actor validation
  • optional authority checks
  • effect application
  • destroy or respawn behaviour

Extend or compose around it if you need custom world pickup logic.

🎮 Create Custom Interactable Pickups

Use:

InteractablePickupBase

This provides a richer interaction flow:

  • auto pickup
  • press-to-pickup
  • hold-to-pickup
  • prompt UI
  • facing checks
  • respawn behaviour

Override DoPickup() to implement custom consumption logic.

❤️ Integrate Other Systems

Pickups does not depend on other gameplay systems directly.

Instead, integrations are typically implemented through:

  • custom PickupEffect implementations
  • decorators that wrap effects
  • external systems invoking PickupEffectRunner

Examples:

  • applying health changes
  • granting inventory items
  • awarding currency
  • applying status effects

Typical pattern:

PickupEffectDefinition
→ factory builds effect chain
→ effect or decorator calls into external system

This keeps the Pickups system modular and dependency-free.

⚠️ What Not To Extend

Avoid modifying:

  • internal decorator implementations
  • effect runner internals
  • cooldown systems
  • internal utility MonoBehaviours
  • reflection bridges or internal helpers

If behaviour does not fit any integration surface listed here, it likely belongs in another system.

🧠 Rule of Thumb

When adding behaviour ask:

Question Correct Surface
What happens when consumed? PickupEffect
What wraps that behaviour? PickupEffectDecorator
How is the pickup authored? PickupEffectDefinitionBase
What triggers the pickup? TriggerPickup / InteractablePickupBase
Who is allowed to consume it? IPickupAuthority
What UX surrounds the event? IPickupFeedback

If you follow this mapping, the Pickups system stays clean and composable.