ebitengine-game

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Ebitengine game

Ebitengine 游戏

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.

交付一款在请求范围内易于理解、响应灵敏且功能完整的游戏。一次请求可以包含多轮内部构建、试玩和打磨。仅有脚手架、成功构建或一张精美截图并不代表游戏已经完成。对于聚焦的修复，应保留项目设计，并将工作流限制在受影响的行为范围内。

捆绑的 starter 以 Ebitengine v2.10.5 / Go 1.25+ 为目标。这是一个固定的基线，并不代表最新版。除非升级确有必要且已获授权，否则应保留现有项目的版本。使用较新或实验性 API 前，应检查固定版本的公开 API。参考资料仅包含可供改编的模式；只有捆绑的脚本和 starter 属于可执行交付物。其检查无法验证每个参考代码片段。

Delivery workflow

交付工作流

Inspect and decide. Read repository instructions,
```
go.mod
```
, the
```
RunGame
```
entrypoint and existing tests/assets. For new games, read Design and quality. 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.
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.
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.
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.
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.

检查并决策。 阅读仓库说明、
```
go.mod
```
、
```
RunGame
```
入口点以及现有测试和资源。对于新游戏，阅读设计与质量。明确玩家目标、反复作出的决策、决策后果、结束/重试路径、预期视觉风格、目标平台和支持的输入方式。合理推断默认值；仅当缺失的选择会实质影响产品时才询问。将简短任务说明和可观察的验收标准记录在项目中。
构建具有代表性的可玩切片。 让核心交互及其反馈能够按照预期操作方式和视觉方向运行。在扩展内容前先检查手感。将范围控制在可完成的规模；根据游戏本身而非模板选择手工创作或程序生成内容。根据玩家的实际能力校准内容，再增加关卡数量。对于美术资源集，使用资源与动画统一视角、比例、锚点和调色板角色。
完成并打磨。 实现承诺的开始 → 游玩 → 结果 → 重试/继续循环（或适合该游戏的持续/沙盒循环）。结合整体情境打磨层次、动画、音效、难度和过渡。仅阅读所选系统所需的技术参考资料。在本次交付中修复发现的缺陷，而不是要求用户反复迭代。
验证产品。 测试规则和重要状态转换，使用真实输入，检查有代表性的渲染状态，并构建/运行请求的目标平台。包含失败/重试和边界情况。脚本化演示无法证明操控手感；静音音频接收端也无法证明音质。对于自动化的多步交互，应将观察到的画面与同一 tick 时的实际状态对应起来；参见试玩诊断。
交付。 提供启动/构建说明、实际产物路径和资源许可。说明运行和观察到了什么、哪些内容尚未验证，以及任何实质性限制。发布、购买和外部上传是用户请求范围内的独立操作。

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.

命令路径应相对于此 skill 的目录，而不是游戏的工作目录。将

skill_dir

设置为实际安装位置，然后例如：

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

starter 通过一个小型 platformer 演示场景、动作输入、文本、声音、摄像机、暂停和脚本化捕获。它只是集成示例，并不构成游戏类型或架构要求。应替换其规则、控制方式、关卡、表现和场景流程，以契合任务说明；拼图或卡牌游戏不应继承重力、跳跃、摄像机滚动或 platformer HUD。现有项目很少需要脚手架。

--ci

会添加工作流和工具；启用前应检查其触发条件、目标和发布行为。

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.

方法	职责	重要区别
`Update() error`	采样操作、推进模拟、应用场景切换并触发事件音频	默认目标为每秒 60 个固定 tick。追赶更新、焦点暂停和性能较慢的机器会影响实际调度。
`Draw(screen *ebiten.Image)`	渲染更新产生的状态	调用次数与 tick 并非一一对应。不要在此推进玩法、消费输入边沿或启动声音。渲染器拥有的缓存与模拟状态相互分离。
`Layout(outsideW, outsideH int) (int, int)`	选择用于渲染和输入的逻辑尺寸	固定和响应式设计都可行。需考虑小窗口、宽高比和可读性。

使用 tick 或明确的固定
```
dt
```
表示模拟时长。在 60 TPS 下，30 个 tick 等于 0.5 秒模拟时间。
```
ActualTPS
```
是诊断指标，不是时间差。
```
SetTPS
```
会改变整个更新时钟，并非通用的慢动作控制。对于要求固定步长的规则，应避免使用
```
SyncWithFPS
```
。
从
```
Update
```
返回
```
ebiten.Termination
```
以正常停止。其他错误从
```
RunGame
```
返回；应传播失败，而不是隐藏失败。
只加载和解码一次图像与字体源；复用离屏资源和热路径切片。在将对象池或零分配规则设为通用要求前，先进行性能分析。
在有助于测试的情况下，将规则与设备/GPU 代码分离。小型游戏不应在无必要时引入 ECS、场景栈或服务层。

