jayli · jayli · May 27, 2026 · May 27, 2026
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -221,3 +221,10 @@ npm run lint
 
 ## 代码提交
 任何修改都不能自动提交代码，必须等待明确的指令才能提交。
+
+## Active Technologies
+- JavaScript (ES Modules, 无构建步骤) + Three.js 0.160.0 → 0.184.0 (CDN via jsdelivr) (001-upgrade-threejs-r184)
+- IndexedDB (持久化，本次升级不涉及) (001-upgrade-threejs-r184)
+
+## Recent Changes
+- 001-upgrade-threejs-r184: Added JavaScript (ES Modules, 无构建步骤) + Three.js 0.160.0 → 0.184.0 (CDN via jsdelivr)
diff --git a/index.html b/index.html
@@ -192,9 +192,9 @@ <h2 style="margin:0">物品清单 (点击装备)</h2>
     <script type="importmap">
        {
             "imports": {
-                "three": "https://cdn.jsdelivr.net/npm/three@0.160.0/build/three.module.js",
-                "three/addons/": "https://cdn.jsdelivr.net/npm/three@0.160.0/examples/jsm/",
-                "stats": "https://cdn.jsdelivr.net/npm/three@0.160.0/examples/jsm/libs/stats.module.js"
+                "three": "https://cdn.jsdelivr.net/npm/three@0.184.0/build/three.module.js",
+                "three/addons/": "https://cdn.jsdelivr.net/npm/three@0.184.0/examples/jsm/",
+                "stats": "https://cdn.jsdelivr.net/npm/three@0.184.0/examples/jsm/libs/stats.module.js"
             }
         }
     </script>

