improve-game

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Performance Notes

性能说明

Take your time to do this thoroughly
Quality is more important than speed
Do not skip validation steps

请耐心并彻底地完成工作
质量比速度更重要
不要跳过验证步骤

Improve Game

改进游戏

Make your game better. This command deep-audits gameplay, visuals, code quality, performance, and player experience, then implements the highest-impact improvements. Run it as many times as you want — each pass finds the next most impactful thing to fix.

让你的游戏变得更好。此命令会深度审计玩法、视觉表现、代码质量、性能和玩家体验，然后实施影响最大的改进。你可以任意次数运行——每一轮都会找出下一项影响最大的待修复事项。

Instructions

说明

Improve the game in the current directory. If

$ARGUMENTS

specifies a focus area (e.g., "gameplay", "visuals", "performance", "polish", "game-over"), weight that area higher but still audit everything.

改进当前目录中的游戏。如果

$ARGUMENTS

指定了重点领域（例如“gameplay”“visuals”“performance”“polish”“game-over”），请提高该领域的权重，但仍要审计所有方面。

Step 1: Deep audit

第 1 步：深度审计

Read the entire game codebase to build a complete picture:

```
package.json
```
— engine, dependencies, scripts
```
src/core/Constants.js
```
— all configuration values
```
src/core/EventBus.js
```
— all events and their usage
```
src/core/GameState.js
```
— state shape and reset logic
```
src/core/Game.js
```
(or
```
GameConfig.js
```
) — orchestrator and game loop
Every file in
```
src/scenes/
```
or
```
src/systems/
```
— gameplay logic
Every file in
```
src/entities/
```
— game objects
Every file in
```
src/ui/
```
— game over, overlays
Every file in
```
src/audio/
```
— music and sound effects
```
index.html
```
— markup, overlays, styles, viewport meta
```
src/systems/InputSystem.js
```
— input handling, mobile support (gyro, joystick, touch)
```
tests/
```
— test coverage and quality

Don't skim. Read every file completely so you understand the full picture before making recommendations.

读取整个游戏代码库，以建立完整认知：

```
package.json
```
——引擎、依赖项和脚本
```
src/core/Constants.js
```
——所有配置值
```
src/core/EventBus.js
```
——所有事件及其使用方式
```
src/core/GameState.js
```
——状态结构和重置逻辑
```
src/core/Game.js
```
（或
```
GameConfig.js
```
）——编排器和游戏循环
```
src/scenes/
```
或
```
src/systems/
```
中的每个文件——玩法逻辑
```
src/entities/
```
中的每个文件——游戏对象
```
src/ui/
```
中的每个文件——游戏结束界面和浮层
```
src/audio/
```
中的每个文件——音乐和音效
```
index.html
```
——标记、浮层、样式和 viewport meta
```
src/systems/InputSystem.js
```
——输入处理和移动端支持（gyro、joystick、touch）
```
tests/
```
——测试覆盖率和质量

不要走马观花。完整读取每个文件，确保在提出建议前已理解整体情况。

Step 2: Score and diagnose

第 2 步：评分与诊断

Rate each area on a 1–5 scale (1 = broken/missing, 3 = functional but basic, 5 = polished and complete). Present a diagnostic table:

Area	Score	Diagnosis
Gameplay feel		Is the core loop fun? Are controls responsive? Does difficulty ramp?
Visual polish		Backgrounds, colors, particles, animations, screen effects
Game Over & UI		Game over screen, transitions, restart flow, buttons
Audio		BGM for each state, SFX for each action, volume balance, mute toggle
Code architecture		EventBus, GameState, Constants, no circular deps
Restart safety		Does GameState.reset() fully clean up? 3 restarts identical? No stale listeners/timers?
Performance		Delta capping, object pooling, disposal, no leaks
Player experience		Onboarding, feedback, difficulty curve, replayability
Mobile support		Touch input, responsive layout, gyro/joystick, 44px touch targets
Play.fun safe zone		All UI elements below `SAFE_ZONE.TOP` (~8% / 75px)? Nothing hidden behind Play.fun widget?
Gameplay invariants		Can the player score? Can the player die? Do game-over buttons show text? Does `render_game_to_text()` return valid JSON?
Entity sizing		Are characters large enough to read? Character-driven games need 12–15% of GAME.WIDTH. Proportional sizing ( `GAME.WIDTH * ratio` ), not fixed pixels?
Test coverage		Boot, gameplay, scoring, restart, visual, perf tests

