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