Skip to content

🎁 Pickups — Abstractions

Folder: Runtime/Systems/Pickups/Abstractions

This folder contains the public contracts and lightweight data structures used by the Pickups system.

These types define how effects are invoked and what context they may receive, without depending on any concrete implementation.

🎯 Purpose

The Abstractions layer defines the contract between the pickup system and effect implementations.

It exists to:

  • describe how effects are executed
  • define optional context-aware execution paths
  • provide safe extension points for custom pickup behaviour

This folder does not contain:

  • effect implementations
  • decorator logic
  • cooldown or gating systems

Those live in Core, Effects, and Decorators.

📦 Folder Overview

This folder provides:

  • execution contracts for pickup effects
  • optional context-aware execution interfaces
  • lightweight data structures for effect invocation

It is a public extension surface intended for integration and custom behaviour.

🧩 What Lives Here

Key types in this folder:

  • IEffectAllowsNullDamageable
  • IPickupEffectWithContext
  • ItemUseContext

These types are intentionally lightweight and do not contain runtime logic.

🧠 Usage Guidance

Standard Execution Path

PickupEffect.ApplyTo(IDamageable, GameObject)
  • Runs through built-in gating
  • Handles null-damageable checks and cooldown enforcement
  • Used by default for most effects

Context-Aware Execution Path

IPickupEffectWithContext.ApplyTo(...)
  • Called directly by the runner
  • Bypasses base gating
  • Provides access to additional context

Use this only when you need explicit control over execution rules.

⚠️ Important Notes

  • Context-aware execution does not apply base validation or cooldowns
  • Implementations must handle null checks and validation explicitly
  • IEffectAllowsNullDamageable only affects the standard execution path
  • ItemUseContext fields may be null or partially populated

🧩 Interfaces

IEffectAllowsNullDamageable

Marker interface that allows an effect to run without an IDamageable.

Use this when your effect:

  • does not modify health
  • operates on transforms, visuals, or audio
  • only requires a GameObject context

Notes:

  • applies only to the standard execution path
  • does not add validation

IPickupEffectWithContext

Optional interface for effects that require additional context.

void ApplyTo(IDamageable damageable, GameObject target, ItemUseContext ctx);

Use this when your effect needs:

  • item definitions
  • ownership or source tracking
  • slot index or metadata
  • custom cooldown handling

When implemented:

  • the system does not call the standard PickupEffect.ApplyTo(...) path
  • base gating is not applied automatically

📦 Data Structures

ItemUseContext

Lightweight struct describing the source of a pickup effect invocation.

Fields:

  • itemDef — optional ScriptableObject
  • owner — GameObject that triggered the use
  • slotIndex — index or -1 if not applicable

Rules:

  • all fields are optional
  • data may be partial or null
  • should be treated as advisory input

Typical uses:

  • item correlation
  • UI updates
  • analytics
  • conditional logic

🚫 Not for Production Use

This folder is not intended for:

  • gameplay logic implementations
  • decorators or execution pipelines
  • Unity scene components

It defines contracts only.

  • Core
  • Effects
  • Definitions
  • Decorators