ebitengine-game

Ebitengine 游戏

交付一款易于理解、响应灵敏且完整的游戏，范围应符合要求。一次请求可以包含多轮内部构建、试玩和优化。仅有脚手架、成功构建或吸引人的截图，都不代表游戏已经完成。对于针对特定问题的修复，应保留项目设计，并将工作流程限制在受影响的行为上。

随附的起始项目面向 Ebitengine v2.10.5 / Go 1.25+。这是固定的基准版本，并不代表最新版本。除非确有必要且已获授权升级，否则请保留现有项目的版本。使用更新版或实验性 API 前，请先查阅固定版本的公开 API。参考资料中的内容是供调整使用的模式；只有随附脚本和起始项目是可执行交付物。它们的检查并不会验证所有参考代码片段。

交付工作流程

1. 检查并确定方案。 阅读仓库说明、go.mod、RunGame 入口以及现有测试和资源。对于新游戏，请阅读设计与质量。确定玩家目标、重复进行的决策、决策后果、结束和重试路径、预期外观、平台及支持的输入方式。推断合理的默认选择；只有缺少会实质改变产品的选项时才询问。将简短的需求说明和可观察的验收标准记录到项目中。
2. 构建具有代表性的可玩切片。 使用预期的控制方式和视觉方向，实现核心交互及其反馈。扩展内容前，先检查实际体验。将范围控制在可完成的大小；根据游戏本身选择手工制作或程序化生成的内容，而不是照搬模板。扩充关卡前，应根据玩家的实际能力校准内容。制作一套美术资源时，请参考资源与动画，统一透视、比例、锚点和调色板用途。
3. 完成并优化。 实现承诺的开始 → 游玩 → 结果 → 重试/继续循环（或适当的持久化/沙盒循环）。结合实际游戏情境，优化视觉层级、动画、音效、难度和过渡。只阅读所选系统所需的技术参考资料。在本次交付中修复发现的问题，而不是让用户反复迭代来替你完成。
4. 验证产品。 测试规则和重要过渡，实际操作输入，检查有代表性的渲染状态，并构建/运行指定目标。包括失败/重试和边界情况。脚本化演示无法验证操控手感；静音音频输出也无法验证音效质量。对于自动化的多步骤交互，应将观察到的图像与同一游戏帧的实际状态配对；请参阅试玩诊断。
5. 交接。 提供启动/构建说明、实际产物路径和资源许可信息。说明运行并观察了哪些内容、哪些内容仍未经验证，以及任何重大限制。发布、购买和外部上传属于独立操作，只有在用户要求的范围内才应执行。

启动项目

命令应相对于此技能所在目录解析，而不是相对于游戏的工作目录。将 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/...

起始项目使用一款小型平台游戏演示场景、操作输入、文本、音效、摄像机、暂停和脚本化捕获。这只是一个集成示例，并不要求采用特定类型或架构。请根据需求说明替换其规则、控制方式、关卡、呈现形式和场景流程；益智游戏或卡牌游戏不应沿用重力、跳跃、摄像机滚动或平台游戏 HUD。现有项目通常不需要脚手架。--ci 会添加工作流和工具；启用前，请检查其触发条件、目标及发布行为。

循环与资源约定

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

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

Ebitengine 的关键选择

• 输入： 在 Update 中将设备映射为操作。区分按住／按下／释放；如果符合预期行为，应在计算操作边沿前合并绑定。标准手柄映射需要可用性检查和摇杆死区。还应通过菜单和重试流程验证所声明支持的设备。 输入。
• 渲染： GeoM 操作按调用顺序生效。像素艺术需要谨慎选择采样和缩放方式；平滑风格的美术需要合适的滤波和抗锯齿几何图形。批处理时应保持图层顺序；共用图集并不保证只产生一条命令。自定义最终屏幕变换时，指针坐标转换也必须匹配。 渲染。
• 文本／UI： 保留合适的现有位图／图集文本渲染方式。编写新的轮廓字体代码时，使用 text/v2 并且只解析一次字体源。应包含覆盖已发布文字脚本的字体及其许可证。测量实际字符串，并验证焦点、长文本和目标尺寸下的可读性。 文本／UI。
• 音频： 每个进程只使用一个 audio.Context。采样率和 PCM 格式必须匹配： DecodeF32 不会重新采样；DecodeWithSampleRate 返回 16 位 PCM。 重叠的音效需要独立播放器或语音池；密集事件应限制并发数。浏览器音频应在用户手势后恢复。 音频。
• 系统： 补间动画、粒子、屏幕抖动、物理和地图加载器都是可选工具，用于支持核心交互。 游戏系统。
• 状态： 将外部回调排队，留待 Update 处理；确保重置／重试能清理状态；将游戏逻辑随机性与装饰性随机性分开；如果承诺支持持久化，则应测试存档。 架构／测试。

验证

在游戏目录中运行命令；保留 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 会返回共享检查器架构；--strict 会在出现警告时失败，--max-issues N 会限制报告内容，但不会更改总数。已弃用的 API 是警告，并不代表构建必然损坏。检查结果干净，既不能证明 API 正确，也不能证明质量良好。还要运行其他相关的包测试；在 Linux 上，初始化图形的测试需要使用 xvfb-run -a。

对于起始项目，使用 -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 的可选 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 桌面后端的要求。

在本目录中组合使用

此技能负责 Ebitengine／Go API。对于可移植的设计问题，请将它与相关的已安装规范（例如 game-ui-ux、game-feel、create-game-assets 或 save-systems）、游戏类型或发布工作流搭配使用。将引擎相关部分映射到此技能的参考资料，而不是其他引擎的示例代码。仅加载任务所需的内容；完整文件夹也可以独立使用。

按需阅读

• 设计与质量：简介、游戏类型选择、完整循环、呈现方式和试玩验收；适用于新游戏／重新设计。
• 项目与构建：桌面、WASM 和移动端。
• 渲染、输入、文本／UI、音频。
• 资源与动画：制作或导入美术资源集时使用；涵盖共享视觉规则、缩放、轴心和精灵表 QA。
• 试玩诊断：编写交互脚本或重现故障时使用；涵盖受控帧数、状态／图像证据。
• 架构／测试和游戏系统：状态、存档、动画、碰撞和可选刚体。Tiled 地图仅涵盖受限的加载器，且仅适用于使用 Tiled 的游戏。
• 网络：仅适用于有在线游玩需求的情况。
• 发布／平台、变现、CI／发布：仅适用于有分发／集成需求的工作。

如果可用，Ebitengine 仓库中的技能 writing-kage-shaders 和 run-ebitengine-app-headless 可提供特定版本的高级工作流。其他游戏设计／商店技能可作为可选补充；无需外部技能目录，此技能也能使用。