npm - evomeme-dev - Versions diffs - 0.1.7 - Mend

evomeme-dev 0.1.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (101) hide show

package/skills/threejs-3d-game/references/file-structure.md ADDED Viewed

@@ -0,0 +1,353 @@
+# 3D 游戏文件结构规范
+本文档定义浏览器 3D 游戏的标准文件结构。项目是 Vite + React + React Three Fiber 应用：3D 画面由 R3F / Three.js 管理，DOM UI 由 React 管理。**这是本插件所有 3D 代码结构和配置文件的唯一规范来源**，`game-director`、`game-designer`、`game-art`、`threejs-aaa-graphics-builder`、`game-test` 在涉及 3D 项目的 config 或目录结构时必须遵循本文件。
+**核心原则：** React Three Fiber（`<Canvas>`）拥有 3D / WebGL 世界；React DOM（`src/ui`）拥有所有正式 HUD、菜单、对话框、设置、背包、任务与叙事面板。禁止用 R3F `<Html>` 替代正式 HUD。跨层通信走 **事件总线**、**输入动作** 与显式 **模拟状态**。
+## `/public/config.json` 规则
+`/public/config.json` 是游戏运行时外置配置文件，构建后原样输出为 `/dist/config.json`。
+### 存储规则
+1. 所有用户可调颜色、玩法参数、平衡数值和资源 URL 必须写入 `/public/config.json`，禁止硬编码在业务代码中。
+2. 游戏代码必须通过 `fetch("./config.json")`（相对路径）读取配置；禁止使用绝对路径 `/config.json`；禁止从 `src` 目录直接 `import config.json`。
+3. 不得在 React、R3F、Three、CSS 中重复硬编码同一份用户可调值。
+### 结构要求：必须严格扁平
+config **必须是扁平顶层对象**，每个参数都是直接顶层 key，**禁止**按 `assets`、`images`、`gameplay`、`colors`、`params` 等分组：
+```json
+// 正确 —— 扁平
+{ "image_background": { ... }, "player_move_speed": { ... } }
+// 错误 —— 禁止嵌套分组
+{ "assets": { "background": { ... } }, "gameplay": { "speed": { ... } } }
+```
+每个 key 分两类：
+- **可见参数**（key 不以 `_` 开头）：暴露给用户编辑，必须使用下方标准 schema。
+- **不可见参数**（key 以 `_` 开头）：内部字段（如 `_game_name`、`_config_version`），原始值即可，不使用 schema。
+### 可见参数 schema
+```json
+"key_name": {
+  "value": <实际值>,
+  "type": "int" | "float" | "color" | "bool" | "string" | "audio" | "image" | "video",
+  "label": "<用户语言标签，≤10字>",
+  "min": <数字>,
+  "max": <数字>
+}
+```
+规则：
+- `type` 只能是 `int`、`float`、`color`、`bool`、`string`、`audio`、`image`、`video`。
+- `label` 使用用户语言，长度不超过 10 个字符。
+- `min`/`max` 只在 `int`/`float` 时出现，且必须同时给出。
+- `type: "color"` 使用十六进制颜色字符串。
+- `type: "image"` 必须额外声明 `"image_type": "Asset"` 和 `"size": "宽x高"`（如 `"1440x2560"`），供无法读取真实图片尺寸时判断显示尺寸。
+- `audio`/`image`/`video` 的 `value` 必须是真实可访问的外部 `http(s)` URL；禁止本地相对路径。图片/网格由上游异步生成，URL 短暂 404 不代表素材失效，不得因此改写、替换或删除素材。
+### 示例
+```json
+{
+  "_game_name": "示例 3D 游戏",
+  "_config_version": 1,
+  "player_move_speed": { "value": 4.5, "type": "float", "label": "移动速度", "min": 1, "max": 12 },
+  "camera_follow_lag": { "value": 0.12, "type": "float", "label": "镜头滞后", "min": 0.01, "max": 0.5 },
+  "theme_background_color": { "value": "#0b1020", "type": "color", "label": "背景色" },
+  "enable_shake": { "value": true, "type": "bool", "label": "震屏开关" },
+  "start_button_text": { "value": "开始游戏", "type": "string", "label": "开始文案" },
+  "bgm_main": { "value": "https://example.com/bgm.mp3", "type": "audio", "label": "背景音乐" },
+  "model_player": {
+    "value": "https://example.com/player.glb",
+    "type": "string",
+    "label": "玩家模型"
+  }
+}
+```
+代码侧读取方式：
+```ts
+await loadConfig()
+const speed = getSetting<number>('player_move_speed', 4.5)
+```
+## `/user_upload` 目录规则
+`/user_upload` 是用户上传素材的虚拟目录，其下文件不是真实素材文件，只保存素材链接或元数据。
+1. 需要使用用户上传素材时，先读取 `/user_upload` 下对应文件，提取真实 URL。
+2. 不要把 `/user_upload/...` 当成本地素材路径；最终代码必须引用提取出的真实 URL。
+## 部署与路径规则
+1. 最终部署产物固定为 `/dist`，以静态站点形式部署，运行时资源必须能通过浏览器直接访问。
+2. `/dist` 必须能脱离源码目录独立运行：所有运行时代码、资源、chunk、CSS、音频、图片、模型与配置只能引用 `/dist` 内文件或外部 `http(s)` 链接，必须使用相对路径或构建产物内部路径，严禁指向源码目录的运行时引用。
+3. `vite.config.ts` 必须设置 `base: './'`，使构建产物使用相对路径（`./assets/...`），保证在任意子路径部署都能运行。
+4. 所有运行时字符串路径（`fetch`、`Audio`、动态 `import`、CSS `url()`、GLTFLoader）必须使用 `./` 相对路径或外部 `http(s)` URL，禁止以 `/` 开头的绝对路径（站点根路径）。
+## 项目根目录必需文件
+- `/project.md`：唯一游戏需求来源（策划案），后续所有开发依据此文件。
+- `/public/config.json`：运行时配置与素材绑定契约。
+- `/src`：Vite + React + R3F 源码。
+- `/dist`：构建产物，交付物。
+## Tech Stack
+| Tech | Role |
+| --- | --- |
+| Vite | 构建与开发服务器 |
+| React | App 壳与 DOM UI |
+| React Three Fiber (R3F) | 挂载 Three.js `Canvas`、生命周期、`useFrame` 编排 |
+| Three.js | WebGL 渲染、相机、灯光、网格、`AnimationMixer`、GLB 等 |
+| Tailwind CSS v4 | DOM UI 样式 |
+| mitt | React UI 与游戏运行时之间的事件总线 |
+| `public/config.json` | 运行时外置配置 |
+| pnpm | 包管理器（`pnpm install` / `pnpm build`） |
+## 必需顶层结构
+```text
+.
+├── index.html
+├── package.json
+├── public/
+│   ├── config.json
+│   └── assets/            # 可选静态资源目录
+└── src/
+    └── main.tsx
+```
+完整推荐树：
+```text
+.
+├── index.html
+├── package.json
+├── pnpm-lock.yaml
+├── tsconfig.json
+├── vite.config.ts
+├── public/
+│   ├── config.json
+│   └── assets/
+└── src/
+    ├── main.tsx
+    ├── App.tsx
+    ├── index.css
+    ├── config/
+    │   ├── config.ts          # fetch public/config.json → loadConfig() / getSetting()
+    │   └── types.ts           # 配置类型（可选）
+    ├── game/
+    │   ├── bridge/
+    │   │   ├── gameBus.ts     # mitt 事件总线
+    │   │   ├── gameCommands.ts
+    │   │   └── gameEvents.ts
+    │   ├── simulation/
+    │   │   ├── state.ts       # 可序列化、可测试的游戏状态
+    │   │   ├── systems/       # 确定性玩法系统
+    │   │   └── rules.ts       # 无 Three / React 依赖的规则
+    │   ├── content/
+    │   │   ├── encounters/
+    │   │   ├── items/
+    │   │   └── maps/
+    │   ├── input/
+    │   │   ├── actions.ts
+    │   │   ├── bindings.ts
+    │   │   └── inputState.ts
+    │   ├── assets/
+    │   │   └── manifest.ts    # 稳定资产键、URL、元数据
+    │   ├── audio/
+    │   │   ├── audioManager.ts
+    │   │   ├── audioHooks.ts
+    │   │   └── audioPrefs.ts
+    │   └── three/             # 无 React import；可单测的 Three 模块
+    │       ├── buildWorld.ts
+    │       ├── orbitCameraRig.ts
+    │       ├── character/
+    │       └── creatures/
+    ├── ui/
+    │   ├── components/
+    │   │   └── GameCanvas.tsx # R3F <Canvas>、useFrame、世界挂载
+    │   ├── hud/
+    │   ├── menus/
+    │   ├── overlays/
+    │   └── store/
+    │       └── useGameUiStore.ts
+    ├── components/            # 共享 DOM UI 原语（非游戏业务 UI）
+    └── lib/
+        └── utils.ts
+```
+## 文件职责
+| Path | Owner | Role |
+| --- | --- | --- |
+| `index.html` | tech | 壳页面；挂载 `#root` / `#app`，加载 `/src/main.tsx`。 |
+| `package.json` | tech | 脚本与依赖；必须暴露 `build`（通常还有 `dev`）。 |
+| `public/config.json` | product / ops | 运行时可调参数与内容指针；优先改这里而非源码。 |
+| `src/main.tsx` | tech | 启动：`loadConfig()` 后 `createRoot(...).render(<App />)`。 |
+## 交付物
+游戏未完成，除非 **两者都存在**：
+| Artifact | When | Why |
+| --- | --- | --- |
+| `public/config.json` | 始终在源码树 | 运维/运行时配置源；Vite 构建时复制进 `dist/`。 |
+| `dist/index.html` | `pnpm build` 之后 | 可交付静态入口。 |
+成功构建后还应有 `dist/config.json`（`public/config.json` 的运行时副本）。
+## 包管理与脚本
+- 包管理器：**pnpm**（默认；不用 npm/yarn）。
+- 安装：`pnpm install`
+- 生产构建：`pnpm build`
+- 本地开发：`pnpm dev`
+最小脚本约定：
+```json
+{
+  "scripts": {
+    "dev": "vite --host 127.0.0.1",
+    "build": "tsc && vite build",
+    "preview": "vite preview --host 127.0.0.1"
+  }
+}
+```
+新项目就绪前验证：
+1. `public/config.json` 存在。
+2. `pnpm install` 成功。
+3. `pnpm build` 成功并产出 **`dist/index.html`**（及 `dist/config.json`）。
+4. 入口链正常：`index.html` → `src/main.tsx` → `loadConfig()` → `<App />`（`GameCanvas` + DOM HUD）。
+## 启动流
+```text
+main.tsx
+  -> loadConfig()
+  -> createRoot(...).render(<App />)
+App.tsx
+  -> GameCanvas (R3F <Canvas>, World + useFrame)
+  -> Hud / MobileHud
+  -> PauseMenu, overlays（按需）
+GameCanvas.tsx
+  -> buildWorldInto / GLTFLoader（via game/three）
+  -> useFrame: simulation step + scene sync + camera
+```
+`GameCanvas.tsx` 是 **WebGL ↔ React DOM 边界**。DOM UI 叠在 Canvas 之上（在 `App` 中组合）。卸载时 dispose Three 资源与总线订阅。
+## 分层规则
+### R3F / 3D 运行时（`src/ui/components/GameCanvas.tsx` + `src/game/three/`）
+**`GameCanvas.tsx`（挂载边界）负责：**
+- 创建 R3F `<Canvas>`（阴影、`gl`、`dpr` 等默认见 `engine-runtime.md`）
+- `useFrame` 编排：读输入/模拟 → 更新 `Object3D` 或状态 → `mixer.update` → 相机（交给 R3F 渲染；除非离屏否则不要手调 `renderer.render`）
+- 组装场景根：`buildWorldInto(group)`、异步 GLB 加载
+- StrictMode 重挂载 / 卸载时 dispose 几何、材质、`AnimationMixer` 与总线订阅
+**`game/three/*`（纯 Three 模块）负责：**
+- 无 React import 的场景构建、数学与加载助手
+- 不在 React ref 之外偷偷改 DOM
+用 `gameBus.emit()` 发出玩法事实；通过 `gameBus` / 命令类型接受 UI 命令（暂停、重置、使用道具等）。
+**禁止：**
+- 在 `game/three` 内 `import` React 组件或 hooks
+- 用 R3F `<Html>` 堆正式 HUD/菜单
+- 把触控摇杆 / 手势映射散落在 `useFrame` 或随机组件里（集中到 `game/input` 或 UI → 统一动作）
+### React DOM UI（`src/ui` + `src/components`）
+**负责：** HUD、条、按钮、主/暂停/设置菜单、背包、任务、对话框、结算、toast；经 `gameBus` 发 `command:*`；经 `useGameUiStore()`（或等价物）读运行时状态。
+**禁止：** 在 HUD 里直接拿 `Mesh` / `Object3D` 每帧改 `position`；在 UI 组件里写核心规则；把每局业务 UI 塞进 `src/components`；在多个组件里复制摇杆绑定而不走 `game/input`。
+### Simulation（`src/game/simulation`）
+负责玩家/敌人状态、背包、任务、战斗数值、纯规则、可序列化存档。要求无 Three.js / R3F / React 依赖。
+### Content（`src/game/content`）
+负责关卡、地图、遭遇、波次、道具、奖励等静态设计数据。禁止 React 组件与 `Object3D` 生命周期耦合。
+### Input（`src/game/input`）
+负责统一动作、键鼠/虚拟摇杆/触控绑定，以及 UI 与 `GameCanvas` 共用的语义输入面。禁止未文档化的散落硬编码绑定；禁止直接改写持久模拟根状态。
+### Assets（`src/game/assets`）
+负责 glTF / 贴图 / 音频 / VFX 的稳定键、URL、类型与元数据。禁止在玩法、UI、场景模块中到处硬编码 `"/foo/bar.glb"`。
+### Audio（`src/game/audio`）
+负责从 config 读 BGM/SFX 路径与开关、Web Audio / HTMLAudio 播放与 dispose、监听 `gameBus` 映射玩法事实到声音、应用 HUD 发来的 `command:audio-prefs`。禁止在 HUD 里 `new Audio()` 播局内音效；禁止每帧 `useFrame` 新建音源或脚步循环；退出/结算/失败/重开后不得残留局内 BGM。解锁、事件钩子与清理细则见 `engine-audio.md`。
+## 事件桥规则
+文件：`src/game/bridge/gameBus.ts`、`gameEvents.ts`、`gameCommands.ts`。
+命名：
+- `command:*` — React → 游戏运行时
+- `game:*` — 全局会话 / 世界事件
+- `player:*` — 玩家状态
+- `enemy:*` — 敌人状态
+- `ui:*` — 面向 UI 的事件
+- `game:feedback` / `player:movement` — 局内反馈线索（SFX + VFX）；payload 为普通数据
+新增事件时，同一次改动更新 `gameCommands.ts` / `gameEvents.ts` 类型。
+## 诊断与测试钩子
+在 `GameCanvas` 挂载时安装，卸载时清理；类型声明放在 `src/vite-env.d.ts`。
+- `window.__THREE_GAME_DIAGNOSTICS__`：渲染器 info、模拟快照、输入状态、实体计数等（供 canvas inspector / AAA scorecard）。
+- `window.__THREE_GAME_TEST_HOOKS__`：`seed` / `setState` / `setPausedForScreenshot` / `setReducedMotion` / `hideDebugUi`（供视觉回归与 bot playtest）。
+确定性随机放在 `src/lib/random.ts` 或 `src/game/simulation/random.ts`，禁止业务路径使用 `Math.random`。
+## 硬性方法论
+- **保持分层：** `game/three` 不得 import React；DOM UI 不得直接驱动 `Object3D`。优先 `gameBus` 或单一输入/模拟门面。
+- **模拟优先：** 规则在 `game/simulation`，不在 `useFrame` 或 `Hud.tsx`。
+- **输入集中：** 物理 → 语义映射在 `game/input`。
+- **内容是数据：** 关卡/地图/道具在 `game/content`。
+- **资产目录：** glTF / 贴图 / 音频经 `manifest.ts` 或 config key。
+- **局内音频集中：** 仅 `game/audio`；偏好经总线。
+- **配置集中：** 可调参数在 `public/config.json`。
+- **UI 放置：** 业务 DOM UI 在 `src/ui`；共享原语在 `src/components`；正式 HUD 永不当 R3F 子节点。
+- **验证：** 有意义改动后跑 `pnpm build`。
+## 反模式
+- 在 `useFrame` 里搭完整菜单 / 背包 / 设置
+- 从任意 React 组件抓场景内部 ref 到处改 mesh
+- 把战斗规则放进 `Hud.tsx`
+- 用 `Mesh.userData` 当 UI/存档的持久数据库
+- 输入与状态多源漂移
+- 多文件复制同一触控动作映射
+- 多处硬编码同一 glTF/贴图 URL 字符串
+- 按本规范却用 `src/main.ts` 代替 `src/main.tsx`
+- 用 CRA、Next.js 或仅 npm 脚手架替换本布局（除非用户要求）
+## 输出期望
+新增功能时说明所属层（R3F/Three 编排 / React UI / Simulation / Content / Input / Assets / Audio）及原因。跨层行为经 `gameBus`（或约定的单一门面）路由，并更新事件类型。以 `pnpm build` 确认。

