Table of Contents

Oxide Engine — working notes

Project Overview

Core Feature Goals (Phase 1 — the general-purpose engine)
Built-in Modules (Phase 2 — optional, feature-gated)
Platform & Targets

Development Philosophy
Documentation & File Maintenance

The engine documentation

Packaging, Installation & Export
Language & Tooling
Repository
Git Workflow & Branching
Working with Claude

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

Oxide Engine — working notes

The project's rules and context. This page was the repository's CLAUDE.md until 2026-08-08; it is loaded by reading it, not automatically, so read it before starting work.

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 Roadmap):

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 Roadmap 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

The documentation is this wiki, and it is not in the repository. It moved here on 2026-08-08 and was removed from the repository's history in the same pass. The repository holds the engine and what ships with it — README.md, LICENSE, install.sh — and nothing written about the work. Do not recreate CLAUDE.md, PLAN.md, HANDOFF.md or a docs/ directory inside it.

Always update this page, Roadmap, the repository's README.md, and .gitignore when project rules, goals, stage definitions, or project structure change.
Roadmap is the authoritative roadmap — keep it accurate and up-to-date.
README.md stays in the repository and must reflect the current build/install instructions and feature list at all times. Keep it a short overview — detailed documentation belongs on this wiki, not in 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 any of this become stale after structural or process changes.

The engine documentation

This wiki holds the full documentation of the engine — both usage (how to call each system) and inner workings (how/why it works). The project is far too large to fit that in README.md.
Write documentation as you work, not after. A stage is not complete until its systems are documented here.
One topic per page; link between pages rather than duplicating. Home is the index — add new pages to it.
When an API changes, update the affected page and its code snippets in the same session so the documentation never drifts from the code. It is a separate repository (Oxide.wiki, cloned beside Oxide), so this is a second commit rather than part of the code commit — push both.

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 Roadmap 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: ssh://git@git.houmeres.sk:2222/Houmeres/Oxide.git
Documentation: this wiki, cloned beside the repository as Oxide.wiki/

Git Workflow & Branching

Two long-lived branches: dev (integration) and main (stable). Full detail in Development; the rules an agent 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 Roadmap for the full staged plan 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 this page, Roadmap, and the repository's README.md before considering the task done