# Oxide — Session Handoff

Drop this file into a new session and say "continue from HANDOFF.md". It
captures where we are, how we work, and exactly what to do next. Authoritative
roadmap is `PLAN.md`; project rules are `CLAUDE.md`; this is the "current
state + how to continue" snapshot.

_Last updated: 2026-06-17. **`main` and `dev` are aligned.** **Stage 9 — Physics
is ✅ COMPLETE on `main`.** **Stage 10 — Scripting, Live Reload & Editor Terminal:
core ✅ on `main`** (all eye-checked & approved 2026-06-17 in the `untitled`
project): the `oxide-script` crate (`Script` + `.rhai` loader + sandboxed
`ScriptEngine`), the `init`/`update(dt)` lifecycle via `ScriptHost`, the
`Vec3`/transform engine API, live reload (`examples/script_spin`), editor
integration (`Script` addable; play-loop shares the editor
`AssetServer`/`AssetDatabase` so a live `.rhai` edit updates a *playing* scene),
the **Console** (captures the `log` stream — script `print`/errors), a **command
terminal** (`$` → `sh -c`), and an **interactive PTY terminal** (`portable-pty` +
`vt100`; tabbed, auto-closes a tab when its program exits, Tab/arrows/Esc routed
to the program — runs shells / TUIs / `claude`), and the **richer script API**
(scripts now `spawn_entity`/`despawn` and `add_component`/`set_component`/
`remove_component` on any entity via RON through the reflection registry —
closing the last PLAN round-trip criterion; pure-logic + headless tests → on
`main`). **What's left in Stage 10:** the maintainer's editor-UX batch —
Unity-style file explorer, native New/Open-Project dialog (typing the path by
hand is too hard), a **New Script** button on the `Script` inspector,
open-script-in-editor. See §5 to start. Parked, not blockers: editor-authored
joint **components** need a serializable entity-reference type._

---

## 1. Where we are

- **Phase 1 / Stages 5–8.7: ✅ on `main`.** Engine core, editor framework,
  input + gizmos, comprehensive UI, Reflection v2 + asset database (Stage 8.5),
  and editor Play Mode (Stage 8.7).
- **Phase 1 / Stage 9 — Physics: ✅ complete on `main`.** All pieces 1–8c done
  and promoted (eye-checked & approved 2026-06-17).
- **Phase 1 / Stage 10 — Scripting: 🚧 core done on `main`** (crate, lifecycle,
  live reload, editor integration, Console, command terminal, interactive PTY
  terminal — all eye-checked & approved; **richer script API**
  spawn/despawn/component-edit — pure-logic, on `main`). One follow-up remains
  (the editor-UX batch — GUI, needs eye-check). Piece table + what's next in §5;
  details in `docs/scripting.md`.

### Stage 9 — piece status (all on `main`)

| # | Piece | Where |
|---|-------|-------|
| 1 | Component data model + module wiring: `RigidBody`/`RigidBodyKind`, `Collider`/`ColliderShape`, `PhysicsModule`, `PhysicsSettings` | `physics/` (the `oxide-physics` crate) |
| 2 | Rapier-backed sim: build the world from components, step on `FixedUpdate`, write transforms back; by-entity forces/velocities/sleep | `physics/src/world.rs` |
| 3 | Collision groups/masks via `LayerMask`, sensors, collision/trigger events (enter/stay/exit) | `physics/src/world.rs` |
| 4 | Scene queries: raycast, sphere-cast, point/overlap with `LayerMask` filtering | `physics/src/world.rs` |
| 5 | Joints/constraints: fixed, spherical, revolute, prismatic (programmatic API) | `physics/src/world.rs` |
| 6 | Kinematic capsule character controller: move-and-slide, step offset, slope limit, grounded | `physics/src/{character,world}.rs` |
| 7 | `examples/physics_stack` + `examples/character_capsule` (headless console demos) | `examples/` |
| 8a | Editor integration: register RigidBody/Collider/CharacterController (addable, reflected) + enums; wire `PhysicsModule` into the play `App` (physics = first real consumer of Play; Stop reverts via snapshot) | `editor/src/state.rs`, `editor/src/main.rs` |
| 8b | **Collider wireframe gizmos**: box/sphere/capsule/cylinder outlines over the viewport; green=solid, amber=sensor, selected drawn thicker; matches the sim (ignores `Transform::scale`); **View ▸ Show Colliders** toggle (on by default) | `editor/src/shell.rs` |
| 8c | **Raycast debug probe**: `PhysicsWorld::sync_to_scene` (query the edited scene with no Play) + **View ▸ Raycast Probe** — click freezes a camera→cursor ray into the world (orbit to see it as a 3D line), cyan ray + magenta hit dot + normal whisker, status hint on cast. Overlay `view_proj` decoupled from selection (colliders/probe show with nothing selected) | `physics/src/world.rs`, `editor/src/{shell,main}.rs` |
| — | Bug fix: namespace every inspector field widget per component (`ui.push_id(component_name)`) so a field name shared by two components (e.g. both `MeshRenderer` and `Collider` have `shape`) can't collide egui ids and block edits | `editor/src/shell.rs` |