package/skills/threejs-aaa-graphics-builder/SKILL.md ADDED Viewed

@@ -0,0 +1,62 @@
+---
+name: threejs-aaa-graphics-builder
+description: 用高品质美术方向、材质、灯光、着色器、VFX、素材获取与渲染预算升级 Three.js 场景。在 3D 浏览器游戏需要超越原型画面的可度量视觉提质时使用。
+---
+# Three.js AAA Graphics Builder
+## Purpose
+Own the production graphics pass. Convert basic screenshots into authored, high-density, performance-aware visual experiences.
+## Use When
+Screenshots still look basic, models look primitive, worlds are sparse, UI/world art feels generic, or the user asks for premium, AAA, high-fidelity, showcase, or less-basic graphics.
+## Required References
+These references are required phase-entry gates, not optional reading:
+- Load `../game-art/references/scene-profiles.md` and select a `scene_profile_id` before world kit, lighting polish, or any claim that World/environment is authored. Read only the **World + 3D · Lighting + Entities + Reject** sections for that profile; this skill executes the production pass against it.
+- Load `references/visual-scorecard.md` before scoring, judging completion, or making any premium/AAA/showcase claim.
+- Load `references/implementation-blueprint.md` before changing graphics architecture, materials, VFX, rendering, diagnostics, or broad visual systems.
+- Load `references/model-recipes.md` before building or upgrading hero/player, obstacle, enemy, pickup, world-kit, material, or prop models.
+- Load `references/render-recipes.md` before changing lighting, tone mapping, shadows, fog, post-processing, materials, or render composition.
+- Load `references/technical-art.md` before premium/AAA/showcase graphics work, shaders/material systems, VFX systems, generated/imported asset cleanup, LOD/instancing work, or visual changes that could affect browser performance.
+- Load `references/shader-cookbook.md` before writing any custom shader, `onBeforeCompile` injection, material recipe, sky, or post-processing chain; use its proven values and GLSL patterns instead of improvising.
+- Load `references/checklists/aaa-game-quality-gate.md` and `references/checklists/aaa-visual-scorecard.md` before declaring a game premium, AAA, showcase, complete, release-ready, or less basic.
+- Load the relevant checklist before focused work: `references/checklists/procedural-model-quality.md`, `references/checklists/material-lighting-quality.md`, `references/checklists/performance-safe-visual-detail.md`, or `references/checklists/technical-art-quality.md`.
+- Load `references/graphics-prompt-templates.md` only when the user asks for reusable prompts, a graphics-pass prompt, or a task template.
+For broad "still looks basic", premium, AAA, high-fidelity, showcase, or less-basic graphics work, load the scene-profiles paradigm (3D Lighting rail) plus all five core references (`visual-scorecard`, `implementation-blueprint`, `model-recipes`, `render-recipes`, `technical-art`) as the first action in the phase. Track them in a reference ledger with yes/no, path, and failure reason. Do not mark the graphics phase complete while any required reference is skipped.
+External asset sourcing gate:
+- For premium/AAA/showcase/high-fidelity/less-basic graphics with a hero/player, character, creature, boss, vehicle, ship, building, weapon, signature prop, complex pickup, or hero environment piece, prefer authored procedural factories from `references/model-recipes.md` before settling for placeholders. Remote mesh generation is offline in the current release.
+- For concept needs, texture/material references, decals, logos, faction marks, icons, GUI art, skies, backgrounds, or title/menu art: prefer procedural/CSS/canvas UI art; use user-supplied local images via `evomeme_upload_game_asset`.
+- Create an asset sourcing ledger for each high-value surface: procedural / hybrid / user-provided, plus outputs or skip reason.
+- `not-needed` is valid only after the relevant path was considered and the ledger explains why external assets would not improve a non-hero support surface, or why an attempted MCP/CDN call shows a real blocker.
+- For premium hero surfaces, procedural-only is allowed; document that constraint and still meet silhouette/material/lighting quality via procedural authorship or user-provided GLB/FBX.
+## Workflow
+1. Capture or inspect active desktop/mobile screenshots.
+2. Confirm or select a `scene_profile_id` from `../game-art/references/scene-profiles.md` (World / 3D · Lighting / Entities). If missing, write it before upgrading surfaces.
+3. Score visuals across art direction, hero/player, obstacles, rewards, world, materials, render, VFX, UI, and performance evidence.
+4. Add missing graphics architecture: material library, procedural textures/decals, model factories, world prop kit, technical-art budget, VFX system, render pipeline, diagnostics.
+5. Fill the external asset sourcing ledger per surface: procedural Three.js factory, user-provided model/2D reference, or a hybrid.
+6. Upgrade every weak visible surface, not only one hero object. World layers must match the chosen scene-profiles paradigm (Play / Near / Mid / Far / Motion).
+7. Add lighting/render/material polish after authored forms exist, following the paradigm's Lighting stack intent and `references/render-recipes.md`.
+8. Add event-driven VFX tied to gameplay state.
+9. Re-score screenshots against the calibration anchors, citing the inspector's measured metrics. Continue until every premium category is at least 2/3 or report exact blockers.
+10. Run the fresh-eyes review per `references/visual-scorecard.md` before finalizing premium/AAA/showcase claims.
+11. Verify renderer diagnostics against the render budget table, technical-art budget, desktop/mobile screenshots, console/page errors, canvas pixels, imported asset budgets, and playability.
+## Core Rule
+Do not make primitives look AAA by adding glow. First build authored forms, then materials, then lighting, then effects.
+## Final Response
+Report the reference ledger, external asset sourcing ledger, technical art brief, score before/after, production surfaces upgraded, files changed, screenshots/artifacts, renderer diagnostics, imported asset diagnostics when relevant, VFX readability and render-budget tradeoffs, and remaining blockers. For premium/AAA/showcase claims, include the filled visual scorecard exactly as defined in `references/visual-scorecard.md`, including average and automatic failures remaining.

