Back to Details

threejs-game-generator-skill

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Three.js Game Generator

Three.js 游戏生成器

Turn a game brief or an unfinished Three.js scene into a small, complete browser game. Lead with one satisfying playable loop, make the direction original, work in the user's existing stack, and verify the result in a real browser.
将游戏设计简报或未完成的 Three.js 场景转化为小型、完整的浏览器游戏。以一个令人满意且可实际游玩的游戏循环为核心，确保方向原创，适配用户现有技术栈，并在真实浏览器中验证结果。

Choose the operating mode

选择运行模式

  • New game: create the smallest maintainable project that fits the request. Default to Three.js with Vite when no stack exists.
  • Existing game: preserve the package manager, architecture, routes, assets, controls, and working systems. Change only what the requested outcome needs.
  • Scene-to-game: keep the useful scene, then add an explicit goal, player verbs, feedback, failure or completion, restart, and progression.
  • Polish pass: profile and play the current build before changing it. Fix broken feedback, camera, controls, pacing, performance, and state transitions in that order.
Do not publish, buy assets, call paid services, or mutate external systems unless the user explicitly asks.
  • **新游戏：**创建符合请求且尽可能小、易于维护的项目。技术栈尚未确定时，默认使用 Three.js 与 Vite。
  • **现有游戏：**保留包管理器、架构、路由、资源、控制方式和正常工作的系统。仅修改实现请求结果所必需的部分。
  • **场景转游戏：**保留有用的场景，然后添加明确目标、玩家动作、反馈、失败或完成条件、重启和进度推进。
  • **优化打磨：**修改前先对当前构建进行性能分析并试玩。按顺序修复反馈、摄像机、控制、节奏、性能和状态转换问题。
除非用户明确要求，否则不要发布内容、购买资源、调用付费服务或更改外部系统。

Establish the game contract

建立游戏契约

Infer what is missing when the brief is loose, but do not silently expand a prototype into a large production.
Write a compact contract before implementation:
  1. Fantasy: what the player should feel they are doing.
  2. Core loop: the repeatable action, response, reward, and escalation.
  3. Win, loss, or completion: how a run ends and how the player restarts.
  4. Camera and controls: perspective, movement model, input devices, and touch behavior.
  5. Visual thesis: one recognizable art direction tied to the mechanic.
  6. Scope: the smallest content set that proves the loop, plus explicitly deferred features.
When the user names an existing title, borrow only high-level interaction ideas. Create original characters, environments, layouts, UI, names, audio, and art.
需求简报宽泛时，可以推断缺失内容，但不要在未说明的情况下将原型扩展为大型生产项目。
实现前编写一份简明的游戏契约：
  1. **幻想体验：**玩家应感觉自己正在做什么。
  2. **核心循环：**可重复的动作、响应、奖励和升级。
  3. **胜利、失败或完成：**一局游戏如何结束，以及玩家如何重启。
  4. **摄像机和控制：**视角、移动模型、输入设备及触控行为。
  5. **视觉主题：**一种与机制相呼应、易于识别的美术方向。
  6. **范围：**能够证明核心循环的最小内容集，以及明确延后的功能。
当用户指定现有作品名称时，仅借鉴高层交互理念。角色、环境、布局、UI、名称、音频和美术均应原创。

Read references selectively

有选择地阅读参考资料

  • Read engine-patterns.md when setting up or changing the game loop, renderer, controls, camera, collisions, loading, persistence, object lifetime, or performance.
  • Read visuals.md when choosing lighting, materials, procedural geometry, asset style, atmosphere, UI treatment, shadows, or quality tiers.
  • Read audio-recipes.md when the game needs music, feedback sounds, spatial audio, user-gesture activation, or mixing.
  • Read genres.md when the brief needs a viable mechanic set, camera/control mapping, content budget, or genre-specific risk check.
Do not load every reference by default.
  • 设置或更改游戏循环、渲染器、控制、摄像机、碰撞、加载、持久化、对象生命周期或性能时，阅读 engine-patterns.md。
  • 选择照明、材质、程序化几何体、资源风格、氛围、UI 风格、阴影或画质档位时，阅读 visuals.md。
  • 游戏需要音乐、反馈音效、空间音频、用户手势激活或混音时，阅读 audio-recipes.md。
  • 简报需要可行的机制组合、摄像机与控制映射、内容预算或类型专属风险检查时，阅读 genres.md。
默认不要加载所有参考资料。

Workflow

工作流

1. Inspect the workspace

1. 检查工作区

Identify:
  • package manager, scripts, entry points, Three.js version, addons, and build tool;
  • current scene graph, renderer, cameras, input, state management, physics, assets, UI, and audio;
  • the production build command and any existing tests;
  • local modifications that must be preserved.
Run the current project when possible. Record visible failures and browser console errors before editing. Do not replace a functioning project merely to use a preferred scaffold.
确定：
  • 包管理器、脚本、入口点、Three.js 版本、addons 和构建工具；
  • 当前场景图、渲染器、摄像机、输入、状态管理、物理、资源、UI 和音频；
  • 生产构建命令和现有测试；
  • 必须保留的本地修改。
