跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
视频与音频

ebitengineer

Engineering architecture and best practices for building 2D games in Go using Ebitengine (v2). Covers modular game architecture, scene state machines, virtual resolution scaling, delta-time physics, zero-allocation draw loops, Kage shaders, and WebAssembly audio synchronization. Activate when designing, building, optimizing, or debugging 2D games in Go, implementing game systems with Ebitengine, or compiling games to WebAssembly.

Daniela Petruzalek (daniela@danicat.dev) · 已有静态检查记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add danicat/skills --skill ebitengineer

技能说明


name: ebitengineer description: > Engineering architecture and best practices for building 2D games in Go using Ebitengine (v2). Covers modular game architecture, scene state machines, virtual resolution scaling, delta-time physics, zero-allocation draw loops, Kage shaders, and WebAssembly audio synchronization. Activate when designing, building, optimizing, or debugging 2D games in Go, implementing game systems with Ebitengine, or compiling games to WebAssembly. license: Apache-2.0 metadata: category: game-dev tags: "ebitengine, go, golang, game-dev, 2d, wasm, shaders" author: Daniela Petruzalek (daniela@danicat.dev) version: "0.3.0" catalog: https://skills.danicat.dev

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}.

4. Aspect Ratio & Virtual Pixel Canvas

  • 16:9 Widescreen Priority: Unless explicitly specified otherwise, target a 16:9 virtual resolution (320x180, 640x360, 1280x720, 1920x1080).
  • Virtual Pixel Canvas: All entity physics, collision math, camera coordinates, Kage shader pixel units, and UI layouts operate strictly in virtual canvas coordinates.
  • Automatic Multi-Resolution Scaling: Layout(outsideWidth, outsideHeight int) returns constant virtual dimensions (virtualWidth, virtualHeight).

5. Cycle Timing & Frame Synchronization

  • Target Frame Rate: Standard target is 60 TPS (ebiten.SetTPS(60)).
  • Delta-Time Integration: Integrate movement, camera exponential decay, and timers using delta time ($dt = 1.0 / 60.0$ or measured frame delta) for consistent behavior across refresh rates.
  • Windowing & Fullscreen Toggle: Support fullscreen toggling via F11 or Alt+Enter:
if inpututil.IsKeyJustPressed(ebiten.KeyF11) || (ebiten.IsKeyPressed(ebiten.KeyAlt) && inpututil.IsKeyJustPressed(ebiten.KeyEnter)) {
    ebiten.SetFullscreen(!ebiten.IsFullscreen())
}

Engine Reference Modules

Consult these deep technical reference guides for complete, zero-allocation, fail-fast Go implementations:

ModuleReference FileKey Topics Covered
Project Structurereferences/project_structure.mdPackage tree and internal/ subsystem responsibilities.
Camera & Game Feel ("Juice")references/camera_and_juice.md2D ebiten.GeoM camera, frame-rate independent exponential lerp, trauma screen shake, hitstop freeze frames, and spring squash-and-stretch.
Kage Shaders & text/v2references/shaders_and_text_v2.mdKage //kage:unit pixels shaders (2D lighting, CRT, hit-flash) and ebiten/v2/text/v2 font loading and aligned layout.
WASM Audio & Save Storagereferences/wasm_audio_and_persistence.md4-byte aligned PCM Seek() math for browser autoplay unlock and build-tagged desktop vs. WASM fail-fast save storage.
UI & HUD Systemreferences/ui_and_hud.mdPremultiplied alpha invariant (R <= A), pre-sliced 9-slice panels, anchoring math, zero-alloc progress bars, and text/v2 buttons.
Physics & Collisionreferences/physics_and_collision.mdGenre-agnostic Circle & AABB overlap, axis-separated sweep resolution, spatial hash grids, and slope math.
Tilemaps & Levelsreferences/tilemaps_and_levels.mdPre-sliced tileset validation, camera frustum culling, isometric projection, and 16-pipe bitmask autotiling.
Input Action Mappingreferences/input_action_mapping.mdRebin
阅读完整来源 ↗