package/skills/threejs-aaa-graphics-builder/agents/openai.yaml ADDED Viewed

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Three.js AAA Graphics Builder"
+  short_description: "全面提升三维游戏的模型、材质、灯光、特效和渲染品质"
+  default_prompt: "请使用 $threejs-aaa-graphics-builder 提升这个三维游戏的整体画面品质，完善模型、材质、灯光、特效与性能表现。"
+policy:
+  allow_implicit_invocation: false

package/skills/threejs-aaa-graphics-builder/assets/scorecard-anchors/scene-1.jpg ADDED Viewed

Binary file

package/skills/threejs-aaa-graphics-builder/assets/scorecard-anchors/scene-2.jpg ADDED Viewed

Binary file

package/skills/threejs-aaa-graphics-builder/assets/scorecard-anchors/scene-3.jpg ADDED Viewed

Binary file

package/skills/threejs-aaa-graphics-builder/references/checklists/aaa-game-quality-gate.md ADDED Viewed

@@ -0,0 +1,23 @@
+# AAA Browser Game Quality Gate
+- The game is immediately playable and not presented as a landing page.
+- The core loop has objective, scoring/progress, fail/retry, pacing, and feedback.
+- Screenshots do not read as a collection of default primitives, debug HUDs, or generic placeholder panels.
+- Unadorned boxes, cones, spheres, flat planes, and stretched buildings are not the dominant art language unless explicitly intentional.
+- UI is genre-specific, compact, readable during motion, responsive, and includes needed modal states.
+- Player, threats, rewards, and objectives have distinct silhouettes and material/feedback language.
+- Player/hero asset has primary silhouette, secondary structure, tertiary detail, material contrast, and state feedback.
+- Obstacle/enemy set includes at least three authored variants with unique telegraphs.
+- Reward/interactable set includes at least two authored variants with collection/interaction feedback.
+- World kit includes reusable modules and does not rely on one repeated skyline/block/road primitive.
+- The scene has foreground, midground, and background depth instead of one flat play lane.
+- Lighting, shadows, fog, and post-processing clarify depth and mood without hiding gameplay.
+- Procedural models use the authored factories, shared material kit, reusable prop kits, and collision proxies from `../implementation-blueprint.md` and `../technical-art.md`.
+- Movement, camera, speed, impact, and restart loop feel tuned through play, not just configured.
+- Audio/visual feedback exists for core actions and state transitions.
+- Mobile viewport preserves framing, safe areas, touch targets, and text fit.
+- Renderer diagnostics from `../technical-art.md` are reviewed when visual fidelity changes.
+- Visual scorecard in `../visual-scorecard.md` passes: every category at least 2 and average at least 2.3.
+- Build, browser run, console/page errors, screenshots, nonblank canvas, interaction, and responsive checks all pass.
+- A screenshot critique identifies no unresolved high-impact placeholder-quality blockers.
+- If any premium surface was intentionally deferred, the final report says which one and why.

