Skip to content

🎁 Pickups — Decorators

Folder: Runtime/Systems/Pickups/Decorators

This folder contains the wrapper layer used to add behaviour around pickup effects without modifying the core effect itself.

Decorators are pickup effects that wrap another PickupEffect and run logic before and/or after it.

🎯 Purpose

The Decorators folder enables behaviour composition around pickup effects.

It is responsible for:

  • defining the base decorator type
  • providing registry and creator contracts
  • supplying built-in decorator implementations
  • supplying built-in creator implementations

This folder does not include:

  • the main effect execution pipeline
  • cooldown storage
  • context-aware dispatch
  • authoring definitions
  • scene triggers or interactables

📦 Folder Overview

This folder provides:

  • wrapper-based effect composition
  • before and after execution hooks
  • optional cancellation before inner execution
  • factory-driven construction via creators

🧩 What Lives Here

  • PickupEffectDecorator → base decorator type
  • DecoratorType → built-in decorator identifiers
  • IPickupDecoratorCreator → decorator factory contract
  • IPickupDecoratorRegistry → creator registry abstraction
  • DefaultPickupDecoratorRegistry → default registry implementation

Built-in decorators:

  • ConditionalDecorator
  • DebugLogDecorator
  • VFXDecorator
  • PersistentVFXDecorator
  • SoundDecorator

🧠 Usage Guidance

Decorator Execution Model

A decorator wraps another effect and runs logic around it.

Execution flow:

  1. BeforeApply(...)
  2. optional cancellation
  3. wrappedEffect.ApplyTo(...)
  4. AfterApply(...)

Notes:

  • cancellation prevents both inner execution and AfterApply(...)
  • wrapped effects still execute through their own standard pipeline
  • null wrapped effects result in no execution

Factory Integration

Decorators are constructed by PickupEffectFactory.

Construction flow:

  1. create the core effect
  2. collect decorator definitions
  3. sort by ascending priority
  4. resolve creators
  5. wrap effects in order
  6. return outermost effect

Ordering:

  • lower priority wraps first
  • higher priority becomes outermost

Registry Behaviour

DefaultPickupDecoratorRegistry provides the default creator set.

  • registrations are deduplicated by runtime type
  • lookup scans from newest to oldest
  • later registrations take precedence

🧪 Diagnostics

Built-in decorators apply behaviour conditionally based on runtime context.

Typical behaviours include:

  • conditional gating (tag, random chance)
  • debug logging before execution
  • VFX spawning after execution
  • persistent VFX attachment
  • sound playback via AudioSFXChannel

Behaviour depends on provided context and available components.

⚠️ Important Notes

  • decorators wrap effects but do not replace the core pipeline
  • wrapped effects still enforce their own gating and cooldown rules
  • built-in decorators are internal implementations
  • users should extend via creators rather than relying on internal classes

🚫 Not for Production Use

This folder does not provide:

  • standalone gameplay systems
  • scene interaction logic
  • authority enforcement

It is a composition layer for effects.

  • Core
  • Definitions
  • Effects
  • Abstractions