Import Oxide engine (Stages 0–10) under MIT license
Full project snapshot migrated to new Gitea remote without history: engine, editor, physics, script, examples, tests, docs, and assets. Relicensed from GPLv3 to MIT and updated repo URLs. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Homer Simpson
@@ -1,3 +1,252 @@
|
||||
# Oxide
|
||||
# Oxide Engine
|
||||
|
||||
Oxide general purpose 3D game engine
|
||||
|
||||
|
||||
> **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 [PLAN.md](PLAN.md)): **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 [PLAN.md](PLAN.md))
|
||||
|
||||
**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 [PLAN.md](PLAN.md), 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 in [`docs/`](docs/README.md).
|
||||
Start there for anything beyond this overview:
|
||||
|
||||
- [Getting Started](docs/getting-started.md) — build, run, test, install
|
||||
- [Architecture](docs/architecture.md) — workspace and design overview
|
||||
- [Conventions](docs/conventions.md) — coordinate system, units, color space
|
||||
- [Development Workflow](docs/development.md) — branches, testing, contributing
|
||||
- [Math & Core Primitives](docs/math.md) — Stage 1 API reference
|
||||
- [Windowing & App Loop](docs/windowing.md) — Stage 2 window/event-loop reference
|
||||
- [Render Context](docs/render-context.md) — Stage 2 GPU/surface reference
|
||||
- [Scene Graph & Entities](docs/scene.md) — Stage 3 scene/hierarchy/serialization reference
|
||||
- [Rendering](docs/rendering.md) — Stage 4 mesh/material/camera/forward-renderer reference
|
||||
|
||||
---
|
||||
|
||||
## Project layout
|
||||
|
||||
```
|
||||
Oxide/
|
||||
├── assets/ # Project logos and shared assets
|
||||
├── docs/ # Full engine documentation
|
||||
├── 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
|
||||
├── PLAN.md # Staged development roadmap
|
||||
└── CLAUDE.md # Context and rules for Claude Code
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Development roadmap
|
||||
|
||||
Development follows a staged plan — each stage is fully tested before the next begins.
|
||||
See [PLAN.md](PLAN.md) for the complete roadmap.
|
||||
|
||||
---
|
||||
|
||||
## License
|
||||
|
||||
MIT — see [LICENSE](LICENSE).
|
||||
|
||||
Reference in New Issue
Block a user