Skip to content

📘 How to Use These Docs

RevFramework is not a single script or a “drop-in MonoBehaviour”. It’s a set of modular systems designed to be composed, extended, and learned incrementally.

This page explains how to read the documentation, so you don’t feel overwhelmed and don’t end up extending the wrong layer.

🧭 The Big Picture

Every system in RevFramework follows the same documentation pattern:

Overview
→ Mental Model
→ Public API
→ FAQ
→ Runtime Structure
→ Teachable Panels (Live)
→ Samples

You do not need to read everything.

Most developers only need one path depending on what they’re trying to do.

🟢 If You’re New (Read This Path)

If this is your first time using a system:

  1. Overview
  2. What the system is responsible for

  3. What it explicitly does not do

  4. Mental Model

  5. How data flows through the system
  6. Which layers mutate state vs observe

  7. Where your code should plug in

  8. Teachable Panels (Live)

  9. Open the provided Teachable Panel for the system
  10. See the system running live in Unity

  11. Toggle features, break things, and watch the output change

  12. Samples

  13. Open the 00 • Quickstart scene
  14. Run it, inspect it, and modify it

👉 Stop here unless you need to extend something.

🟡 If You’re Integrating a System

If you already understand the idea and want to wire it into your game:

  1. Mental Model

  2. Confirm where your logic belongs

  3. Public API

  4. Supported calls and extension points

  5. What is safe vs internal

  6. Teachable Panels

  7. Validate behaviour live against your expectations

  8. Use them as a reference implementation

  9. Runtime Folders

  10. See how the system is actually organised

  11. Match docs to real classes

  12. Samples

  13. Look for scenes that match your use case

🔵 If You’re Extending or Customising

If you want to add behaviour (rules, handlers, modifiers, adapters):

  1. Mental Model (mandatory)

  2. This prevents architectural misuse

  3. Public API

  4. Interfaces you are expected to implement

  5. Guaranteed-stable seams

  6. FAQ

  7. “Is this the right extension point?”

  8. “Can I do X with Y?”

  9. Teachable Panels

  10. Act as hostile consumers
  11. Exercise the public API exactly as a real project would

  12. If the panel works, the API is correct

  13. Samples

  14. Find an example doing something similar
  15. Copy patterns, not code blindly

🧪 Teachable Panels (Hostile Consumers)

Every major system in RevFramework ships with Teachable Panels.

These panels are not demos — they are hostile consumers:

  • They use only the public API
  • They assume nothing about internal implementation
  • They are designed to break if the API is wrong or misleading

If a Teachable Panel: - compiles - runs - behaves as documented

…then the public API is doing its job.

Why this matters

  • It prevents “it works in my code” APIs
  • It keeps documentation honest
  • It proves behaviour live, not just in text

YouTube Parity

Each Teachable Panel has a matching YouTube video.

What you see in the video: - is the exact same panel - with the same labels - driving the same code - producing the same behaviour

No slides. No mocks. No hand-waving.

🔴 If Something Isn’t Working

Before assuming it’s a bug:

  1. FAQ

  2. Most “why doesn’t this work?” cases live here

  3. Teachable Panels

  4. Does the panel behave the same way?

  5. If not, you’ve likely found a real issue

  6. Samples

  7. Does the same thing work in a sample scene?

  8. Mental Model

  9. Are you mutating state in the wrong layer?
  10. Are you bypassing the intended pipeline?

If it still looks wrong: - Reach out with what you tried, what you expected, and which layer you touched

🧱 Runtime vs Documentation vs Teaching

You’ll see three major categories:

Runtime/Systems/...

  • Shipped code
  • Organised by responsibility
  • Some folders are internal implementation details

Documentation/...

  • Mental models
  • API guarantees
  • Decision guidance

Teaching/...

  • Teachable Panels
  • Live validation tools
  • Hostile consumer tests

📌 Rule of thumb
If documentation and Teachable Panels disagree, the panel wins — and the docs should be updated.

🧠 Mental Model vs Public API (Important)

These two are intentionally separate:

Mental Model

Answers: - Where does this logic belong? - What layer is allowed to do what?

Public API

Answers: - What methods can I call? - What interfaces should I implement?

Reading API without the mental model often leads to misuse.

🧪 Samples Are Not Demos

Samples are: - Runnable - Inspectable - Editable - Intentionally simple

They are meant to be: - copied - modified - stripped down

If a feature exists, there is always a sample scene showing it.

⚠️ What You Don’t Need to Read

You can safely skip: - Internal folders (marked as such) - Systems you are not using - Advanced samples until you need them

RevFramework is designed so you can adopt one system at a time.

🧩 One Last Rule

If you find yourself asking:

“Where should this code go?”

You’re already in the right place — go back to the Mental Model.

✅ TL;DR

  • Start with Overview → Mental Model
  • Use Teachable Panels to see behaviour live
  • Use Samples to learn by doing
  • Use Public API to integrate safely
  • Use FAQ to avoid wrong extension points

This documentation is designed to prove behaviour, not just describe it.