majidmanzarpour/threejs-game-skills

# Three.js 游戏技能 用于构建可玩、精制 Three.js 浏览器游戏的独立 Codex 和 Claude Code 技能。安装这些技能后，要求你的 agent 使用 `threejs-game-director`；该主导者将处理游戏玩法、图形、UI、资产生成、音频、调试和发布验证，无需用户手动逐一选择各个专家技能。 该包包含了 agent 所需的运行时素材：`SKILL.md` 文件、参考、清单、prompt 模板、辅助脚本，以及打包在相关技能文件夹中的 Vite + TypeScript + Three.js 脚手架。生成的游戏附带确定性测试钩子、带有种子的 RNG，以及用于冒烟测试、视觉回归基准和机器人试玩的 Playwright 模板，以便 agent 能够端到端地验证其工作。 由 [Majid Manzarpour](https://x.com/majidmanzarpour) 创建。 ## 演示 | 游戏 | 视频 | 试玩 | | --- | --- | --- | | Neon Ridge Drift | [在 X 上观看](https://x.com/majidmanzarpour/status/2064565389036540327) | [ridgedrift.netlify.app](https://ridgedrift.netlify.app) | | Championship Snooker Arena | [在 X 上观看](https://x.com/majidmanzarpour/status/2064673249129071096) | [snookerarena.netlify.app](https://snookerarena.netlify.app) | | Starship Dogfight | [在 X 上观看](https://x.com/majidmanzarpour/status/2065065340510281888) | [starshipdogfight.netlify.app](https://starshipdogfight.netlify.app) | | Tide Singer | [在 X 上观看](https://x.com/majidmanzarpour/status/2065570428723007555) | [tidesinger.netlify.app](https://tidesinger.netlify.app) | | Ripcore | [在 X 上观看](https://x.com/majidmanzarpour/status/2066687620709544070) | [ripcore.netlify.app](https://ripcore.netlify.app) | ## 安装 为 Codex 安装所有技能： ``` npx skills add majidmanzarpour/threejs-game-skills --skill '*' -a codex -g -y ``` 为 Claude Code 安装所有技能： ``` npx skills add majidmanzarpour/threejs-game-skills --skill '*' -a claude-code -g -y ``` 如果你安装的 `skills` CLI 不支持其中某个目标，请改为从克隆的代码库中执行安装：使用 `./install.sh --codex` 为 Codex 安装，使用 `./install.sh --claude` 为 Claude Code 安装，或使用 `./install.sh --all` 同时为两者安装。 用于从克隆的代码库进行本地开发： ``` ./install.sh --codex ./install.sh --claude ./install.sh --all ``` 本地安装程序会将 `skills/` 复制到选定的 agent 技能目录中。除非你传递 `--force` 参数，否则它将跳过同名的技能；除非明确要求使用 `--prune-managed`，否则它绝不会移除不相关的用户技能。 ``` ./install.sh --codex --force ``` ## 使用技能 安装后，在空项目文件夹或你想要改进的现有 Three.js 游戏中打开 Codex 或 Claude Code。然后使用你期望的结果提示 agent 并指明主导者技能： ``` Use threejs-game-director to build a premium futuristic tower defense game from scratch. Automatically use the relevant gameplay, graphics, UI, asset generation, audio, debug, and QA skills. Build a playable loop first, then iterate until it passes browser, mobile, visual, UI, performance, and release checks. ``` 这两个运行器都共享相同的 `SKILL.md` 文件，并且一旦安装完毕就会自动发现这些技能；上面的 prompt 在两者中均可工作： - **Claude Code** 从 `~/.claude/skills` 读取技能，并根据每个 `SKILL.md` 描述进行路由。使用 `/threejs-game-director` 调用主导者，或者只需在 prompt 中指明它——它会自动加载同级技能。 - **Codex** 从 `~/.codex/skills` 读取技能，每个技能的 `agents/openai.yaml` 提供了其显示名称和默认的启动 prompt。在你的 prompt 中指明主导者，它会以相同的方式引入专家技能。 该 agent 应该： - 在进行广泛的游戏工作时，首先加载 `threejs-game-director`。 - 当请求需要时，加载用于游戏系统、AAA 级图形、UI、调试/分析、QA/发布、3D 生成、图像生成和音频生成的同级技能。 - 当从空文件夹开始时，在内部使用打包好的脚手架。 - 在你的项目中创建或更新游戏代码。 - 在宣布完成之前，运行构建、浏览器检查、截图、canvas 像素检查、移动端视口检查和 QA 门控。 - 为高级工作报告技能加载账本、参考账本、资产/音频来源决策、视觉评分卡以及剩余风险。 用户通常不需要直接运行脚手架或 QA 辅助脚本。这些脚本已经打包，以便技能可以将它们作为工作流的一部分来使用。 ## 可选的 API 密钥 核心的 Three.js 技能无需付费的 API 密钥即可工作。当缺少密钥时，主导者应报告凭据探测输出，跳过外部生成，并回退到程序化/本地资产。仅当你希望 agent 生成外部模型、图像或音频时才添加密钥。 切勿提交 API 密钥或将其放在浏览器端的游戏代码中。这些技能使用来自本地 agent 工具的提供商 API，然后将生成的资产保存到你的游戏项目中。 | 提供商 | 技能 | 环境变量 | 用途 | 密钥设置 | | --- | --- | --- | --- | --- | | Tripo API | `threejs-3d-generator` | `TRIPO_API_KEY` | 文本/图像/多视图转 3D、可直接用于游戏的 GLB/FBX 主角模型、车辆、道具、建筑物、武器、纹理、绑定、动画、风格化、网格转换、后处理。 | [Tripo 快速入门](https://platform.tripo3d.ai/docs/quick-start) 和 [Tripo API 概览](https://www.tripo3d.ai/api)。 | | Gemini image API | `threejs-image-generator` | `GEMINI_API_KEY` | 概念图、图生 3D 源图像、纹理参考、贴花、天空、背景、图标、Logo、GUI 美术、标题/菜单美术。 | [Gemini API 密钥文档](https://ai.google.dev/gemini-api/docs/api-key) 和 [Google AI Studio 密钥](https://aistudio.google.com/app/apikey)。 | | ElevenLabs API | `threejs-audio-generator` | `ELEVENLABS_API_KEY` | SFX、环境音循环、UI 声音、播音员台词、对话 TTS、语音转换、音频清理、游戏音频清单。 | [ElevenLabs 快速入门](https://elevenlabs.io/docs/eleven-api/quickstart) 和 [API 身份验证](https://elevenlabs.io/docs/api-reference/authentication)。 | 在你的 shell 配置文件中设置密钥，然后重启终端。 使用 `zsh` 或 `bash` 的 macOS/Linux： ``` export TRIPO_API_KEY="..." export GEMINI_API_KEY="..." export ELEVENLABS_API_KEY="..." ``` 对于 `zsh`，请将这些行放在 `~/.zshrc` 或 `~/.zprofile` 中。对于 `bash`，请将它们放在 `~/.bashrc` 或 `~/.bash_profile` 中。 Windows PowerShell，仅限当前终端会话： ``` $env:TRIPO_API_KEY = "..." $env:GEMINI_API_KEY = "..." $env:ELEVENLABS_API_KEY = "..." ``` Windows PowerShell，对你的用户账号永久生效： ``` [Environment]::SetEnvironmentVariable("TRIPO_API_KEY", "...", "User") [Environment]::SetEnvironmentVariable("GEMINI_API_KEY", "...", "User") [Environment]::SetEnvironmentVariable("ELEVENLABS_API_KEY", "...", "User") ``` 设置永久的 Windows 变量后，请重启你的终端、Codex 或 Claude Code，以便 agent 进程能够看到新的环境。 主导者技能包含一个凭据探测器，在确定某个密钥缺失之前，它会先加载常见的 shell 配置文件。在你安装技能的任何位置运行它： ``` # Claude Code bash ~/.claude/skills/threejs-game-director/scripts/probe_asset_credentials.sh # Codex bash ~/.codex/skills/threejs-game-director/scripts/probe_asset_credentials.sh ``` 它会打印 `TRIPO_API_KEY=SET|MISSING`（Gemini 和 ElevenLabs 同理），但绝不会打印密钥的具体值。 提供商说明： - Tripo 是可选的，但对于仅靠程序化代码很少能做到高级的高价值 3D 表面非常有用：主角车辆、boss、武器、建筑物、生物、道具以及带有纹理的 GLB/FBX 资产。 - Gemini 图像生成是可选的，但在进行 Tripo 图生 3D 之前以及用于获取高质量纹理、天空、图标、Logo、贴花和 GUI 源素材时非常有用。 - ElevenLabs 是可选的，但对于通过交互式 SFX、环境音、UI 反馈、语音和清理让游戏感觉更完整非常有用。 - Google 也支持 `GOOGLE_API_KEY`，但这些技能为了清晰起见统一使用 `GEMINI_API_KEY`。 - 尽可能使用提供商侧的密钥限制和配额。ElevenLabs 记录了 endpoint 作用域、信用配额和密钥处理方式；Google 推荐使用环境变量，并正在将 Gemini 用户迁移至使用身份验证密钥。 ## 最佳切入点 - 对于完整的游戏、重大升级、高级打磨、可发布的工作或任何广泛的任务，请使用 `threejs-game-director`。 - 对于机制、架构、输入、镜头、物理、计分、目标和游戏手感，请使用 `threejs-gameplay-systems`。 - 当截图看起来很基础或游戏需要更强的模型、材质、光照、VFX、世界细节或渲染打磨时，请使用 `threejs-aaa-graphics-builder`。 - 对于 HUD、菜单、叠加层、响应式布局、安全区域、图标、触摸控件和文本适配，请使用 `threejs-game-ui-designer`。 - 对于黑屏、运行时错误、加载问题、缩放/移动端 bug、性能、draw call、三角形、纹理和内存，请使用 `threejs-debug-profiler`。 - 对于生产构建、浏览器验证、截图、canvas 像素、移动端检查、发布风险报告和静态托管就绪情况，请使用 `threejs-qa-release`。 - 对于 Tripo API 文本/图像转 3D 模型、纹理、绑定、动画、转换和 GLB/FBX 游戏资产，请使用 `threejs-3d-generator`。 - 对于 Gemini 生成的概念图、图生 3D 输入、纹理、贴花、天空、背景、图标、Logo、GUI 美术和标题/菜单美术，请使用 `threejs-image-generator`。 - 对于 ElevenLabs SFX、环境音、UI 声音、语音/TTS、语音转换、清理和 Three.js 音频集成，请使用 `threejs-audio-generator`。 对于大多数面向用户的游戏请求，请从 `threejs-game-director` 开始，让它自动引入专家技能。 ## 良好的使用示例 对于新游戏： ``` Use threejs-game-director to create a AAA-inspired hover racing game from scratch. Make it playable, add premium track visuals, vehicle feel, HUD, SFX hooks, desktop and mobile controls, and run the full verification pass before reporting done. ``` 对于视觉升级： ``` Use threejs-game-director to upgrade this Three.js game from prototype visuals to premium browser-game quality. Use the AAA graphics, UI, image, 3D, audio, debug, and QA skills as needed. Include the visual scorecard and evidence from active-play screenshots. ``` 对于已经损坏的游戏： ``` Use threejs-game-director to debug and finish this Three.js game. First get it running, then improve gameplay feel, UI, graphics, performance, and release verification until the remaining risks are explicit. ``` 对于包含大量资产的游戏： ``` Use threejs-game-director to build a premium space dogfight game. Use threejs-image-generator for concepts, skies, decals, icons, and GUI art; use threejs-3d-generator for hero ships and weapons when credentials are available; use threejs-audio-generator for SFX and ambience. If generation is blocked, report the credential probe output and fallback plan. ``` ## 预期证据 对于有意义的 Three.js 工作，技能在宣布成功之前应该收集证据： - `npm run build` - 本地浏览器运行 - 浏览器控制台和页面错误检查 - Playwright 截图 - canvas 非空白像素检查，以及检查器测量的指标（颜色熵、边缘密度、亮度对比度、渲染预算行） - 桌面端和移动端视口通过 - 主控制路径的交互检查 - 用于广泛游戏创建的游戏设计简报、核心循环契约和关卡/遭遇战计划 - 当图形、资产、shader 或后处理发生更改时的性能快照 - 当高级图形发生更改时，技术美术预算的目标与实际情况对比 - 当 UI 发生更改时，UI 文本适配、重叠、安全区域和触摸目标检查 - 带有测量证据和全新视角审查的视觉评分卡，用于高级、AAA、展示或更高要求的声明 - 用于可发布的视觉 QA 的视觉测试框架决策（添加/扩展/跳过的截图基准） - 用于可发布游戏玩法声明的机器人试玩指标 - 当生成的资产或音频在范围内时的外部资产/音频来源账本 高级/AAA 声明不应依赖于静态场景、占位符立方体、通用的属性卡 HUD 或未经核实的截图。游戏应该具有活跃的可玩循环和填写完整的视觉评分卡。 ## 技能系统 - `threejs-game-director`：用于完整游戏构建和编排的主入口——运行器能力检查、技能路径阶梯、阶段剧本、账本、报告审计。 - `threejs-gameplay-systems`：可玩循环、架构、游戏设计和关卡设计、机制、实体、控制、镜头、物理选择和游戏手感（卡帧、屏幕震动、缓动、打击反馈）。 - `threejs-aaa-graphics-builder`：带有校准锚点的视觉评分卡、技术美术预算、shader/材质指南、资产架构、模型、材质、VFX、渲染打磨。 - `threejs-game-ui-designer`：HUD、菜单、叠加层、响应式 UI、图标、安全区域、UI 状态。 - `threejs-debug-profiler`：场景/运行时/渲染 bug、移动端 bug、性能分析、渲染器指标。 - `threejs-qa-release`：浏览器 QA、截图、带有测量指标的 canvas 像素检查、视觉测试框架、机器人试玩、响应式检查、生产构建、发布风险报告。 - `threejs-3d-generator`：Tripo API 文本/图像转 3D、纹理、自动绑定、动画、转换、下载和 Three.js 导入指南。 - `threejs-image-generator`：用于概念图、纹理、贴花、天空、图标、GUI 美术和图生 3D 输入的 Gemini 图像生成。 - `threejs-audio-generator`：基于 ElevenLabs 的 SFX、环境音、UI 声音、语音/TTS、语音转换、清理和 Three.js 音频集成。 ## 打包资源 安装的技能是独立的。它们不依赖于根目录文档、根目录脚手架、根目录 prompt 或根目录清单。 - `skills/`完整的公开包。每个技能都拥有其所需的 `SKILL.md`、`references/`、`scripts/` 和 `assets/`。 - `skills/threejs-gameplay-systems/assets/threejs-vite-game/`：从空项目开始时由技能使用的打包游戏脚手架。附带确定性测试钩子（`__THREE_GAME_TEST_HOOKS__`）、带种子的 RNG，以及用于冒烟测试、视觉回归基准和机器人试玩的 `tests/` 模板。 - `skills/threejs-qa-release/scripts/inspect-threejs-canvas.mjs`：打包的浏览器/canvas 检查助手——报告非空白像素、测量的视觉指标（颜色熵、边缘密度、亮度对比度）和渲染预算行；`--state`/`--seed` 驱动测试钩子以实现基于状态的确定性捕获。 - `skills/threejs-aaa-graphics-builder/assets/scorecard-anchors/`：用于视觉评分卡的校准参考截图。 - `scripts/`：供维护者使用的本地验证助手。 - `install.sh`：用于处理此代码库检出的本地安装程序。 ## 维护者检查 验证此工作流代码库： ``` npm install npm run check:scripts npm run validate:skills ``` 维护者在测试技能包时可以直接运行打包的助手，但普通用户应通过 agent prompt 进行交互： ``` python3 skills/threejs-gameplay-systems/scripts/create_threejs_game.py ../my-threejs-game node skills/threejs-qa-release/scripts/inspect-threejs-canvas.mjs --url http://127.0.0.1:5188 --mobile node skills/threejs-qa-release/scripts/inspect-threejs-canvas.mjs --url http://127.0.0.1:5188 --state active-play --seed 12345 ``` ## 许可证 MIT。详见 [LICENSE](LICENSE)。

标签：Three.js, TypeScript, 前端脚手架, 安全插件, 游戏开发, 特征检测