package/skills/threejs-aaa-graphics-builder/references/checklists/aaa-visual-scorecard.md ADDED Viewed

@@ -0,0 +1,19 @@
+# AAA Visual Scorecard Checklist
+Use with `../visual-scorecard.md`.
+- Current desktop and mobile active-play screenshots are available.
+- Art direction category scored 0-3.
+- Hero/player asset category scored 0-3.
+- Obstacles/enemies category scored 0-3.
+- Rewards/interactables category scored 0-3.
+- World/environment category scored 0-3.
+- Materials/textures category scored 0-3.
+- Lighting/render category scored 0-3.
+- VFX/motion category scored 0-3.
+- UI/HUD category scored 0-3.
+- Performance evidence category scored 0-3.
+- No automatic failure is present: check every item in the canonical Automatic Failures list in `../visual-scorecard.md` (do not rely on a from-memory summary of it).
+- Technical-art evidence includes material kit, VFX readability, instancing/LOD/culling decision, DPR/post/shadow tradeoffs, and imported asset diagnostics when generated/imported assets are used.
+- Premium gate passes only when every category is at least 2 and average score is at least 2.3.
+- Showcase gate passes only when at least six categories are 3, no category is below 2, and average score is at least 2.7.

package/skills/threejs-aaa-graphics-builder/references/checklists/material-lighting-quality.md ADDED Viewed

