threejs-gameplay-systems

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Three.js Gameplay Systems

Three.js 游戏玩法系统

Purpose

用途

Create or evolve a playable browser game loop with clear ownership, responsive controls, deterministic update order, strong design intent, playable spaces, and verified player-facing behavior.

创建或优化可运行的浏览器游戏循环，确保职责清晰、操控响应灵敏、更新顺序确定、设计意图明确、游戏空间可玩，且玩家可见行为经过验证。

Use When

适用场景

Starting a new game, repairing a weak prototype, adding mechanics/entities, designing architecture, defining a game design brief, planning levels/arenas/tracks/waves/holes/puzzles, tuning camera/controls, implementing rules/objectives, building encounters, or improving game feel.

启动新游戏项目、修复不完善的原型、添加机制/实体、设计架构、定义游戏设计brief、规划关卡/竞技场/赛道/波次/洞穴/谜题、调校相机/操控、实现规则/目标、构建遭遇战，或提升游戏手感时。

Workflow

工作流程

Load

references/gameplay-workflows.md

as the first action when the task includes first playable setup, architecture, mechanics, entities, input, camera, collision/physics, scoring, objectives, feedback, or feel tuning.

Load

references/game-design-level-design.md

before broad new-game creation, major gameplay changes, level/arena/track/wave/hole/puzzle design, combat/encounter design, progression/difficulty work, or any claim that gameplay is premium, polished, complete, or less generic.

Load

references/physics-engine-selection.md

before adding or changing physics, collision-heavy gameplay, vehicle movement, rolling balls, mini-golf, pool/snooker, pinball, rigid-body puzzles, character controllers, sensors, high-speed projectiles, moving platforms, or physics QA.

Load

references/game-feel.md

before feel/juice/impact tuning, or before claiming gameplay is premium or polished. Track every loaded reference in a reference ledger with yes/no, path, and failure reason. Do not mark the gameplay phase complete while a required reference is skipped.

Load

references/checklists/new-game-definition-of-done.md

before claiming a new game or first playable slice is complete.

Load

references/checklists/game-design-level-design.md

before claiming a new game, major gameplay upgrade, level/encounter pass, premium gameplay, or polished gameplay is complete.

Load

references/checklists/game-feel.md

before claiming feel/impact tuning or premium gameplay is complete.

Load

references/checklists/endless-runner-premium-quality.md

for endless runner work.

Load

references/prompt-templates.md

only when the user asks for reusable prompts, starter prompts, or a task template.

Load

threejs-audio-generator

when implementing real SFX, ambience, UI sounds, voice/TTS, or audio cleanup beyond simple placeholder hooks. Gameplay code should emit audio events; the audio skill should generate or process the actual assets and define the runtime audio matrix.

Inspect project structure, scripts, dependencies, current loop, input, camera, entities, state, UI, and diagnostics.
Write the compact game design brief: player promise, target feeling, primary verb, objective, pressure, reward, fail/retry, skill expression, non-goals.
Define the core loop contract: verb, objective, pressure, reward/progression, fail/retry.
Define the level/encounter plan before implementation: start, first decision, first threat, first reward, landmarks, escalation, recovery beats, readability, and tuning knobs.
Choose small architecture boundaries:
```
core
```
,
```
game
```
,
```
entities
```
,
```
systems
```
,
```
assets
```
,
```
ui
```
,
```
tests
```
.
Implement mechanics in playable increments: input, state, entity, collision/physics, feedback, HUD/audio hook, diagnostics.
Tune feel with
```
references/game-feel.md
```
: movement, acceleration, camera follow/FOV/shake, hitstop, impact feedback, cooldowns, difficulty, restart loop.
Keep hot paths allocation-light and update order explicit.
Verify with build, browser, screenshot, canvas pixels, console/page errors, and one real input path.

当任务包含首个可玩版本搭建、架构设计、机制开发、实体创建、输入控制、相机配置、碰撞/物理系统、计分机制、目标设定、反馈效果或手感调校时，第一步需加载

references/gameplay-workflows.md

。

在进行全新游戏创建、重大玩法变更、关卡/竞技场/赛道/波次/洞穴/谜题设计、战斗/遭遇战设计、进度/难度调整工作，或声称玩法达到优质、 polished（打磨完成）、完整或非通用水平前，需加载

references/game-design-level-design.md

。

在添加或更改物理系统、碰撞密集型玩法、载具移动、滚动球体、迷你高尔夫、台球/斯诺克、弹珠台、刚体谜题、角色控制器、传感器、高速投射物、移动平台或物理QA测试前，需加载

references/physics-engine-selection.md

。

在进行手感/质感/冲击调校，或声称玩法达到优质或polished水平前，需加载

references/game-feel.md

。将所有加载的参考文档记录在参考台账中，包含是否加载成功、路径及失败原因。若跳过必需的参考文档，不得标记玩法阶段完成。

在声称新游戏或首个可玩版本完成前，需加载

references/checklists/new-game-definition-of-done.md

。