Overall score: X / 65

每个领域按 1–5 分评分（1 = 损坏/缺失，3 = 可用但基础，5 = 已打磨且完整）。给出诊断表：

领域	分数	诊断
游戏手感		核心循环有趣吗？控制响应及时吗？难度是否有递进？
视觉打磨		背景、色彩、粒子、动画和屏幕特效
游戏结束与 UI		游戏结束画面、转场、重启流程和按钮
音频		每个状态的 BGM、每个操作的 SFX、音量平衡和静音开关
代码架构		EventBus、GameState、Constants，且无循环依赖
重启安全性		`GameState.reset()` 是否彻底清理？连续重启 3 次是否一致？是否残留监听器或定时器？
性能		delta capping、object pooling、disposal，且无泄漏
玩家体验		新手引导、反馈、难度曲线和重玩价值
移动端支持		触控输入、响应式布局、gyro/joystick、44px 触控目标
Play.fun 安全区		所有 UI 元素是否都位于 `SAFE_ZONE.TOP` （约 8% / 75px）以下？是否没有被 Play.fun widget 遮挡？
玩法不变量		玩家能否得分？能否死亡？游戏结束按钮是否显示文本？ `render_game_to_text()` 是否返回有效 JSON？
实体尺寸		角色是否足够大、易于辨认？角色驱动型游戏需要占 GAME.WIDTH 的 12–15%。是否按比例计算尺寸（ `GAME.WIDTH * ratio` ），而不是使用固定像素？
测试覆盖率		启动、玩法、计分、重启、视觉和性能测试

总分：X / 65

Step 3: Improvement plan

第 3 步：改进计划

From the audit, identify the top 5–8 improvements ranked by player impact. For each one:

Title — short name (e.g., "Add difficulty progression")
Area — which category it improves
Impact — why this matters to the player
What to do — plain-English description of the change
Files touched — which files will be created or modified

Format as a numbered list. Put the highest-impact items first.

Present the plan to the user and ask which improvements to implement. Options:

"All" — implement everything
Specific numbers — implement selected items
"Top 3" — just the most impactful

Wait for the user to choose before implementing.

根据审计结果，找出按对玩家的影响排序的最重要 5–8 项改进。每项改进包含：

标题——简短名称，例如“增加难度递进”
领域——该改进所属的类别
影响——为什么这对玩家很重要
具体做法——用通俗语言描述变更
涉及文件——将创建或修改哪些文件

使用编号列表展示计划，并将影响最大的项目放在最前面。

向用户展示计划，并询问要实施哪些改进。选项包括：

"All"——实施全部改进
具体编号——实施选定项目
"Top 3"——仅实施影响最大的项目

等待用户选择后再实施。

Step 4: Implement

第 4 步：实施

For each selected improvement, follow these rules:

Constants first — add all new config values to
```
Constants.js
```
. Zero hardcoded values.
Events next — add any new events to
```
EventBus.js
```
using
```
domain:action
```
naming.
State if needed — add new state fields to
```
GameState.js
```
with proper reset.
New files in proper directories — entities in
```
entities/
```
, systems in
```
systems/
```
, UI in
```
ui/
```
.
Wire through orchestrator — register new systems in
```
Game.js
```
with proper lifecycle.
EventBus for communication — modules never import each other directly.
Match existing code style — same patterns, naming, formatting as the rest of the project.
Don't break what works — existing gameplay, controls, and scoring must still function identically unless the improvement specifically targets them.

After implementing each improvement, run

npm run build

to catch errors immediately. Fix any build errors before moving to the next improvement.

实施每项选定的改进时，遵循以下规则：

先处理 Constants——将所有新配置值添加到
```
Constants.js
```
。不得硬编码任何值。
然后处理 Events——使用
```
domain:action
```
命名方式将所有新事件添加到
```
EventBus.js
```
。
按需处理 State——在
```
GameState.js
```
中添加新状态字段，并正确实现重置逻辑。
将新文件放入正确目录——实体放在
```
entities/
```
，系统放在
```
systems/
```
，UI 放在
```
ui/
```
。
通过编排器连接——在
```
Game.js
```
中注册新系统，并正确管理 lifecycle。
使用 EventBus 通信——模块之间不得直接 import。
匹配现有代码风格——采用项目现有的模式、命名和格式。
不要破坏已有功能——除非改进项目本身针对该功能，否则现有玩法、控制和计分必须保持相同行为。

