Oxide/README.md

# Oxide Engine

![Oxide Engine](assets/oxide.png)

> **Notice:** This project was developed with the assistance of [Claude Code](https://claude.ai/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](https://git.houmeres.sk/Houmeres/Oxide/wiki/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()` → `DrawCommand`s 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](https://git.houmeres.sk/Houmeres/Oxide/wiki/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](https://git.houmeres.sk/Houmeres/Oxide/wiki/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:

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

---

## Building

```sh
cargo build --release
```

To build and run the editor directly:

```sh
cargo run -p oxide-editor --release
```

### Examples

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

```sh
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:

```sh
cargo bench -p oxide-engine
```

---

## Installing (Linux)

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

```sh
chmod +x install.sh
./install.sh
```

After installation the editor is available as:

```sh
oxide-editor
```

To uninstall:

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

---

## Running tests

```sh
cargo test
```

Lint and format checks:

```sh
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](https://git.houmeres.sk/Houmeres/Oxide/wiki). Start there for anything
beyond this overview:

- [Getting Started](https://git.houmeres.sk/Houmeres/Oxide/wiki/Getting-started) — build, run, test, install
- [Architecture](https://git.houmeres.sk/Houmeres/Oxide/wiki/Architecture) — workspace and design overview
- [Conventions](https://git.houmeres.sk/Houmeres/Oxide/wiki/Conventions) — coordinate system, units, color space
- [Development Workflow](https://git.houmeres.sk/Houmeres/Oxide/wiki/Development) — branches, testing, contributing
- [Math & Core Primitives](https://git.houmeres.sk/Houmeres/Oxide/wiki/Math) — Stage 1 API reference
- [Windowing & App Loop](https://git.houmeres.sk/Houmeres/Oxide/wiki/Windowing) — Stage 2 window/event-loop reference
- [Render Context](https://git.houmeres.sk/Houmeres/Oxide/wiki/Render-context) — Stage 2 GPU/surface reference
- [Scene Graph & Entities](https://git.houmeres.sk/Houmeres/Oxide/wiki/Scene) — Stage 3 scene/hierarchy/serialization reference
- [Rendering](https://git.houmeres.sk/Houmeres/Oxide/wiki/Rendering) — Stage 4 mesh/material/camera/forward-renderer reference

The [Roadmap](https://git.houmeres.sk/Houmeres/Oxide/wiki/Roadmap) is the staged
plan, and [Working notes](https://git.houmeres.sk/Houmeres/Oxide/wiki/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](https://git.houmeres.sk/Houmeres/Oxide/wiki/Roadmap) for the complete plan.

---

## License

MIT — see [LICENSE](LICENSE).