在声称新游戏、重大玩法升级、关卡/遭遇战优化、优质玩法或polished玩法完成前，需加载

references/checklists/game-design-level-design.md

。

在声称手感/冲击调校或优质玩法完成前，需加载

references/checklists/game-feel.md

。

进行无尽跑酷类游戏开发时，需加载

references/checklists/endless-runner-premium-quality.md

。

仅当用户要求可复用提示词、初始提示词或任务模板时，才可加载

references/prompt-templates.md

。

在实现真实音效、环境音、UI音效、语音/TTS，或进行超出简单占位钩子的音频清理工作时，需加载

threejs-audio-generator

。游戏玩法代码应触发音频事件；音频技能负责生成或处理实际资产，并定义运行时音频矩阵。

检查项目结构、脚本、依赖项、当前循环、输入控制、相机、实体、状态、UI及诊断信息。
撰写简洁的游戏设计brief：玩家承诺、目标感受、核心动作、目标、压力、奖励、失败/重试机制、技能表现、非目标内容。
定义核心循环约定：核心动作、目标、压力、奖励/进度、失败/重试。
在实现前定义关卡/遭遇战规划：起点、首个决策点、首个威胁、首个奖励、地标、难度升级、恢复节点、可读性及调校参数。
选择小型架构边界：
```
core
```
、
```
game
```
、
```
entities
```
、
```
systems
```
、
```
assets
```
、
```
ui
```
、
```
tests
```
。
分可玩增量实现机制：输入控制、状态、实体、碰撞/物理系统、反馈效果、HUD/音频钩子、诊断功能。
借助
```
references/game-feel.md
```
调校手感：移动、加速度、相机跟随/视野/震动、hitstop、冲击反馈、冷却时间、难度、重启循环。
确保热路径内存分配轻量化，更新顺序明确。
通过构建、浏览器测试、截图、画布像素检查、控制台/页面错误排查及真实输入路径测试进行验证。

Packaged Scaffold

打包脚手架

Use the bundled scaffold when starting a new project or when the user asks for a starter game:

bash

python3 <this-skill-dir>/scripts/create_threejs_game.py ./my-game

The script copies

assets/threejs-vite-game/

, rewrites the project name in

package.json

and

package-lock.json

, and keeps generated games self-contained with their own visual test and canvas-inspection script. Use

--force

only when the target directory may be overwritten.

启动新项目或用户要求初始游戏框架时，使用捆绑的脚手架：

bash

python3 <this-skill-dir>/scripts/create_threejs_game.py ./my-game

该脚本会复制

assets/threejs-vite-game/

，重写

package.json

和

package-lock.json

中的项目名称，确保生成的游戏独立且包含自身的视觉测试和画布检查脚本。仅当目标目录可能被覆盖时使用

--force

参数。

Library Guidance

库使用指南

Use TypeScript, Vite, Three.js modules.
Physics/collision engine choice (custom collision vs Rapier vs cannon-es), timestep, and collider strategy: follow
```
references/physics-engine-selection.md
```
.
```
lil-gui
```
for live-tuned constants when useful.
Web Audio for runtime playback and procedural feedback;
```
threejs-audio-generator
```
for generated game audio assets.

使用TypeScript、Vite、Three.js模块。
物理/碰撞引擎选择（自定义碰撞、Rapier或cannon-es）、时间步长及碰撞体策略：遵循
```
references/physics-engine-selection.md
```
。
必要时使用
```
lil-gui
```
进行实时参数调校。
使用Web Audio进行运行时播放和程序化反馈；使用
```
threejs-audio-generator
```
生成游戏音频资产。

Common Failure Modes

常见失败模式

Static demo instead of playable loop.
Static scene with mechanics bolted on after the fact, instead of a design brief plus level/encounter plan driving implementation.
Core loop is described but not proven through real input, pressure, reward/progression, and fail/retry.
Level/track/arena/map is decorative and does not shape player decisions.
Mechanic compiles but cannot be triggered by real input.
Camera/controls feel delayed or hide the next decision.
State changes do not drive UI/audio/VFX.
Architecture abstractions appear before mechanics need them.

仅为静态演示而非可玩循环。
先构建静态场景再附加机制，而非以设计brief和关卡/遭遇战规划驱动实现。
仅描述核心循环，但未通过真实输入、压力、奖励/进度及失败/重试机制验证。
关卡/赛道/竞技场/地图仅作装饰，未引导玩家决策。
机制可编译但无法通过真实输入触发。
相机/操控延迟或隐藏下一个决策点。
状态变更未驱动UI/音频/视觉特效。
在机制需要前过早引入架构抽象。

Final Response

最终输出

Report the reference ledger, game design brief, core loop contract, level/encounter plan, gameplay checklist outcome, behavior, controls, changed files, architecture choices, tuned values, verification evidence, artifacts, and remaining edge cases.

汇报参考台账、游戏设计brief、核心循环约定、关卡/遭遇战规划、玩法检查清单结果、行为表现、操控方式、修改的文件、架构选择、调校参数、验证证据、产出物及剩余边缘案例。