Oxide/README.md

Oxide Engine

Notice: This project was developed with the assistance of Claude Code (Anthropic's AI coding assistant). All generated code, configuration, and documentation has been reviewed and tested by the author. Claude Code was used as a development tool; all design decisions, requirements, and sign-offs are the author's own.

A general-purpose 3D game engine written in Rust — built to make any 3D game, scaling from stylized low-poly to realistic graphics, and shipping only what each game uses.

---

Status

Oxide is built in two phases (see the Roadmap): Phase 1 (Stages 0–16) is the general-purpose engine — everything needed to build and export any game; Phase 2 (Stages 17+) adds optional, feature-gated built-in modules.

Stages 0–9 are complete on main. Stage 8 shipped the engine's full in-game UI stack — widget tree, layout, themed styling, ab_glyph-backed text shaping + R8 glyph atlas, screen-space and world-space render passes, hit-test + hover/focus/press router, immediate-mode event queries with typed WidgetValue data binding, and the editor's visual UI canvas. Stage 8.5 added reflection v2 (public fields auto-appear in the inspector, no per-type editor code), prefabs, the asset database, and layers/groups. Stage 8.7 added editor play mode — Play/Pause/Step/Stop the open scene in the viewport (Ctrl+P / Ctrl+.), with snapshot-on-Play / bit-for-bit restore-on-Stop. Stage 9 added comprehensive physics (oxide-physics on rapier3d) — rigid bodies, colliders, collision/trigger events, scene queries (raycast/ shape-cast/overlap), joints, a kinematic character controller, and editor integration (addable components, collider wireframe gizmos, a freeze-on-click raycast debug probe). Stage 10 — Scripting, Live Reload & Editor Terminal (rhai, the oxide-script crate) is now in progress: the Script component, the .rhai asset loader, and the sandboxed script engine have landed; lifecycle execution, live reload, and the editor terminal follow.

Available now:

• oxide_engine::math — Transform, Aabb, Ray, Plane, Frustum, Color, Rect, Range3
• oxide_engine::window — window creation, WindowApp trait + event loop, raw input events (winit)
• oxide_engine::render — GPU setup (wgpu), surface management, clear loop, and a forward renderer: Mesh/Vertex (+ cube/plane/sphere primitives), Material, Camera, ForwardRenderer; data-driven RenderPipeline (RenderPass/ClearPass/ForwardPass)
• oxide_engine::scene — Scene, Node, entity hierarchy with world-transform resolution, RON serialization (hecs)
• oxide_engine::app — the App core, Module/DefaultModules, and the Schedule (system phases + fixed timestep)
• oxide_engine::layer — LayerMask, LayerRegistry, and Layers/Tags components (shared filtering primitive)
• oxide_engine::reflect — TypeRegistry for generic, name-keyed component access (dual-editability)
• oxide_engine::asset — AssetServer + ref-counted Handle<T> (dedup, background load, reload by path)
• oxide_engine::project — Project (create/open/save, folder layout, enabled modules, per-project settings) + RecentProjects MRU list
• oxide_engine::settings — typed Settings sections (engine/editor/per-module), export/import (RON)
• oxide_engine::watch — FileWatcher with a debounced/deduplicated change-event stream and reload_changed_assets helper that drives AssetServer::reload_path
• oxide_editor::shell::Shell — docking shell (menu bar, dock area, status bar, Preferences window); oxide_editor::command / commands — CommandStack + SetTransformCmd (drag-coalesce) / RenameCmd; oxide_editor::extension — module → editor EditorModule extension API
• oxide_engine::input — per-frame InputState (keyboard / mouse / cursor / scroll, edge detection), remappable ActionMap with Binding / AxisBinding / Axis2DBinding, RON-persistable ActionOverrides (Stage-7 piece 1–3)
• oxide_editor::gizmo — pure-logic transform-gizmo math (hit testing, drag projection, snap); oxide_editor::bindings — default editor action set (camera + gizmo hotkeys); oxide_editor::preferences — ~/.config/oxide/editor.ron load/save. The viewport ships a flythrough camera (F-toggle), translate / rotate / scale gizmos with Ctrl-snap and undo, and an Input Bindings preferences page (Stage-7 pieces 4–6)
• oxide_engine::ui — in-game UI system (Stage-8 pieces 1–6): Widget tree with stack / grid / anchor layouts, DPI-aware sizing, per-widget visual styles with named-style Theme cascade, ab_glyph-backed text shaping + shelf-packed R8 GlyphAtlas, paint() → DrawCommands consumed by screen-space and world-space (UiPanel) UiOverlayPass in oxide_engine::render, hit-test + hover/focus/press Router with immediate-mode RouterFrame::clicked_left(...) queries, typed WidgetValue (Bool / Int / Float / Text) for game-data round-tripping. Runnable example: cargo run -p oxide-examples --bin ui_menu (Stage-8 piece 7)

Features (planned — see the Roadmap)

Phase 1 — the general-purpose engine:

• ✅ Math & core primitives (transforms, bounds, rays, frustum culling)
• ✅ Window, GPU context & clear-color render loop (winit + wgpu)
• ✅ Scene graph and entity management (ECS-based, hecs)
• ✅ Basic 3D rendering (meshes, PBR-lite materials, camera, GLTF import, editor viewport)
• ✅ Engine core framework: module/plugin system, layers & tags, asset server, reflection registry, data-driven render pass pipeline
• ✅ Editor framework & project system: top menu, dockable panels, undo/redo, module extension API, settings/preferences, create/open/save projects with live file watching
• ✅ Input system with remappable named actions (per-key edges + button/axis actions; RON-persisted remap surfaced through the editor's Input Bindings preferences page) and editor transform gizmos (translate / rotate / scale with Ctrl-snap and undo, W/E/R hotkeys, flythrough viewport camera)
• ✅ Comprehensive in-game UI system (widgets, layout, theming, text) authored in a visual editor canvas
• ✅ Reflection-driven inspector, prefabs, asset database, layers/groups (Stage 8.5)
• ✅ Editor play mode: Play/Pause/Step/Stop with snapshot-on-Play / restore-on-Stop (Stage 8.7)
• ✅ Comprehensive rigid-body physics (rapier3d): colliders, joints, scene queries, collision/ trigger events, kinematic character controller, editor integration + collider/raycast gizmos (Stage 9)
• Scripting with live reload + an in-editor terminal (host tools/AI agents that edit game code live)
• Skeletal animation · GPU-driven particles · shader hot-reload & scalable post-processing
• Standard audio (mixer/spatial)
• Built-in content kit: prototyping primitives, shaders, and a character controller
• Game export to standalone Linux and Windows binaries
• In-engine editor (oxide-editor) built alongside the engine

Phase 2 — optional built-in modules (feature-gated):

• Ray-traced spatial audio (wave propagation, occlusion, reverb)
• Developer console & cheats
• Procedural toolkit (noise + composable modifier stack)
• Terrain: generate, sculpt & paint with brushes, scatter grass/trees/objects
• Open world streaming (chunking, async asset loading, LOD)
• Pathfinding & NPC AI (navmesh, agents, behavior trees, perception)
• Water (rendering + buoyancy/swim/flow mechanics)

---

Requirements

• Rust stable toolchain (rustup recommended)
• Linux — primary target, on both Wayland and Xorg (X11). Windows support and cross-platform game export are planned (see the Roadmap, Stage 16); other platforms are not yet tested.
• A GPU with Vulkan or Metal support (for wgpu)

Install Rust if you don't have it:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

---

Building

cargo build --release

To build and run the editor directly:

cargo run -p oxide-editor --release

Examples

Each stage ships at least one runnable example. List and run them with:

cargo run -p oxide-examples --bin math_demo      # Stage 1: math primitives tour
cargo run -p oxide-examples --bin hello_window   # Stage 2: window + clear color (1–5/Space to recolor, Esc quits)
cargo run -p oxide-examples --bin scene_basic    # Stage 3: build a hierarchy, print world transforms, round-trip RON
cargo run -p oxide-examples --bin hello_mesh     # Stage 4: lit 3D meshes (spinning cube + sphere + ground), Esc quits
cargo run -p oxide-examples --bin ui_menu        # Stage 8: themed main menu + settings (draggable slider, checkbox), Esc quits
cargo run -p oxide-examples --bin ui_hud         # Stage 8: HUD (HP/ammo/minimap/crosshair) over a 3D scene, Esc quits
cargo run -p oxide-examples --bin physics_stack    # Stage 9: a stack of boxes settles + a ball lands (headless console)
cargo run -p oxide-examples --bin character_capsule # Stage 9: a capsule walks, climbs a step, jumps, hits a wall (headless console)
cargo run -p oxide-examples --bin script_spin      # Stage 10: a rhai script spins an entity; the script is edited live and the spin rate jumps (headless console)

Benchmarks

Performance-sensitive systems have criterion benchmarks:

cargo bench -p oxide-engine

---

Installing (Linux)

The install.sh script compiles the project and installs it to your system (/usr/local):

chmod +x install.sh
./install.sh

After installation the editor is available as:

oxide-editor

To uninstall:

sudo rm /usr/local/bin/oxide-editor
sudo rm -rf /usr/local/share/oxide

---

Running tests

cargo test

Lint and format checks:

cargo clippy -- -D warnings
cargo fmt --check

---

Documentation

The full documentation — usage guides, per-system API references, and explanations of the engine's inner workings — lives on the wiki. Start there for anything beyond this overview:

• Getting Started — build, run, test, install
• Architecture — workspace and design overview
• Conventions — coordinate system, units, color space
• Development Workflow — branches, testing, contributing
• Math & Core Primitives — Stage 1 API reference
• Windowing & App Loop — Stage 2 window/event-loop reference
• Render Context — Stage 2 GPU/surface reference
• Scene Graph & Entities — Stage 3 scene/hierarchy/serialization reference
• Rendering — Stage 4 mesh/material/camera/forward-renderer reference

The Roadmap is the staged plan, and Working notes holds the project's rules. Both used to be files in this repository.

---

Project layout

Oxide/
├── assets/          # Project logos and shared assets
├── engine/          # Core engine library (oxide-engine)
├── editor/          # In-engine editor binary (oxide-editor)
├── examples/        # Runnable stage examples (oxide-examples)
├── tests/           # Integration test harness (oxide-tests)
└── install.sh       # Build + system install script

---

Development roadmap

Development follows a staged plan — each stage is fully tested before the next begins. See the Roadmap for the complete plan.

---

License

MIT — see LICENSE.