Homer
d08bee1361
Stage-10 editor-UX follow-up, second half of in-editor script authoring: - "✏ Edit" button on the Script inspector section (enabled once a source is assigned) and double-click on any script in the Project panel open the .rhai in the user's editor. Non-script assets double-click through xdg-open. - Resolution order: the new External Editor preference command (spawned detached as `<command> <file>`, flags allowed), else $VISUAL/$EDITOR in a new Terminal-panel tab (TUI editors work in-editor via the existing PTY widget), else xdg-open. - New `editor.external_editor` settings section (ExternalEditorPrefs) registered by EditorState, persisted with the preferences file, with a rich row in the Preferences window; registration covered by a unit test. Editor crate now depends on serde directly for its own sections. Saved edits flow back through the file watcher's live reload, including into a playing scene. GUI piece — needs an eye-check before promotion. 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).