Skip to content

Economy — Diagnostics (Runtime)

This folder contains optional diagnostic and inspection surfaces for the Economy system.

These types are not part of the gameplay contract.
They exist solely to support editor tooling, teachable panels, debugging, and inspection without polluting the core APIs.

What belongs here

Types in this folder may:

  • Expose opaque handles or snapshots for inspection
  • Be consumed by Teachables, editor panels, or debug UI
  • Provide read-only visibility into runtime state
  • Be implemented optionally by runtime adapters

Types in this folder must not:

  • Be required for normal gameplay
  • Be relied upon for correctness
  • Be used as extension points for game logic
  • Introduce behavioural coupling to specific implementations

If a system works without these types present, it is working correctly.

Design intent

The Economy runtime follows a strict separation:

  • Abstractions
    Supported gameplay contracts (IItemStore, IShopService, IValueLedger, …)

  • Diagnostics (this folder)
    Optional, opt-in inspection surfaces for tooling and debugging

  • Teaching
    Hostile consumers that demonstrate correct usage of the public API

This separation allows the framework to provide rich debugging and teaching tools without accidentally expanding the supported gameplay surface.

Example: IItemStoreDebug

IItemStoreDebug is an optional diagnostic interface that runtime item-store adapters may implement.

It exposes an opaque Handle intended for: - Editor panels - Teachables - UI binding or inspection

Usage is explicit and conditional:

if (store is IItemStoreDebug dbg)
{
    var handle = dbg.Handle;
    // inspect or display, never rely on for gameplay
}

Gameplay code must never assume this interface is present.

Stability guarantees

  • Types in this folder are best-effort stable, but not gameplay contracts
  • They may evolve as diagnostics and tooling improve
  • Changes here should not break correct gameplay code

If you are writing game logic and think you need something from this folder, you are probably reaching too low in the stack.

Summary

This folder exists to answer one question only:

“How do we provide visibility without leaking internals?”

If a type here starts influencing behaviour, it is in the wrong place.