Contribute to Byte Engine

Use this section when you work on the engine repository. For application development, start with Develop with Byte.

Test your changes

Install and run the engine's default test harness from the workspace root:

cargo install cargo-nextest --version 0.9.140 --locked
cargo nextest run --workspace

Nextest does not run Rust documentation tests. If you add or change an example in API documentation, run it separately:

cargo test --doc --workspace

The default Nextest profile skips the GHI rendering integration tests because they need a local GPU. Run them explicitly when you change GHI rendering, resource lifetime, or backend command behavior:

cargo nextest run --ignore-default-filter \
  -p byte-engine-ghi \
  --test rendering

This command runs the rendering tests for your operating system's active GHI backend. Presentation and ray-tracing tests that are marked as ignored remain skipped.

Run benchmarks

Run all available benchmarks from the repository root:

cargo bench --workspace

To run one benchmark target, pass its name and any required features. For example, run the audio graph benchmarks with:

cargo bench -p byte-engine --bench audio_graph

This Divan report compares callback-time evaluation for direct playback, sample-rate conversion, custom processing, and pitch shifting. Graph setup, sample loading, and buffer allocation happen before each measured loop.

To compare animation graph playback and inertialized transitions across different skeleton sizes, run:

cargo bench -p byte-engine --bench animation_graph

This benchmark also prepares graphs, resident clips, and retained pose buffers before each measured loop.

To check that one benchmark target builds and starts without collecting timing data, pass --test to Divan. For example:

cargo bench -p byte-engine --bench animation_graph -- --test

Measure code coverage

Install cargo-llvm-cov:

cargo install cargo-llvm-cov

Then generate an LCOV report:

cargo llvm-cov --lcov --output-path coverage/lcov.info

To view the report in Visual Studio Code, install the markis.code-coverage extension.

Write documentation

Use ISO 24495-1 plain-language principles for Rust comments and API documentation. Keep useful links between types, traits, functions, methods, and modules even when a strict plain-language rewrite would remove them. Developers use these links to navigate the API.

When an API participates in a larger workflow, include a short next-step hint with a link to the type, method, or trait that a developer normally uses next. Add these hints to modules, types, constructors, and transition methods where they clarify the path through the engine. Skip trivial fields and accessors.

Use the Microsoft Writing Style Guide for pages in docs. Address the reader directly, lead with their goal, use familiar words, and make the next action clear.