# 《我要当市长》3D 原型 · 微信小游戏适配评估

> 日期：2026-10-08 ｜ 对象：`/vol1/ai/projects/wyszz-new/3d-spike/`（Three.js 0.186.1 原型）
> **声明：本轮没有微信开发者工具、没有真实手机。浏览器验证 ≠ 微信小游戏验证。凡未实测的一律标注「通过资料推断」或「尚未验证」。**

---

## 一、原型在浏览器里实际用到的 API 清单

| 分类 | 具体 API | 使用位置 |
| --- | --- | --- |
| 全局对象 | `window.addEventListener('error' / 'unhandledrejection' / 'resize' / 'orientationchange' / 'pointermove' / 'pointerup' / 'pointercancel')`、`window.setTimeout/clearTimeout`、`window.devicePixelRatio`、`window.innerWidth/innerHeight`、`window.__spike`（调试接口） | `src/platform/browser.ts`、`src/main.ts` |
| DOM | `document.createElement('canvas')`、`document.getElementById('app' / 'name-tag')`、`Element.classList`、`textContent`、`appendChild` | `src/platform/browser.ts` |
| CSS | 页面布局（`#app` / `#name-tag` / `#hint`）、`touch-action:none`、opacity 过渡 | `index.html` |
| 指针输入 | Pointer Events：`pointerdown/move/up/cancel`（`pointerId` / `pointerType` / `clientX/Y`） | `src/platform/browser.ts` |
| 鼠标滚轮 | `WheelEvent`（实验缩放） | `src/platform/browser.ts` |
| 渲染 | `canvas.getContext('webgl2'/'webgl')`（由 three `WebGLRenderer` 调用）、`getBoundingClientRect`、`setSize`、阴影贴图（framebuffer） | three.js 内部 + `src/main.ts` |
| 动画帧 | `requestAnimationFrame`（three `setAnimationLoop`）、`performance.now()` | three.js 内部 + `src/main.ts` |
| three 内部浏览器依赖 | `document.createElementNS`（纹理上传/图片）、`Image`、`XMLHttpRequest`（FileLoader；本原型**未加载**任何外部资源） | three.js 内部 |

**本原型未使用**：音视频、localStorage、fetch/XHR 资源加载、Web Worker、WebGL 浮点纹理、后期处理扩展、字体文件、外部贴图/模型。

---

## 二、哪些 API 在微信小游戏里不可用 / 需要替换

| 浏览器 API | 微信小游戏现状 | 替换方案 |
| --- | --- | --- |
| `window` / `document` / DOM / CSS | ❌ 不存在（小游戏无 DOM/BOM，只有一个全屏 canvas） | UI（`#name-tag` 名称条、`#hint` 提示条）改为 **canvas 2D 文字**或 `wx.showToast`；布局代码删除 |
| `document.createElement('canvas')` | ❌ | `wx.createCanvas()`（**第一次调用返回上屏画布**，其后为离屏画布） |
| Pointer Events | ❌ | `wx.onTouchStart / onTouchMove / onTouchEnd / onTouchCancel`；`touch.identifier` → `SpikePointerEvent.id`，`touch.clientX/Y` → `x/y`（已按此形态定义在 `src/platform/types.ts`） |
| `WheelEvent` | ❌ 不存在滚轮 | 移除；缩放只保留双指 pinch（`touches.length === 2` 距离比） |
| `window.devicePixelRatio` | ❌ | `wx.getSystemInfoSync().pixelRatio` |
| `resize` / `orientationchange` | ❌ | `wx.onWindowResize`；并用 `game.json` 固定竖屏（`deviceOrientation: "portrait"`） |
| `performance.now()` | ⚠️ | 小游戏全局 `performance`（部分基础库）或 `Date.now()` 兜底 |
| `requestAnimationFrame` | ⚠️ | 小游戏全局提供；若缺由 `weapp-adapter` 补齐 |
| `window.__spike` 调试接口 | ❌ | 移除或挂在 `GameGlobal`（开发期保留、发布剔除） |
| XHR / `Image`（three 内部） | ❌ | `wx.request` / `wx.getFileSystemManager` / `wx.createImage`（由适配层补齐） |
| WebGL 上下文 | ✅ 有 `canvas.getContext('webgl')` | 直接可用；**WebGL2 及扩展（浮点纹理、`EXT_color_buffer_float` 等）在真机的可用性尚未验证** |

---

## 三、是否依赖 window / document / DOM / CSS / WebGL 扩展？

