Homer
4f1e9a48d7
Stage-10 editor-UX follow-up. The Script component's inspector section now ends with a name field + "➕ New Script" button (Enter in the field also submits): it writes a fresh .rhai from the tested template into assets/scripts/ via create_script_file (sanitized stem, collisions suffixed), registers it in the asset database, saves the manifest, and assigns it to the component's `source` through the normal edit path — so the assignment is one undoable SetFieldCmd. Disabled with a hint while no project is open; failures land in the Console via the log. GUI piece — needs an eye-check before promotion to main. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Oxide Engine Documentation
This directory is the canonical, in-depth documentation for the Oxide engine. The
top-level 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 | Installing the toolchain, building, running examples, running tests and benchmarks |
| architecture.md | Workspace layout, crate responsibilities, design philosophy, staged development model |
| conventions.md | Coordinate system, handedness, units, color space, and other cross-cutting conventions |
| development.md | Branch workflow (dev/main), testing protocol, documentation policy, how to add a stage |
| math.md | Full reference for the oxide_engine::math module (Stage 1) |
| windowing.md | Window creation, the App trait and event loop, raw input events (Stage 2) |
| render-context.md | GPU acquisition, surface configuration, the clear-color frame loop (Stage 2) |
| scene.md | Scene graph, entities, the transform hierarchy, and serialization (Stage 3) |
| rendering.md | Meshes, materials, camera, and the forward renderer (Stage 4) |
| layers.md | Layers, groups & tags: single-valued Layer + multi-valued Tags/GroupRegistry, the shared LayerMask filter primitive (Stage 5) |
| reflection.md | Reflection / type registry: generic name-keyed component access for dual-editability (Stage 5) |
| prefabs.md | Prefabs: data-driven named spawn templates (component specs applied via the registry) (Stage 8.5) |
| assets.md | Asset server & handles: ref-counted loading, dedup, loaders, background load, reload (Stage 5) |
| modules.md | App, modules & scheduling: composing the engine, system phases, fixed timestep, enable/disable/remove (Stage 5) |
| render-pipeline.md | Data-driven render pass pipeline: composable passes, scalable fidelity, camera layer visibility (Stage 5) |
| projects.md | Project system: project file, folder layout, create/open/save, recent projects (Stage 6) |
| settings.md | Settings & preferences framework: typed sections, export/import, per-module/per-project settings (Stage 6) |
| file-watching.md | File-watcher foundation: debounced/deduplicated change events; asset live-reload wiring (Stage 6) |
| editor-extensions.md | Module → editor extension API: how a module contributes menus, panels, tools, inspectors, settings pages (Stage 6) |
| editor-shell.md | Editor docking shell: menu bar, dockable panels, status bar, Preferences window, command stack + file watcher wiring (Stage 6) |
| 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 | 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 WidgetValues (Stage 8 — pieces 1–6, GUI tail coming) |
| 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 module (oxide-physics, rapier3d): RigidBody/Collider components, LayerMask-filtered collision, the ECS-as-source-of-truth model, module wiring (Stage 9) |
| 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, getting-started.md |
| 1 | Math & core primitives | math.md |
| 2 | Window & render context | windowing.md, render-context.md |
| 3 | Scene graph & entity system | scene.md |
| 4 | Basic 3D rendering | rendering.md |
| 5 | Engine core framework | modules.md, layers.md, reflection.md, assets.md, render-pipeline.md |
| 6 | Editor framework & project system | projects.md, settings.md, file-watching.md, editor-extensions.md, editor-shell.md |
| 7 | Input system | input.md |
| 8 | Comprehensive UI system (in progress) | ui.md |
| 8.7 | Editor play mode | play-mode.md |
| 9 | Physics integration (in progress) | physics.md |
| 10 | Scripting, live reload & editor terminal (in progress) | 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).