> For the complete documentation index, see [llms.txt](https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/.spec_system/archive/phases/phase_30/session_07_play_runtime_integration.md).

# Session 07: Play Runtime Integration

**Session ID**: `phase30-session07-play-runtime-integration` **Status**: Complete **Completed**: 2026-06-22 **Estimated Tasks**: \~12-25 **Estimated Duration**: 2-4 hours

***

## Objective

Connect the simulation, renderer, assets, controls, and first spendable upgrade into a complete playable run.

***

## Scope

### In Scope (MVP)

* Wire committed player, enemy, tile, fog, hazard, currency, relic, and compact UI atlas assets into PixiJS.
* Render the simulated world, player, enemies, pickups, combat feedback, health, status pips, run marker, and basic UI frames.
* Connect start, pause, reset, resume, save/load, win, loss, and run-completion events between React and the runtime.
* Add one spendable upgrade that affects a run and consumes wallet state through the loadout flow.
* Add accessibility controls for reduced motion, contrast, input remapping, and pause.

### Out of Scope

* Skill-linked classes, model-flavored resources, and expanded content (Session 08).
* Mobile layout and audio (Session 09).

***

## Prerequisites

* [x] Session 03 runtime boundary.
* [x] Session 05 persistence and save contracts.
* [x] Session 06 deterministic simulation.

***

## Deliverables

1. A playable first dungeon slice on `/extensions/ai-rogue/play`.
2. Loadout interaction for one wallet-backed upgrade.
3. Runtime asset wiring and animation frame use within media and bundle budgets.

***

## Reference Code (`EXAMPLES/`)

This session wires sim -> renderer -> assets -> controls, which both examples do end to end. Adapt to PixiJS v8 asset/ticker APIs.

* **Sim/render separation** -- `EXAMPLES/frogue/src/fae/systems.cljs` splits `state` systems (update, rotate) from `effect` systems (`graphics-system` -> `engine/set-graphics-position`), so simulation steps first and graphics merely reflect the result. This is the clean seam to keep between the Session 06 pure-TS sim and the renderer.
* **Stage/sprite lifecycle** -- `EXAMPLES/frogue/src/fae/engine.cljs` (`add-actor-to-stage`, `remove-actor-from-stage`, `clear-stage`, `sort-by-z-index`, `sprite` with anchors) is a compact model for adding/removing entity sprites and z-ordering as the run mutates.
* **Texture-atlas wiring** -- `EXAMPLES/Rotten-Soup/src/assets/js/game/ResourceLoader.js` plus `GameDisplay.js:loadAssets` slice a 32x32 tileset into per-tile `PIXI.Texture`s (via `PIXI.Rectangle` frames) keyed in a `tilesetMapping`. Mirror the slice-atlas-into-textures idea, but use **`Assets.load`** in v8 (the `PIXI.loader` API shown here was removed).
* **Movement feedback + fog overlay** -- `GameDisplay.js` interpolates `movingSprites` toward targets each tick (smooth step animation) and overlays a `spriteBox` for FOV shadowing -- references for combat/movement feedback and rendering the fog the simulation computes.
* **Coarse runtime<->menu state** -- `EXAMPLES/frogue/src/fae/state.cljs` keeps a small `:game-state` (`:stopped`/...), `:scene`, `:progress`, and `:to-spawn` -- the kind of coarse, serializable bridge between React menus and the imperative runtime (start/pause/reset/resume/win/loss).

## Locked Visual Assets (`visual-assets.md`)

The art this session wires is **already committed** under `src/assets/ai-rogue/` as two TexturePacker-style atlases (format RGBA8888, scale 1). Load them with PixiJS v8 `Assets.load` and reference frames by name -- no art generation here.

* **`gameplay-atlas.{png,json}`** (48 frames, 256x90) -- everything in-world:
  * Player: `player_{down,up,left,right}_{0,1,2}` (4 dirs x 3 frames = idle + 2 move).
  * Enemies: `enemy_errant_process_{0,1}`, `enemy_firewall_sentry_{0,1}`; boss `boss_kernel_sentinel_{0,1}` (Session 08).
  * Pickups: `pickup_insight_shard_{0,1}` (in-run currency, with glint frame), `pickup_health`, `pickup_upgrade_relic` (the one spendable upgrade).
  * Hazards/projectile/fog: `hazard_magenta_spark`, `hazard_acid_spark`, `projectile_firewall_line`, `fog_tile_dense`, `fog_tile_soft`, `fog_edge_{left,right}`.
  * Tiles: `tile_floor_*`, `tile_wall_*`, `tile_door_*`, `tile_coolant`, `tile_hazard_pool`, `tile_void_edge`.
* **`ui-atlas.{png,json}`** (21 frames, 256x38) -- HUD/run UI: `icon_shard_hud`, `icon_insight_cache`, `icon_run_marker`, `icon_shield_status`, `icon_danger_status`, `icon_claim_reward`, `icon_cache_chest`; pips `pip_health_{full,empty}`, `pip_shield`, `pip_danger`; and `frame_*` corner/edge/panel pieces for HUD framing.
* **Scale/footprints**: render at 2x nearest-neighbor (32 CSS px/tile); 16x16 footprints for player/standard enemies, 32x32 for the boss. HUD icons are 16x16 source shown at 32px; pips are 8x8 shown at 16px.
* **Shard feedback vs banked reward**: use `pickup_insight_shard_*` for tactile in-run pickups and `icon_insight_cache` for the post-run/claim banked reward (matches the Session 04 economy rule).

## Success Criteria

* [x] A user can start a run, move, fight, discover fogged areas, reach win or loss, and reset or resume without page reload.
* [x] The first committed art set appears in runtime instead of geometric placeholders except for explicit diagnostics.
* [x] Reduced-motion and input-remapping settings visibly affect runtime behavior.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/.spec_system/archive/phases/phase_30/session_07_play_runtime_integration.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.