Skip to content

Getting started ​

Requirements ​

  • Rust 1.95 or later. rust-toolchain.toml selects the stable channel with rustfmt and clippy, and the workspace's rust-version is 1.95, which CI checks.

  • On Linux: ALSA's and udev's development packages, for cpal (sound) and gilrs (gamepads). On Debian and Ubuntu:

    sh
    sudo apt-get install -y libasound2-dev libudev-dev
  • A GPU, for some tests. wgpu finds a hardware or a software adapter (llvmpipe, WARP). The tests that draw report a skip and pass when there is none.

  • Node 22.18 or later and a SHAG checkout, only to regenerate golden vectors (see Golden vectors).

Build and test ​

sh
git clone https://github.com/Higher-Standard-Games/shagger
cd shagger
cargo build --workspace
cargo test --workspace

The workspace has two crates, shagger_shared and shagger (Project structure). Neither has a binary: the programs are the games built on them.

Some tests read data that is not in the repository. They pass without it and say so:

VariableWhat the test reads
SHAGGER_PLAYER_DATAa folder holding washoi_player_model.pk3, for tests/player_model_golden.rs
SHAGGER_TEST_FONTa TrueType or OpenType file, for the font and Hud2d tests
SHAGGER_TEST_MP3an MP3 file, for the music decoder test

The checks CI runs, and the ones to run before pushing, are listed in Contributing.

Use it from a game ​

A game depends on both crates by git revision. wash-fps-rust pins one in its Cargo.toml:

toml
[dependencies]
shagger = { git = "https://github.com/Higher-Standard-Games/shagger", rev = "<commit>" }

shagger re-exports shagger_shared as shagger::shared, and the renderer re-exports wgpu and glam as shagger::rendering::wgpu and shagger::rendering::glam, so a game builds against the same versions the engine does.

To move the pin, change rev and run cargo update -p shagger.

Working on the engine and a game together ​

Clone shagger next to the game and point Cargo at the local copy in the game's .cargo/config.toml (wash-fps-rust keeps that file out of git):

toml
[patch."https://github.com/Higher-Standard-Games/shagger"]
shagger = { path = "../shagger/crates/shagger" }
shagger_shared = { path = "../shagger/crates/shagger_shared" }

The patch also rewrites the game's Cargo.lock. Do not commit that change: land the engine change in shagger first, then move the game's pin to the merged commit with the patch set aside, so the lock file names the git revision.

Reading this manual locally ​

The manual reads on GitHub as it is. To serve it as a site with search, as SHAG's is, use VitePress (Node 18 or later):

sh
npm install
npm run docs:dev      # http://localhost:5173
npm run docs:build    # writes dist-docs/, and fails on a dead link

Node is only for the manual and the golden vectors; the engine builds with Cargo alone.

Next ​

Released under the MIT License. Babylon.js ports under Apache-2.0.