@@ -0,0 +1,14 @@
+# Material and Lighting Quality Checklist
+Gate the lighting/material recipes in `../render-recipes.md` and the material kit in `../technical-art.md`.
+- Renderer color space, tone mapping, exposure, and shadow settings are intentional.
+- Key, fill, rim, ambient, and environment lighting follow the lighting stack in `../render-recipes.md` and clarify depth and gameplay roles.
+- Materials avoid flat default looks through roughness/metalness/emissive/vertex-color variation.
+- Important objects have readable silhouettes against background, fog, and effects.
+- Shadows help ground assets without obscuring navigation or collision boundaries.
+- Fog, bloom, particles, and post-processing support readability instead of hiding it.
+- Procedural textures or decals are scaled, stable, and not visually noisy during movement.
+- Materials reuse the shared kit in `../technical-art.md` where possible and are disposed when obsolete.
+- Desktop and mobile screenshots are checked after lighting/material changes.
+- Renderer info or frame-time evidence is gathered when render cost changes.

package/skills/threejs-aaa-graphics-builder/references/checklists/performance-safe-visual-detail.md ADDED Viewed

@@ -0,0 +1,14 @@
+# Performance-Safe Visual Detail Checklist
+Gate the render budget and instancing/LOD guidance in `../technical-art.md`.
+- Baseline renderer info is captured when increasing fidelity.
+- Draw calls, triangles, geometries, materials, textures, and frame time are reviewed against the render budget in `../technical-art.md` after changes.
+- Repeated details use the instancing/LOD approach in `../technical-art.md`: instancing, shared resources, atlases, or generated texture reuse where practical.
+- High segment counts are limited to silhouette-critical forms.
+- Shadows are scoped by light count, shadow map size, casters/receivers, and camera distance.
+- Post-processing is justified by gameplay readability or strong art direction.
+- DPR caps or adaptive quality are considered for mobile.
+- Generated resources have a disposal/reuse strategy.
+- The worst-case gameplay scene, not only idle view, is inspected.
+- Visual detail remains readable at mobile resolution without excessive GPU cost.