尽可能运行当前项目。编辑前记录可见故障和浏览器控制台错误。不要仅仅为了使用偏好的脚手架而替换可正常工作的项目。

2. Prove a vertical slice

2. 验证垂直切片

Build the smallest complete loop before adding breadth:
  • one controllable player or primary interaction;
  • one objective and one meaningful obstacle;
  • visible feedback for success, damage, collection, or progress;
  • start, active, paused, completed/failed, and restart states;
  • a 30–180 second play session that demonstrates the intended feel.
Use graybox geometry until scale, movement, camera, and pacing work. A beautiful scene without a finishable loop is not a game.
先构建最小完整循环，再扩展内容：
  • 一个可控玩家或主要交互；
  • 一个目标和一个有意义的障碍；
  • 对成功、受伤、收集或进度的可见反馈；
  • 开始、进行中、暂停、完成或失败以及重启状态；
  • 一段 30–180 秒、能够展示预期手感的游玩过程。
在比例、运动、摄像机和节奏调整妥当前，使用 graybox 几何体。没有可完成循环的精美场景不能算作游戏。

3. Build stable foundations

3. 构建稳定的基础

Use the project patterns in engine-patterns.md. Keep these invariants:
  • one renderer and one authoritative animation loop;
  • frame-rate-independent movement with a capped delta, or a fixed simulation step when determinism matters;
  • explicit game states rather than scattered booleans;
  • input sampled into actions so keyboard, pointer, gamepad, and touch can share game logic;
  • world units and coordinate conventions chosen once and used consistently;
  • capped device pixel ratio and a resize path that updates renderer and camera;
  • reusable geometry/materials and intentional disposal of GPU resources;
  • HTML UI for readable menus, settings, and HUD unless 3D placement is essential;
  • asset loading with progress and failure states;
  • no secrets in client code.
Add a physics engine only when the mechanic genuinely needs rigid-body simulation. Use simple spheres, boxes, capsules, raycasts, or spatial partitioning for arcade movement when they are sufficient.
采用 engine-patterns.md 中的项目模式。保持以下不变原则：
  • 使用一个渲染器和一个权威动画循环；
  • 运动应与帧率无关，并限制 delta 上限；需要确定性时则使用固定模拟步长；
  • 使用显式游戏状态，而不是分散的布尔值；
  • 将输入采样为动作，让键盘、指针、手柄和触控输入共用同一套游戏逻辑；
  • 统一选定世界单位和坐标约定，并始终一致地使用；
  • 限制 device pixel ratio，并提供可更新渲染器和摄像机的 resize 路径；
  • 复用几何体和材质，并有意识地释放 GPU 资源；
  • 除非必须使用 3D 布局，否则使用 HTML UI 呈现易读的菜单、设置和 HUD；
  • 资源加载应包含进度和失败状态；
  • 客户端代码中不得包含机密信息。
仅当机制确实需要刚体模拟时，才添加物理引擎。街机式移动已经足够时，可使用简单的球体、盒体、胶囊体、raycast 检测或空间分区。

4. Implement the feel

4. 实现手感

Tune input, movement, camera, and feedback together:
  • controls should respond immediately and remain predictable at low and high frame rates;
  • camera follow should use damping and bounded look-ahead rather than raw player transforms;
  • collisions should produce readable consequences, not silent blocking;
  • actions need anticipation, impact, and recovery appropriate to the genre;
  • screen shake, hit pause, particles, trails, and post-processing must remain restrained and disable cleanly for reduced motion or lower quality;
  • touch targets and virtual controls must fit the actual viewport and not cover critical play space.
Add secondary systems only after the core loop is enjoyable.
协同调整输入、运动、摄像机和反馈：
  • 控制应立即响应，并在低帧率和高帧率下保持可预测性；
  • 摄像机跟随应使用阻尼和受限的前瞻，而不是直接采用玩家 transform；
  • 碰撞应产生易读的后果，而不是无声地阻止移动；
  • 动作应具备与类型相符的预备、冲击和恢复阶段；
  • 屏幕震动、命中停顿、粒子、拖尾和后处理应保持克制，并能在减少动态效果或降低画质时干净地关闭；
  • 触控目标和虚拟控制应适配实际视口，且不得遮挡关键游玩区域。
核心循环变得有趣后，再添加次要系统。

5. Art-direct one world

5. 统一世界的美术方向

Read visuals.md. Define a small palette, lighting model, shape language, material family, and atmosphere. Prefer a coherent low-complexity world over a mixture of unrelated high-detail assets.
Keep color textures in the correct color space, cap expensive shadows, avoid per-frame allocations, and reduce pixel ratio or effects before reducing gameplay clarity. Credit and document every external asset and its license.
阅读 visuals.md。定义一个小型调色板、照明模型、形状语言、材质体系和氛围。优先选择统一且低复杂度的世界，而不是混合互不相关的高细节资源。
确保彩色纹理使用正确的 color space，限制高开销的阴影，避免每帧分配内存，并在降低游戏可读性之前先降低 pixel ratio 或特效。为所有外部资源注明来源并记录其许可证。

