/ebitengine-game

name: ebitengine-game
description: >
  Create, improve, debug and package playable 2D games in Go with Ebitengine
  (github.com/hajimehoshi/ebiten/v2). Use for Ebitengine game requests: game design
  translated into a complete loop, input, rendering, text, audio, scenes, gameplay
  tests and desktop, browser or mobile builds. Also use when fixing these systems
  in an existing Ebitengine game. Do not apply to unrelated Go software or
  engine-internal patches merely because they depend on Ebitengine.

Ebitengine game

Deliver a game that is understandable, responsive and complete at the requested scope. One request can include several internal build/play/refine passes. A scaffold, successful build or attractive screenshot alone is not a finished game. For a focused fix, preserve the project's design and limit the workflow to the affected behavior.

The bundled starter targets **Ebitengine v2.10.5 / Go 1.25+**. This is a pinned baseline, not a claim about the latest release. Keep an existing project's versions unless an upgrade is needed and authorized. Check the pinned version's public API before using newer or experimental APIs. References contain patterns to adapt; only the bundled scripts and starter are executable deliverables. Their checks do not validate every reference snippet.

Delivery workflow

1. **Inspect and decide.** Read repository instructions, `go.mod`, the `RunGame` entrypoint and existing tests/assets. For new games, read [Design and quality](references/design-and-quality.md). Establish the player's goal, repeated decision, consequence, end/retry path, intended look, platform and supported input. Infer reasonable defaults; ask only for missing choices that materially change the product. Record a short brief and observable acceptance criteria in the project. 2. **Build a representative playable slice.** Make the central interaction and its feedback work with the intended controls and visual direction. Check the feel before expanding content. Keep scope small enough to finish; choose authored or procedural content based on the game, not the template. Calibrate content against actual player capabilities before multiplying levels. For an art set, establish shared perspective, scale, anchors and palette roles using [Assets and animation](references/assets-and-animation.md). 3. **Complete and refine.** Implement the promised start → play → outcome → retry/continue loop (or the appropriate persistent/sandbox loop). Refine hierarchy, animation, sound, difficulty and transitions in context. Read only the technical references needed for the selected systems. Fix discovered defects within this delivery rather than asking the user to iterate for you. 4. **Verify the product.** Test rules and important transitions, exercise real input, inspect representative rendered states, and build/run requested targets. Include failure/retry and boundary cases. A scripted demo cannot establish control feel; a silent audio sink cannot establish sound quality. For automated multi-step interactions, pair observed images with actual state at the same tick; see [Playtest diagnostics](references/playtest-diagnostics.md). 5. **Hand off.** Supply launch/build instructions, actual artifact paths and asset licences. State what was run and observed, what remains unverified, and any material limitations. Publishing, purchases and external uploads are separate actions within the user's requested scope.

Starting a project

Resolve commands relative to this skill's directory, not the game's working directory. Set `skill_dir` to the actual installed location, then for example:

python3 "$skill_dir/scripts/new_game.py" --out mygame \
  --module example.com/mygame --title "My Game"
cd mygame
go mod tidy
go test ./world/...

The starter demonstrates scenes, action input, text, sound, a camera, pause and scripted capture using a small **platformer**. It is an integration example, not a genre or architecture requirement. Replace its rules, controls, level, presentation and scene flow to fit the brief; a puzzle or card game should not inherit gravity, jumping, camera scrolling or a platformer HUD. Existing projects rarely need a scaffold. `--ci` adds a workflow and tools; inspect its triggers, targets and release behavior before enabling it.

Loop and resource contracts

| Method | Responsibility | Important distinction | | --- | --- | --- | | `Update() error` | Sample actions, advance simulation, apply scene changes and trigger event audio | Default target is 60 fixed ticks/s. Catch-up updates, focus pauses and slow machines affect actual scheduling. | | `Draw(screen *ebiten.Image)` | Render the state produced by updates | Calls are not one-to-one with ticks. Do not advance gameplay, consume input edges or start sounds here. Renderer-owned caches are separate from simulation state. | | `Layout(outsideW, outsideH int) (int, int)` | Choose logical dimensions for rendering and input | Fixed and responsive designs are both valid. Account for small windows, aspect ratio and readability. |

• Express simulation durations in ticks or use an explicit fixed `dt`. At 60

TPS, 30 ticks is 0.5 seconds of simulation time. `ActualTPS` is a diagnostic, not a delta. `SetTPS` changes the whole update clock; it is not a universal slow-motion control. Avoid `SyncWithFPS` for rules that require a fixed step.

• Return `ebiten.Termination` from `Update` for a clean stop. Other errors return

from `RunGame`; propagate failures rather than hiding them.

• Load/decode images and font sources once; reuse offscreens and hot-path

slices. Profile before making pooling or zero-allocation rules universal.

• Separate rules from device/GPU code where that makes them testable. A small

game need not grow an ECS, scene stack or service layer without need.

Essential Ebitengine choices

• **Input:** Map devices to actions in `Update`. Sepa