- **DOM / CSS 依赖：有，但集中在两处**，属于可控面：
  1. `index.html`（页面骨架 + CSS）；
  2. `src/platform/browser.ts`（画布创建、指针、滚轮、名称展示）——这是**唯一**允许碰 DOM 的文件，`src/main.ts` 只额外用了 `window.addEventListener('error')` 与 `window.__spike` 调试接口。
- **three.js 内部 DOM 依赖：有**（canvas/Image/createElementNS/XHR），需靠 `weapp-adapter` 或 `three-platformize` 的平台层补齐。
- **WebGL 扩展：**three 阴影贴图用标准 framebuffer + 深度纹理；PCFSoft 阴影在 WebGL1/2 下路径不同。**真机表现尚未验证**。

---

## 四、初始化 / 触摸 / 画布 / 资源加载的替换对照

| 环节 | 浏览器实现（当前） | 微信小游戏实现（待做） |
| --- | --- | --- |
| 入口 | `index.html` + `<script type="module" src="/src/main.ts">` | `game.js` 入口 + 打包后的 JS（**不能用 ES module 直接引入**，需打包为单文件/分包） |
| 画布 | `document.createElement('canvas')` 挂到 `#app` | `wx.createCanvas()`，`canvas.width/height = 窗口 × pixelRatio`，`style` 概念不存在 |
| 渲染器 | `new THREE.WebGLRenderer({ canvas })` | 同一行，canvas 来源换成 `wx.createCanvas()` |
| 输入 | Pointer Events 归一化为 `SpikePointerEvent` | `wx.onTouch*` 归一化为同一个 `SpikePointerEvent`（接口已就位） |
| 缩放 | 滚轮 + 双指 pinch | 只保留双指 pinch |
| 名称展示 | DOM `#name-tag` | canvas 2D 文字 / `wx.showToast` |
| 资源加载 | 无外部资源（全程序化几何） | 未来 glTF：`GLTFLoader` 的 FileLoader 需换 `wx.request`；纹理换 `wx.createImage` |
| 生命周期 | 页面可见性（未处理） | `wx.onShow / onHide` 暂停/恢复渲染循环 |
| 适配层落点 | `src/platform/browser.ts` | 新增 `src/platform/wechat.ts`，`main.ts` 按平台选择实现 |

**结论：接口切面已经按「一个 PlatformAdapter 换实现」设计好，微信端不需要动 3D 场景/控制/拾取代码。**

---

## 五、Three.js 是否已有微信小游戏适配方式？

| 方案 | 说明 | 状态（资料推断） |
| --- | --- | --- |
| `three-platformize`（deepkolos） | `THREE.PLATFORM.set(new WechatPlatform(canvas))`，宣称适配微信**小游戏真机 + 模拟器**、淘宝、字节 | GitHub 592 stars；CHANGELOG 停在 2021 年，**维护状态存疑** |
| `weapp-adapter`（微信官方模板内置 + finscn 分支） | 补 `document`/`Image`/`XHR` 等浏览器 API，社区文章普遍用它跑 three | 多篇实战文章（腾讯云/知乎/indienova）确认路线可行 |
| 社区 demo（`wx_game_three` 等） | three + weapp-adapter 的小游戏模板 | 公开可查 |
| three 官方 | **没有**官方微信小游戏适配包（WebGPU/WebGL 均面向浏览器） | — |

> 以上均为**通过资料推断**：路线存在且有先例，但没有一条在本机验证过。

---

## 六、结论分级（强制声明）

| 状态 | 内容 |
| --- | --- |
| **已验证（本机 headless 浏览器）** | 正交相机；鼠标拖动旋转 10 次；触摸拖动 10 次（CDP `Input.dispatchTouchEvent`）；射线点击 4 对象名称一致 + 空白处不误报；阴影渲染；390×844 竖屏显示；Docker 无头构建（tsc + vite）；运行时 0 报错 |
| **通过资料推断** | three.js 经适配层可在微信小游戏运行；`wx.onTouch*` 与指针事件可一一映射；包体可通过分包/引擎插件控制；LayaAir 官方微信发布链路成熟但依赖 GUI IDE |
| **尚未验证** | 微信开发者工具运行；微信真机渲染与性能；WebGL2/扩展可用性；iOS 微信内存表现；微信主包/分包实际占用；触摸手感与 `touchcancel` 行为 |
| **真机未验证** | ✅ 本轮没有任何真实手机测试 |
| **微信端未验证** | ✅ 本轮没有微信开发者工具，微信小游戏未做任何运行验证 |