6. Add audio and persistence proportionally

6. 适度添加音频与持久化

Read audio-recipes.md if audio is in scope. Start audio only after a user gesture, expose mute and volume controls, and keep critical feedback understandable without sound.
Persist only useful state such as settings, best score, unlocked level, or checkpoint. Version stored data and recover safely from missing or invalid values.
如果音频属于项目范围，阅读 audio-recipes.md。仅在用户手势后启动音频，提供静音和音量控制，并确保无声时仍能理解关键反馈。
仅持久化有用的状态，例如设置、最高分、已解锁关卡或检查点。为存储数据加入版本，并安全处理缺失或无效的值。

7. Verify the actual game

7. 验证实际游戏

Run the production build first and fix every error. Then test the built or development version in a browser.
Check:
  • start → play → pause/resume → win/lose → restart works without reloading;
  • every documented control works, including touch when promised;
  • resize, orientation change, backgrounding, and focus loss do not corrupt state;
  • browser console has no uncaught errors or missing assets;
  • UI is readable and keyboard accessible;
  • audio activation and mute behavior are correct;
  • save data survives a reload and invalid save data does not crash;
  • the busiest scene remains responsive on the target device class;
  • reduced-motion and lower-quality modes remove expensive effects without hiding essential feedback.
Play at least one complete run. Automated build success alone is insufficient.
先运行生产构建并修复每一个错误。然后在浏览器中测试构建版本或开发版本。
检查：
  • 开始 → 游戏 → 暂停或恢复 → 获胜或失败 → 重启的完整流程无需重新加载即可运行；
  • 每个已记录的控制方式均有效，包括承诺支持的触控控制；
  • 调整尺寸、旋转屏幕、进入后台和失去焦点均不会破坏状态；
  • 浏览器控制台中没有未捕获错误或资源缺失；
  • UI 易读且可通过键盘操作；
  • 音频激活和静音行为正确；
  • 保存的数据在重新加载后仍然存在，无效保存数据也不会导致崩溃；
  • 负载最高的场景在目标设备等级上仍能保持响应；
  • 减少动态效果和低画质模式能够移除高开销特效，同时不隐藏必要反馈。
至少完整试玩一局。仅有自动化构建成功并不足够。

Quality bar

质量标准

  • A stranger can understand the objective and controls without reading source code.
  • The first meaningful interaction arrives quickly.
  • The game has a complete loop and restart flow, not only a scene or technical demo.
  • Camera, movement, collision, and feedback feel like one system.
  • The art direction is recognizable and original.
  • Performance degrades gracefully before it becomes unplayable.
  • The project remains understandable enough to extend.
  • 陌生用户无需阅读源代码即可理解目标和控制方式。
  • 首个有意义的交互应尽快出现。
  • 游戏应具备完整循环和重启流程，而不只是场景或技术演示。
  • 摄像机、运动、碰撞和反馈应像一套协调一致的系统。
  • 美术方向应易于识别且具有原创性。
  • 性能应在变得不可玩之前平滑降级。
  • 项目应保持足够清晰，以便进一步扩展。

Avoid

避免

  • recreating copyrighted characters, levels, UI, music, or branded assets;
  • installing a large engine or physics stack before proving it is necessary;
  • one file containing rendering, input, state, UI, audio, and every entity;
  • tying movement directly to frame count;
  • allocating vectors, materials, geometries, or loaders inside the hot loop;
  • unbounded particles, lights, shadow casters, or device pixel ratio;
  • pointer lock with no escape path or touch controls with no desktop fallback;
  • hiding load failures, unsupported WebGL, or missing credentials behind a blank canvas;
  • shipping a polished title screen around an unfinished mechanic.
  • 复刻受版权保护的角色、关卡、UI、音乐或品牌资源；
  • 在证明确有必要前安装大型引擎或物理技术栈；
  • 将渲染、输入、状态、UI、音频和所有实体都放在一个文件中；
  • 将运动直接绑定到帧数；
  • 在热循环内分配向量、材质、几何体或 loader；
  • 使用无上限的粒子、灯光、阴影投射体或 device pixel ratio；
  • 使用没有退出路径的 pointer lock，或没有桌面端回退方案的触控控制；
  • 将加载失败、不受支持的 WebGL 或缺失凭据隐藏在空白 canvas 之后；
  • 围绕尚未完成的机制打造精致的标题画面。

Handoff

交付

Lead with how to run the game. Then report:
  • the implemented core loop and control map;
  • build and playtest commands with results;
  • asset sources and licenses;
  • browser/device limitations;
  • deferred features that were intentionally kept out of scope.
首先说明如何运行游戏。然后报告：
  • 已实现的核心循环和控制映射；
  • 构建与试玩命令及其结果；
  • 资源来源和许可证；
  • 浏览器或设备限制；
  • 有意排除在范围之外的延后功能。