Skip to content

About

Runnable usage examples for the cog engine

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

149 Commits

Folders and files

Repository files navigation

cog-examples

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.

Layout

  • cmd/<plugin>/<demo>/main.go — one main.go per 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 under cmd/ 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 six cmd/sound/ demos open no window: audio needs no GPU, so each supplies its own app.MainLoop rather than composing gogpu, and each prints what sound derived so all of them are worth running on a machine with no sound card too. mixer is the exception and composes gogpu like any other windowed demo, because it is the one you drive and cog's input binds to gogpu's window.
  • assets/ — the vendored demo models, one .glb per asset, plus ATTRIBUTION.md.
  • cmd/prepare-assets/ — the tool that builds assets/, and the manifest that says where each model comes from and what its licence obliges.
  • cmd/looptag/ — the tool that writes LOOPSTART and LOOPLENGTH into 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 is internal/looptag, so a demo can check its own clip against the recording it came from.
  • internal/assets — mounts assets/ through storage.
  • internal/permanentfs — storage's PermanentFS Adapter for the platform a demo is built for: diskstorage on the desktop, jsstorage in a browser.
  • internal/soundbackend — the same choice for sound's Backend: otosound on the desktop, jssound in 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 plain go test beside its main.go.
  • cmd/web/ — the WebAssembly page any demo can be built into. See Running in a browser.

Building against a local cog

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.

Running

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

Running in a browser

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.

Tests under node

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.

Assets

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.

About

Runnable usage examples for the cog engine

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages