Skip to content

🎁 Pickups System — Public API

This page defines the supported, stable public API for the RevFramework Pickups System.

If something is not listed here, it is not supported as a public integration point — even if it appears accessible in code.

Audience: Developers integrating Pickups into gameplay, tools, or UI
Scope: Runtime public API, supported runtime components, and supported extension seams
Stability: Breaking changes to items listed on this page are avoided or clearly versioned

📌 Core Concepts

  • Pickups are built around effects (PickupEffect) and definitions (PickupEffectDefinitionBase).
  • World pickups and interactables are provided as Unity-facing runtime components.
  • Effect construction is factory-driven and supports decorator composition.
  • Public APIs are intentionally kept smaller than the total code surface.
  • Internal helpers, internal concrete implementations, and test-only visibility hooks are not part of the supported contract.

🧱 Core Runtime Effect Model

PickupEffect

The base class for pickup effects using the standard apply path.

Responsibilities

  • Defines the core effect contract for pickup execution
  • Applies cooldown gating on the standard apply path
  • Enforces null-damageable policy unless the effect explicitly allows otherwise
  • Provides the base extension surface for custom pickup effects

IEffectAllowsNullDamageable

Marker interface for effects that can run without an IDamageable.

Typical uses include:

  • VFX-only effects
  • transform/movement effects
  • animator-trigger effects
  • other context-only behaviour

IPickupEffectWithContext

Optional richer effect entrypoint for effects that need item/source context.

Supported scenarios include:

  • inventory-driven item use
  • slot-aware effects
  • ownership/source-sensitive logic
  • telemetry / analytics
  • custom context-sensitive logic

Important: Effects using this interface are invoked directly by PickupEffectRunner and do not automatically go through the standard PickupEffect.ApplyTo(...) gating path.

ItemUseContext

Structured advisory context passed to context-aware effects.

Contains:

  • item definition
  • owner
  • slot index

All values are advisory and may be partially populated.

PickupEffectRunner

Canonical helper for applying pickup effects across:

  • world pickups
  • inventory-driven use
  • integrations that need consistent dispatch between standard and context-aware effects

PickupEffectFactory

Builds decorated pickup effect chains from authorable definitions.

Responsibilities:

  • creates the core effect from a definition
  • applies decorators in priority order
  • allows registry replacement
  • allows custom decorator creator registration

PickupEffectStaticCooldowns

Global in-memory cooldown store used by the standard pickup effect path.

Supported for:

  • reset flows
  • deterministic test setup
  • explicit owner cooldown cleanup
  • runtime cooldown clearing when required by project logic

🧩 Definitions & Authoring Surface

PickupEffectDefinitionBase

The abstract ScriptableObject base for pickup effect definitions.

Derive from this type to create custom authorable pickup definitions.

DecoratorDefinition

Authoring record describing:

  • decorator type
  • decorator priority

Used by PickupEffectDefinitionBase.decorators.

Supported Built-in Definition Types

  • AnimatorTriggerPickupDefinition
  • ShieldPickupDefinition
  • TeleportPickupDefinition
  • VfxBurstPickupDefinition

✨ Supported Built-in Effect Types

  • AnimatorTriggerEffect
  • CompositeEffect
  • TeleportEffect
  • VfxBurstEffect

Some built-in definitions may create internal concrete effect implementations.
Those internal implementation types are not automatically supported as public extension points unless listed on this page.

🎨 Decorator Extension Surface

PickupEffectDecorator

Base class for decorator-style pickup effects.

Use this when you want to wrap another effect and run logic:

  • before application
  • after application
  • conditionally cancel the wrapped effect

DecoratorType

Well-known decorator categories used by the factory and creator pipeline.

Built-in categories:

  • VFX
  • Sound
  • DebugLog
  • Conditional
  • PersistentVFX

IPickupDecoratorCreator

Extension contract for custom decorator creation.

IPickupDecoratorRegistry

Registry contract used by PickupEffectFactory.

Supported Built-in Creator Types

  • ConditionalDecoratorCreator
  • DebugLogDecoratorCreator
  • PersistentVFXDecoratorCreator
  • SoundDecoratorCreator
  • VFXDecoratorCreator
  • DefaultPickupDecoratorRegistry

🔐 Authority Surface

IPickupAuthority

Defines whether an actor is allowed to consume a pickup.

PickupAuthority

Resolver/cache for locating an active IPickupAuthority from scene, hierarchy, or fallback runtime context.

PickupAuthorityBinder

Default MonoBehaviour implementation of IPickupAuthority.

Suitable for simple single-player setups, demos, or placeholder authority behaviour.

🔔 Feedback Surface

IPickupFeedback

Success feedback contract.

IPickupFailFeedback

Failure feedback contract.

Built-in Feedback Components

  • PickupSuccessSFX
  • PickupSuccessVFX
  • PickupFailSFX
  • PickupFailFlash

🌍 Unity Runtime Components

TriggerPickup

Trigger-driven world pickup that applies a PickupEffect when an allowed actor enters.

Supported behaviour includes:

  • layer filtering
  • optional tag filtering
  • optional authority checks
  • duplicate-consume protection for multi-collider actors

InteractablePickupBase

Abstract Unity-facing base class for interactable pickups supporting:

  • Auto, PressToPickup, and HoldToPickup modes
  • optional facing checks
  • optional respawn behaviour
  • prompt UI support
  • success/failure feedback hooks
  • trigger-forwarded interaction flow

PickupMode

Interaction modes:

  • Auto
  • PressToPickup
  • HoldToPickup

Trigger Relay Components

  • TriggerRelay2D
  • TriggerRelay3D

These forward Unity trigger callbacks into the pickup trigger receiver contract.

IPickupTriggerReceiver

Shared trigger-forwarding contract used by trigger relays and pickup runtime components.

🏗 Prefab Authoring Surface

Used by pickup prefab builders and tooling:

  • PickupDimension
  • Collider2DType
  • Collider3DType
  • PickupPrefabSettings

Other Supported Runtime Components

  • PickupBillboard
  • ShieldSystem

ShieldSystem is a supported runtime component used by shield-based pickup flows.

❌ Explicitly Not Supported

The following are not supported public extension points unless explicitly documented elsewhere:

  • internal concrete decorator implementations
  • internal utility MonoBehaviour helpers
  • reflection into pickup internals
  • test-only visibility files
  • private/internal runtime state manipulation
  • relying on internal bridge/helper classes

TL;DR

If a type appears on this page, treat it as a supported public API surface.

If it does not appear here, treat it as internal implementation detail, even if it is visible in code.