bunyip

Bunyip

A complete game engine in Go. It draws 2D sprites and physically based 3D models in the same frame, and includes an entity component system, physics, animation, celestial mechanics, interface toolkit, audio mixer, asset pipeline, saves, translation and networking, all written for this engine and documented in one voice. It is built for games that simulate as much as they render: roguelikes, 4X strategy, space games, arcade games. Pure Go, no cgo, with headless screenshot tests for the rendering examples.

How it is built

• Pure Go, CGO_ENABLED=0 everywhere. Vulkan is called through a generated binding and every native library is opened at run time with purego; MoltenVK provides Vulkan on macOS.
• Native window, input and audio layers per platform. No SDL, no GLFW.
• Two loop modes: a fixed timestep for real-time games, or turn-based, where the process sleeps in the operating system until input arrives.
• Go 1.27 generic methods keep typed operations on their owning objects. Graphics manages GPU lifetimes; closures manage temporary drawing state, deferred entity changes and context cleanup.
• Rendering examples run to a screenshot without a window, and the renderer's tests render into offscreen images and read the pixels back.

What it does

• 2D: sprites, sheets and tilemaps, autotiling with blob, edge, dual-grid and Wang tilesets on square, hexagonal and isometric grids, Tiled maps and terrain sets, a camera with follow, clamp and shake that culls what it cannot see, sort keys within a layer, atlases with tag animations, Aseprite files read as they are saved, vector paths with gradients and dashes, particles on the CPU or as instanced quads for hundreds of thousands, HarfBuzz-shaped text with colour glyphs (COLR, SVG and bitmap emoji), rich markup and hyphenation in thirteen languages, colour matrices, lit sprites with shadows cast from occluders, blend modes and game-written WGSL shaders, compiled offline or at runtime in Go with hot reload. See the shader guide.
• 3D: physically based materials with clearcoat, sheen, subsurface, glass, iridescence, anisotropy, specular tinting and fur as shells; glTF models with skeletal animation, blend spaces, IK and morph targets blended in the vertex shader, whose materials any part can override; cascaded shadows, spot and point lights with shadows, clustered lighting for a thousand lights a frame, a procedural sky with atmospheric scattering and aerial perspective or image-based lighting from OpenEXR, Radiance or ordinary panoramas, fog; reflection probes, baked light probe grids and screen-space reflections; order-independent transparency; instancing, frustum and occlusion culling, static batches behind a bounding volume hierarchy, levels of detail and impostors baked from a model; billboards, decals, outlines, x-ray and stencil masks; dynamic meshes and chunked terrain with a splat map; SSAO, bloom, tone mapping and colour grading, multisampling, FXAA or temporal anti-aliasing with a velocity buffer, depth of field, motion blur, god rays and lens effects, and the same post pass over a 2D-only frame; render textures and picking.
• Interface: immediate-mode widgets with themes and skins, from panels and windows to tables, trees, menus, modals, text editing, drag and drop, and keyboard or gamepad navigation, with an accessibility tree.
• Audio: a mixer with streamed WAV, Ogg Vorbis and MP3, positional voices with panning or a binaural head model, Doppler and occlusion, buses, reverb zones, microphone capture, and a tracker player for MOD, S3M, XM and IT.
• Simulation: an archetype entity component system with saving, prefabs, cloning and a JSON scene format; 2D and 3D rigid bodies with joints, ragdolls, character controllers and queries; cloth, volumetric soft bodies and 2D fluids on the same colliders; celestial mechanics for any star system.
• Services: assets and pack files with background loading, an offline texture pipeline that compresses to the BC formats with their mip chains, and hot reload that swaps a changed texture or shader into the objects a game already holds, saves and settings, translation with plural rules, seeded random numbers, timers and cutscene sequences, tweens, grids with pathfinding and field of view, and networking over TCP (with TLS) and UDP (with reliable channels, prediction and interpolation helpers).
• The window: a fixed view scaled into the window, fullscreen, cursor capture and images, the clipboard on every platform, pausing while unfocused or hidden, gamepads, macOS IME text input, action maps with rebinding, a frame-timing overlay on F3, and optional pprof.
• Debugging: an in-game console with commands, variables, key bindings and the log, and panels for the frame timings, per-pass GPU times from timestamp queries, the GPU resources and post-processing, a world's entities and systems, the physics simulation, the mixer, the input devices and a game's own services.