实施每项改进后，运行

npm run build

以立即发现错误。在继续下一项改进前，修复所有构建错误。

Step 5: Verify

第 5 步：验证

After all improvements are implemented:

Run
```
npm run build
```
— confirm clean build with no errors
Run
```
npm test
```
if tests exist — confirm all tests still pass
If tests fail because of intentional changes (new scenes, changed elements), fix the tests to match the new behavior
If the game has visual regression tests, update snapshots:
```
npm run test:update-snapshots
```

实施所有改进后：

运行
```
npm run build
```
——确认构建成功且没有错误
如果存在测试，运行
```
npm test
```
——确认所有测试仍然通过
如果测试因有意变更而失败（新场景、变更元素等），调整测试以匹配新行为
如果游戏包含视觉回归测试，更新 snapshots：运行
```
npm run test:update-snapshots
```

Step 6: Report

第 6 步：报告

Tell the user what changed:

Improvement report

Score: X/65 → Y/65 (+Z points)

Implemented:

[Title] — [one-sentence summary of what changed]

[Title] — [one-sentence summary of what changed] ...

Files created: [list new files] Files modified: [list changed files]
How to test: Run
npm run dev
and try:
[specific thing to look for]

[specific thing to look for]
Next improvements: Run
/game-creator:improve-game
again to find the next batch.

告诉用户发生了哪些变化：

改进报告

分数：X/65 → Y/65（+Z 分）

已实施：

[标题]——[用一句话说明改了什么]

[标题]——[用一句话说明改了什么] ……
新建文件：[新文件列表] 修改文件：[已修改文件列表] 测试方法： 运行
npm run dev
并尝试：
[需要重点观察的具体内容]
[需要重点观察的具体内容] 后续改进： 再次运行
/game-creator:improve-game
，找出下一批改进项。

Focus areas

重点领域

When

$ARGUMENTS

includes a focus area keyword, weight these specific checks:

"gameplay" — core loop, controls, difficulty progression, enemy variety, power-ups, risk/reward, pacing, level design

"visuals" — load the game-designer skill and apply its full design audit (backgrounds, palette, animations, particles, transitions, typography, juice)

"performance" — delta capping, object pooling, geometry/material disposal, event listener cleanup, requestAnimationFrame usage, draw call count, texture atlas usage

"polish" — screen shake, hit pause, squash/stretch, easing curves, sound timing, button feedback, score popups, death animations, transition smoothness

"game-over" — game over screen appeal, restart flow, button styling, score display, best score display, animations. Button text must be visible — verify the

createButton()

pattern uses Container + Graphics + Text (Graphics first, Text second, Container interactive). If button labels are invisible, the pattern is broken. Note: games do not have title/menu screens by default (Play.fun handles the chrome). Only add a title screen if the user explicitly requests one. Score HUD is handled by the Play.fun widget — do not add a separate in-game score display. All game-over UI must be below

SAFE_ZONE.TOP

"audio" — load the game-audio skill. Check BGM coverage (every game state should have music), SFX coverage (every player action should have feedback), volume mixing, transition smoothness between tracks

"mobile" — touch input implemented (tap zones, virtual joystick, or gyroscope), responsive canvas (

Phaser.Scale.FIT

or CSS

width:100%

), 44px minimum touch targets, virtual joystick or tap zones for movement, gyroscope support for tilt games, no hover-only interactions, tested on mobile viewport (Pixel 5 emulation). Read

InputSystem.js

, all scene/system

update()

methods,

index.html

viewport meta, and

Constants.js

for touch target sizes.

"ux" — onboarding (does the player know what to do?), feedback (does every action have a response?), difficulty curve (is it too hard/easy?), replayability (is there a reason to play again?)

当

$ARGUMENTS

包含某个重点领域关键词时，应提高以下具体检查项的权重：

"gameplay"——核心循环、控制、难度递进、敌人类型、power-ups、风险/收益、节奏和关卡设计

"visuals"——加载 game-designer skill，并应用其完整设计审计（背景、调色板、动画、粒子、转场、字体排印和 juice）

"performance"——delta capping、object pooling、geometry/material disposal、事件监听器清理、requestAnimationFrame 使用、draw call 数量和 texture atlas 使用

"polish"——screen shake、hit pause、squash/stretch、easing curves、声音时机、按钮反馈、分数弹出动画、死亡动画和转场流畅度

