Simulation Harness

Simulation Harness (PSPH v2.0)

"You shouldn't need a game to evaluate a game framework."

---

The Problem

You are evaluating a game framework. It claims to handle save games, audio, loading screens, game flow, data registries, and eight more systems. You want to see them work. But to see them work, you need a game project with configured Data Assets, a working game loop, level transitions, and enough content to exercise each system.

So you face a chicken-and-egg problem: you cannot evaluate the framework without building on it, and you cannot justify building on it without evaluating it first.

This is not an edge case. Every framework evaluation, every stakeholder demo, every team onboarding session, and every integration test suite hits the same wall. You need data in the systems to see the systems work, but generating that data requires exactly the kind of game-specific setup the framework is supposed to simplify.

---

The Solution

The PGX Simulation Harness (PSPH — PGX Simulation, Population & Harness) operates in two modes that solve two different problems.

Demo Mode: Content Without Authoring

Demo Mode populates the Content Browser with 20 Data Asset entries across 7 categories, all filled with realistic, internally consistent sample data.

What gets created:

• Save configurations with domains, contexts, and slot definitions
• Game flow states with channels and transition rules
• Audio configurations with channel profiles, mix settings, and dialogue entries
• Loading screen configurations with contexts and PSO coordination settings
• PSO warm-up configs with shader contexts and pipeline definitions
• Data Registry definitions with sample entries across categories
• Event handler configurations with behavior rules and telemetry settings

These are not empty shells. Each Data Asset is populated with values that reflect how a real game project would configure the system. Save domains have meaningful names and slot counts. Audio channels have proper priority levels and volume defaults. Game flow states define transitions that make logical sense.

The result: you open the editor, activate Demo Mode, and every inspector panel immediately shows meaningful data. The Hub dashboard lights up. The System Observer graphs start moving. You can browse, inspect, and understand every system without authoring a single asset.

Harness Mode: Deep System Exercise

Demo Mode fills the configuration layer. Harness Mode fills the runtime layer.

When activated, Harness Mode performs deep injection across all 13 implemented systems with approximately 160 API calls covering roughly 90% of each system's public surface area. This is not random data — it is a structured exercise of each system's capabilities:

Save System: Populates 4 save slots with 17 key-value entries each. Exercises slot creation, data writing, domain organization.

Game Flow: Executes 30 sequential state transitions across 8 channels. Builds a realistic transition history that the Game Flow inspector renders as a timeline.

PSO (Pipeline State Objects): Registers 3 shader contexts, activates recording, triggers warm-up cycles. The PSO inspector shows precache progress and context status.

Data Registry: Inserts 10 definition entries (5 items, 5 NPCs) with full metadata — tags, categories, display names. The Registry browser populates with browseable content.

Event Handler: Fires 13 event resolutions with full context payloads. The Event Debugger shows execution history, telemetry, and cache behavior.

Level Flow & Loading: Simulates a full game session — level transition requests, streaming operations, loading screen lifecycles.

Message Bus: Broadcasts 25 messages across 5 channels. The Message inspector shows broadcast history, listener counts, and channel activity.

Audio: Exercises playback requests, channel transitions, music crossfades, dialogue queuing, and backend operations.

Profile, Log, MGOS: Exercises platform queries, domain logging, and GC observation.

The Live Simulation Ticker

After initial injection, the harness does not stop. A simulation ticker continues to exercise cross-system interactions:

• Every 4th tick: cycles to the next save slot (testing slot rotation)
• Every 6th tick: fires a random event handler (testing handler resolution under load)
• Continuous: game flow transitions, message broadcasts, audio state changes

This creates a living, breathing simulation that exercises system interactions over time — the kind of behavior that only emerges in a real game session but that the harness can produce on demand.

---

Use Cases

Framework Evaluation

A technical lead evaluating PGX for a new project can:

1. Open the editor with PGX installed
2. Activate Demo Mode in the Simulation Harness panel
3. Browse every inspector panel with realistic data
4. Activate Harness Mode to see live system interactions
5. Make an informed decision without writing a single line of game code

Time to first informed opinion: under 5 minutes.

Integration Testing

The harness exercises the same API surface that game code would use. If the harness runs without errors, you have confidence that 90% of the framework's public API is functional. This makes it a de facto integration test suite that requires no test authoring.

Editor Panel Development

If you are building custom inspector panels or extending PGX's editor tooling, the harness provides the data you need to see your UI render correctly. No need to create test assets by hand — activate the harness and your panel has data.

Stakeholder Demos

Product managers, artists, and other non-programming stakeholders can see the framework's capabilities without a game build. The Demo Mode creates recognizable, domain-appropriate content that communicates what each system does.

Onboarding

New team members can explore every PGX system in a pre-populated state. Combined with the framework's 18 interactive tutorials (5 onboarding + 13 per-system), the harness provides the "sandbox" that makes learning by exploration possible.

---

Architecture

The harness runs entirely in the editor. No runtime dependencies. No game thread interference. All injected data is created through the same public APIs that game code would use, ensuring that the exercise is realistic — not a shortcut that bypasses normal system behavior.

Key design decisions:

• Tag-based identification: All harness-created content is tagged for easy identification and cleanup.
• Idempotent execution: Running the harness multiple times does not create duplicates. Existing harness data is detected and updated.
• Transactional cleanup: All created assets can be removed in one operation.
• No special code paths: The harness calls the same public API that Blueprint and C++ game code would call. If it works in the harness, it works in production.

---

Coverage

System	Injection Depth	API Calls	Key Operations
Save	4 slots, 17 keys	~25	Slot creation, data read/write, domain organization
GameFlow	30 transitions, 8 channels	~35	State changes, channel operations, history building
PSO	3 contexts	~15	Recording, warm-up, precache, pipeline management
DataRegistry	10 entries	~15	Registration, lookup, cache, category queries
EventHandler	13 executions	~15	Resolution, execution, telemetry, cache eviction
LevelFlow	Session simulation	~10	Transitions, streaming, sublevel operations
Loading	Session simulation	~10	Screen lifecycle, PSO coordination, progress
Message	25 broadcasts, 5 channels	~15	Pub/sub, history, listener management
Audio	Full exercise	~25	Playback, music, dialogue, channels, backends
Profile	5-layer query	~5	Platform capabilities, budget queries
Log	Domain logging	~5	Multi-domain log entry creation
MGOS	Profile + history	~5	GC observation, mode queries
Construction	Slot queries	~5	Configuration validation, class resolution

Total: ~160 API calls, ~90% public surface coverage.

---

Resumen en Espanol

El Simulation Harness (PSPH v2.0) resuelve el problema de evaluacion del framework sin necesidad de un proyecto de juego. El Modo Demo puebla el Content Browser con 20 Data Assets realistas en 7 categorias, haciendo que todos los paneles de inspeccion muestren datos significativos inmediatamente. El Modo Harness realiza inyeccion profunda en los 13 sistemas con ~160 llamadas API cubriendo ~90% de la superficie publica: slots de guardado, transiciones de game flow, contextos de shaders, entradas de registro, ejecuciones de eventos, sesiones de nivel, mensajes, audio y mas. Un ticker de simulacion en vivo ejercita interacciones entre sistemas de forma continua. Los casos de uso incluyen evaluacion del framework, pruebas de integracion, desarrollo de paneles de editor, demos para stakeholders y onboarding de nuevos miembros del equipo. Todo corre en el editor, usa las mismas APIs publicas que usaria el codigo del juego, y es completamente idempotente y limpiable.