The `oxide-physics` crate: the **ECS is the source of truth**; the rapier world
is a transient resource rebuilt from components each step, so play-mode
snapshot/restore works for free. Full usage + internals in `docs/physics.md`.

### Key design decisions (also in memory + PLAN.md)

- **Layers = Unity "Model A"** ([[layer-group-model-decision]]): an entity is on
  **one** `Layer` (single index, render/physics filter slot); multi-category
  needs are served by **Groups** = the multi-valued `Tags` component + a
  project-level `GroupRegistry`. **Do NOT reintroduce multi-valued `Layer`
  membership.** Physics `Collider.membership`/`filter` are `LayerMask`s.
- **Component multiplicity = hybrid** ([[component-multiplicity-decision]]):
  one component of a type per entity (`hecs` archetypal). For "multiple things on
  one node": a **local-offset field** for naturally-single positioned things, and
  **child entities** for genuine multiples. NOT internal multi-instance lists.
- **`AssetRef<T>` not `Handle<T>` in components**: a component stores a
  serializable `AssetRef<T>` (= `Option<AssetUid>`); `AssetRef::resolve(db,
  server)` yields the process-local `Handle<T>` at runtime. The inspector
  recognises both spellings via `asset_ref_target`.

---

## 2. How we work (follow this exactly)

- **Build each stage as small, independently-tested pieces.** One piece = one
  green commit. Split a piece into a pure-logic part (→ `main`) and a GUI part
  (→ `dev`) when cleaner.
- **Local gate before every commit:**
  `cargo fmt --check && cargo clippy --all-targets -- -D warnings && cargo test`.
  (`#![deny(warnings)]` is on in the editor — clippy lints are hard errors, e.g.
  `too_many_arguments` fires at >7 params; bundle args into tuples/structs.)
- **Branch promotion rule (from CLAUDE.md):**
  - Pure-logic, fully proven by automated tests → commit to `dev` **and**
    fast-forward `main`. Continue without asking. (Headless GPU pixel tests count
    as proof — run them yourself.)
  - Interactive GUI / rendering-feel / shell polish (anything a human must
    **look at**) → push to `dev` only, **ask the maintainer to run + eye-check**,
    promote after explicit approval.
  - Decision rule: "Can an automated test prove this without a human looking?"
    Yes → `main`-eligible. No → stop at `dev`.
- **Promotion commands** (from `dev`, after committing + pushing dev):
  `git checkout main -q && git merge --ff-only dev -q && git push origin main && git checkout dev -q`
- **Commit messages** end with: `Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>`
- **Document as you build:** keep `PLAN.md`/`README.md`/`docs/` current in the
  **same** change. Physics docs live in `docs/physics.md`.

### egui gotcha
egui's bundled font has a **limited glyph set**. Confirmed-rendering: `🗑 ➕ ⚙ ✏
▾ … ↺`. Confirmed-tofu (avoid): `✕` (U+2715), `⧉`, `⣿` (braille). Reuse an icon
already in the codebase or test it before shipping; prefer plain text if unsure.
Also: egui assigns widget ids from a hash of the call path + a salt — when the
same logical widget appears twice (two components with a same-named field), scope
it under `ui.push_id(unique_key)` or it errors and edits silently break.

---

## 3. Conventions (match the existing code)

- Heavy rustdoc: each public type/fn gets a one-line summary + the "why".
  Module-level `//!` docs explain the piece's role.
- Unit tests in `#[cfg(test)] mod tests` at the bottom of each file; integration
  tests in `tests/src/lib.rs`. Even for visual pieces, factor the math into pure
  helpers and unit-test those (e.g. `collider_wire_segments`/`push_arc` in 8b),
  so only the painting itself needs the eye-check.