Essential Ebitengine choices

Ebitengine 的必要选择

Input: Map devices to actions in
```
Update
```
. Separate held/pressed/released; combine bindings before computing an action edge if that is the intended behavior. Standard gamepad mappings need an availability check and stick dead zones. Verify the advertised devices through menus and retry too. Input.
Rendering:
```
GeoM
```
operations apply in call order. Pixel art needs deliberate sampling/scaling; smooth art needs suitable filtering and antialiased geometry. Preserve layer order while batching; sharing a sheet does not guarantee one command. Custom final-screen transforms need matching pointer conversion. Rendering.
Text/UI: Preserve suitable existing bitmap/atlas text rendering. For new outline-font code, use
```
text/v2
```
and parse font sources once. Include fonts covering the shipped scripts and their licences. Measure actual strings and verify focus, long text and target-size readability. Text/UI.
Audio: One
```
audio.Context
```
per process. Match sample rate and PCM format:
```
DecodeF32
```
does not resample;
```
DecodeWithSampleRate
```
returns 16-bit PCM. Overlapping effects need independent players or a voice pool; bound concurrency for dense events. Resume browser audio after a gesture. Audio.
Systems: Tweens, particles, shake, physics and map loaders are optional tools supporting the central interaction. Gameplay systems.
State: Queue external callbacks for
```
Update
```
, make reset/retry clear, separate gameplay and cosmetic randomness, test saves if persistence is promised. Architecture/testing.

输入： 将设备输入映射到
```
Update
```
中的动作。区分按住、按下和释放；如果这是预期行为，应先合并绑定，再计算动作边沿。标准手柄映射需要检查设备可用性和摇杆死区。也要通过菜单和重试流程验证已声明的设备。输入
渲染：
```
GeoM
```
操作按调用顺序生效。像素美术需要有意选择采样和缩放方式；平滑美术需要合适的过滤和抗锯齿几何。批处理时应保持图层顺序；共享同一图集并不能保证只产生一个绘制命令。自定义最终屏幕变换时，需要进行对应的指针坐标转换。渲染
文本/UI： 保留合适的现有位图或图集文本渲染实现。新建描边字体代码时，使用
```
text/v2
```
并只解析一次字体源。确保字体能够覆盖随项目发布的脚本，并附上相应许可。测量实际字符串，并验证焦点状态、长文本和目标尺寸下的可读性。文本/UI
音频： 每个进程使用一个
```
audio.Context
```
。匹配采样率和 PCM 格式：
```
DecodeF32
```
不会重采样；
```
DecodeWithSampleRate
```
返回 16-bit PCM。重叠音效需要独立播放器或 voice pool；密集事件应限制并发量。浏览器中需在用户操作后恢复音频。音频
系统： 补间、粒子、震屏、物理和地图加载器都是支撑核心交互的可选工具。玩法系统
状态： 将外部回调放入队列，交由
```
Update
```
处理；使重置和重试清晰明确；区分影响玩法的随机性与仅影响表现的随机性；如果承诺提供存档功能，则测试存档。架构/测试

Verification

验证

Run commands from the game directory; retain

go.mod

and

go.sum

. Use repository build flags;

-buildvcs=false

below avoids depending on surrounding Git metadata.

go vet ./...
go test ./world/...   # starter's GPU-independent rules
python3 "$skill_dir/scripts/check_ebitengine.py" .
go build -buildvcs=false -o game .

Run the checker after changing loop/input/audio code or reviewing old APIs. It is a read-only, text-based advisory scan: inspect warnings in context.

--json

returns the shared checker schema;

--strict

fails on warnings and

--max-issues N

limits the report without changing totals. Deprecated APIs are warnings, not proof of a broken build. A clean result proves neither API correctness nor quality. Run other relevant package tests too; on Linux, tests that initialize graphics need

xvfb-run -a

For the starter, capture with

-demo -shot frame.png -shot-tick 240

. On Linux, use a virtual display and, if needed, null audio without changing HOME:

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. Inspect more states as needed: first play, a busy/difficult moment, failure and outcome. Adapt scripted actions/capture points after changing the game; the template demo no longer proves anything about a different loop. For deeper input/replay tests, v2.10's opt-in VM may help (see Architecture/testing).

Build only promised targets, for example:

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

Cross-compilation establishes buildability, not runtime support. Run browser builds over HTTP and inspect console/input/audio when they are a target. Native SDKs, store bindings and cgo dependencies can add requirements beyond Ebitengine's pure-Go desktop backend.

