ebitengineer

Ebitengine 2D Game Development Guide (ebitengineer)

Comprehensive, genre-agnostic engineering guidelines for building modular, high-performance, cross-platform 2D games (top-down, tactics, shmup, puzzle, isometric, and platformer) in Go using Ebitengine v2.

---

Trigger Conditions

Activate this skill whenever:

• Designing or implementing 2D game architecture, scene flow, camera systems, or rendering pipelines in Go.
• Working with Ebitengine interfaces (ebiten.Game), state machines, input management, audio, Kage shaders, or ebiten/v2/text/v2 typography.
• Optimizing cycle timing, WASM audio synchronization, build-tagged save persistence, Cloud Run hosting, or writing unit tests for Go game components.

---

Core Architecture & Fail-Fast Engineering Rules

1. Modular Architecture (internal/)

Organize the codebase into modular subsystems under internal/. Never build monolithic single-file games.

• For the complete directory tree and package responsibilities, see references/project_structure.md.

2. Fail-Fast Asset Embedding & Validation (No Silent Fallbacks)

• Zero-Dependency Embedding: Embed all game assets (sprites, TTF/OTF fonts, audio streams, Kage shaders) directly into the compiled Go binary using embed.FS (internal/assets).
• No Silent Fallbacks: Never ignore errors (_ = err), never substitute dummy 1×1 fallback textures when an asset fails to decode, and never silently clamp out-of-bounds tile or frame IDs. Always fail fast and return rich fmt.Errorf diagnostics during Boot initialization.
• Mandatory Binary Format Validation: Always validate asset files using file identification tools (file, mimetype, or http.DetectContentType in Go) during asset ingestion. Misnamed or corrupt asset files cause decoding failures or black screens on WebAssembly.

3. Premultiplied Alpha Invariant (color.RGBA vs. color.NRGBA)

• In Go's image/color and Ebitengine, color.RGBA is alpha-premultiplied: every channel must satisfy $R \le A$, $G \le A$, $B \le A$.
• Never construct non-premultiplied literals like color.RGBA{255, 0, 0, 100} (where $R > A$). Use valid premultiplied color.RGBA{100, 0, 0, 100} or straight-alpha color.NRGBA{255, 0, 0, 100}.