- Serialization is `serde` + RON throughout. New optional fields use
  `#[serde(default, skip_serializing_if = ...)]` so older documents still parse.
- Errors are `thiserror` enums with specific variants.
- Reflection: **public fields only**; `#[reflect(skip)]` drops a public field;
  `#[reflect(min=, max=)]` on an f32 → slider. Register editor-visible types in
  `oxide_editor::state::register_builtin_types`; addable ones via
  `register_addable::<T>` (needs `Default`); enums via `register_enum::<E>`.
- New deferred ideas → `PLAN.md` backlog, not the current piece.

---

## 4. Key architecture facts

```rust
// Per-field reflection on any component (zero per-type editor code):
#[derive(Reflect, Serialize, Deserialize)]
struct Timer { pub repeating: bool, pub duration: f32, #[reflect(skip)] pub elapsed: f32 }
registry.register_reflected::<Timer>("Timer");   // editor + scripts

// Inspector renders generically: components_on -> field_infos -> get_field/set_field,
// edits routed through SetFieldCmd (undoable, drag-coalesced).
```

- **`oxide_engine::reflect`**: whole-value (`get_ron`/`set_ron`) + per-field
  (`Reflect` + `register_reflected`) layers. `register_addable` adds an "Add
  Component" constructor; `register_enum` lists variants for combo widgets.
- **`oxide_engine::prefab`**: `Prefab { name, components }`,
  `ComponentSpec { type_name, ron }`; editor seeds built-ins (Empty/Cube/…).
- **`oxide_engine::layer`**: single-valued `Layer { index }`; `LayerMask`
  (filter); `LayerRegistry` (names); `Tags` + `GroupRegistry` (groups).
- **Editor inspector** (`oxide_editor::shell::ShellTabViewer`): node-baked
  section (Layer/Groups/Transform) then modular components (drag-reorder,
  enable/disable, remove, Add Component menu). `field_widget` dispatches on
  `FieldInfo.type_name`.