package/skills/threejs-aaa-graphics-builder/references/checklists/procedural-model-quality.md ADDED Viewed

@@ -0,0 +1,15 @@
+# Procedural Model Quality Checklist
+Gate the procedural modeling guidance in `../model-recipes.md` and the material kit in `../technical-art.md`.
+- The model has a recognizable silhouette from the gameplay camera.
+- Primary forms read clearly before material or post-processing detail.
+- Secondary detail supports the asset role: panels, trims, ridges, tubes, fins, sockets, decals, or emissive accents.
+- Tertiary detail is visible at intended camera distance and does not create noise.
+- Materials use the kit in `../technical-art.md` with purposeful contrast in roughness, metalness, color, emissive, or texture.
+- Bevels, curves, and segment counts improve silhouette or highlight behavior.
+- Repeated props use shared geometries/materials, instancing, or pools when practical.
+- Visual mesh and gameplay collision/proxy are intentionally separated when needed.
+- The factory returns named groups/meshes and keeps ownership/disposal clear.
+- Renderer diagnostics from `../technical-art.md` are checked when triangles, materials, textures, or draw calls increase.
+- Mobile screenshot still shows the asset as more than a primitive placeholder.

package/skills/threejs-aaa-graphics-builder/references/checklists/technical-art-quality.md ADDED Viewed