diff --git a/specs/001-upgrade-threejs-r184/checklists/requirements.md b/specs/001-upgrade-threejs-r184/checklists/requirements.md
@@ -0,0 +1,35 @@
+# Specification Quality Checklist: Three.js r160 → r184 升级
+
+**Purpose**: Validate specification completeness and quality before proceeding to planning
+**Created**: 2026-05-27
+**Feature**: [spec.md](../spec.md)
+
+## Content Quality
+
+- [x] No implementation details (languages, frameworks, APIs)
+- [x] Focused on user value and business needs
+- [x] Written for non-technical stakeholders
+- [x] All mandatory sections completed
+
+## Requirement Completeness
+
+- [x] No [NEEDS CLARIFICATION] markers remain
+- [x] Requirements are testable and unambiguous
+- [x] Success criteria are measurable
+- [x] Success criteria are technology-agnostic (no implementation details)
+- [x] All acceptance scenarios are defined
+- [x] Edge cases are identified
+- [x] Scope is clearly bounded
+- [x] Dependencies and assumptions identified
+
+## Feature Readiness
+
+- [x] All functional requirements have clear acceptance criteria
+- [x] User scenarios cover primary flows
+- [x] Feature meets measurable outcomes defined in Success Criteria
+- [x] No implementation details leak into specification
+
+## Notes
+
+- FR-001 和 FR-002 提到了具体文件名，这在升级类任务中是合理的（属于范围界定而非实现细节）
+- 所有验证项通过，spec 已就绪
diff --git a/specs/001-upgrade-threejs-r184/plan.md b/specs/001-upgrade-threejs-r184/plan.md
@@ -0,0 +1,63 @@
+# Implementation Plan: Three.js r160 → r184 升级
+
+**Branch**: `001-upgrade-threejs-r184` | **Date**: 2026-05-27 | **Spec**: [spec.md](./spec.md)
+**Input**: Feature specification from `/specs/001-upgrade-threejs-r184/spec.md`
+
+## Summary
+
+将项目的 Three.js 从 r160 (0.160.0) 升级到 r184 (0.184.0)。核心改动为 CDN 版本号变更和 `BufferAttribute.updateRange` API 迁移。升级保持 WebGLRenderer 路径不变，为未来 WebGPU 迁移铺路。
+
+## Technical Context
+
+**Language/Version**: JavaScript (ES Modules, 无构建步骤)
+**Primary Dependencies**: Three.js 0.160.0 → 0.184.0 (CDN via jsdelivr)
+**Storage**: IndexedDB (持久化，本次升级不涉及)
+**Testing**: Playwright headless 浏览器测试 (`node command/run-tests.js`)
+**Target Platform**: 现代 Web 浏览器 (WebGL 2.0)
+**Project Type**: 纯客户端体素游戏（无后端）
+**Performance Goals**: 60 fps，区块加载无卡顿
+**Constraints**: 无构建步骤，ES Modules + Import Maps 直接加载 CDN
+**Scale/Scope**: 单文件改动 3 处，影响面极小
+
+## Constitution Check
+
+*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
+
+| 原则 | 状态 | 说明 |
+|------|------|------|
+| I. 面向对象与逻辑分层 | ✅ 通过 | 不改变架构分层 |
+| II. 内存效率与垃圾回收 | ✅ 通过 | `addUpdateRange` 语义与原 API 等价，无额外内存开销 |
+| III. 主动资源释放 | ✅ 通过 | 不影响资源释放机制 |
+| IV. WebGL/Three.js 性能优化 | ✅ 通过 | InstancedMesh 机制不变，`addUpdateRange` 支持更精确的增量更新 |
+| V. 简洁性与核心机制 | ✅ 通过 | 最小改动量，无过度工程 |
+| VI. 资源管理与学习参考 | ✅ 通过 | 不涉及资源目录 |
+
+**GATE RESULT**: 全部通过，无违反项。
+
+## Project Structure
+
+### Documentation (this feature)
+
+```text
+specs/001-upgrade-threejs-r184/
+├── plan.md              # This file
+├── spec.md              # Feature specification
+├── research.md          # Phase 0 output
+├── checklists/
+│   └── requirements.md  # Spec quality checklist
+└── tasks.md             # Phase 2 output (by /speckit.tasks)
+```
+
+### Source Code (affected files)
+
+```text
+index.html                              # Import Maps CDN 版本号
+src/core/GlobalInstancedMeshManager.js  # updateRange → addUpdateRange
+src/core/Engine.js                      # 可能需要 outputColorSpace 设置
+```
+
+**Structure Decision**: 本次升级是版本号变更 + API 适配，不新增文件，仅修改现有文件。
+
+## Complexity Tracking
+
+无违反项，不需要填写。
diff --git a/specs/001-upgrade-threejs-r184/quickstart.md b/specs/001-upgrade-threejs-r184/quickstart.md
@@ -0,0 +1,44 @@
+# Quickstart: Three.js r160 → r184 升级
+
+## 改动清单
+
+### 1. index.html — CDN 版本号
+
+将 Import Maps 中的三处 `0.160.0` 改为 `0.184.0`：
+
+```
+"three": "https://cdn.jsdelivr.net/npm/three@0.184.0/build/three.module.js"
+"three/addons/": "https://cdn.jsdelivr.net/npm/three@0.184.0/examples/jsm/"
+"stats": "https://cdn.jsdelivr.net/npm/three@0.184.0/examples/jsm/libs/stats.module.js"
+```
+
+### 2. GlobalInstancedMeshManager.js — updateRange 迁移
+
+替换 `updateRange.offset` / `updateRange.count` 为 `addUpdateRange`：
+
+```javascript
+// 替换前
+this.mesh.instanceMatrix.updateRange.offset = offset;
+this.mesh.instanceMatrix.updateRange.count = count;
+
+// 替换后
+this.mesh.instanceMatrix.clearUpdateRanges();
+this.mesh.instanceMatrix.addUpdateRange(offset, count);
+```
+
+### 3. Engine.js — 颜色空间（视情况）
+
+如果画面出现色偏，在 renderer 初始化后添加：
+
+```javascript
+this.renderer.outputColorSpace = THREE.SRGBColorSpace;
+```
+
+## 验证步骤
+
+1. `npm run start` 启动开发服务器
+2. 打开浏览器访问游戏
+3. 检查控制台无报错
+4. 放置/删除方块验证渲染正常
+5. `node command/run-tests.js` 确认测试通过
+6. `npm run lint` 确认无新增错误
diff --git a/specs/001-upgrade-threejs-r184/research.md b/specs/001-upgrade-threejs-r184/research.md
@@ -0,0 +1,83 @@
+# Research: Three.js r160 → r184 升级
+
+## 1. BufferAttribute.updateRange API 迁移
+
+**Decision**: 使用 `addUpdateRange(start, count)` + `clearUpdateRanges()` 替代旧的 `updateRange = {offset, count}`
+
+**Rationale**:
+- r184 中 `BufferAttribute` 不再有单一的 `updateRange` 属性
+- 新 API 使用数组 `updateRanges`，支持多段更新（更灵活）
+- `addUpdateRange(start, count)` 中 `start` 对应旧 API 的 `offset`
+
+**Alternatives considered**:
+- 直接设置 `needsUpdate = true`（全量上传）：性能退化，不可接受
+- 降级到兼容版本（如 r170）：无意义，r184 改动量一样
+
+**Migration pattern**:
+```javascript
+// 旧 API (r160)
+buffer.updateRange.offset = offset;
+buffer.updateRange.count = count;
+buffer.needsUpdate = true;
+
+// 新 API (r184)
+buffer.clearUpdateRanges();
+buffer.addUpdateRange(offset, count);
+buffer.needsUpdate = true;
+```
+
+## 2. 颜色空间管理
+
+**Decision**: 预计无需改动，r160 已使用 `SRGBColorSpace`，r184 默认行为一致
+
+**Rationale**:
+- 项目已使用 `THREE.SRGBColorSpace`（5 处引用）
+- `renderer.outputColorSpace` 在 r164+ 默认为 `SRGBColorSpace`，与项目现有行为一致
+- 项目未使用已废弃的 `outputEncoding` / `sRGBEncoding` / `LinearEncoding`
+
+**Alternatives considered**:
+- 显式设置 `renderer.outputColorSpace = THREE.SRGBColorSpace`：可作为防御性措施，但非必须
+
+## 3. InstancedMesh 兼容性
+
+**Decision**: 无需改动，r184 保持 API 兼容
+
+**Rationale**:
+- `setMatrixAt` / `instanceMatrix` / `InstancedBufferAttribute` 均未变更
+- `mesh.count` 仍为直接属性（非 getter/setter）
+- 自定义 attribute 通过 `geometry.setAttribute` 添加的模式不变
+
+## 4. ShaderMaterial / onBeforeCompile 兼容性
+
+**Decision**: 无需改动
+
+**Rationale**:
+- `ShaderMaterial` 仍支持 GLSL vertex/fragment shader 字符串
+- `onBeforeCompile` 在 WebGLRenderer 路径下仍被调用（r184 源码确认）
+- GLSL 内置函数（`texture2D`、`gl_Position`、`gl_FragColor`）在 WebGL 路径下不变
+
+## 5. CDN 路径结构
+
+**Decision**: 直接替换版本号即可
+
+**Rationale**:
+- `three@0.184.0/build/three.module.js` — 已验证 HTTP 200
+- `three@0.184.0/examples/jsm/loaders/GLTFLoader.js` — 已验证 HTTP 200
+- `three@0.184.0/examples/jsm/utils/BufferGeometryUtils.js` — 已验证 HTTP 200
+- `three@0.184.0/examples/jsm/libs/stats.module.js` — 已验证 HTTP 200
+
+## 6. 其他确认安全的 API
+
+| API | r184 状态 |
+|-----|-----------|
+| `WebGLRenderer` | 存在 |
+| `PCFSoftShadowMap` | 存在 |
+| `ACESFilmicToneMapping` | 存在 |
+| `MeshLambertMaterial` | 存在 |
+| `MeshStandardMaterial` | 存在 |
+| `BoxGeometry` / `PlaneGeometry` | 存在 |
+| `DynamicDrawUsage` | 存在 |
+| `LineSegments` | 存在 |
+| `DirectionalLight` | 存在 |
+| `AudioListener` | 存在 |
+| `Raycaster` | 存在 |
diff --git a/specs/001-upgrade-threejs-r184/spec.md b/specs/001-upgrade-threejs-r184/spec.md
@@ -0,0 +1,91 @@
+# Feature Specification: Three.js r160 → r184 升级
+
+**Feature Branch**: `001-upgrade-threejs-r184`  
+**Created**: 2026-05-27  
+**Status**: Draft  
+**Input**: 将项目的 Three.js 从 r160 (0.160.0) 升级到 r184 (0.184.0)
+
+## User Scenarios & Testing *(mandatory)*
+
+### User Story 1 - CDN 版本升级后游戏正常运行 (Priority: P1)
+
+作为开发者，我希望将 Three.js CDN 引用从 0.160.0 升级到 0.184.0 后，游戏的所有核心功能（渲染、交互、物理）仍然正常工作，不出现运行时错误。
+
+**Why this priority**: 这是升级的基础前提。如果游戏无法正常运行，其他一切都没有意义。
+
+**Independent Test**: 启动开发服务器，进入游戏，执行基本操作（移动、放置方块、挖掘方块），观察控制台无报错，画面正常渲染。
+
+**Acceptance Scenarios**:
+
+1. **Given** CDN 版本号已改为 0.184.0，**When** 启动开发服务器并打开游戏页面，**Then** 游戏正常加载，控制台无 Three.js 相关报错
+2. **Given** 游戏已加载，**When** 玩家移动、挖掘、放置方块，**Then** InstancedMesh 渲染正常，方块显示正确
+3. **Given** 游戏已加载，**When** 触发区块加载/卸载，**Then** 区块正常生成和渲染，无内存泄漏警告
+
+---
+
+### User Story 2 - 已废弃 API 适配 (Priority: P1)
+
+作为开发者，我需要将项目中使用的已废弃 Three.js API（`BufferAttribute.updateRange`）迁移到新版 API（`addUpdateRange`），确保 InstancedMesh 的增量更新机制正常工作。
+
+**Why this priority**: `updateRange` API 在 r184 中已被移除，不适配会导致运行时报错，属于必须完成的阻塞项。
+
+**Independent Test**: 进入游戏后放置/删除多个方块，触发 GlobalInstancedMeshManager 的增量更新逻辑，验证方块渲染正确无闪烁。
+
+**Acceptance Scenarios**:
+
+1. **Given** 使用新的 `addUpdateRange` API，**When** 放置单个方块触发 InstancedMesh 局部更新，**Then** 新方块正确渲染，无视觉闪烁
+2. **Given** 使用新的 `addUpdateRange` API，**When** 批量操作方块触发合并机制，**Then** 合并后的 InstancedMesh 显示正确
+
+---
+
+### User Story 3 - 颜色输出一致性 (Priority: P2)
+
+作为开发者，我需要确保升级后游戏画面的色彩表现与 r160 版本一致，不出现色偏或过亮/过暗。
+
+**Why this priority**: r164+ 默认启用 SRGBColorSpace 输出，可能导致色彩偏差。虽不致命但影响视觉体验。
+
+**Independent Test**: 对比升级前后的游戏画面截图，确认方块材质颜色、天空颜色、光照效果一致。
+
+**Acceptance Scenarios**:
+
+1. **Given** 升级到 r184，**When** 观察游戏场景中方块材质颜色，**Then** 颜色与 r160 版本视觉一致，无明显色偏
+2. **Given** 升级到 r184，**When** 经历白天/夜晚光照切换，**Then** 日夜光照效果表现正常
+
+---
+
+### Edge Cases
+
+- 自定义 ShaderMaterial（水面、雨滴、BatchedMaterial）在 r184 下的 GLSL 兼容性
+- 大量 InstancedMesh 实例（>10000 个方块）时的增量更新性能
+- Worker 传回数据后 InstancedBufferAttribute 更新时序
+
+## Requirements *(mandatory)*
+
+### Functional Requirements
+
+- **FR-001**: index.html 中 Import Maps 的 Three.js CDN 地址 MUST 从 `three@0.160.0` 更新为 `three@0.184.0`（含 build 和 examples/jsm 路径）
+- **FR-002**: `GlobalInstancedMeshManager.js` 中的 `buffer.updateRange = {offset, count}` 模式 MUST 替换为 `buffer.addUpdateRange(start, count)` + `buffer.clearUpdateRanges()`
+- **FR-003**: 升级后所有现有测试 MUST 通过（`node command/run-tests.js`）
+- **FR-004**: 升级后 `npm run lint` MUST 无新增错误
+- **FR-005**: 如果颜色输出有偏差，MUST 通过显式设置 `renderer.outputColorSpace` 修复
+
+### Key Entities
+
+- **Import Map**: index.html 中的 Three.js CDN 路径配置，控制运行时加载的 Three.js 版本
+- **GlobalInstancedMeshManager**: 管理所有 InstancedMesh 实例的增量更新、扩容和回收
+
+## Success Criteria *(mandatory)*
+
+### Measurable Outcomes
+
+- **SC-001**: 游戏启动后控制台无 Three.js 相关报错或 deprecation 警告
+- **SC-002**: 所有自动化测试通过（`node command/run-tests.js` 返回成功）
+- **SC-003**: 方块放置/删除操作响应流畅，无视觉闪烁或渲染异常
+- **SC-004**: 游戏画面色彩与升级前保持视觉一致
+
+## Assumptions
+
+- 项目中仅有 `GlobalInstancedMeshManager.js` 使用了已废弃的 `updateRange` API
+- `ShaderMaterial` 中的 GLSL 代码在 r184 的 WebGLRenderer 路径下仍完全兼容
+- `onBeforeCompile` 钩子在 r184 的 WebGLRenderer 路径下仍正常工作
+- CDN (jsdelivr) 上 three@0.184.0 的目录结构与 0.160.0 一致（build/、examples/jsm/）