# Bunyip

> A complete game engine in Go: a Vulkan renderer without cgo that draws 2D sprites and physically based 3D models in the same frame, an entity component system, rigid-body physics, skeletal animation, celestial mechanics, an immediate-mode interface, an audio mixer with a tracker player, and asset, save, translation and networking services, for real-time and turn-based games.

The guides explain each area of the engine; the package pages are the full API reference with doc comments, declarations and examples. Runtime import path: github.com/matjam/bunyip/engine.

The whole documentation in one file: https://matjam.github.io/bunyip/llms-full.txt

## Start guides

- [Introduction](https://matjam.github.io/bunyip/guides/introduction.md): what Bunyip is, how it is put together, and what to read next
- [Why Go?](https://matjam.github.io/bunyip/guides/why-go.md): why Go is a practical foundation for a game engine, and the tradeoffs to understand
- [Getting started](https://matjam.github.io/bunyip/guides/getting-started.md): install the Vulkan driver, open a window, learn the loop and the window controls
- [API design](https://matjam.github.io/bunyip/guides/api-design.md): ownership, cleanup, scoped work, useful defaults and typed operations
- [Building Tetris](https://matjam.github.io/bunyip/guides/tetris.md): a complete game on the entity component system, step by step

## Engine guides

- [The window](https://matjam.github.io/bunyip/guides/window.md): how the window is opened, sized and controlled, what is fixed at start and what changes at run time
- [Input](https://matjam.github.io/bunyip/guides/input.md): keys, mouse, gamepads, action maps and rebinding
- [Entities and systems](https://matjam.github.io/bunyip/guides/ecs.md): the entity component system, how it stores data, and how to structure a game around it
- [Game services](https://matjam.github.io/bunyip/guides/services.md): assets, saves, translation, random numbers, timers, sequences, tweens, grids and networking
- [The debug console](https://matjam.github.io/bunyip/guides/console.md): the in-game command line, its commands and variables, and the panels that show what the engine is doing

## Graphics guides

- [2D graphics](https://matjam.github.io/bunyip/guides/graphics-2d.md): sprites, bounds, reusable geometry, atlases, cameras, tilemaps, text, vector paths, particles, lights and render textures
- [3D graphics](https://matjam.github.io/bunyip/guides/graphics-3d.md): cameras, meshes and models, materials, lights and shadows, sky and fog, culling and LOD, post-processing and render textures for a 3D game
- [Shaders](https://matjam.github.io/bunyip/guides/shaders.md): WGSL authoring, native Go compilation, engine hooks, uniforms and texture bindings
- [Animation](https://matjam.github.io/bunyip/guides/animation.md): keyframe clips for 2D sprites and 3D transforms, flipbooks, skeletons with crossfades, events, root motion, layers, blend spaces, IK and morph targets
- [The interface](https://matjam.github.io/bunyip/guides/ui.md): immediate-mode widgets, layout, keyboard and gamepad navigation, drag and drop, themes and skins

## Simulation guides

- [Physics](https://matjam.github.io/bunyip/guides/physics.md): rigid bodies in 2D and 3D: shapes, collisions, queries, joints, ragdolls and character controllers, and the cloth, soft bodies and fluids beside them
- [Orbits and space](https://matjam.github.io/bunyip/guides/space.md): celestial mechanics for any star system: Kepler orbits, N-body gravity, ships under thrust

## Audio guides

- [Audio](https://matjam.github.io/bunyip/guides/audio.md): sounds, music, positional voices, reverb, occlusion, effects and tracker music

## Example programs

Screenshot-capable examples run headless; the window smoke test requires a desktop. Each walkthrough explains the whole program section by section. The list: https://matjam.github.io/bunyip/examples/index.md

- [Animation](https://matjam.github.io/bunyip/examples/animation.md): keyframe clips on 2D sprites and 3D transforms, a flipbook, crossfades driven by Finished events, and three skeletal arms showing an animation event, two-bone IK and a blend space
- [Assets](https://matjam.github.io/bunyip/examples/assets.md): a directory of images loaded on worker goroutines behind a progress bar, reloaded when they change on disk, packed into a pack file, with settings that persist between runs
- [Audio](https://matjam.github.io/bunyip/examples/audio.md): positional voices orbiting a listener with Doppler, occlusion and a binaural head model, reverb and low-pass on sliders, fades, pitch, voice stealing, a synthesised music stream and microphone capture
- [Autotile](https://matjam.github.io/bunyip/examples/autotile.md): terrain that picks its own tiles: a 47-tile blob set expanded from a six-tile template, a 16-tile edge set for walls, a corner Wang set whose shorelines curve, and a 64-tile hexagonal edge set in the strip below
- [Clear](https://matjam.github.io/bunyip/examples/clear.md): the renderer's smoke test: a window cleared to a cycling colour, with one frame written to a PNG
- [Gallery](https://matjam.github.io/bunyip/examples/gallery.md): every widget in the interface package, the built-in themes, a texture skin, menus, modals, drag and drop, tables, scalable text and a live particle editor
- [Inputs](https://matjam.github.io/bunyip/examples/inputs.md): everything the input package reports, drawn live: keys, mouse, wheel, capture, fullscreen, typed text with IME composition, and four gamepads
- [Lighting](https://matjam.github.io/bunyip/examples/lighting.md): skinned meshes bent by joint matrices under cascaded shadows, two lamps with cube shadow maps over a field of 160 clustered point lights, a procedural sky that thins to orbit, image-based lighting, and every post-processing setting on a slider including temporal anti-aliasing, depth of field, motion blur, god rays and the lens effects
- [Materials](https://matjam.github.io/bunyip/examples/materials.md): every material feature on a row of spheres and a few props: clearcoat, sheen, subsurface, glass, iridescence, anisotropy, a specular tint, fur, alpha cutout, vertex colours, a scrolling texture, a decal, an outline, an x-ray tint and a stencil mask
- [Network](https://matjam.github.io/bunyip/examples/network.md): a chat room over TCP with pointer positions over UDP, turn-based and asleep until a message arrives, with reliable UDP and its round trip and loss
- [Particles](https://matjam.github.io/bunyip/examples/particles.md): a campfire of fire and smoke, instanced rain, sparks on click and confetti on Space, with a panel that retunes the fire while it burns
- [Pathfinding](https://matjam.github.io/bunyip/examples/pathfinding.md): A*, Dijkstra maps, field of view, flood fill and lines on a grid painted with the mouse, saved and loaded through the save package
- [Physics lab](https://matjam.github.io/bunyip/examples/physics-lab.md): capsules, hulls and boxes on a mesh terrain, a hinge chain, a motorised paddle wheel, a ragdoll and a character controller on stairs
- [Physics 2D](https://matjam.github.io/bunyip/examples/physics2d.md): balls, boxes and triangles falling into a pit with a ramp, a kinematic paddle, a car on sprung wheel joints, a trigger zone and a raycast
- [Physics 3D](https://matjam.github.io/bunyip/examples/physics3d.md): five hundred textured cubes of wood, plastic, metal, gold, car paint, velvet, glass and glowing material falling into a concrete pen
- [Probes](https://matjam.github.io/bunyip/examples/probes.md): a reflection probe baked inside a glowing room, a grid of light probes that colours the matte balls by the wall they stand near, and screen-space reflections on a polished floor, each on a checkbox
- [Roguelike](https://matjam.github.io/bunyip/examples/roguelike.md): a turn-based dungeon crawl with generated rooms, line of sight, chasing goblins and a message log, running in the engine's turn-based mode
- [Shaders](https://matjam.github.io/bunyip/examples/shaders.md): game-written WGSL compiled to SPIR-V in Go, as 2D sprite shaders and mesh surface and vertex hooks, with uniforms driven by sliders
- [Soft bodies](https://matjam.github.io/bunyip/examples/softbody.md): a cloth flag flapping on a pole, a jelly cube that drops and can be kicked beside a rigid crate, and a tank of 2D fluid breaking around a post
- [Solar system](https://matjam.github.io/bunyip/examples/solar.md): the entity component system driving a 3D scene loaded from a scene document, with a prefab, a parent-child hierarchy, an instanced asteroid belt, picking and a render-texture minimap
- [Space](https://matjam.github.io/bunyip/examples/space.md): a ship under gravity in a fictional star system on exact Kepler orbits, with a floating origin, orbit prediction and a slider panel
- [Sprites](https://matjam.github.io/bunyip/examples/sprites.md): a few hundred textured sprites bouncing over a grid, a lit brick floor where a circling lamp throws shadows from three crates, and a key that runs the 2D frame through the post pass
- [Terrain](https://matjam.github.io/bunyip/examples/terrain.md): a chunked terrain with levels of detail and a splat map, impostors, billboards, point and spot lights, fog, world text and live edits
- [Tetris](https://matjam.github.io/bunyip/examples/tetris.md): a complete game on the entity component system, with components, resources, events, systems, timers, tweens, sound and a panel
- [Shaped text](https://matjam.github.io/bunyip/examples/text.md): HarfBuzz shaping, bidirectional and vertical text, fallback fonts, wrapping, hyphenation in the text's own language, rich text, colour glyphs and distance-field text
- [Tiled maps](https://matjam.github.io/bunyip/examples/tiled.md): a map from the Tiled editor, embedded as a .tmj, built into tilemaps with animated and flipped tiles and outlined objects
- [Tiles](https://matjam.github.io/bunyip/examples/tiles.md): a sprite sheet, a culled tilemap, a following 2D camera, a walk cycle, layers, timers, tweens and a nine-slice HUD
- [Vector paths](https://matjam.github.io/bunyip/examples/vector.md): filled and stroked paths, fill rules, curves, caps and joins, textured fills, blend modes and the transform stack
- [Model viewer](https://matjam.github.io/bunyip/examples/viewer.md): an orbit camera over a generated 3D scene, or a glTF model loaded from disk, with lights, shadows and ambient occlusion
- [Window](https://matjam.github.io/bunyip/examples/window.md): the platform layer's smoke test, opening a native window and presenting cleared frames without the engine

## Engine

- [engine](https://matjam.github.io/bunyip/pkg/engine.md): Package engine runs a game's main loop.
- [input](https://matjam.github.io/bunyip/pkg/input.md): Package input reports the state of the keyboard, mouse and gamepads, and names the keys, buttons and axes the platform layers fill that state with.
- [console](https://matjam.github.io/bunyip/pkg/console.md): Package console is the engine's in-game debug console: a drop-down command line over the top of the view, and a window of panels that show what every part of the engine is doing.

## Graphics

- [gfx](https://matjam.github.io/bunyip/pkg/gfx.md): Package gfx draws a game's 2D and 3D graphics.
- [gfx/ktx2](https://matjam.github.io/bunyip/pkg/gfx/ktx2.md): Package ktx2 reads and writes KTX2 texture files and encodes and decodes the block-compressed formats they carry.
- [gfx/shaders](https://matjam.github.io/bunyip/pkg/gfx/shaders.md): Package shaders holds the gfx package's WGSL sources and committed SPIR-V, and the preludes that game shaders are compiled against.
- [anim](https://matjam.github.io/bunyip/pkg/anim.md): Package anim animates entities.
- [ui](https://matjam.github.io/bunyip/pkg/ui.md): Package ui is an immediate-mode interface toolkit drawn with gfx.
- [particle](https://matjam.github.io/bunyip/pkg/particle.md): Package particle simulates 2D particles on the CPU and draws them through the sprite stream: fire, smoke, sparks, rain and confetti from an Emitter of plain fields.
- [tiled](https://matjam.github.io/bunyip/pkg/tiled.md): Package tiled reads maps saved by the Tiled editor and builds drawable levels from them.
- [gltf](https://matjam.github.io/bunyip/pkg/gltf.md): Package gltf loads glTF 2.0 models (.gltf with external or embedded buffers, and .glb) into plain Go slices: positions, normals, UVs, vertex colours, joints and weights, indices, materials with their textures and the KHR extensions the renderer supports (clearcoat, sheen, transmission, volume, IOR, emissive strength, texture transforms, specular, iridescence, anisotropy and converted specular-glossiness), decoded images, morph targets with their default weights, skins, animation clips (node transforms and morph weights) and the flattened node hierarchy with world matrices.
- [lin](https://matjam.github.io/bunyip/pkg/lin.md): Package lin provides the engine's linear algebra: vectors, matrices and quaternions in float32.

## Simulation

- [ecs](https://matjam.github.io/bunyip/pkg/ecs.md): Package ecs is the engine's entity component system.
- [phys](https://matjam.github.io/bunyip/pkg/phys.md): Package phys simulates rigid bodies in 2D and 3D on the entity component system.
- [phys/soft](https://matjam.github.io/bunyip/pkg/phys/soft.md): Package soft simulates soft bodies, cloth and fluids as particles on the entity component system.
- [orbit](https://matjam.github.io/bunyip/pkg/orbit.md): Package orbit computes celestial mechanics for space games.
- [orbit/sol](https://matjam.github.io/bunyip/pkg/orbit/sol.md): Package sol holds real-world constants for games set in our solar system.

## Audio

- [audio](https://matjam.github.io/bunyip/pkg/audio.md): Package audio mixes sounds in Go and passes float32 stereo frames to the platform's output device.
- [audio/tracker](https://matjam.github.io/bunyip/pkg/audio/tracker.md): Package tracker loads and plays tracker music: ProTracker MOD (4 to 32 channels), ScreamTracker 3 S3M, FastTracker 2 XM and Impulse Tracker IT.

## Services

- [asset](https://matjam.github.io/bunyip/pkg/asset.md): Package asset finds and loads a game's files.
- [save](https://matjam.github.io/bunyip/pkg/save.md): Package save stores a game's files in the platform's own data directory: settings, save slots and anything else worth keeping between runs, written as JSON through a synced temporary file and renamed into place to avoid exposing partial JSON.
- [locale](https://matjam.github.io/bunyip/pkg/locale.md): Package locale translates a game's strings.
- [rng](https://matjam.github.io/bunyip/pkg/rng.md): Package rng provides a small, fast, seedable random number generator (PCG32) for games.
- [timer](https://matjam.github.io/bunyip/pkg/timer.md): Package timer schedules callbacks on game time, after a delay or on every interval.
- [tween](https://matjam.github.io/bunyip/pkg/tween.md): Package tween animates values over time.
- [grid](https://matjam.github.io/bunyip/pkg/grid.md): Package grid provides the tile-map helpers roguelikes and strategy games need: a generic cell grid, A* and Dijkstra pathfinding, Bresenham lines, shadowcasting field of view and flood fill.
- [grid/autotile](https://matjam.github.io/bunyip/pkg/grid/autotile.md): Package autotile picks tile frames from a terrain grid, so a map of plain terrain ids draws with matching edges, corners and transitions.
- [network](https://matjam.github.io/bunyip/pkg/network.md): Package network moves typed messages between game instances over TCP and UDP.

## Tools

- [cmd/bunyip-bundle](https://matjam.github.io/bunyip/pkg/cmd/bunyip-bundle.md): Command bunyip-bundle packages a built game for distribution: a .app bundle on macOS with the Vulkan loader and MoltenVK inside, or a plain folder with the executable and assets elsewhere.
- [cmd/bunyip-docs](https://matjam.github.io/bunyip/pkg/cmd/bunyip-docs.md): Command bunyip-docs renders the module's documentation as a static website: guides written in Markdown, a walkthrough of every example program, every package's godoc with its examples, a symbol search, and links back to the source on GitHub.
- [cmd/bunyip-info](https://matjam.github.io/bunyip/pkg/cmd/bunyip-info.md): Command bunyip-info reports the graphics stack Bunyip would run on: which Vulkan library loaded, the instance version, and every physical device with its driver and queue families.
- [cmd/bunyip-pack](https://matjam.github.io/bunyip/pkg/cmd/bunyip-pack.md): Command bunyip-pack bundles an asset directory into a pack file that asset.Open can read alongside, or instead of, loose directories.
- [cmd/bunyip-play](https://matjam.github.io/bunyip/pkg/cmd/bunyip-play.md): Command bunyip-play plays an audio file through the engine's mixer and the native output device: WAV, Ogg Vorbis, MP3, MOD, S3M, XM or IT.
- [cmd/bunyip-shader](https://matjam.github.io/bunyip/pkg/cmd/bunyip-shader.md): Command bunyip-shader compiles WGSL to SPIR-V using the pure-Go compiler.
- [cmd/bunyip-tex](https://matjam.github.io/bunyip/pkg/cmd/bunyip-tex.md): Command bunyip-tex compresses PNG and JPEG images into KTX2 texture files that asset.Texture and gfx.NewCompressedTexture upload straight to the GPU, with the whole mip chain built here rather than while a game runs.
- [cmd/vkgen](https://matjam.github.io/bunyip/pkg/cmd/vkgen.md): Command vkgen generates the Vulkan binding in internal/vk from the Khronos registry.