mcpField
T
threejs-gameplay-systems

threejs-gameplay-systems

github.com/majidmanzarpour开发2.6k3.4k 次安装4 周前更新
代码仓库

关于 threejs-gameplay-systems

面向 Three.js 浏览器游戏开发的技能，指导构建可玩的游戏循环、响应式控制和明确的更新顺序。它还提供设计、物理选择、手感调优及测试脚手架方面的指导。

主要功能

  1. 01规划核心循环与关卡
  2. 02分阶段构建可玩机制
  3. 03明确系统边界和更新顺序
  4. 04使用种子随机数支持确定性测试
  5. 05调节控制、镜头与反馈

适用场景

  1. 01从脚手架创建 Three.js 游戏
  2. 02为现有游戏增加或调整机制
  3. 03设计关卡、遭遇和难度曲线
  4. 04处理碰撞、车辆或角色物理

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/majidmanzarpour/threejs-game-skills --skill threejs-gameplay-systems

安装后在 Claude Code 中输入/threejs-gameplay-systems确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

agents/
openai.yaml
assets/threejs-vite-game/
.gitignore
index.html
package-lock.json
package.json
playwright.config.ts
tsconfig.json
vite.config.ts
assets/threejs-vite-game/scripts/
inspect-threejs-canvas.mjs
assets/threejs-vite-game/src/
main.ts
styles.css
vite-env.d.ts
assets/threejs-vite-game/src/core/
InputController.ts
Loop.ts
Renderer.ts
assets/threejs-vite-game/src/entities/
Pickup.ts
Player.ts
assets/threejs-vite-game/src/game/
Game.ts
assets/threejs-vite-game/src/systems/
AudioSystem.ts
CameraRig.ts
CollisionSystem.ts
DebugTools.ts
Hud.ts
assets/threejs-vite-game/src/utils/
dispose.ts
random.ts
assets/threejs-vite-game/tests/
bot-playtest.template.ts
visual-regression.template.ts
visual.spec.ts
references/
game-feel.md
genre-design.md

详细介绍

Three.js 游戏系统

创建或改进可游玩的浏览器游戏循环，明确职责归属，提供响应灵敏的控制、确定性的更新顺序，以及能够影响玩家决策的空间。

从实际加载的技能文件解析 <this-skill-dir> 和本地引用；使用运行器发现的替代项之前，先解析同级技能。

参考资料

文件何时阅读
references/game-feel.md调整手感、反馈效果、冲击感、受击停顿、屏幕震动，或声称游戏玩法经过精心打磨时
references/genre-design.md设计关卡、竞技场、赛道、波次、洞穴、谜题、遭遇战或难度曲线时
references/physics-engine-selection.md添加或更改物理、碰撞密集型玩法、载具、滚动球、角色控制器、传感器、移动平台时

从这里开始

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

复制 assets/threejs-vite-game/，重写项目名称，并为游戏提供专属的视觉测试和画布检查器。--force 会将文件复制到非空目录，覆盖与脚手架文件冲突的文件，并保留其他所有文件。

先设计

对于广泛的游戏创建或重大设计变更，请编写三个简短文档，或更新现有文档。范围较小的机制修复应沿用现有设计，并保留无关系统：

设计简介。 玩家承诺（一句话描述幻想）· 目标感受 · 主要动词 · 次要动词 · 玩家每 5–30 秒重复做什么 · 1–5 分钟内会发生什么变化 · 玩家如何失败、学习并重新开始 · 什么会获得奖励，什么会带来风险 · 更优秀的玩家会采取哪些不同做法 · 如何传达下一个决策 · 本阶段不包含的内容。

核心循环约定。 玩家执行[动词]以实现[目标]，同时[压力]带来风险；成功获得[奖励]，失败导致[代价/重试]。 随后在代码中验证每个部分：动词对应实际输入，目标在游戏世界或 HUD 中可见，首个可玩分钟内就存在压力，奖励会改变状态而不只是视觉效果，失败能让玩家明白发生了什么，重启足够迅速，能够吸引玩家再次尝试。

关卡或遭遇计划。 空间布局 · 摄像机能看到和看不到的内容 · 玩家起点、第一个决策、第一个威胁、第一个奖励 · 地标 · 挑战如何每 20–60 秒或每波次/洞穴/圈数逐步升级 · 恢复节奏 · 如何预示危险 · 哪些部分采用模块化或参数化设计。

“探索一个很酷的场景”不是设计简介。简介必须包含决策、压力、反馈和后果。

构建

  1. 检查现有结构、脚本、依赖项、循环、输入、摄像机、实体、状态、UI 和诊断工具。
  2. 保持小而清晰的职责边界：core、game、entities、systems、assets、ui、tests。
  3. 分阶段实现并保持可玩——输入、状态、实体、碰撞、反馈、HUD 和音频钩子、诊断工具——确保每一步都有可玩的内容。 在扩展内容之前，先按预期的摄像机尺度，使用实际的主角和反馈，搭建一个有代表性的遭遇场景。敌人、奖励和道具的多样性应服务于游戏类型所需的决策，而非满足通用的资源配额。
  4. 调整手感：移动、加速、摄像机跟随和视野角、受击停顿、冲击反馈、冷却时间、难度、重启。
  5. 保持热路径的分配开销较低，并明确更新顺序。
  6. 通过脚手架提供的带种子 RNG 处理所有游戏随机性，以确保确定性测试钩子继续正常工作。

协同开发时，先定义输入意图、实体/资源接口和事件，再分派相互独立的模块。向负责人汇报行为变更和本地检查结果，由负责人负责整合后的浏览器测试。用户更改需求时，更新现有简介和待办任务，而不是重新开始已完成的工作。

游戏玩法代码负责发出音频事件；threejs-audio-generator 负责生成实际资源和运行时音频矩阵。

技术栈

TypeScript、Vite、Three.js 模块、three/addons/... 中的官方控制器、加载器和后期处理功能。使用 lil-gui 实时调整常量。使用 Web Audio 进行运行时播放。物理引擎的选择、时间步长和碰撞体策略遵循 references/physics-engine-selection.md——当游戏需要真实模拟时，默认使用 Rapier。

常见问题

静态演示，而不是可玩的循环 · 在先搭建好的场景上生硬地添加机制 · 描述了核心循环，却从未通过真实输入、压力、奖励和失败／重试进行验证 · 赛道或竞技场只起装饰作用，而不影响决策 · 机制虽能编译，却没有任何输入可以触发 · 摄像机和控制响应滞后或遮挡下一个决策 · 状态变化未传递到 UI、音频或 VFX · 在任何机制需要之前就构建抽象层。

报告

说明行为和控制方式、规模较大的构建所需的三个设计产物、架构选择和调优后的数值、已修改的文件，以及实际游玩时的观察结果。如果涉及物理，请注明物理引擎、时间步长和碰撞体策略。

评论

支持 Markdown