Oxide/CLAUDE.md

# Oxide Engine — Claude Code Context

## Project Overview

**Oxide** is a general-purpose 3D game engine written in Rust. It is built to make **any** 3D game,
scaling from stylized low-poly (e.g. with a VCR/CRT post filter) to realistic graphics, and to **ship
only what each game uses**. It ships with an **in-engine editor** (`oxide-editor`) developed alongside
the engine and gaining capabilities at each stage.

The work is split into two phases (see `PLAN.md`):
- **Phase 1 — general-purpose engine (Stages 0–16):** everything needed to build *and export* any
  game. Stage 16 (game export to Linux + Windows) is the milestone.
- **Phase 2 — built-in modules (Stages 17+):** optional, self-contained capabilities (ray-traced
  audio, developer console, procedural toolkit, terrain, open world, pathfinding/AI, water), each a
  feature-gated **module** built on Phase-1 systems.

Simulation, open world, and procedural generation are **capabilities the engine supports through
modules**, not design drivers. The guiding idea is **build tools, not games**.

### Core Feature Goals (Phase 1 — the general-purpose engine)
- Scene graph and entity management
- **Engine core framework**: a **module/plugin system** (compile-time feature-gated crates + a
  runtime `Module` trait + `rhai` script modules), system scheduling, a **layers & tags** system
  (`LayerMask` for physics/render/query filtering + gameplay tags), a central **asset server** with
  handles, a **reflection/type registry**, and a **data-driven render pass pipeline**
- **Editor framework & project system**: top menu, dockable panels, undo/redo command stack, a
  **module→editor extension API** (modules add panels/menus/tools/inspectors), a **settings/
  preferences framework** (engine + editor + per-module settings, enable/disable modules), and a
  **project system** (create/open/save projects, file watching)
- **Comprehensive input mapping**: map any key to press/up/down, *and* named remappable actions
  (e.g. a `Jump` action defaulting to `Space` that game code references by name while players rebind
  the physical key in settings)
