Install

To create and play games, install the prebuilt gozen binary for your operating system. No Go compiler is required. Go 1.26.10 or later is needed only when building the engine.

The gozen command #

Download the archive for your OS and processor from Releases, extract it, and put its executable in a directory on your PATH. Keep the license notices from the archive. You can also install it with Homebrew:

brew install --cask nao1215/tap/gozen   # macOS and Linux with Homebrew

The release page has .tar.gz and .zip archives for Linux, macOS and Windows (amd64 and arm64) and .deb, .rpm and .apk packages for Linux. The prebuilt binaries are built without cgo, so they have no ONNX inference for gozen mosaic. Each release signs checksums.txt with cosign and attaches SBOMs and SLSA provenance; Verifying a release shows the commands.

After installation, gozen version reports the installed version. Follow Getting started to create your first game. new, check and simulation do not need a display; run needs the graphics runtime described below. Inference tools have additional prerequisites described in Production tools.

Optional installation from Go source #

These steps are for engine developers and existing Go projects. They are not needed for YAML game creation.

go install github.com/nao1215/gozen/cmd/gozen@latest
gozen version

To keep the command pinned with your game, add it as a Go tool in your module and run it with go tool gozen:

go get -tool github.com/nao1215/gozen/cmd/gozen@latest
go tool gozen check game

In GitHub Actions #

setup-gozen installs the release binary of the version in your go.mod, checked against the release checksums:

- uses: actions/checkout@v6
- uses: nao1215/setup-gozen@1c378fc446f62ecb29a7bcd40aea6dff8565d698 # v0.1.1
- run: gozen check game

version also takes latest or a release such as v0.2.0, and go-mod-path points at a go.mod below the root. Without the action, go run github.com/nao1215/gozen/cmd/gozen check game builds the same version from go.mod. See the CI recipe.

Verifying a release #

Each release has a cosign-signed checksums.txt, an SPDX SBOM per archive, SLSA provenance (multiple.intoto.jsonl), and the dependency licenses under THIRD_PARTY_LICENSES/.

cosign verify-blob \
  --bundle checksums.txt.sigstore.json \
  --certificate-identity-regexp 'https://github.com/nao1215/gozen/\.github/workflows/release\.yml@refs/tags/.*' \
  --certificate-oidc-issuer 'https://token.actions.githubusercontent.com' \
  checksums.txt
sha256sum --check --ignore-missing checksums.txt

gh attestation verify gozen_<version>_<os>_<arch>.tar.gz --repo nao1215/gozen

slsa-verifier verify-artifact gozen_<version>_<os>_<arch>.tar.gz \
  --provenance-path multiple.intoto.jsonl \
  --source-uri github.com/nao1215/gozen \
  --source-tag v<version>

What the window needs #

Gozen draws with Ebitengine v2.10. A normal build needs no C compiler. The race detector needs cgo and a C compiler on every OS.

OS	Prepare
Linux (Ubuntu 24.04 or later)	`sudo apt-get install libx11-6 libgl1 libglx-mesa0 libxcursor1 libxi6 libxinerama1 libxrandr2 libxrender1 libxext6 libasound2t64`. These are needed at run time even with `CGO_ENABLED=0`.
Windows	A GPU driver with OpenGL and a logged-in desktop.
macOS	A desktop session. For the race detector, `xcode-select --install`.

Check the setup by opening a generated game:

gozen new window-check

gozen run window-check

CI runs the screen tests and a packaged game on Linux, Windows and macOS runners, with the sound muted. Play by hand has been done on Linux only; reports from Windows and macOS are welcome.

Without a screen (CI, servers) #

On Linux, run the window inside Xvfb, a virtual display. This creates a game, captures its title screen and quits:

sudo apt-get install xvfb xauth
gozen new ci-check
printf 'wait 20\nshot title\nquit\n' > check.txt
xvfb-run -a gozen run ci-check --dev --mute --script check.txt --shots frames

frames/title.png contains the title screen. Scripted runs, traces and screenshot capture use the same runner as ordinary play. gozen check and gozen sim need no display at all.

Optional tools #

Tool	Used by
ffmpeg	`--record` to write an MP4 of a scripted or automatic play (`sudo apt-get install ffmpeg`, `brew install ffmpeg`, or the ffmpeg build’s `bin` on `PATH` on Windows)
zenity	`--external-input` on Linux, for typing text in a system dialog instead of in the window
A C compiler and ONNX Runtime	`gozen mosaic` detection; see Production tools

No model, ONNX Runtime or asset download is needed to build or play a game.