gamedev-skills/awesome-gamedev-agent-skills

ebitengine-game

Creates, debugs and packages 2D games in Go with Ebitengine v2: a play-and-retry loop, input, pixel-art scaling, text, audio and desktop, WASM or mobile builds.

소스 보기

사용 방법

  1. 설치 명령을 복사하고 자신의 에이전트 환경에 설치하기 전에 소스 패키지를 확인하세요.
  2. 필요한 도구, 인증 정보, 지원 환경은 원본 문서에서 확인하세요.
  3. 입력과 원하는 산출물을 설명하고 출처와 결과를 대조하세요.
npx skills add https://github.com/gamedev-skills/awesome-gamedev-agent-skills --skill ebitengine-game

시작 전 확인

  • 설치에는 모델 구독, API 한도, 파일 접근 권한이 포함되지 않습니다.
  • 별점 수와 설치 수는 활동 지표이며 독립적인 품질·보안 검증이 아닙니다.
원본 Skill 문서

원본 저장소의 제목, 예시, 코드, 표, 링크, 이미지를 유지해 표시합니다.

Ebitengine game

Deliver a game that is understandable, responsive and complete at the requested scope. A scaffold, a clean build or a good screenshot alone is not a finished game. For a focused fix, keep the project's design and touch only the affected behaviour.

The bundled starter targets Ebitengine v2.10.6 / Go 1.25+. Keep an existing project's versions unless an upgrade is needed and authorized, and check the pinned version's API before using newer or experimental APIs. Only the bundled scripts and starter are tested deliverables; reference snippets are patterns to adapt.

Delivery workflow

  1. Inspect and decide. Read repository instructions, go.mod, the RunGame entry

point and existing tests and assets. For a new game, read Design and quality. Settle the player's goal, repeated decision, consequence, end/retry path, look, platform and inputs; infer defaults and ask only about choices that change the product. Write a short brief with observable acceptance criteria into the project.

  1. Build a representative playable slice. Make the central interaction and its

feedback work with the intended controls and look before adding content. Calibrate content against what the player can actually do. For an art set, fix perspective, scale, anchors and palette first (Assets and animation).

  1. Complete and refine. Implement the promised start → play → outcome →

retry/continue loop (or the right persistent/sandbox loop). Refine hierarchy, animation, sound, difficulty and transitions in context, reading only the references for the systems you use. Fix the defects you find within this delivery.

  1. Verify the product with the commands under Verification: rules and transitions in

tests, real input paths, rendered states at important moments, and every promised target built. Include failure/retry and boundary cases. For multi-step scripted interactions, pair each image with the game state at the same tick (Playtest diagnostics).

  1. Hand off. Give launch/build instructions, actual artifact paths and asset licences.

State what was run and observed and what was not. A scripted demo cannot judge control feel and a null audio sink cannot judge sound, so ask the user to play a session and report on feel, audio and difficulty. Publishing, purchases and uploads are separate actions that need the user's go-ahead.

Starting a project

Run the scripts from this skill's directory (set skill_dir to where it is installed):

sh
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 is a small platformer that demonstrates scenes, action input, text, sound, a camera, pause and scripted capture. It is an integration example, not a template for every genre: a puzzle or card game should drop gravity, jumping, camera scrolling and the platformer HUD. Existing projects rarely need it. --ci adds a GitHub Actions workflow and its tools; read its triggers, targets and release steps before enabling it. For a macOS release, scripts/package_macos_app.py assembles a (universal) .app from built binaries; run it with --help first, and sign and notarize separately on a Mac.

Loop and resource contracts

MethodResponsibilityImportant distinction
Update() errorSample actions, advance simulation, apply scene changes, trigger event audio60 fixed ticks/s by default. Catch-up updates, focus pauses and slow machines change the real schedule.
Draw(screen *ebiten.Image)Render the state the updates producedNot one call per tick. Never advance gameplay, consume input edges or start sounds here.
Layout(outsideW, outsideH int) (int, int)Choose the logical size for rendering and inputFixed and responsive designs are both valid; check small windows, aspect ratio and readability.
  • Express durations in ticks or an explicit fixed dt (30 ticks = 0.5 s at 60 TPS).
  • Return ebiten.Termination from Update for a clean stop; propagate other errors out of

RunGame.

  • Decode images and parse font sources once; reuse offscreens and hot-path slices.
  • Keep rules apart from device and GPU code so they are testable. A small game does not

need an ECS, scene stack or service layer.

Essential Ebitengine choices

  • Input: map devices to actions in Update; separate held, pressed and released;

check gamepad availability and apply stick dead zones. Input.

  • Rendering: GeoM operations apply in call order. Choose sampling deliberately for