"game-over"——游戏结束画面的吸引力、重启流程、按钮样式、分数显示、最高分显示和动画。按钮文本必须可见——确认

createButton()

模式使用 Container + Graphics + Text（先 Graphics，后 Text，Container 具备交互能力）。如果按钮标签不可见，说明该模式已损坏。请注意：游戏默认没有标题/菜单画面（Play.fun 负责 chrome）。仅当用户明确要求时才添加标题画面。分数 HUD 由 Play.fun widget 处理——不要添加单独的游戏内分数显示。所有游戏结束 UI 都必须位于

SAFE_ZONE.TOP

以下。

"audio"——加载 game-audio skill。检查 BGM 覆盖范围（每个游戏状态都应有音乐）、SFX 覆盖范围（每个玩家操作都应有反馈）、音量混音以及音轨之间的平滑过渡

"mobile"——已实现触控输入（tap zones、virtual joystick 或 gyroscope）、响应式 canvas（

Phaser.Scale.FIT

或 CSS

width:100%

）、44px 最小触控目标、使用 virtual joystick 或 tap zones 进行移动、为倾斜类游戏提供 gyroscope 支持、不存在仅悬停才可触发的交互，并已在移动端 viewport（Pixel 5 模拟）上测试。读取

InputSystem.js

、所有 scene/system 的

update()

方法、

index.html

的 viewport meta，以及

Constants.js

中的触控目标尺寸。

"ux"——新手引导（玩家知道该做什么吗？）、反馈（每次操作都有响应吗？）、难度曲线（太难还是太简单？）和重玩价值（玩家为什么还要再玩一次？）

Example Usage

使用示例

General improvement

通用改进

/improve-game

Result: Deep audit → scores 38/65 → identifies top 6 improvements (difficulty progression, screen shake, better game-over, particle effects, mobile touch, restart safety) → asks which to implement → implements selected → score rises to 52/65.

/improve-game

结果：深度审计 → 评分 38/65 → 确定影响最大的 6 项改进（难度递进、screen shake、更好的游戏结束界面、粒子效果、移动端触控、重启安全性）→ 询问要实施哪些改进 → 实施选定项 → 分数提升至 52/65。

Focused improvement

聚焦改进

/improve-game gameplay

Result: Weights gameplay checks higher → finds enemy variety is low and difficulty is flat → adds 3 enemy types with distinct behaviors, progressive speed ramp, and score-based difficulty tiers.

/improve-game gameplay

结果：提高 gameplay 检查项的权重 → 发现敌人类型较少且难度较为平缓 → 添加 3 种具有不同行为的敌人、渐进式速度提升，以及基于分数的难度等级。

Troubleshooting

故障排查

Improvements break existing gameplay

改进破坏了现有玩法

Cause: Changes to shared systems (physics, scoring) have cascading effects. Fix: Test each improvement individually. Run existing tests after each change. Revert if a change breaks core gameplay.

原因： 对共享系统（物理、计分）的更改产生了连锁影响。 修复： 逐项测试每项改进。每次更改后运行现有测试。如果更改破坏了核心玩法，则回退。

Too many changes at once

一次进行了过多更改

Cause: Audit identified 10+ issues and all were implemented simultaneously. Fix: Prioritize top 3-5 improvements. Ship incrementally. Verify after each change.

原因： 审计发现了 10 个以上问题，却同时实施了所有更改。 修复： 优先处理影响最大的 3–5 项。逐步交付，并在每次更改后进行验证。

Tips

提示

This command is designed for iterative improvement. Run it multiple times:

First pass: fix the biggest gaps (missing features, broken UX)

Second pass: add polish (particles, transitions, juice)

Third pass: fine-tune (difficulty curve, timing, balance)

Each run picks up where the last left off — previously fixed areas will score higher, surfacing new priorities.
For targeted work, use the focus area:
/game-creator:improve-game gameplay
or
/game-creator:improve-game visuals

此命令专为迭代改进而设计。请多次运行：

第一轮：修复最大的缺口（缺失功能、损坏的 UX）

第二轮：添加打磨效果（粒子、转场、juice）

第三轮：微调（难度曲线、时序、平衡性）

每次运行都会从上次结束的位置继续——已修复领域的评分会提高，从而显现新的优先事项。
如需针对特定领域工作，请使用重点领域：
/game-creator:improve-game gameplay
或
/game-creator:improve-game visuals