# Kaijuengine Game Dev

> Essential reference for building games and tools on the Kaiju Engine (Go module `kaijuengine.com`, Vulkan-backed). Covers the GameInterface bootstrap, the Host runtime and frame/update order, entities and the custom matrix Transform, the custom `kaijuengine.com/matrix` math library (never use gonum/mathgl), the Vulkan rendering/Drawing system, the HTML/CSS-like UI system (no JS runtime), build tags, and integration testing. Use this whenever working in a kaijuengine project — writing or modifying Go that imports `kaijuengine.com/...`, scaffolding a new game, editing engine or editor source, or answering how-to/architecture questions about entities, rendering, materials/shaders, or the UI — even when the user doesn't explicitly say "Kaiju". Prefer this over generic guidance for anything touching the kaiju engine tree.

- Skill: `kaijuengine/kaijuengine-game-dev` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx skillmds@latest add kaijuengine/kaijuengine-game-dev`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kaijuengine/kaijuengine-game-dev/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: kaijuengine (https://skillmd.com/u/kaijuengine)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/kaijuengine/kaijuengine-game-dev

---


# Kaiju Engine — Game Development

Kaiju Engine is a 2D/3D game engine in Go (`kaijuengine.com`, Go 1.25.0+) backed
by Vulkan, with a custom math library, a hierarchical entity system, and a
web-inspired UI. Cross-platform: Windows, Linux, macOS, Android.

A game is a type implementing `bootstrap.GameInterface` (`ContentDatabase`,
`PluginRegistry`, `Launch`). The engine creates a `*engine.Host` — the central
runtime mediator — and calls `Launch(host)`. Your code creates entities, attaches
drawings, and registers per-frame update functions on the host.

> **Source of truth:** this skill is distilled from the engine's `AGENTS.md`. When
> it disagrees with the current source, trust the source — and verify a symbol
> exists before relying on it, since some details here describe internals
> conceptually and may drift from the live API.

## Critical rules (do not violate)

1. **Use `kaijuengine.com/matrix` for ALL math.** Never import gonum, mathgl, or
   any external math library. Use `matrix.Float` (configurable, default float32)
   instead of bare `float32`/`float64` in engine-facing code.
2. **Attach the entity transform to the drawing**: `Transform: &entity.Transform`.
   This is the link that makes a drawing follow its entity. Without it the drawing
   won't track the entity.
3. **Create entities with the work group**: `engine.NewEntity(host.WorkGroup())` —
   enables concurrent transform updates.
4. **Clean up in `OnDestroy`**: destroy `ShaderData` and remove updaters
   (`host.Updater.RemoveUpdate(&id)`) to avoid leaks. `RemoveUpdate` takes a
   pointer to the id.
5. **UI markup has NO JavaScript.** `.go.html` files are Go templates; an
   `onclick="fn"` maps to a SINGLE Go function in the funcMap. Chained JS-style
   calls (`a(); b()`) are invalid. CSS is custom-parsed; manage active states with
   CSS classes via `document.SetElementClasses(elm, ...)`.
6. **Content paths are relative to the working directory at runtime.** Games load
   content via `assets.NewFileDatabase("game_content")`; the editor places content
   in `database/content` by UUID.
7. **`deltaTime` is in seconds.** `host.Runtime()` is seconds since start;
   `host.Frame()` is the current frame number.

## Engine Go conventions

Follow the repo's Go style guide (also in the user's global instructions):
builder-is-implementation pattern, public API surface is interfaces/methods only
(no exported structs), locks are a last resort (prefer channels or
`github.com/puzpuzpuz/xsync/v4`), and platform build-tag files
(`_darwin.go`/`_linux.go`/`_windows.go`) hold ONLY what differs — shared structs
and constructors live in a single untagged file.

## Quick start — minimal game

```go
package main

import (
    "reflect"
    "kaijuengine.com/bootstrap"
    "kaijuengine.com/engine"
    "kaijuengine.com/engine/assets"
)

type Game struct{ host *engine.Host }

func (Game) PluginRegistry() []reflect.Type        { return nil }
func (Game) ContentDatabase() (assets.Database, error) {
    return assets.NewFileDatabase("game_content")
}
func (g *Game) Launch(host *engine.Host) {
    g.host = host
    // create entities, add drawings, register updates here
    id := host.Updater.AddUpdate(g.update)
    _ = id
}
func (g *Game) update(deltaTime float64) { /* game logic; deltaTime in seconds */ }

func getGame() bootstrap.GameInterface { return &Game{} }
```

See `reference/making-a-game.md` for the full entity+drawing example.

## Frame / update order

Each frame the host runs, in order:

1. **FrameRunner** — functions scheduled via `RunAfterFrames` / `RunNextFrame`
   (run after window poll, before the UI)
2. **UIUpdater** — UI update logic
3. **UILateUpdater** — late UI updates
4. **Update** — main game logic (`host.Updater`)
5. **LateUpdate** — physics, collision (`host.LateUpdater`)
6. **EndUpdate** — internal frame preparation (input state transitions)

## Reference index (read on demand)

- **`reference/making-a-game.md`** — GameInterface, Launch steps, the complete
  entity-with-drawing example, and common patterns (update registration,
  frame-safe ops). Read when scaffolding a game or wiring entities to drawings.
- **`reference/host-entities-transform.md`** — Host responsibilities and methods,
  the Entity type (hierarchy, named data, activation), and the matrix Transform
  (local vs world, direction vectors, dirty-flag system). Read for entity
  hierarchy, positioning, or host caches.
- **`reference/rendering.md`** — Vulkan architecture, the caches, building
  Drawings, pre-built meshes, and terrain texture painting / splat-map contract.
  Read for rendering, meshes, materials, shaders, or terrain.
- **`reference/ui.md`** — the UI system: Manager, element types, events, layout,
  panel/label/input ops, dirty flags, and the HTML/CSS markup system. Read for any
  UI work in a game or the editor.
- **`reference/matrix.md`** — the custom math library: vector/matrix/quaternion
  types and common operations. Read before doing any math.
- **`reference/building-and-testing.md`** — build prerequisites, build tags, build
  commands, content layout, and the integration-testing framework (screenshots +
  video). Read to build, run, or visually test.

## Verifying visually

- For automated visual checks, use the **integration testing** framework
  (screenshots / video) — see `reference/building-and-testing.md`.
- To drive a *running* game interactively (screenshot + inject input), build with
  `-tags ai_driver` and use the **`kaiju-aidriver`** skill.