从游戏目录运行命令；保留

go.mod

和

go.sum

。使用仓库的构建标志；下面的

-buildvcs=false

用于避免依赖周围的 Git 元数据。

go vet ./...
go test ./world/...   # starter's GPU-independent rules
python3 "$skill_dir/scripts/check_ebitengine.py" .
go build -buildvcs=false -o game .

修改循环、输入或音频代码，或者审查旧 API 后，应运行检查器。它是一项只读、基于文本的建议性扫描；应结合上下文检查警告。

--json

返回共享检查器 schema；

--strict

遇到警告时失败，

--max-issues N

可限制报告中显示的问题数量，但不会改变统计总数。弃用 API 只会产生警告，并不能证明构建已经损坏。干净的检查结果既不能证明 API 正确，也不能证明质量合格。还要运行其他相关包的测试；在 Linux 上，需要图形初始化的测试应使用

xvfb-run -a

。

对于 starter，使用

-demo -shot frame.png -shot-tick 240

捕获画面。在 Linux 上，使用虚拟显示器；如有需要，可使用空音频设备，但不要更改 HOME：

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"

打开 PNG。根据需要检查更多状态：首次游玩、局面紧张或难度较高的时刻、失败和结果。修改游戏后应调整脚本化操作和捕获点；模板演示无法再证明不同游戏循环的任何特性。对于更深入的输入/回放测试，v2.10 的 opt-in VM 可能会有所帮助（参见架构/测试）。

仅构建承诺的目标，例如：

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

交叉编译只能证明可构建性，不能证明运行时支持。浏览器构建属于目标时，应通过 HTTP 运行，并检查控制台、输入和音频。原生 SDK、商店绑定和 cgo 依赖可能引入超出 Ebitengine 纯 Go 桌面后端的要求。

Compose within this catalog

在此目录中组合使用

This skill owns Ebitengine/Go APIs. For portable design concerns, pair it with the relevant installed discipline (for example

game-ui-ux

game-feel

create-game-assets

input-systems

performance-optimization

save-systems

), genre or shipping workflow. Bind the engine slots to this skill's references, not another engine's example code. Load only what the task needs; the complete folder also works on its own.

此 skill 负责 Ebitengine/Go API。对于可复用的设计问题，应与相关的已安装 discipline 配对，例如

game-ui-ux

、

game-feel

、

create-game-assets

、

input-systems

、

performance-optimization

或

save-systems

，以及游戏类型或发布工作流。将引擎相关槽位绑定到此 skill 的参考资料，而不是其他引擎的示例代码。仅加载任务所需的内容；整个目录也可以独立使用。

Read as needed

按需阅读

Design and quality: brief, genre choices, complete loop, presentation and playtest acceptance; for new games/redesigns.
Project and builds: desktop, WASM and mobile.
Rendering, input, text/UI, audio.
Assets and animation: when making or importing an art set; shared visual rules, scale, pivots and sprite-sheet QA.
Playtest diagnostics: when scripting interactions or reproducing failures; controlled ticks, state/image evidence.
Architecture/testing and gameplay systems: state, saves, animation, collision and optional rigid bodies. Tiled maps covers a constrained loader only when the game uses Tiled.
Networking: only for requested online play.
Publishing/platforms, monetization, CI/release: only for requested distribution/integration work.

If available, Ebitengine's repository skills

writing-kage-shaders

and

run-ebitengine-app-headless

provide version-specific advanced workflows. Other game-design/store skills are optional supplements; this skill remains usable without an external skill catalog.

设计与质量：任务说明、类型选择、完整循环、表现和试玩验收；适用于新游戏或重新设计。
项目与构建：桌面、WASM 和移动端。
渲染、输入、文本/UI、音频。
资源与动画：制作或导入美术资源集时使用；涵盖共享视觉规则、比例、枢轴点和 sprite sheet QA。
试玩诊断：编写脚本化交互或复现故障时使用；涵盖受控 tick，以及状态与图像证据。
架构/测试和玩法系统：状态、存档、动画、碰撞和可选刚体。Tiled 地图仅在游戏使用 Tiled 时适用，其中涵盖一个受限的加载器。
网络：仅用于请求在线游戏时。
发布/平台、变现、CI/发布：仅用于请求分发或集成工作时。

如果可用，Ebitengine 仓库中的

writing-kage-shaders

和

run-ebitengine-app-headless

skill 可提供针对特定版本的高级工作流。其他游戏设计或商店 skill 是可选补充；即使没有外部 skill 目录，此 skill 仍然可以使用。