pixel art versus smooth art. A custom final-screen transform needs matching pointer conversion. Rendering.

  • Text/UI: keep a suitable existing bitmap or atlas renderer; new outline-font code uses

text/v2 with fonts that cover the shipped scripts (and their licences). Measure real strings and check focus and long text. Text/UI.

  • Audio: one audio.Context per process; match sample rate and PCM format; give

overlapping effects their own players. Audio.

  • Systems: tweens, particles, shake, physics and map loaders are optional helpers for

the central interaction. Gameplay systems.

  • State: queue external callbacks into Update, make reset/retry complete, split

gameplay and cosmetic randomness, and test saves when persistence is promised. Architecture/testing.

Verification

Run from the game directory and keep go.mod and go.sum. -buildvcs=false avoids depending on surrounding Git metadata.

sh
go vet ./...
go test ./world/...   # the starter's GPU-independent rules; run your other packages too
python3 "$skill_dir/scripts/check_ebitengine.py" .
go build -buildvcs=false -o game .

Run the checker after changing loop, input or audio code or when reviewing old APIs. It is a read-only text scan: warnings (deprecated APIs, ReadPixels, work in Draw) need a look in context, and notes (ambiguous .At() calls the scanner cannot type) never fail --strict. --json prints the shared checker schema with note_count and notes; --max-issues N caps the report without changing totals. A clean result proves neither correctness nor quality.

Capture the starter with -demo -shot frame.png -shot-tick 240. On Linux, use a virtual display and, if there is no sound card, a null ALSA device without touching HOME:

sh
audio_config=$(mktemp)
printf 'pcm.!default { type null }\n' > "$audio_config"
ALSA_CONFIG_PATH="$audio_config" xvfb-run -a ./game \
  -demo -shot frame.png -shot-tick 240
rm "$audio_config"

Open the PNG, then capture other states that matter: first play, a busy moment, failure and the outcome screen. Once the game differs from the template, update the scripted actions and capture points; the template demo proves nothing about another loop. Tests that initialize graphics need xvfb-run -a on Linux. For injected input and replay tests, v2.10's opt-in exp/vmhost is covered in Architecture/testing.

Build only the promised targets, for example:

sh
GOOS=windows GOARCH=amd64 go build -buildvcs=false -o game.exe .
GOOS=js GOARCH=wasm go build -buildvcs=false -o game.wasm .

Cross-compiling proves buildability, not runtime support. Serve browser builds over HTTP and check the console, input and audio. Native SDKs, store bindings and cgo dependencies add requirements beyond Ebitengine's pure-Go desktop backend.

Gotchas

  • A key press is sometimes missed, or fires twice → input edges (inpututil.IsKeyJustPressed

and friends) are tick-based. Read them once per tick in Update, never in Draw, and combine bindings before computing an action's edge.

  • Animation or gameplay speed changes with the monitor's refresh rate → state advances

in Draw, or code uses ActualTPS/ActualFPS as a delta. Advance in Update by ticks. SetTPS changes the whole clock, so it is not a slow-motion switch.

  • Sprite rotates around the wrong point or drifts → GeoM applies in call order:

translate the pivot to the origin, scale and rotate, then translate to the position.

  • Pixel art is blurry or uneven → sampling and scale policy were not chosen. Read the

scaling section of the rendering reference; strict integer scaling with a custom final screen also needs matching cursor conversion.

  • A sound plays about 9% fast and high, or as noise → DecodeF32 does not resample, and

F32 streams need the …F32 players. Convert assets to the context rate or use DecodeWithSampleRate with NewPlayer.

  • `audio: context is already created` panic → audio.NewContext ran twice. Create one

context at start-up and pass it around (audio.CurrentContext() returns it).

  • A rapid sound effect cuts itself off → one audio.Player is rewound for every hit.

Use a small voice pool and cap concurrent voices.

  • No sound in the browser → browsers allow audio only after a user gesture. Start

music from a title-screen action and check ctx.IsReady(); an embedding iframe needs allow="autoplay".

  • Frame rate drops when text is on screen → a font file is parsed with

text.NewGoTextFaceSource every frame, or Size is animated (glyphs are rebuilt per size). Parse each font once and keep the source; to zoom text, scale a pre-drawn image.

  • The HUD shows an old value → text was cached (an image or a wrapped layout) and not

rebuilt when the value changed. Rebuild the cache on change, or draw the text directly.

  • The game hangs or slows at a `ReadPixels`/`At` call → GPU readback waits for the GPU,

and ReadPixels cannot run before RunGame. Keep it to tests and screenshots.

  • Deprecation warnings from the checker → ebiten.DeviceScaleFactor →

