Skip to content

🎁 Pickups — Documentation Guide

🧭 Where should I start?

🔹 New to Pickups?

Start with:

👉 System Overview (README + Mental Model)

This explains: - What the Pickups system is - How pickups move from world interaction to effect application - How Pickups separates definitions, effects, decorators, and runtime components - Typical setup and usage patterns

🔹 Want to know what you can safely depend on?

Read:

👉 PublicAPI/

This document defines: - The supported runtime surface - Stable types, components, interfaces, and extension seams - Guaranteed behaviours - Explicitly unsupported usage

If something is not listed there, it is not supported — even if it appears public in code.

This is the contract.

🔹 Adding gameplay or extending the system?

Start with:

👉 Integration Surfaces/

This shows exactly where logic belongs: - pickup effects - decorators and wrapping behaviour - definitions and authoring - authority and feedback - world and interactable runtime components

Then use:

👉 FAQ/

The FAQ answers questions like: - Should this be an effect, decorator, or interactable? - Why didn’t my pickup apply? - Why did it trigger twice? - How should other systems integrate? - What should I avoid?

It focuses on decision-making, not API reference.

🔹 Want the shortest explanation of how Pickups executes?

Read:

👉 Pickup Execution Flow/

This shows the main authored-data-to-runtime path:

  • definition
  • factory
  • effect chain
  • runtime pickup
  • runner
  • actor

Use it when you want the quickest mental model of how Pickups actually fits together.

🧠 How these documents work together

Document Purpose
Overview Explains the system
Public API Defines what is supported
FAQ Guides correct usage choices
Integration Surfaces Shows where new logic should plug in
Mental Model Explains how to think about the system
Pickup Execution Flow Shows the authored-data-to-runtime flow
Guarantees Matrix Defines behavioural contracts

Each document serves a specific purpose.
You do not need to read everything — start with what matches your task.

🛑 Important support note

RevFramework Pickups is:

  • Effect-driven
  • Definition-backed
  • Decorator-composed
  • Runtime-component delivered
  • Authority-aware
  • UX-extensible
  • Netcode-agnostic

Support is provided for:

  • Behaviour defined in PublicAPI
  • Usage patterns described in Overview, FAQ, Integration Surfaces, and Pickup Execution Flow
  • Guarantees listed in the Guarantees Matrix

Support is not provided for:

  • Depending on undocumented internal helpers
  • Reflecting into pickup internals
  • Putting gameplay logic into the wrong layer
  • Treating runtime pickup components as the gameplay payload
  • Assuming external systems are present unless your effects handle that explicitly

  • Teaching Panels
    Add debug or teachable panels to inspect pickup behaviour, decorators, and interaction flows live

  • Samples
    See /Samples/Pickups/ for runnable examples

  • MkDocs site
    Mirrors this documentation for web browsing

🧠 System philosophy

Pickups is:

  • An effect-delivery pipeline (not an inventory or loot database)
  • A layered system (definition → effect → decorator → runtime delivery)
  • A composition-first architecture (behaviour is wrapped, not hardcoded into world objects)
  • A netcode-agnostic interaction system (permission hooks exist; replication does not)

Every public extension seam exists for a reason.
If something feels unclear, you're likely using the wrong layer.

✅ TL;DR

  • Want to understand Pickups → Overview
  • Want the fastest runtime picture → Pickup Execution Flow
  • Want to build safely → Public API
  • Want to choose correctly → FAQ
  • Want to extend cleanly → Integration Surfaces

If you stay within these boundaries, Pickups will behave predictably and remain supportable.