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>
2026-07-05 20:41:02 +02:00
parent 2afb56b329
commit 9eead719b0
157 changed files with 47270 additions and 2 deletions
@@ -0,0 +1,113 @@
+# Getting Started
+
+This guide takes you from a clean machine to building Oxide, running an example,
+and running the test and benchmark suites.
+
+## Prerequisites
+
+- **Rust stable toolchain.** Install via [rustup](https://rustup.rs):
+  ```sh
+  curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+  ```
+  Oxide tracks the stable channel and sets a minimum supported Rust version
+  (MSRV) in the workspace `Cargo.toml` (`rust-version`).
+- **Linux** is the primary target. Other platforms are not yet tested.
+- **A GPU with Vulkan support** (`wgpu` is integrated since Stage 2; on Linux
+  the Vulkan backend is the default). Backend selection can be overridden with
+  the `WGPU_BACKEND` environment variable.
+
+## Cloning
+
+```sh
+git clone https://git.houmeres.sk/Houmeres/Oxide.git
+cd Oxide
+```
+
+## Building
+
+Build the whole workspace (engine, editor, examples, tests):
+
+```sh
+cargo build            # debug
+cargo build --release  # optimized
+```
+
+The workspace is a Cargo workspace with these members:
+
+- `oxide-engine` — the core library
+- `oxide-editor` — the in-engine editor binary
+- `oxide-examples` — runnable examples (one or more per stage)
+- `oxide-tests` — the integration test harness
+
+## Running the editor
+
+```sh
+cargo run -p oxide-editor --release
+```
+
+The editor opens its own window with a placeholder viewport (Stage 2); editor
+panels arrive with the systems they edit in later stages. Quit with `Ctrl+Q`.
+Raw input logging is visible with `RUST_LOG=debug`.
+
+## Running examples
+
+Examples live in `examples/src/bin/` and each is a standalone binary:
+
+```sh
+cargo run -p oxide-examples --bin math_demo
+```
+
+| Example | Stage | Description |
+|---------|-------|-------------|
+| `math_demo` | 1 | Prints a tour of transforms, bounds, ray/plane queries, frustum culling, color, and value ranges |
+| `hello_window` | 2 | Opens a window cleared to a configurable color — keys `1`–`5` pick presets, `Space` cycles, `Esc` quits; FPS logged once per second |
+
+## Running tests
+
+```sh
+cargo test                       # the whole workspace
+cargo test -p oxide-engine       # engine unit tests only
+cargo test -p oxide-tests        # integration tests only
+```
+
+Unit tests live next to the code they test (a `#[cfg(test)] mod tests` block in
+each module). End-to-end and cross-cutting tests live in the `oxide-tests` crate.
+
+## Running benchmarks
+
+Performance-sensitive systems use [criterion](https://github.com/bheisler/criterion.rs):
+
+```sh
+cargo bench -p oxide-engine
+```
+
+Stage 1 ships the `transform` benchmark, which includes `compose_1m` (the Stage 1
+budget is 1,000,000 transform compositions in under 10 ms).
+
+## Lint and format
+
+Both must be clean before any change is committed:
+
+```sh
+cargo clippy --all-targets -- -D warnings
+cargo fmt --check
+```
+
+The engine and editor crates are compiled with `#![deny(warnings)]`, so warnings
+are hard errors.
+
+## Installing to the system (Linux)
+
+```sh
+chmod +x install.sh
+./install.sh                 # installs to /usr/local
+PREFIX=$HOME/.local ./install.sh   # custom prefix
+```
+
+This builds in release mode and installs the `oxide-editor` binary plus assets.
+To uninstall:
+
+```sh
+sudo rm /usr/local/bin/oxide-editor
+sudo rm -rf /usr/local/share/oxide
+```