Runtime/Common¶

Shared framework glue. Not a gameplay integration surface.

Runtime/Common holds two small presentation-adjacent helpers shared by samples, teachables and one Pickups decorator: an audio channel and a reason-text mapper. That is all of it.

The cross-system seams and foundation utilities are in Runtime/Core, not here — see the table below if you arrived looking for one. This folder is not where you build game features either.

Not a Supported Extension Point¶

• ❌ Not intended for gameplay integration
• ❌ Not intended as a primary public API surface
• ❌ Not a stable extension contract (contents may evolve as systems are refined)

If you’re integrating a system into your game:

👉 Start in Runtime/Systems/<System> and follow that system’s: - Public API - Mental Model - FAQ - Samples - Teachables

Teachables live in: RevFramework/Teaching
Samples live in: RevFramework/Samples

What Lives Here (so you don’t panic when you see it)¶

Common is two small folders and nothing else. It is much smaller than its name suggests, and that is deliberate — a folder called Common attracts everything unless somebody keeps saying no.

1) Audio/ — AudioSFXChannel¶

A one-field MonoBehaviour holding an AudioSource for SFX playback. It manages no pooling, routing or mixing; it exists so a component that wants to play a one-shot has somewhere on the GameObject to find one. SoundDecorator in the Pickups system looks for it.

See Audio/README.md.

2) UX/ — the ReasonText family¶

Maps machine-readable codes (usually enum names) to human-readable strings for teachables, samples and debug UI. Each system's mapping is a separate partial in its own file, compiled only when that system is present, so no system is forced to know about another's reason codes.

Runtime systems must not depend on ReasonText. A system that needs to explain itself does so through its own result type.

See UX/README.md.

What Does Not Live Here (and where it actually is)¶

Earlier versions of this page inventoried types that live elsewhere. If you came looking for one of these, it is not missing — it was never here:

One name on the old list has no row at all: ResolveUtility, which does not exist and never did. The name it echoes is ReflectionResolveUtility, removed in 1.0.4 — see the changelog if you are upgrading from 1.0.3 or earlier.

If you need a supported integration point, it should be documented on the System’s Public API page — not inferred from Common.

If you can’t do something through documented public seams, you shouldn’t be doing it.
If you believe a supported seam should exist: reach out — we’ll review it.

Design Intent¶

Common is a shared substrate:

• Systems depend on Common
• Nothing here should force system-to-system references

The two assemblies differ in how strictly they hold that line, and the split is the reason they are two assemblies rather than one:

• RevFramework.Common (Audio/) references only RevFramework.Core.Abstractions. It depends on no system and never will.
• RevFramework.Common.UX (UX/) takes a reference on RevFramework.Currency, because the ReasonText mapping for Currency reads that system's own CurOpCode values. It is compiled behind REV_CURRENCY_PRESENT, so the file disappears in a package without Currency. This is the one system reference in Common, it is confined to the optional presentation assembly, and it is why the reason-text code was not put in RevFramework.Common alongside the audio channel.

If you add something here:

• keep it small
• keep it boring
• keep it dependency-light
• and double-check it doesn’t belong inside a specific system module instead

TL;DR¶

Two folders: an audio channel and a reason-text mapper. That is the whole of Common.
The foundation you are probably looking for is Runtime/Core.
Use Runtime/Systems/<System> and the documented seams.
If you need a capability that isn’t exposed, ask — seams are added deliberately.