- **Viewport overlay** (`editor/src/shell.rs`): the host feeds a
  `ViewportOverlay { view_proj, gizmo_size }` each frame; the Viewport tab paints
  2D over the 3D scene via `project(world, &view_proj, tab_rect) -> Pos2`.
  Transform gizmo handles, the play-state border, **and the new collider
  wireframes** all paint this way. Reuse `project` + `painter.line_segment` for
  any new world-space overlay (e.g. piece 8c's raycast viz).
- **Play loop** (`oxide_editor::main::drive_play` + `oxide_engine::scene::
  SceneSnapshot`): owns a play `App` (DefaultModules + PhysicsModule +
  ScriptModule; **`app.assets` is set to a clone of the editor's `AssetServer`**
  and the project `AssetDatabase` is inserted as a resource so scripts resolve +
  live-reload reaches a playing scene), built on Play / dropped on Stop, **swaps
  `state.scene` in/out per tick** so the editor scene stays the single source of
  truth. Snapshot covers reflected components + `Tags`/`DisabledComponents`. Undo
  cleared on Play/Stop.
- **Host input** (`oxide_editor::main`): viewport orbit/pan/zoom + WASD gated on
  `cursor_over_viewport && !pointer_over_floating`.

---

## 5. Exactly what to do next — finish Stage 10 (Scripting)

**Stage 10's core is done and on `main`** (all eye-checked & approved). The
`oxide-script` crate is the worked-out twin of `oxide-physics` (same
"ECS-as-truth, transient runtime resource, snapshot-for-free" shape). Full usage
+ internals: `docs/scripting.md`. What shipped (all on `main`):

| Piece | Where |
|-------|-------|
| `oxide-script` crate: `Script`, `ScriptAsset` + `.rhai` loader (`AssetKind::Script`), sandboxed `ScriptEngine` (compile/run, op cap, `ScriptError`), `ScriptModule` | `script/` |
| Lifecycle: `ScriptHost` + `run_scripts` (Update schedule); `init`/`update(dt)`; **engine API** (`bridge.rs`) — scripts read/write their `Transform` via a staged shared context (`position`/`translate`/`rotate_*`/`Vec3`), `rhai` `f32_float` | `script/src/{host,engine,bridge}.rs` |
| **Live reload**: `ScriptHost` holds each script's `Handle<ScriptAsset>` alive → watcher's in-place reload recompiles (no restart); `examples/script_spin` | `script/src/host.rs`, `examples/` |
| **Editor integration**: `Script` addable in `register_builtin_types`; `drive_play` adds `ScriptModule` + **shares the editor `AssetServer`** + a db snapshot → live `.rhai` edits update a *playing* scene | `editor/src/{state,main}.rs` |
| **Console**: capturing logger mirrors the `log` stream into a ring buffer the panel renders (script `print` + paused-script errors via `target:"oxide_script"`) | `editor/src/console.rs`, `shell.rs::console` |
| **Command terminal**: `$` prompt → `sh -c <cmd>` in the project root, streams stdout/stderr into the Console | `editor/src/terminal.rs` |
| **Interactive PTY terminal**: `PanelKind::Terminal` — tabbed, auto-closes a tab when its program exits, Tab/arrows/Esc routed to the program; runs shells / TUIs / `claude` | `editor/src/pty.rs`, `shell.rs::terminal_panel` |

### Remaining for Stage 10

**1. Richer script API — ✅ DONE, on `main`.** Scripts now `spawn_entity()` /
`spawn_entity(name)`, `despawn(e)`, and `add_component`/`set_component`/
`remove_component` on any entity, plus `entity()` for their own. Implemented as a
**deferred command buffer** in `bridge.rs` (`EntityHandle` + `ScriptCommand`):
the `rhai` functions can't borrow the ECS (must be `Send + Sync`), so each call
buffers a command the host drains in `ScriptHost::apply_commands` and applies via
the reflection registry (`app.types`, `set_ron`/`add_default`/`remove`). `spawn_entity`
returns a **provisional** handle resolvable in the same frame (`spawn` is a rhai
reserved word, hence the longer name). Component edits go through RON, closing the
last PLAN round-trip criterion. Headless tests in `host.rs`/`bridge.rs`; docs in
`docs/scripting.md` ("Spawning entities and editing components").

**2. Maintainer's editor-UX batch (GUI → `dev` + eye-check).** Details in
PLAN.md "Editor-UX follow-ups" + [[editor-file-explorer-preference]]. The
maintainer asked for these after the terminal work:
- **"New Script" button** on the `Script` inspector — write a `.rhai` template
  into `assets/scripts/`, register it in the db, auto-assign it to the component.
  There is **no in-editor script creation today** (scripts are authored as
  files). Good small first one to pull forward.
- **Open a script in an editor** — double-click / button to open a `.rhai` in an
  in-editor text view or launch `$EDITOR` / a configured external editor; edits
  flow back through live reload (you can also just run `$EDITOR file` in the new
  PTY terminal).
- **Unity-style file explorer** in the Project panel (create/rename/move folders,
  drag-in OS import, context menus) over the existing `AssetDatabase`.
- **Native New/Open-Project dialog** (`rfd`, must work on Wayland + X11) —
  typing the project path by hand "is very hard to use".

**Reuse, don't reinvent:** `oxide-physics`/`oxide-script` are the template for
"new crate → `Module` + schedule → reflected/addable components → editor
registration → play-loop integration". The play loop
(`oxide_editor::main::drive_play`) runs scripts alongside physics and shares the
editor's asset server, so live reload reaches a playing scene.

**Terminal design note:** the embedded terminal is a general PTY widget
(`portable-pty` + `vt100`); run any program (incl. `claude`) from a *Shell* tab.
A "one-app launcher" was considered and rejected — it needs the same
PTY+VT+render+input stack, so the general widget is strictly better.

**Don't do these unless asked (parked in PLAN.md):** editor authoring of joint
**components** (needs a serializable entity-reference type); standalone game
"Launch" (deferred to Stage 16).

---

## 6. Quick orientation commands

```sh
cargo test                                           # full suite (all green at handoff)
cargo test -p oxide-script                           # the scripting crate (lifecycle, live reload)
cargo test -p oxide-editor --lib pty                 # PTY terminal pure helpers
cargo run  -p oxide-examples --bin script_spin       # headless live-reload demo
cargo run  -p oxide-editor                           # the editor (Console + Terminal panels)
git log --oneline -15                                # recent per-piece commits
sed -n '/## Stage 10/,/## Stage 11/p' PLAN.md        # Stage 10 spec + status
```

Memory files (auto-loaded each session) track decisions: `MEMORY.md` index →
`layer-group-model-decision.md` → `component-multiplicity-decision.md` →
`run-on-target-pc.md` (headless-vs-eye-check rule) →
`workflow-auto-continue.md` (don't pause between pure-logic pieces).