macOS is the tested target. The Windows (Win32, WASAPI, XInput) and Linux (Wayland or X11, ALSA, joystick devices) layers sit behind the same internal/platform and internal/audioout interfaces. The Linux window layer has run on real hardware, both Wayland and X11, and so have Linux audio output and capture; the Linux gamepad layer, macOS capture and the whole Windows layer cross-compile and vet but have not. On Linux the window layer uses Wayland where a compositor is running and falls back to X11 through xcb; BUNYIP_X11=1 forces X11.

Documentation

Guides (including a step-by-step Tetris) and the API reference for every package, with runnable examples and symbol search, are published at https://matjam.github.io/bunyip/ by the Docs workflow on each push to main. The site is built by go run ./cmd/bunyip-docs -out site from the Markdown in docs/guides and the packages' godoc, so go doc ./gfx shows the same text and go test ./... runs every example that prints output. The guides are grouped: Start (introduction, Why Go?, getting started, API design and Tetris), Engine (the window, input, entities and systems, game services), Graphics (2D graphics, 3D graphics, shaders, animation, the interface), Simulation (physics, orbits) and Audio.

Every page is also published as Markdown for language models and other tools: the guides at guides/<name>.md, each package at pkg/<package>.md, an index at llms.txt and everything in one file at llms-full.txt. CLAUDE.md in the repository is written for a model working on the engine or writing a game with it.

Why Go? explains the benefits and tradeoffs of Go as the engine's foundation. The API design guide explains resource ownership, cleanup, defaults and scoped operations with examples.

Packages

A game

Import the runtime as github.com/matjam/bunyip/engine; graphics, input and other systems remain separate packages in the same module.

type game struct{ tex *gfx.Texture }

func (g *game) Init(ctx *engine.Context) error {
	var err error
	g.tex, err = ctx.Gfx.NewTexture(img, gfx.TextureOptions{})
	return err
}

func (g *game) Update(ctx *engine.Context) error {
	if ctx.Input.KeyPressed(input.KeyEscape) {
		ctx.Quit()
	}
	return nil
}

func (g *game) Draw(ctx *engine.Context) error {
	ctx.Gfx.DrawTexture(g.tex, 100, 100)
	return nil
}

func main() {
	engine.Run(engine.Config{Title: "Hello", Width: 1280, Height: 720}, &game{})
}

Examples

Screenshot-capable examples take -seconds N and -shot file.png, so a run can verify itself without a person watching the screen. The headless harness excludes window (native platform), network (needs a peer), and clear (uniform output). assets is checked for nonblank output but has no golden comparison because it changes its files and run counter.

Each one has a walkthrough on the documentation site that quotes the whole program and explains it section by section: matjam.github.io/bunyip/examples/.

Requirements

Go 1.27 or later, and a Vulkan driver.

Set CGO_ENABLED=0 for all Go commands shown here: export CGO_ENABLED=0 in a POSIX shell, or $env:CGO_ENABLED = "0" in PowerShell.

macOS: the Vulkan loader and MoltenVK (brew install vulkan-loader molten-vk), or the LunarG Vulkan SDK. Optional: brew install vulkan-validationlayers for validation in tests and examples. Set BUNYIP_VULKAN_LIBRARY to point at a specific library.

Linux: a Vulkan driver, libasound, and either libwayland-client 1.20 or later for a Wayland session or libxcb for an X11 one. libxkbcommon gives text input on both, libxkbcommon-x11 is needed for X11, libxcb-xkb gives X11 detectable key repeat, and libwayland-cursor gives the pointer its shapes under Wayland. Windows: a Vulkan driver (vulkan-1.dll ships with GPU drivers).

Developing

go generate ./internal/vk        # after updating third_party/vulkan/vk.xml
go generate ./gfx/shaders ./internal/render/shaders   # uses the native Go shader compiler
go test ./...                    # headless GPU tests skip without a driver
go vet ./...

Renderer tests render into offscreen images, read the frame back and check pixels; headless mode needs no window system and no surface extension, so it works without a desktop when the driver supports the renderer's Vulkan features. go test ./examples/ runs the examples covered by the harness headless for a moment and compares the frame against a stored image in examples/testdata: a mean difference over the whole frame, and a tighter comparison of both frames blurred, which is what catches something moving rather than something changing colour. A failure writes the frame, the stored image and a diff to a temporary directory it names. The runs are made reproducible by BUNYIP_FIXED_CLOCK=1, which counts frames instead of reading the wall clock. Rerecord the images after a deliberate change with go test ./examples -run TestExamplesRun -update, adding -docs to rewrite the walkthrough screenshots from the same run. It needs a GPU and is skipped with -short. The parsers have fuzz targets: go test -fuzz=Fuzz ./audio/... and the same in gltf, tiled and gfx.