ebiten.Monitor().DeviceScaleFactor(); inpututil.PressedKeys → AppendPressedKeys; ebiten.GamepadIDs/TouchIDs → AppendGamepadIDs/AppendTouchIDs; text.Advance → text.AdvanceAt. Deprecated code still builds; change it when touched.

  • **Visible stutter when the frame rate is near the TPS (or a multiple of it), at startup or

after a long frame** → fixed in v2.10.6 (issue 4015). Upgrade an older v2.10 pin before tuning the game's own timing.

  • `go: go.mod requires go >= 1.25.0 (running go 1.22…; GOTOOLCHAIN=local)` → the local

Go is older than v2.10 needs. Install Go 1.25+, or allow the toolchain download (GOTOOLCHAIN=auto, the default).

Compose within this catalog

This skill owns Ebitengine and Go APIs. For portable design, pair it with the relevant discipline (game-ui-ux, game-feel, audio-design, create-game-assets, input-systems, performance-optimization, save-systems), a genre skill or a shipping workflow, and bind their engine slots to this skill's references rather than another engine's code. The folder also works on its own.

Read as needed

genre structure, complete loop, presentation and playtest acceptance.

WASM or mobile targets, or writing the release checklist.

text/UI, audio: when changing that system.

art set; shared visual rules, pivots and sprite-sheet checks.

reproducing a failure; controlled ticks with paired state and image evidence.

entities, saves, randomness or tests, or using exp/vmhost.

particles, shake and hit-stop, or rigid bodies. Tiled maps: only when levels come from Tiled.

monetization, CI/release: only for requested distribution, store or automation work.

Ebitengine's own repository has agent skills under skills/ on its main branch (run-ebitengine-app-headless, writing-kage-shaders, avoiding-blurry-ebitengine-rendering, efficient-ebitengine-rendering). Use them when installed for headless input injection, Kage shaders and rendering performance, and check that what they describe exists in the project's pinned version: they track the next release.

Version notes

Last verified: 2026-11-11.

  • Ebitengine v2.10.6 (2026-11-07) is the latest stable release; v2.11.0-alpha exists. v2.10.6

changes only the internal tick clock (the stutter fix, issue 4015) and the PureGo dependency, so the v2.10.5 API notes in the references carry over unchanged.

  • Ebitengine v2.10 needs Go 1.25 or later (go 1.25.0 in its go.mod).
  • The starter was generated with new_game.py (default --ebiten v2.10.6), then

go mod tidy, go vet, go test ./world/..., the checker, native, Windows and WASM builds and the Xvfb capture above were run with Go 1.25.0.

v2.10 release notes, v2.10.5...v2.10.6 diff, issue 4015, repository skills.

같은 저장소의 Skills

더 많은 Skills

모든 Skills
gamedev-skills
커뮤니티

game-ui-ux

Engine-neutral design rules for game HUDs and menus: anchors and containers, scaling, safe areas, gamepad focus, HUDs driven by events instead of polling, and accessibility minimums. Use for menus, health bars or inventory screens that break on ultrawide or phones. Pair with godot-ui-control or roblox-ui. Not for button juice (game-feel) or rebinding (input-systems).

24시간 설치 수
433
GitHub Stars
1만
업데이트
11월 12일
gamedev-skills
커뮤니티

game-feel

Adds engine-neutral juice to a working mechanic: trauma-based screen shake, hit-stop, eased tweens, squash and stretch, and knockback. Use when the game feels flat, weightless or not punchy, or hits and jumps should feel satisfying. Not for coyote time (platformer), input buffering (input-systems), camera follow (camera-systems) or HUD layout (game-ui-ux).

24시간 설치 수
431
GitHub Stars
1만
업데이트
11월 12일
gamedev-skills
커뮤니티

create-game-assets

Plans, generates or sources, and validates consistent game art: style guides, sprites, pixel art, tilesets, icons and textures, with QA and licence records. Use when making or AI-generating game art, fixing fake transparency, or checking Steam AI disclosure. Not for engine import (godot-tilemap, godot-animation, unity-tilemap-2d), UI layout (game-ui-ux) or sound (audio-design).

24시간 설치 수
365
GitHub Stars
1만
업데이트
11월 12일
gamedev-skills
커뮤니티

performance-optimization

Finds and fixes game frame-rate problems by measurement in Godot, Unity, Unreal or Roblox: CPU- vs GPU-bound, then the biggest fix (draw calls, pooling, GC spikes). Use for low FPS, stutter, a first-use hitch, or requests to optimize or profile. Not for build size (unity-build-size), physics jitter (physics-tuning) or network lag (roblox-networking, godot-multiplayer).

24시간 설치 수
360
GitHub Stars
1만
업데이트
11월 12일