- **Comprehensive in-game UI system**: widgets, layout, theming, text, and input routing that ship
  inside exported games (distinct from the editor's `egui`); UI documents are serializable and
  dual-editable, authored in a visual editor canvas
- **Comprehensive** physics simulation (`rapier3d`: colliders, joints, scene queries, sensors,
  layer-filtered collision/triggers, kinematic character controller — not a thin wrapper)
- **Scripting + live reload + in-editor terminal**: game scripts are watched and hot-reloaded; the
  editor hosts a terminal that can run tools and AI agents which edit game code live
- Animation system · particle engine · shader support (simple → advanced, scalable fidelity)
- **Standard audio**: mixer/spatial system (ray-traced spatial sound is a Phase-2 module)
- **Dual-editable types**: every engine object/component type (`Transform`, `Script`, materials,
  colliders, …) is editable from both the editor UI and from scripts/code via one reflected/
  serializable representation, so any editor or AI agent can author game code and data in real time
- Built-in content kit (prototyping primitives, shaders, character controller) for fast starts
- **Game export** to standalone Linux + Windows binaries (ships only the modules a project uses)
- **In-engine editor** (first-class; not an afterthought)

### Built-in Modules (Phase 2 — optional, feature-gated)
- Ray-traced spatial audio (wave propagation, occlusion, reverb)
- Developer console & cheats (drop-in dev interface; compiled out of release)
- Procedural toolkit (noise + composable modifier stack — tools, not a fixed world generator)
- Terrain system (generate, sculpt, paint splat layers, scatter foliage/objects)
- Open world support (streaming, LOD, chunking)
- Pathfinding & NPC AI (navmesh, agents, behavior trees/state machines, perception)
- Water (rendering + buoyancy/swim/flow mechanics)

Anyone can write a module; each ships docs for **both** using it **and** authoring one.

### Platform & Targets
- **Linux is the primary platform, on both Wayland and Xorg (X11)** — keep both backends working at
  every stage (`winit` `wayland` + `x11` features).
- **Windows support is added later**, once the engine is substantial; avoid Linux-only assumptions.
- **Game export targets both Linux and Windows** standalone binaries (editor runs on Linux and can
  cross-export). See PLAN.md Stage 16.

## Development Philosophy

- Build in stages; each stage must be tested and stable before the next begins
- **Build tools, not games** — ship composable building blocks; genre-specific behavior lives in
  game code or optional modules
- **Ship only what's used** — subsystems are feature-gated modules; an exported game compiles in only
  the modules it registers
- **Scalable fidelity** — the data-driven render pass pipeline lets a project run anything from a flat
  low-poly/stylized look to a full realistic stack, paying only for the passes it enables
- **Modules are the primary extension point** — a module registers engine logic *and* editor UI *and*
  its own settings through one documented API; anyone (including AI agents) can write one
- Every system should be composable and independently usable
- Prefer correctness and clarity over premature optimization
- Keep public APIs minimal — internal complexity is fine, external surface should be clean
- No feature creep between stages; additions go into the backlog for later stages
- The editor (`oxide-editor`) grows with the engine — each stage adds editor support for new systems
  through the Stage-6 editor framework (panels, menus, undo stack, settings pages)

## Documentation & File Maintenance

- **Always update** `CLAUDE.md`, `PLAN.md`, `README.md`, and `.gitignore` when project rules, goals, stage definitions, or project structure changes
- `PLAN.md` is the authoritative roadmap — keep it accurate and up-to-date
- `README.md` must reflect the current build/install instructions and feature list at all times. Keep it a **short overview** — detailed documentation belongs in `docs/`, not the README
- `.gitignore` must be updated whenever new tools, output formats, or file types are introduced that should not be tracked (e.g. new build targets, generated files, editor temp files)
- Do not let these files become stale after structural or process changes

### Full documentation in `docs/`

- The `docs/` directory holds the full documentation of the engine — both **usage** (how to call each system) and **inner workings** (how/why it works). The project is too large to fit this in `README.md`.
- **Write documentation as you work, not after.** A stage is not complete until its systems are documented under `docs/`.
- One topic per file; link between files rather than duplicating. `docs/README.md` is the documentation index — add new docs to it.
- When an API changes, update the affected doc and its code snippets **in the same change** so docs never drift from the code.
- Current docs: `architecture.md`, `conventions.md`, `getting-started.md`, `development.md`, and per-system references (e.g. `math.md`, `windowing.md`, `render-context.md`, `scene.md`).

## Packaging, Installation & Export

- The project must be compilable to a Linux installable package
- `install.sh` at the repo root builds in release mode and installs the editor binary plus assets to the system (`/usr/local` by default, overridable via `PREFIX`)
- Keep `install.sh` updated whenever new binaries or assets are added
- The installed binary name is `oxide-editor`
- The editor must run on Linux under **both Wayland and Xorg**
- A later stage adds a **Windows build** of the editor/engine and **game export** to standalone
  Linux *and* Windows binaries (the exported game links the engine runtime without the editor) — see
  PLAN.md Stage 16; keep packaging docs current when that lands

## Language & Tooling

- Language: Rust (stable toolchain)
- Build: Cargo workspace (`engine/`, `editor/`, `examples/`, `tests/`)
- Graphics: `wgpu` (portability across Vulkan, Metal, DX12)
- Physics: `rapier3d`
- Math: `glam`
- ECS: `hecs` (preferred lightweight approach)
- Editor UI: `egui` (integrated into `oxide-editor`)
- Scripting: `rhai` (preferred — embeddable, sandboxed); file watching via `notify` for live reload
- Audio: standard system via `kira`/`rodio`; ray-traced model built on the engine's own ray casts
- Windowing backends: `winit` with both `wayland` and `x11` enabled (Linux); Win32 later

## Repository

- Remote: `https://git.houmeres.sk/Houmeres/Oxide.git`
- Local: `/home/homer/Oxide`

## Git Workflow & Branching

Two long-lived branches: **`dev`** (integration) and **`main`** (stable). Full
detail in `docs/development.md`; the rules Claude follows:

- **Auto-commit and push to `dev`** every new piece of work that can be **fully
  verified automatically** (it builds and its unit/integration/fuzz tests and
  benchmarks pass). Do this as soon as the work is complete and green — no need
  to ask first for these.
- **Manual-test gate before `main`.** If a change cannot be fully verified by
  automated tests — anything involving the GUI, rendering, audio, input feel, or
  otherwise needing a human to run the engine and observe it — push it to `dev`
  only, then ask the maintainer to test it. Promote to `main` **only after the
  maintainer explicitly approves** it works.
- **Fully-automated changes may go to both `dev` and `main` together**, because
  the passing automated suite is the sign-off (e.g. pure-logic modules like the
  math system).
- Decision rule: *"Can a test prove this works without a human looking at it?"*
  Yes → eligible for `main`. No → stop at `dev` and request manual testing. When
  in doubt, treat it as needing manual testing.
- Always run the local gate before committing:
  `cargo fmt --check && cargo clippy --all-targets -- -D warnings && cargo test`.
- End AI-assisted commit messages with the Claude co-author trailer.

## Working with Claude

- Read `PLAN.md` for the full staged roadmap before starting any new stage
- Each stage has defined deliverables and test criteria — do not skip testing phases
- When implementing a system, prefer small focused modules over large monolithic files
- Breaking changes between stages are acceptable; backward compatibility is not a goal during early stages
- After completing work that changes project structure, goals, or process, update `CLAUDE.md`, `PLAN.md`, and `README.md` before considering the task done