@@ -0,0 +1,17 @@
+# Technical Art Quality Checklist
+Use before claiming premium, AAA, showcase, high-fidelity, or less-basic visual quality after graphics changes. Each item gates the guidance in `../technical-art.md`.
+- Technical art brief converts art direction into shapes, material roles, lighting, VFX, camera, UI/world motifs, and budgets.
+- Hero surfaces and support surfaces are identified separately.
+- Material kit uses the named shared roles from `../technical-art.md`, not scattered one-off colors/materials.
+- Shader/post-processing choices have player-facing purpose and measured or bounded cost.
+- VFX follow the event-driven language in `../technical-art.md`: readable, short-lived, and not hiding collision, threats, rewards, or UI.
+- Instancing is used for large repeated same-geometry/same-material detail where appropriate.
+- LOD, culling, or simplified far variants are planned for heavy background/imported assets.
+- Imported/generated models have scale, pivot/orientation, bounds, file size, triangle/material/texture counts when available, and collision proxies checked.
+- Decals/trim/detail systems reinforce function, route, faction, scale, or state.
+- Threats, rewards, interactables, and player state are not communicated by color alone.
+- DPR cap, shadow settings, post-processing passes, and mobile tradeoffs are reported.
+- Renderer diagnostics match the render budget reporting in `../technical-art.md`: calls, triangles, geometries, textures, and material count when available.
+- Final visual scorecard performance evidence category includes budget and technical-art evidence, not only screenshots.