Oxide/docs/README.md

# Oxide Engine Documentation

This directory is the canonical, in-depth documentation for the Oxide engine. The
top-level [`README.md`](../README.md) is a short overview; everything detailed —
usage guides, API references, and explanations of how the engine works
internally — lives here and grows with the engine at every stage.

## How this documentation is organized

| Document | What it covers |
|----------|----------------|
| [getting-started.md](getting-started.md) | Installing the toolchain, building, running examples, running tests and benchmarks |
| [architecture.md](architecture.md) | Workspace layout, crate responsibilities, design philosophy, staged development model |
| [conventions.md](conventions.md) | Coordinate system, handedness, units, color space, and other cross-cutting conventions |
| [development.md](development.md) | Branch workflow (`dev`/`main`), testing protocol, documentation policy, how to add a stage |
| [math.md](math.md) | Full reference for the `oxide_engine::math` module (Stage 1) |
| [windowing.md](windowing.md) | Window creation, the `App` trait and event loop, raw input events (Stage 2) |
| [render-context.md](render-context.md) | GPU acquisition, surface configuration, the clear-color frame loop (Stage 2) |
| [scene.md](scene.md) | Scene graph, entities, the transform hierarchy, and serialization (Stage 3) |
| [rendering.md](rendering.md) | Meshes, materials, camera, and the forward renderer (Stage 4) |
| [layers.md](layers.md) | Layers, groups & tags: single-valued `Layer` + multi-valued `Tags`/`GroupRegistry`, the shared `LayerMask` filter primitive (Stage 5) |
| [reflection.md](reflection.md) | Reflection / type registry: generic name-keyed component access for dual-editability (Stage 5) |
| [prefabs.md](prefabs.md) | Prefabs: data-driven named spawn templates (component specs applied via the registry) (Stage 8.5) |
| [assets.md](assets.md) | Asset server & handles: ref-counted loading, dedup, loaders, background load, reload (Stage 5) |
| [modules.md](modules.md) | App, modules & scheduling: composing the engine, system phases, fixed timestep, enable/disable/remove (Stage 5) |
| [render-pipeline.md](render-pipeline.md) | Data-driven render pass pipeline: composable passes, scalable fidelity, camera layer visibility (Stage 5) |
| [projects.md](projects.md) | Project system: project file, folder layout, create/open/save, recent projects (Stage 6) |
| [settings.md](settings.md) | Settings & preferences framework: typed sections, export/import, per-module/per-project settings (Stage 6) |
| [file-watching.md](file-watching.md) | File-watcher foundation: debounced/deduplicated change events; asset live-reload wiring (Stage 6) |
| [editor-extensions.md](editor-extensions.md) | Module → editor extension API: how a module contributes menus, panels, tools, inspectors, settings pages (Stage 6) |
| [editor-shell.md](editor-shell.md) | Editor docking shell: menu bar, dockable panels, status bar, Preferences window, command stack + file watcher wiring (Stage 6) |
| [input.md](input.md) | Input system: per-frame `InputState` with edge detection, named action mapping (`ActionMap`/`Binding`) with defaults + remapping + RON persistence, 1D/2D directional axes (Stage 7) |
| [ui.md](ui.md) | In-game UI: widget tree, layout (stack/grid/anchor), DPI-aware sizing, per-widget visual styles + named-style themes, RON dual-edit, ab_glyph-backed text shaping + R8 glyph atlas, screen-space + world-space `UiOverlayPass`, hit-test + hover/focus/press `Router`, immediate-mode event queries + typed `WidgetValue`s (Stage 8 — pieces 1–6, GUI tail coming) |
| [play-mode.md](play-mode.md) | Editor play mode: `PlayState`, registry-aware `SceneSnapshot` snapshot/restore, the `tick_for` decision + `App::step`, the scene-swap runner, toolbar/shortcuts/viewport tint (Stage 8.7) |
| [physics.md](physics.md) | Physics module (`oxide-physics`, rapier3d): `RigidBody`/`Collider` components, `LayerMask`-filtered collision, the ECS-as-source-of-truth model, module wiring (Stage 9) |
| [scripting.md](scripting.md) | Scripting module (`oxide-script`, rhai): the `Script` component, `ScriptAsset` + `.rhai` loader, the sandboxed `ScriptEngine` wrapper, module wiring; ECS-as-source-of-truth + live-reload model (Stage 10) |

## Documentation status by stage

Documentation is written alongside the code. A stage is not considered done until
its docs exist here.

| Stage | Subject | Docs |
|-------|---------|------|
| 0 | Project foundation | [architecture.md](architecture.md), [getting-started.md](getting-started.md) |
| 1 | Math & core primitives | [math.md](math.md) |
| 2 | Window & render context | [windowing.md](windowing.md), [render-context.md](render-context.md) |
| 3 | Scene graph & entity system | [scene.md](scene.md) |
| 4 | Basic 3D rendering | [rendering.md](rendering.md) |
| 5 | Engine core framework | [modules.md](modules.md), [layers.md](layers.md), [reflection.md](reflection.md), [assets.md](assets.md), [render-pipeline.md](render-pipeline.md) |
| 6 | Editor framework & project system | [projects.md](projects.md), [settings.md](settings.md), [file-watching.md](file-watching.md), [editor-extensions.md](editor-extensions.md), [editor-shell.md](editor-shell.md) |
| 7 | Input system | [input.md](input.md) |
| 8 | Comprehensive UI system (in progress) | [ui.md](ui.md) |
| 8.7 | Editor play mode | [play-mode.md](play-mode.md) |
| 9 | Physics integration (in progress) | [physics.md](physics.md) |
| 10 | Scripting, live reload & editor terminal (in progress) | [scripting.md](scripting.md) |
| 11+ | — | _added as each stage lands_ |

## Conventions for these files

- One topic per file; keep files focused and link between them rather than
  duplicating content.
- Every public type or system gets: a one-line summary, when to use it, and at
  least one runnable code snippet.
- Code snippets are written so they would compile against the current API. When
  the API changes, update the snippet in the same change.
- Prefer explaining the *why* (design intent, trade-offs) over restating the
  *what* (which the rustdoc comments already cover).