Homer
c47efa876f
The last item of the Stage-10 editor-UX batch. The Project panel's fixed typed-folder listing becomes a real file explorer over assets/: - breadcrumbs + double-click folder navigation, "➕ New Folder", inline rename rows, context menus (Open / Rename / Delete), drag a row onto a folder (or "..") to move it, drag files in from the OS to import into the current folder, double-click to open (scripts via the external-editor flow, others via xdg-open). - All behavior lives egui-free in editor/src/explorer.rs (listing, breadcrumbs, name validation/uniquing, create/rename/move/delete/ import) and is unit-tested; the shell only renders it. Renames and moves ride the uid-preserving AssetDatabase ops so saved AssetRefs keep resolving; unregistered files fall back to fs::rename. Folders delete only when empty — no recursive asset deletion. - Engine: AssetDatabase::scan now walks the WHOLE assets/ tree instead of just the typed folders, so assets organised into custom folders register and survive rescans (covered by updated unit tests). File operations act immediately and bypass the undo stack, like the hierarchy's structural edits. 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).