@playcraft/skills 0.0.2

package/skills/threejs.aicomponent/SKILL.md

@@ -0,0 +1,422 @@
+---
+name: threejs.aicomponent
+description: Three.js 3D 引擎运行时 + 完整可运行空项目。提供 15 个文件：场景生命周期管理（Preloader→Main）、PBR 渲染管线（阴影/色调映射）、响应式视口（ResizeObserver）、资源加载（Texture/GLTF/Audio/CubeTexture）、OrbitControls。安装依赖后 `pnpm dev` 即可看到旋转 Torus Knot + 网格地面。
+triggers: 需要初始化一个新的 Three.js 3D 项目、添加 3D 游戏引擎基础层，或配置 WebGL 渲染器和 3D 场景时触发。
+---
+
+# Three.js 3D 引擎（Three.js Engine + Complete Project Skeleton）
+
+## 说明
+
+本 skill 是所有 Three.js skill 的基础。它贡献的 **15 个文件**构成了一个**完整可运行的 Three.js 空项目**，开箱即用：
+
+```bash
+pnpm install
+pnpm dev      # 开发模式 → 浏览器显示旋转 Torus Knot + 网格地面 + 坐标轴
+pnpm build    # 构建产物
+```
+
+**已内置的基础能力：**
+
+- **场景生命周期管理**：`SceneManager` + `BaseScene` 抽象类，支持 Preloader → Main 多场景切换
+- **PBR 渲染管线**：ACES Filmic 色调映射 + PCF 软阴影 + 自动 HiDPI 像素比
+- **响应式视口**：`ViewportManager` 基于 ResizeObserver，自动更新 Renderer + Camera
+- **资源加载系统**：`AssetLoader` 支持 Texture / GLTF / Audio / CubeTexture 批量加载 + 进度回调
+- **OrbitControls**：带阻尼的轨道相机控制，可通过配置开关
+- **HTML Loading Overlay**：CSS 动画进度条，加载完成自动淡出
+- **TypeScript 完整支持**：资源模块声明（图片/音频/3D模型/HDR/EXR）+ `__DEV__` 全局变量
+
+---
+
+## Scaffold
+
+| 目标路径 | 来源 | 说明 |
+|---------|-----|-----|
+| `src/main.ts` | `ref/main.ts` | **webpack 入口**：import CSS → DOMContentLoaded → StartGame |
+| `src/index.html` | `ref/index.html` | **HTML 容器**：viewport meta + `#game-container` + `#loading-overlay` |
+| `src/index.css` | `ref/index.css` | **全屏样式**：移动端适配 + Loading overlay CSS 动画 |
+| `globals.d.ts` | `ref/globals.d.ts` | **类型声明**：资源模块（图片/音频/3D模型/HDR）+ `__DEV__` 全局 |
+| `tsconfig.json` | `ref/tsconfig.json` | **TypeScript 配置**：target es2020, moduleResolution bundler, paths assets/* |
+| `src/game/index.ts` | `ref/index.ts` | **`StartGame(containerId)`**：配置 Renderer + Camera + SceneManager + 动画主循环 |
+| `src/game/GameConfig.ts` | `ref/GameConfig.ts` | **游戏配置**：渲染参数、相机、灯光、调试开关 |
+| `src/game/SceneKeys.ts` | `ref/SceneKeys.ts` | **场景名枚举**：Preloader / Main |
+| `src/game/SceneManager.ts` | `ref/SceneManager.ts` | **场景管理器**：注册、切换、更新、销毁 |
+| `src/game/scenes/BaseScene.ts` | `ref/BaseScene.ts` | **场景基类**：init/enter/update/exit/dispose 生命周期 |
+| `src/game/scenes/PreloaderScene.ts` | `ref/PreloaderScene.ts` | **预加载场景**：HTML overlay 进度条 + AssetLoader 批量加载 |
+| `src/game/scenes/MainScene.ts` | `ref/MainScene.ts` | **主场景**：Hello Three.js（旋转 Torus Knot + 灯光 + 地面 + 网格） |
+| `src/game/utils/ViewportManager.ts` | `ref/ViewportManager.ts` | **响应式视口**：ResizeObserver 自动更新 Renderer + Camera |
+| `src/game/utils/AssetLoader.ts` | `ref/AssetLoader.ts` | **资源加载器**：Texture/GLTF/Audio/CubeTexture 批量加载 |
+| `package.json` | `ref/package.json` | **依赖**：three + @types/three + webpack 工具链 |
+| `webpack.config.js` | `ref/webpack.config.js` | **Webpack 5 配置**：ts-loader + 3D 模型/HDR 资源 + __DEV__ |
+
+`package.json` 新增：`"three": "^0.172.0"`, `"@types/three": "^0.172.0"`
+
+---
+
+## 空项目文件结构
+
+安装本 skill 后 Remix 项目的完整文件树：
+
+```
+<remix-project>/
+├── src/
+│   ├── main.ts               ← webpack 入口
+│   ├── index.html            ← HTML 容器（含 viewport meta + loading overlay）
+│   ├── index.css             ← 全屏 + 移动端适配 + Loading 动画样式
+│   └── game/
+│       ├── index.ts          ← StartGame()
+│       ├── GameConfig.ts     ← 通用游戏配置
+│       ├── SceneKeys.ts      ← 场景名枚举
+│       ├── SceneManager.ts   ← 场景生命周期管理器
+│       ├── scenes/
+│       │   ├── BaseScene.ts      ← 场景抽象基类
+│       │   ├── PreloaderScene.ts ← 资源加载 + HTML 进度条
+│       │   └── MainScene.ts      ← Hello Three.js（主场景骨架）
+│       └── utils/
+│           ├── ViewportManager.ts ← 响应式视口管理
+│           └── AssetLoader.ts     ← 统一资源加载器
+├── assets/
+│   ├── models/               ← 3D 模型（.glb, .gltf, .fbx）
+│   ├── textures/             ← 贴图（.png, .jpg, .webp, .hdr）
+│   └── sounds/               ← 音频（.mp3, .ogg, .wav）
+├── globals.d.ts              ← 完整类型声明
+├── tsconfig.json             ← TypeScript 配置
+├── package.json              ← three + webpack 依赖
+└── webpack.config.js         ← 构建配置
+```
+
+---
+
+## 文件详解
+
+### src/index.ts（webpack 入口）
+
+```typescript
+import "./index.css";
+import { StartGame } from "./game";
+
+document.addEventListener("DOMContentLoaded", () => {
+  StartGame("game-container");
+});
+```
+
+### src/game/index.ts（StartGame 函数）
+
+```typescript
+import * as THREE from "three";
+import { GameConfig } from "./GameConfig";
+import { SceneManager } from "./SceneManager";
+import { ViewportManager } from "./utils/ViewportManager";
+
+export function StartGame(containerId: string): GameInstance {
+  // 1. 创建 WebGLRenderer（抗锯齿 + 阴影 + ACES Filmic 色调映射）
+  // 2. 创建 PerspectiveCamera（fov/near/far/position 来自 GameConfig）
+  // 3. 注册 PreloaderScene + MainScene → SceneManager
+  // 4. 启用 ViewportManager（ResizeObserver 响应式）
+  // 5. requestAnimationFrame 主循环：update → render
+}
+```
+
+### src/game/GameConfig.ts（通用配置）
+
+```typescript
+export const GameConfig = {
+  antialias: true,                 // 抗锯齿
+  shadows: true,                   // 阴影
+  toneMapping: "ACESFilmic",       // 色调映射
+  toneMappingExposure: 1.0,        // 曝光度
+  maxPixelRatio: 2,                // HiDPI 像素比上限
+
+  camera: {
+    fov: 60,                       // 视场角
+    near: 0.1, far: 1000,         // 裁剪面
+    position: { x: 0, y: 3, z: 5 },
+    lookAt: { x: 0, y: 0, z: 0 },
+  },
+
+  lighting: {
+    ambientColor: 0x404040,        // 环境光
+    directionalColor: 0xffffff,    // 平行光
+    directionalPosition: { x: 5, y: 8, z: 5 },
+  },
+
+  clearColor: 0x1a1a2e,           // 场景背景色
+  debugScene: "main",              // 启动场景
+  showFps: false,                  // FPS 显示
+  showGrid: true,                  // 网格/坐标轴
+  enableOrbitControls: true,       // 轨道控制器
+};
+```
+
+### src/game/SceneManager.ts（场景管理器）
+
+```typescript
+class SceneManager {
+  register(...scenes: BaseScene[])  // 注册场景
+  switchTo(key: SceneKey)           // 切换场景（自动调用 exit/init/enter）
+  update(dt, elapsed)               // 每帧更新活跃场景
+  dispose()                         // 销毁所有场景
+}
+```
+
+### src/game/scenes/BaseScene.ts（场景基类）
+
+```typescript
+abstract class BaseScene {
+  readonly key: SceneKey;
+  readonly scene: THREE.Scene;    // 每个场景拥有独立的 Three.Scene
+
+  protected onInit(): void {}     // 首次进入时调用（创建 3D 对象）
+  protected onEnter(): void {}    // 每次切入时调用
+  protected onUpdate(dt, elapsed): void {}  // 每帧调用
+  protected onExit(): void {}     // 离开时调用
+  protected onDispose(): void {}  // 销毁时调用
+
+  protected goToScene(key): void  // 切换到其他场景
+}
+```
+
+**使用示例**：
+
+```typescript
+import { BaseScene } from "./BaseScene";
+import { SceneKeys } from "../SceneKeys";
+
+export class MyScene extends BaseScene {
+  private cube!: THREE.Mesh;
+
+  constructor() {
+    super(SceneKeys.Main);
+  }
+
+  protected onInit(): void {
+    const geo = new THREE.BoxGeometry(1, 1, 1);
+    const mat = new THREE.MeshStandardMaterial({ color: 0xff6600 });
+    this.cube = new THREE.Mesh(geo, mat);
+    this.scene.add(this.cube);
+  }
+
+  protected onUpdate(dt: number): void {
+    this.cube.rotation.y += dt;
+  }
+}
+```
+
+### src/game/utils/ViewportManager.ts（响应式视口）
+
+```typescript
+class ViewportManager {
+  enable()    // 开始监听 ResizeObserver
+  disable()   // 停止监听
+  refresh()   // 手动触发一次 resize
+  getSize()   // 获取当前 { width, height, aspect }
+}
+```
+
+与 Phaser 的 `resize → reload` 不同，Three.js 版使用 ResizeObserver 动态更新，无需刷新页面。
+
+### src/game/utils/AssetLoader.ts（资源加载器）
+
+```typescript
+const loader = new AssetLoader();
+
+await loader.loadAll({
+  textures:     [{ key: "wood", url: woodTextureUrl }],
+  models:       [{ key: "character", url: characterGlbUrl }],
+  audio:        [{ key: "bgm", url: bgmMp3Url }],
+  cubeTextures: [{ key: "skybox", urls: [px, nx, py, ny, pz, nz] }],
+}, (progress) => {
+  console.log(`Loading: ${(progress * 100).toFixed(0)}%`);
+});
+
+const tex  = loader.getTexture("wood");      // THREE.Texture
+const gltf = loader.getModel("character");   // GLTF (含 scene/animations)
+const buf  = loader.getAudioBuffer("bgm");   // AudioBuffer
+```
+
+### src/game/scenes/MainScene.ts（Hello Three.js 空白主场景）
+
+显示旋转 Torus Knot + 网格地面 + 坐标轴 + "Hello Three.js!" 文字精灵。
+作为开发起点，替换 `onInit()` / `onUpdate()` 内容即可开始编写游戏逻辑。
+
+---
+
+## 架构对比：Phaser vs Three.js
+
+| 概念 | Phaser skill | Three.js skill |
+|------|-------------|---------------|
+| **渲染器** | `Phaser.Game` (内置 WebGL) | `THREE.WebGLRenderer` (显式创建) |
+| **场景系统** | `Phaser.Scene` (引擎内置) | `BaseScene` + `SceneManager` (自建) |
+| **相机** | 2D 隐式相机 | `PerspectiveCamera` (显式 3D) |
+| **生命周期** | `preload/create/update` | `onInit/onEnter/onUpdate/onExit/onDispose` |
+| **资源加载** | `this.load.image()` (内置) | `AssetLoader` (封装 TextureLoader/GLTFLoader) |
+| **响应式** | resize → reload | ResizeObserver (无需刷新) |
+| **Loading UI** | Phaser 场景内绘制 | HTML overlay (CSS 动画) |
+| **坐标系** | 2D 左上角原点 | 3D 右手坐标系 (Y-up) |
+| **设计基准** | 750×1334 dp | 视口宽高比 (aspect ratio) |
+
+---
+
+## 3D 坐标系与基础概念
+
+### 坐标系
+
+- **右手坐标系**：X 向右，Y 向上，Z 朝屏幕外（标准 Three.js / OpenGL 约定）
+- **单位**：1 Three.js 单位 = 1 米（推荐约定，方便物理/灯光计算）
+- **相机默认位置**：(0, 3, 5) 看向原点 (0, 0, 0)
+
+### PBR 渲染管线
+
+| 参数 | 默认值 | 说明 |
+|------|-------|------|
+| `antialias` | true | 抗锯齿 |
+| `shadows` | true | PCF 软阴影 |
+| `toneMapping` | ACESFilmic | ACES 电影级色调映射 |
+| `toneMappingExposure` | 1.0 | 曝光度 |
+| `maxPixelRatio` | 2 | HiDPI 像素比上限（防止 3× 设备过度渲染） |
+
+### 使用规则
+
+1. 每个场景继承 `BaseScene`，在 `onInit()` 中创建 3D 对象
+2. 通过 `this.scene.add(object)` 添加到场景图
+3. `onUpdate(dt, elapsed)` 中执行动画逻辑，`dt` 单位秒
+4. 切场景用 `this.goToScene(SceneKeys.XXX)`
+5. 重型资源在 `PreloaderScene.getManifest()` 中声明，通过 `AssetLoader` 预加载
+6. `onDispose()` 中清理事件监听等自定义资源（GPU 资源由基类自动清理）
+
+---
+
+## 移动端适配清单
+
+| 特性 | 实现位置 | 说明 |
+|------|---------|------|
+| **HiDPI 清晰度** | `StartGame()` | `maxPixelRatio: 2` 限制过高 DPR |
+| **禁止页面缩放** | `index.html` | `viewport` meta：`user-scalable=no, maximum-scale=1` |
+| **iOS 全屏** | `index.html` | `apple-mobile-web-app-capable` + `black-translucent` 状态栏 |
+| **安全区（刘海屏）** | `index.css` | `env(safe-area-inset-*)` padding |
+| **禁止文字选中** | `index.css` | `user-select: none` |
+| **禁止长按菜单** | `index.css` | `-webkit-touch-callout: none` |
+| **禁止 iOS 回弹** | `index.css` | `overscroll-behavior: none; touch-action: none` |
+| **禁止点击高亮** | `index.css` | `-webkit-tap-highlight-color: transparent` |
+| **响应式 resize** | `ViewportManager` | ResizeObserver 自动更新 Renderer + Camera |
+| **Canvas 全屏** | `index.css` | `width: 100% !important; height: 100% !important` |
+
+---
+
+## 新增场景的步骤
+
+1. 在 `SceneKeys.ts` 添加新的场景键：
+
+```typescript
+export const SceneKeys = {
+  Preloader: "Preloader",
+  Main: "Main",
+  GameOver: "GameOver",   // ← 新增
+} as const;
+```
+
+2. 创建场景类（继承 `BaseScene`）：
+
+```typescript
+// src/game/scenes/GameOverScene.ts
+import { BaseScene } from "./BaseScene";
+import { SceneKeys } from "../SceneKeys";
+
+export class GameOverScene extends BaseScene {
+  constructor() { super(SceneKeys.GameOver); }
+
+  protected onInit(): void {
+    // 创建 3D 对象...
+  }
+
+  protected onUpdate(dt: number): void {
+    // 动画逻辑...
+  }
+}
+```
+
+3. 在 `src/game/index.ts` 注册场景：
+
+```typescript
+import { GameOverScene } from "./scenes/GameOverScene";
+
+sceneManager.register(
+  new PreloaderScene(),
+  new MainScene(),
+  new GameOverScene(),  // ← 新增
+);
+```
+
+4. 在任意场景中切换：
+
+```typescript
+this.goToScene(SceneKeys.GameOver);
+```
+
+---
+
+## Imports
+
+本 skill 是所有 Three.js 组件的基础，无 skill 层依赖。
+
+**配套 skill（推荐一起使用）：**
+- `webpack_build.aicomponent` — 如需自定义 webpack 配置（本 skill 已内置基础版 webpack.config.js）
+
+**不再需要单独安装**（已内置）：
+- 资源模块声明 — 已合入 `globals.d.ts`
+- 响应式视口 — `ViewportManager.ts` 已内置
+- 资源加载器 — `AssetLoader.ts` 已内置
+
+## Skill Definition
+
+```yaml
+tools:
+  - read_file
+  - write_file
+inputs:
+  - source: ref/main.ts          (webpack entry)
+  - source: ref/index.html       (HTML container with viewport meta + loading overlay)
+  - source: ref/index.css        (fullscreen + mobile + loading styles)
+  - source: ref/globals.d.ts     (asset module declarations: images/audio/3D models/HDR + __DEV__)
+  - source: ref/tsconfig.json    (TypeScript config)
+  - source: ref/index.ts         (StartGame function)
+  - source: ref/GameConfig.ts    (generic game config: rendering/camera/lighting/debug)
+  - source: ref/SceneKeys.ts     (scene key enum)
+  - source: ref/SceneManager.ts  (scene lifecycle manager)
+  - source: ref/BaseScene.ts     (abstract scene base class)
+  - source: ref/PreloaderScene.ts (preloader scene with HTML overlay)
+  - source: ref/MainScene.ts     (main scene: Hello Three.js skeleton)
+  - source: ref/ViewportManager.ts (responsive viewport via ResizeObserver)
+  - source: ref/AssetLoader.ts   (unified asset loader: Texture/GLTF/Audio/CubeTexture)
+outputs:
+  - projectSkeleton: 15 files forming a complete runnable Three.js project
+  - threeDep: three ^0.172.0 + @types/three ^0.172.0 npm dependencies
+  - sceneLifecycle: BaseScene + SceneManager multi-scene architecture
+  - pbrPipeline: ACES Filmic tone mapping + PCF soft shadows + HiDPI
+  - responsiveViewport: ViewportManager with ResizeObserver
+  - assetLoading: AssetLoader supporting Texture/GLTF/Audio/CubeTexture
+  - mobileAdaptation: viewport meta, safe areas, touch handling
+```
+
+## Recipe
+
+| 决策 | 原因 |
+|-----|-----|
+| **BaseScene + SceneManager** | Three.js 没有内置场景生命周期，需自建；保持与 Phaser skill 相似的开发体验 |
+| **HTML Loading Overlay** | 加载期间无需 Three.js 渲染，CSS 动画更轻量；加载完成后 `hidden` 类触发淡出 |
+| **ResizeObserver 而非 reload** | 3D 场景状态丰富（相机位置、动画进度），reload 会丢失；ResizeObserver 高效且无副作用 |
+| **maxPixelRatio: 2** | 3D 渲染远比 2D 昂贵，3× 设备（如 iPhone）全 DPR 渲染会严重影响帧率 |
+| **ACES Filmic 色调映射** | 影视级色彩表现，比 Linear 更自然，是 PBR 管线的标准选择 |
+| **PCF 软阴影** | 平衡画质与性能；如需更高质量可切 VSM，更轻量可关闭 |
+| **OrbitControls 可配置** | 开发调试必备，正式游戏可通过 `enableOrbitControls: false` 关闭 |
+| **每场景独立 THREE.Scene** | 隔离场景图、灯光、后处理；切场景时只需切 renderer.render 的 target |
+| **AssetLoader 按 key 存储** | 全局唯一 key → 资源映射，任何场景都可按 key 取用；避免重复加载 |
+| **ES2020 target** | Three.js 广泛使用现代 JS 特性（class fields、可选链），ES5 target 会导致问题 |
+
+## Adapter
+
+- **Role**: `threejsEngine` — Three.js 3D 游戏引擎基座，所有 Three.js 系 skill 的运行时依赖
+- **Provides**: `StartGame()` 启动入口、`SceneManager` 场景管理器、`BaseScene` 场景抽象基类、`ViewportManager` 响应式视口、`AssetLoader` 统一资源加载器、`GameConfig` 渲染配置
+- **Requires**: 无 skill 层依赖（`webpack_build.aicomponent` 为配套工具）
+- **Consumed by**: 所有以 `threejs.aicomponent` 为 Imports 硬依赖的 skill，包括 `camera_controller_3d`、`tray_container`（3D Mesh 模式）、`slide_out_to_tray_animation`（3D 模式）等
+- **Integration point**: `src/main.ts` 在 `DOMContentLoaded` 中调用 `StartGame("game-container")`

package/skills/threejs.aicomponent/manifest.json

@@ -0,0 +1,166 @@
+{
+  "schemaVersion": 1,
+  "atomId": "threejs.aicomponent",
+  "bundleType": "aicomponent",
+  "category": "engine",
+  "mode": "fixed",
+  "label": { "zh": "Three.js 3D 引擎", "en": "Three.js 3D engine" },
+  "tags": ["three", "threejs", "game-engine", "webgl", "3d", "scene", "runtime", "skeleton", "responsive", "mobile"],
+  "bindingRoles": ["gameEngine"],
+  "scaffold": {
+    "files": {
+      "src/main.ts": {
+        "source": "ref/main.ts",
+        "mode": "full",
+        "weight": 10,
+        "_comment": "webpack 入口：import CSS + 调用 StartGame"
+      },
+      "src/index.html": {
+        "source": "ref/index.html",
+        "mode": "full",
+        "weight": 10,
+        "_comment": "HTML 容器，包含 viewport meta + #game-container + #loading-overlay"
+      },
+      "src/index.css": {
+        "source": "ref/index.css",
+        "mode": "full",
+        "weight": 10,
+        "_comment": "全屏样式：移动端适配、安全区、Loading overlay"
+      },
+      "globals.d.ts": {
+        "source": "ref/globals.d.ts",
+        "mode": "full",
+        "weight": 10,
+        "_comment": "资源模块声明（图片/音频/3D模型/HDR）+ __DEV__ 全局变量"
+      },
+      "tsconfig.json": {
+        "source": "ref/tsconfig.json",
+        "mode": "merge-json",
+        "weight": 10,
+        "_comment": "TypeScript 配置：target es2020, moduleResolution bundler, paths assets/*"
+      },
+      "src/game/index.ts": {
+        "source": "ref/index.ts",
+        "mode": "full",
+        "weight": 10,
+        "_comment": "StartGame(containerId) 游戏入口，配置 Renderer + Camera + SceneManager + 主循环"
+      },
+      "src/game/GameConfig.ts": {
+        "source": "ref/GameConfig.ts",
+        "mode": "full",
+        "weight": 10,
+        "_comment": "通用游戏配置：渲染参数、相机、灯光、调试开关"
+      },
+      "src/game/SceneKeys.ts": {
+        "source": "ref/SceneKeys.ts",
+        "mode": "full",
+        "weight": 10,
+        "_comment": "场景名枚举，避免字符串硬编码"
+      },
+      "src/game/SceneManager.ts": {
+        "source": "ref/SceneManager.ts",
+        "mode": "full",
+        "weight": 10,
+        "_comment": "场景生命周期管理器：注册、切换、更新、销毁"
+      },
+      "src/game/scenes/BaseScene.ts": {
+        "source": "ref/BaseScene.ts",
+        "mode": "full",
+        "weight": 10,
+        "_comment": "场景基类：统一 init/enter/update/exit/dispose 生命周期"
+      },
+      "src/game/scenes/PreloaderScene.ts": {
+        "source": "ref/PreloaderScene.ts",
+        "mode": "full",
+        "weight": 10,
+        "_comment": "预加载场景：HTML overlay 进度条 + AssetLoader 批量加载"
+      },
+      "src/game/scenes/MainScene.ts": {
+        "source": "ref/MainScene.ts",
+        "mode": "full",
+        "weight": 10,
+        "_comment": "主游戏场景：Hello Three.js（旋转 Torus Knot + 网格 + 坐标轴）"
+      },
+      "src/game/utils/ViewportManager.ts": {
+        "source": "ref/ViewportManager.ts",
+        "mode": "full",
+        "weight": 10,
+        "_comment": "响应式视口管理：ResizeObserver 自动更新 Renderer 尺寸与 Camera 宽高比"
+      },
+      "src/game/utils/AssetLoader.ts": {
+        "source": "ref/AssetLoader.ts",
+        "mode": "full",
+        "weight": 10,
+        "_comment": "统一资源加载器：Texture/GLTF/Audio/CubeTexture 批量加载 + 进度回调"
+      },
+      "package.json": {
+        "source": "ref/package.json",
+        "mode": "merge-json",
+        "weight": 10,
+        "_comment": "项目依赖：three + @types/three + webpack + ts-loader 等"
+      },
+      "webpack.config.js": {
+        "source": "ref/webpack.config.js",
+        "mode": "full",
+        "weight": 10,
+        "_comment": "Webpack 5 配置：ts-loader + 3D 模型资源 + HDR + __DEV__"
+      }
+    },
+    "packageJson": {
+      "dependencies": {
+        "three": { "version": "^0.172.0", "weight": 10 }
+      },
+      "devDependencies": {
+        "@types/three": { "version": "^0.172.0", "weight": 10 }
+      }
+    }
+  },
+  "exports": [
+    { "name": "StartGame",        "kind": "function",  "location": "src/game/index.ts" },
+    { "name": "GameInstance",      "kind": "type",      "location": "src/game/index.ts" },
+    { "name": "GameConfig",        "kind": "object",    "location": "src/game/GameConfig.ts" },
+    { "name": "SceneKeys",         "kind": "object",    "location": "src/game/SceneKeys.ts" },
+    { "name": "SceneManager",      "kind": "class",     "location": "src/game/SceneManager.ts" },
+    { "name": "BaseScene",         "kind": "class",     "location": "src/game/scenes/BaseScene.ts" },
+    { "name": "PreloaderScene",    "kind": "class",     "location": "src/game/scenes/PreloaderScene.ts" },
+    { "name": "MainScene",         "kind": "class",     "location": "src/game/scenes/MainScene.ts" },
+    { "name": "ViewportManager",   "kind": "class",     "location": "src/game/utils/ViewportManager.ts" },
+    { "name": "AssetLoader",       "kind": "class",     "location": "src/game/utils/AssetLoader.ts" }
+  ],
+  "neutralDescriptor": {
+    "geometry": "3D WebGL game engine runtime with complete project skeleton: scene lifecycle manager (Preloader→Main), PBR rendering pipeline (shadows, tone mapping), responsive viewport (ResizeObserver), asset loading (Texture/GLTF/Audio/CubeTexture), OrbitControls",
+    "layers": ["rendering", "scene-management", "input-system", "responsive-viewport", "asset-loading", "project-scaffold"],
+    "replaceable": ["camera type/position", "lighting setup", "scene list", "background color", "tone mapping", "renderer settings"]
+  },
+  "usageHints": [
+    "本 skill 提供完整 Three.js 空项目骨架（15 个文件），包含 package.json + webpack.config.js，scaffold 后 pnpm install && pnpm dev 即可运行",
+    "项目结构：package.json / webpack.config.js / tsconfig.json / globals.d.ts + src/ (12个源文件) + assets/models/ + assets/textures/ + assets/sounds/",
+    "场景生命周期：PreloaderScene（资源加载 + HTML 进度条）→ MainScene（主游戏场景）",
+    "BaseScene 抽象类提供 onInit/onEnter/onUpdate/onExit/onDispose 五个可覆盖方法",
+    "ViewportManager 使用 ResizeObserver 自动处理窗口大小变化，无需刷新页面",
+    "AssetLoader 支持 Texture/GLTF/Audio/CubeTexture 四种资源类型的批量加载 + 进度回调",
+    "PBR 渲染管线：ACES Filmic 色调映射 + PCF 软阴影 + HiDPI 像素比限制",
+    "globals.d.ts 已包含 3D 模型（glb/gltf/fbx/obj）和 HDR/EXR 环境贴图的模块声明",
+    "GameConfig.enableOrbitControls 控制 OrbitControls 开关，带阻尼平滑",
+    "assets/ 目录约定：assets/models/（3D 模型）+ assets/textures/（贴图）+ assets/sounds/（音频），webpack alias 已配置为 'assets' 短路径"
+  ],
+  "files": {
+    "skill":            "SKILL.md",
+    "mainEntry":        "ref/main.ts",
+    "html":             "ref/index.html",
+    "css":              "ref/index.css",
+    "globals":          "ref/globals.d.ts",
+    "tsconfig":         "ref/tsconfig.json",
+    "packageJson":      "ref/package.json",
+    "webpackConfig":    "ref/webpack.config.js",
+    "gameEntry":        "ref/index.ts",
+    "gameConfig":       "ref/GameConfig.ts",
+    "sceneKeys":        "ref/SceneKeys.ts",
+    "sceneManager":     "ref/SceneManager.ts",
+    "baseScene":        "ref/BaseScene.ts",
+    "preloaderScene":   "ref/PreloaderScene.ts",
+    "mainScene":        "ref/MainScene.ts",
+    "viewportManager":  "ref/ViewportManager.ts",
+    "assetLoader":      "ref/AssetLoader.ts"
+  }
+}