📚 Docs: https://byte-engine.0x44491229.dev/docs
Use Byte-Engine to build Rust applications that need graphics, input, audio, physics, resources, networking, and retained UI in one runtime.
Start with the public byte-engine facade for most applications. Use the
lower-level crates when you need direct access to rendering, audio, resources,
shader processing, transport, math, or utilities. Each crate provides a small,
composable engine layer.
Warning
Status: Byte-Engine is early, so expect breaking API changes. Pin the package version and review the changelog before you update.
- 🖼️ Platform graphics paths for Vulkan/Linux, Metal/macOS, and Direct3D 12/Windows.
- 🔊 Platform audio interfaces for Linux, macOS, and Windows.
- 🎮 Action-based input that lets your application respond to intent such as
Move,Fire, orConfirminstead of raw device buttons. - 📨 Actor-style system boundaries built around compact messages, factories, handles, and listeners.
- 📦 Asset pipeline that separates authored assets from runtime-ready resources.
- 🛠️ BELD, the command line each application builds for baking, listing, querying, inspecting, and deleting its resources.
- 🧪 BESL, the Byte Engine Shader Language, for shader parsing, reflection, material integration, and backend shader generation.
- 🧩 Early retained, async-friendly UI primitives that run in the engine render loop.
Byte-Engine currently targets nightly Rust and uses unstable language features.
The repository pins the toolchain in rust-toolchain.toml:
nightly-2026-08-31
Install Rust with rustup. When you run Cargo inside the checkout, it uses the
pinned nightly automatically. Install the engine's default test harness:
cargo install cargo-nextest --version 0.9.140 --lockedPlatform requirements:
| Platform | Required setup |
|---|---|
| Linux | Vulkan development packages, Wayland/X11 packages, ALSA, libudev, D-Bus, CMake |
| macOS | Full Xcode with the Metal Toolchain component, plus CMake and pkg-config |
| Windows | Visual Studio Build Tools with the MSVC C++ toolchain and Windows SDK |
On Linux, run bash install_dependencies.sh from the repository root. This
command installs the dependencies used by CI and development containers.
Use a GPU that supports the active backend, AVX2 on x64 platforms, and at least 4 GB of RAM. For complete setup information, see:
git clone https://github.com/Game-Tek/Byte-Engine.git
cd Byte-Engine
cargo check -p byte-engineRun a small smoke test:
cargo run -p byte-engine --example windowRun the default graphics setup example:
cargo run -p byte-engine --example triangleMost smoke examples set kill-after=60 and exit automatically after about one minute.
use byte_engine::application::Parameter;
use byte_engine::application::graphics::{default_setup, GraphicsApplication};
fn main() {
let mut app = GraphicsApplication::new(
"my-byte-app",
&[
// Useful on devices that do not support mesh shading yet.
Parameter::new("render.ghi.features.mesh-shading", "false"),
],
);
default_setup(&mut app);
app.do_loop();
}Install the latest published Byte-Engine release from crates.io:
cargo add byte-engineGetting the latest unreleased changes requires pulling Byte-Engine from Git and installing it with one of the additional methods in the docs.
| Path | Purpose |
|---|---|
crates/byte-engine |
Main public engine crate and application-facing facade. |
crates/ghi |
Graphics hardware interface used by the renderer. |
crates/ahi |
Audio hardware interface used by engine audio systems. |
crates/resource-management |
Asset handling, resource storage, shader resources, runtime reads, parameters, and the BELD command line. |
crates/besl |
Byte Engine Shader Language parser, lexer, semantic graph, and integration. |
crates/betp |
Byte Engine transport protocol primitives for local and remote sessions. |
crates/math |
Shared math aliases and helpers. |
crates/utils |
Shared allocation, async, sync, collection, and geometry utilities. |
docs |
Documentation source: Introduction, Use (application tasks), Contribute (engine workflow and design notes), Reference (definitions), and the generated API section. |
docs-site |
Documentation site project. |
Where required, crates use the byte-engine-* namespace so crates.io can resolve
each internal layer independently. In Rust code, use the shorter import names
such as ghi, ahi, besl, math, and utils.
Examples live in crates/byte-engine/examples.
Run them from the workspace root:
cargo run -p byte-engine --example <name>Choose an example based on the system you want to exercise:
| Example | What it exercises |
|---|---|
none |
Creates and runs a minimal graphics application without user setup. |
window |
Creates a window through the default window setup. |
triangle |
Runs the default headed graphics setup. |
cube |
Placeholder smoke path for a 3D cube scene. |
sandbox |
Placeholder smoke path for physics sandbox work. |
sound |
Audio synthesizer smoke path. |
replication |
Early networking/replication smoke path. |
Byte-Engine separates the files you author from runtime-ready resources:
- Assets are source files such as PNG, JPEG, glTF/GLB, FBX, WAV, OGG, LUT files,
.bemamaterial declarations, and BESL shader sources. - Resources are processed engine data with metadata such as format, hash, size, image extent, mesh layout, shader reflection data, and binary payloads.
- When debug or development loading is enabled, the resource manager can read an existing resource or ask an asset handler to bake it.
Give your application its own BELD binary, as Add BELD to your application shows, and run its resource commands:
beld --source assets --destination resources bake texture.png scene.glb character.fbx
beld --destination resources list
beld --destination resources inspect texture.png
beld --destination resources query class=Material --group source --format jsonFor design information, see Asset and resource management.
Use the Byte Engine Shader Language (BESL) to integrate shader code with material processing, resource reflection, render-model code generation, and platform shader generation.
The syntax is Rust-inspired, but BESL is not Rust:
albedo: descriptor<{ type: Texture2D, binding: 0, access: read }>;
main: fn (pipeline_input: interface { uv: vec2f }) -> output { color: vec4f } {
let color: vec4f = sample(albedo, pipeline_input.uv);
return { color };
}Backend coverage is still evolving. The project includes GLSL, MSL, HLSL, and platform-generator paths. For language details, see the BESL reference.
Before you make a large change, read the design documentation for the affected system:
- Actor pattern: message-passing system boundaries, factories, handles, and listeners.
- Input: device triggers, seats, actions, value mappings, and tick policies.
- Rendering: render orchestrators, render systems, render domains, and render models.
- UI: retention, invalidation, and the draw path of the UI renderer.
- Resource management: asset processing and resource storage.
Every page in docs belongs to one of five sections, chosen by who
reads it and what they ask:
| Section | The reader asks |
|---|---|
| Introduction | What is this, and where do I start? |
| Use | How do I make my application do this? |
| Contribute | How do I work on the engine, and what must my change keep true? |
| Reference | What exactly is this, and what does it accept? A specification, with no code. |
| API | What does this item do? Generated from doc comments and the inspector's OpenAPI schema. |
Read Write documentation
before you add or move a page. It defines the shape of a page in each section
and the style: the
Microsoft Writing Style Guide for
pages and ISO 24495-1 plain language
for Rust doc comments. AGENTS.md repeats these rules for coding
agents.
Common checks from the workspace root:
cargo fmt --check
cargo check --workspace
cargo nextest run --workspace
cargo test --doc --workspace
cargo clippy --workspace
cargo doc -p byte-engine --no-depsPublishing-specific verification and crate order are documented in
PUBLISHING.md.
- API documentation: https://byte-engine.0x44491229.dev/docs/api/latest/byte_engine
- Repository: https://github.com/Game-Tek/Byte-Engine
- Changelog:
CHANGELOG.md - Publishing notes:
PUBLISHING.md - User documentation: https://byte-engine.0x44491229.dev/docs
- Documentation source:
docs
Byte-Engine is licensed under the MIT license. Adapted code retains its own notices in Third-party notices. See Attribution and thanks for the people and published work the engine builds on.