Runnable usage examples for the cog engine. The module exists so engine work has somewhere to land a small, throwaway app that exercises a contract end to end, without dragging a real game into it. The examples are collected here for later publication alongside the engine.
cmd/<plugin>/<demo>/main.go— onemain.goper demo, grouped by the plugin it exercises:cmd/scene/for the scene plugin,cmd/canvas/for canvas,cmd/ecs/for the entity-component plugin's 2D physics binding,cmd/sound/for audio. Each demo is self-contained: it wires its own plugin list and holds its own gameplay plugin in its own directory. Everything two levels undercmd/is a demo, which is what the browser build and its guard walk; the tools beside them -cmd/prepare-assets/,cmd/looptag/,cmd/web/- are one level and are not. Five of the sixcmd/sound/demos open no window: audio needs no GPU, so each supplies its ownapp.MainLooprather than composinggogpu, and each prints whatsoundderived so all of them are worth running on a machine with no sound card too.mixeris the exception and composesgogpulike any other windowed demo, because it is the one you drive and cog'sinputbinds to gogpu's window.assets/— the vendored demo models, one.glbper asset, plusATTRIBUTION.md.cmd/prepare-assets/— the tool that buildsassets/, and the manifest that says where each model comes from and what its licence obliges.cmd/looptag/— the tool that writesLOOPSTARTandLOOPLENGTHinto a copy of an Ogg Vorbis file, keeping its comments and every audio page byte for byte, and refuses to write unless the copy decodes to its source's frame count. Its logic isinternal/looptag, so a demo can check its own clip against the recording it came from.internal/assets— mountsassets/throughstorage.internal/permanentfs— storage'sPermanentFSAdapter for the platform a demo is built for:diskstorageon the desktop,jsstoragein a browser.internal/soundbackend— the same choice for sound's Backend:otosoundon the desktop,jssoundin a browser. The two cannot both be compiled, so a demo that named either directly would build on one platform only.internal/headless— runs a cog engine with no GPU, so a demo's assertions can be a plaingo testbeside itsmain.go.cmd/web/— the WebAssembly page any demo can be built into. See Running in a browser.
go.mod carries replace github.com/dvoyni/cog => ../cog, so the module builds
against the sibling checkout rather than a tagged release. Clone it next to
cog:
<parent>/
cog/
cog-examples/
That is deliberate: the demos exercise unreleased gfx and scene changes, so
they must compile against the working tree.
go run ./cmd/scene/hello
hello opens a window through storage, input, gfx, canvas and gogpu
and draws one canvas rectangle on a dark background. It proves the module builds
and runs against the sibling cog; every other demo starts from its wiring.
Each demo owns one part of a plugin's contract, and each carries its own
main.go doc comment saying what it exercises and what only eyes can judge.
The scene demos. scene draws Entities, so every one of them but hello is an
ecs app: its Systems spawn and move Entities carrying scene's Components, and
scene's own Systems turn them into draws. Each keeps the Components it declares
in components.go and each System in a file named for it.
| demo | what it is for |
|---|---|
hello |
the smallest cog app, and the wiring every scene demo starts from |
tracer |
the narrowest complete path through every layer, made to be looked at |
box |
the whole debug vocabulary, with no file on disk anywhere in the frame |
procedural |
caller-owned geometry, and a material this program wrote itself, lit through the engine's published sceneShadeSurface |
pbr |
the material and lighting contract, over six Khronos models |
animated |
skinning, morph targets, and the browser canary |
instancing |
one call for five hundred crates, per-instance culling, and the sort key |
cameras |
two cameras, a texture target, layers, and the coordinate helpers |
loading |
residency, model addressing, and the lookup facade |
fountain |
the scene showcase: every scene Component in one frame, spawned and retired by Systems, the motes drawn in batches |
The canvas demos:
| demo | what it is for |
|---|---|
rendertexture |
a layer rendered into a texture, drawn back as a sprite and as a shape |
The ecs physics demos:
| demo | what it is for |
|---|---|
physics2d |
the ecsphysics2d showcase: a stack, a ramp and a jointed figure in one scene, with the app's own gravity |
physics2dtable |
the same engine with no gravity at all: a hundred balls breaking inside four cushions, and a crate per click |
The sound demos. Each carries its own cut of the same public-domain recording,
and each shows what sound derived rather than what it was told — so every one
of them says something on a machine with no sound card. Five of them open no
window and print to the console: orbit runs until Ctrl+C, and buses,
crowd, emitters and loopregion run a script and stop. mixer is the one
that opens a window, because it is the one you drive from the keyboard, and it
plays the whole 176 s recording, streamed rather than held in memory.
| demo | what it is for |
|---|---|
orbit |
the smallest cog app that makes a sound, and the wiring every sound demo starts from: a clip circling the listener while audibility does not move |
buses |
two Voices on two Buses, and the sliders a settings screen writes — including why Master is the default Bus and not a global trim |
crowd |
the voice cap, at eight Voices: quiet music survives a loud crowd because Priority is a band above audibility, and falls to one alarm a band higher |
emitters |
the ecsaudio binding with no renderer: a Voice dying with its Entity, and a finished one-shot that does not restart |
loopregion |
a clip whose own LOOPSTART / LOOPLENGTH tags make a second of intro play once and four seconds repeat with no gap, with the playhead printed so the wrap is visible |
mixer |
the demo a game actually is, and the only windowed one: a 176 s track streaming under one-shots that overlap it, music and effects on separate Buses, and the live Voice table drawn on screen — driven by hotkeys |
bash cmd/web/build.sh animated
python -m http.server 8731 --bind 127.0.0.1 --directory cmd/web
# then open http://127.0.0.1:8731/
build.sh takes any demo's name - it is looked up across every family under
cmd/, so cameras, rendertexture and physics2d all work - and defaults to
pbr. It writes four generated files into cmd/web/, all gitignored:
main.wasm, the assets.tar.gz bundle, demo.js (the demo's name, for the
page title) and a copy of the Go runtime's wasm_exec.js. Serve the directory
with anything that sends Content-Type: application/wasm for .wasm —
Python's http.server does — and open it in a WebGPU-capable browser: Chrome
or Edge 113+, Safari 18+, or Firefox with WebGPU enabled.
No demo carries a line of code about the browser. The whole of the platform
difference is internal/assets.Mount: on disk it walks up to the checkout's
assets/ directory, and under GOOS=js it takes the map index.html unpacked
out of the tar before the module booted. Both land on the assets mount and
answer the same assets/Fox/Fox.glb paths, so a demo that runs on the desktop
runs in a browser by being named to build.sh.
Why bother, when desktop is the acceptance bar. A native device reports hardware limits, which sit far above the WebGPU floor, so a desktop run provably cannot catch a web limit violation — and scene's storage-buffer budget has no spare, where a single unbound binding kills the whole frame with nothing logged. One demo has to actually run in a browser for that to be checked at all.
That demo is animated. It is the one that binds all seven of the bundled
scene shader's storage buffers — group 2's three exist only for animation — and
the first thing in the tree to compile that shader at all, so it carries both
the binding risk and the compile risk, and the two fail identically on the web.
bash cmd/web/build.sh animated
Every other demo builds and runs in a browser too, and go test ./cmd/web
keeps them that way; running a second one is doubled verification rather than
new coverage.
Two things that will otherwise read as bugs. gogpu binds keydown on the
canvas element rather than on the document, so index.html gives the canvas a
tabindex and focuses it — without that a demo's hotkeys silently do nothing.
And navigator.gpu is undefined on about:blank even in a browser where WebGPU
works, so probe it on the served page and not on a blank tab.
go test ./cmd/web cross-compiles every demo for GOOS=js and is the guard on
all of that. It walks cmd/*/* rather than a list, so a new demo - or a new
family of them - is covered without anyone remembering the file exists. The failure it catches — an import
that only exists on the desktop, or a call that assumed a filesystem — costs a
desktop run nothing and is otherwise found only the next time someone opens a
browser.
To drive it headlessly — for a screenshot, or to check a change reaches the
frame — Chrome needs --enable-unsafe-webgpu --use-webgpu-adapter=swiftshader --enable-features=Vulkan. --use-webgpu-adapter=swiftshader is the one that
matters: without it the demo logs wgpu: no suitable GPU adapter found and
stops. Wait for document.getElementById('status').className === 'hidden', then
a few seconds for the first frame.
The js/wasm tests run in node, through the Go runtime's wasm_exec_node.js:
GOOS=js GOARCH=wasm go test -exec="node $(go env GOROOT)/lib/wasm/wasm_exec_node.js" ./...
On Windows, copy wasm_exec_node.js to a path with no spaces first: from
C:\Program Files\Go node reads the -exec argument as C:\Program, and every
package fails before a test runs.
The headless demo tests are not in this run. Every test file in a package
that composes internal/headless is built with //go:build !js, so those
packages report "no test files" here, and go test ./... on the desktop is
where they run. Under GOOS=js a headless composition differs from the desktop
one in two places only: internal/permanentfs composes jsstorage, whose own
tests run under node in cog, and internal/assets.Mount reads the map
index.html preloads. The GPU is the same fake Backend on both, so a node run
would repeat the desktop run and catch none of the WebGPU limits the browser
canary is for — while needing a localStorage and a fresh __cogAssets for
every engine a test starts, since Mount deletes the global it reads. Without
the tag each of them fails composition with jsstorage: browser localStorage is unavailable.
What only js can check is covered on its own: internal/assets' web_test.go
reads a hand-built __cogAssets map as the asset mount. cmd/web's build test
is desktop-only for a different reason: it runs go build over the checkout,
which a wasm test cannot do.
The models the demos load are committed under assets/, one self-contained
.glb per asset, and every one of them is a modified copy of something from the
Khronos glTF Sample Assets
repository. What each one is, where it came from and what its licence obliges is
in assets/ATTRIBUTION.md — which is generated, along
with the assets themselves, by:
go run ./cmd/prepare-assets
You do not need to run it: its output is committed. Run it after editing the manifest in that command, or to check that upstream has not relicensed anything underneath the set — it verifies that before it writes a byte, and stops if the terms have moved.
A demo reaches the set through internal/assets, because storage mounts
nothing by default and go run builds into a temporary directory. The demo's
own plugin contributes the mount in its Register, so every composition of it
main.go's and its tests' alike - reads the same files:
mount, err := assets.Mount()
if err != nil {
return err
}
registrar.ProvideAdapter[assets.StorageReadMount](mount)A test whose plugins provide no mount - a stand-in plugin, or no demo at all -
adds one with headless.Mounting(mount).
storage also requires a PermanentFS Adapter. Every demo composes
permanentfs.New(), which is diskstorageplugin.New() on the desktop and
jsstorageplugin.New() in a browser build, and calls permanentfs.Configure(config)
on its config map, which supplies that Adapter's Config under its Name
(diskstorage.Name or jsstorage.Name). No demo names a platform.
Paths keep the repository's spelling — assets/Fox/Fox.glb.
One thing under assets/ is neither a model nor generated: assets/music/
holds the public-domain track cmd/sound/mixer streams, with its own
ATTRIBUTION.md beside it. It stays outside
cmd/prepare-assets' manifest because that manifest verifies licences against
Khronos' metadata.json, which has nothing to say about an audio file, and
TestAttributionCoversTheVendoredSet asserts the generated credits match the
manifest exactly — so a row appended by hand would read as stale.
cmd/web/build.sh tars the whole directory, so the browser bundle carries the
music with no change to the recipe.