Byte Engine Docs

Add a published release, Git dependency, or local engine checkout to your Rust application.

Install Byte Engine as a Cargo dependency in the project you created.

Complete the environment setup and create your project before following this guide.

Choose an installation method

The installation method determines where Cargo gets the Byte Engine source:

Published release: Choose this for most applications. Cargo selects a released version from crates.io using normal package version resolution.
Git dependency: Choose this when you need unreleased engine changes but don't need to edit the engine locally. Cargo fetches the source from the Byte Engine Git repository.
Local checkout: Choose this when you want to inspect or modify the engine alongside your application. Cargo uses a path to a checkout that you update.

Install the published release

From your project folder, add the latest published Byte Engine release:

cargo add byte-engine

Cargo adds the published package version to your crate's Cargo.toml.

Expose the engine assets

Byte Engine's built-in rendering uses shaders from the engine's assets/ directory. Vendor the resolved crate so the link target doesn't depend on Cargo's registry cache:

cargo vendor --locked vendor
mkdir -p assets
ln -s ../vendor/byte-engine/assets assets/byte-engine

cargo vendor --locked vendor
mkdir -p assets
ln -s ../vendor/byte-engine/assets assets/byte-engine

cargo vendor --locked vendor
New-Item -ItemType Directory -Force assets
New-Item -ItemType SymbolicLink `
  -Path assets/byte-engine `
  -Target (Resolve-Path vendor/byte-engine/assets)

Install a Git dependency

From your project folder, add Byte Engine directly from its Git repository:

cargo add byte-engine --git https://github.com/Game-Tek/Byte-Engine

Cargo records the Git repository in your application's Cargo.toml and fetches the engine source when it resolves dependencies.

Expose the engine assets

Vendor the resolved Git dependency, then link its engine assets into the application's asset namespace:

cargo vendor --locked vendor
mkdir -p assets
ln -s ../vendor/byte-engine/assets assets/byte-engine

cargo vendor --locked vendor
mkdir -p assets
ln -s ../vendor/byte-engine/assets assets/byte-engine

cargo vendor --locked vendor
New-Item -ItemType Directory -Force assets
New-Item -ItemType SymbolicLink `
  -Path assets/byte-engine `
  -Target (Resolve-Path vendor/byte-engine/assets)

Use a local engine checkout

Clone Byte Engine and add it to your application as a local path dependency.

Arrange the local workspaces

Use a shared parent directory for the engine repository and your application workspace. This layout matches the Byte Engine sandbox workspace:

development/
├── Byte-Engine/
│   └── crates/
│       └── byte-engine/
└── my-game/
    ├── Cargo.toml
    ├── rust-toolchain.toml
    └── src/
        └── main.rs

From the shared parent directory, clone Byte Engine:

git clone https://github.com/Game-Tek/Byte-Engine.git

If your directories use different names or locations, adjust the dependency paths in the following steps.

Add the engine crate

From my-game/, add the local checkout with Cargo:

cargo add byte-engine --path ../Byte-Engine/crates/byte-engine

This command adds the following dependency to my-game/Cargo.toml:

[dependencies]
byte-engine = { path = "../Byte-Engine/crates/byte-engine" }

Cargo resolves the path from my-game/Cargo.toml. In this layout, ../Byte-Engine selects the sibling engine checkout.

If your application also uses a lower-level engine crate directly, add its package name and local path. For example:

[dependencies]
byte-engine = { path = "../Byte-Engine/crates/byte-engine" }
ghi = { package = "byte-engine-ghi", path = "../Byte-Engine/crates/ghi" }
resource-management = { package = "byte-engine-resource-management", path = "../Byte-Engine/crates/resource-management" }
utils = { package = "byte-engine-utils", path = "../Byte-Engine/crates/utils" }

Most applications only need the byte-engine dependency.

Expose the engine assets

Create the application asset directory and link the engine checkout's assets into it:

mkdir -p assets
ln -s ../../Byte-Engine/crates/byte-engine/assets assets/byte-engine

mkdir -p assets
ln -s ../../Byte-Engine/crates/byte-engine/assets assets/byte-engine

New-Item -ItemType Directory -Force assets
New-Item -ItemType SymbolicLink `
  -Path assets/byte-engine `
  -Target (Resolve-Path ../Byte-Engine/crates/byte-engine/assets)

The macOS and Linux target is relative to the assets/byte-engine link. The Windows command resolves the same target to an absolute path. Adjust the target if your application and engine checkout don't use the sibling layout shown above.

Verify the local setup

Run this command from my-game/:

cargo check

Cargo builds the application against the local Byte Engine checkout. Pull changes in Byte-Engine/ whenever you want to update the engine, then run the check again.

The assets/byte-engine link gives engine shaders stable resource IDs such as byte-engine/rendering/sky.besl. Keep the link in every developer and CI checkout. On Windows, enable Developer Mode before setting up the directory link. See Bake application resources for platform details and the complete baking workflow.

Next, create your first Byte.

Install Byte Engine

On this page