img2threejs-reconstruction

Img2threejs Reconstruction

这个 skill 用于 BoardGame 项目里把参考图片转成可用的 Three.js 程序化模型原型；只写 BoardGame 的执行边界、临时目录、素材验收和交付口径，不替官方 img2threejs 工具本身背书。

前置锁定

动手前先锁四件事：

• 问题对象：本轮要做的是哪个游戏资产，例如书本、棋盘、卡牌座、骰塔、道具，不要把临近素材当目标。
• 真相来源：用户给的参考图、官方案例仓库、项目素材目录、规则图或原始图集；截图/缩略图只可辅助定位。
• 目标入口：默认先放 temp/<asset>-three-demo/ 或用户指定临时目录；未获明确授权前不要改正式游戏代码或 public/assets/**。
• 验收口径：先约定是用法总结、结构拆解、临时 Three.js 原型、截图验收，还是正式资产候选。

官方/案例读取

当任务提到 img2threejs、官方 showcase、GitHub 案例或“别人生成的效果”时，先读参考仓库，不要凭印象写模型。

• 优先读用户给定仓库或本地克隆的 README.md、CONTRIBUTING.md、src/demos/registry.ts。
• 至少看 2-3 个最终 demo 的 create*Model.ts，观察几何、材质、命名节点、userData.tick、look-dev lights。
• 总结时用用户能听懂的口径说明：参考图是建模蓝图，不是主贴图；模型主体必须靠 Three.js 几何重建。

参考图拆解

写代码前先产出一份轻量结构拆解，至少包含：

• 轮廓与比例：主外形、厚度、开合角、重心、可见面、遮挡关系。
• 部件层级：哪些是主形体，哪些是可动部件、装饰件、贴附件、卡槽、铆钉、接缝、页块等。
• 材质分区：皮革、纸张、金属、木头、布面、印刷图案、污渍磨损分别在哪里。
• 几何策略：每个主要部件用 Shape + ExtrudeGeometry、primitive、curve/tube、自定义 geometry、instancing，还是小 mesh 阵列。
• 贴图策略：CanvasTexture/图片 crop 只能用于 decal、文字、局部图案、bump、roughness 变化；不得用一张图包住主形体来冒充模型。
• 运行时节点：需要暴露哪些命名节点、pivot、socket、动画钩子，供游戏里旋转、开合、翻页、选中或高亮。

参考图追踪门禁

写模型前必须先建立“参考图区域 -> 模型结果”的追踪表。没有这张表，不得进入建模。

表中至少覆盖：

• 主体轮廓：参考图哪一张、哪一区域决定整体比例、外轮廓、厚度、开合状态。
• 主要部件：封面、书脊、页块、扣件、绑带、角件、卡槽等分别来自哪张图的哪个可见证据。
• 材质与颜色：皮革、纸张、金属、骨饰、污损、印刷内容分别从哪里取色或抽象。
• 可借鉴但不可直用：哪些图片只提供风格气质，不能作为主体结构依据。
• 缺源项：参考图没有覆盖的关键部件必须标为“缺参考”，不能用“死灵/法师/旧书”这类主题词脑补成正式结构。

如果用户给的是卡牌贴图、牌背、图标、图集或局部插画，而不是目标资产主体图，必须先说清：这些只能驱动卡牌、徽记、材质/配色或局部浮雕，不能证明书本主体长什么样。此时只能做两种事：

• 请求或寻找书本主体参考图；
• 或明确交付“基于当前贴图风格的概念白模”，不得称为参考图重建或 img2threejs 结果。

禁止泛主题生成

参考图重建的最低标准不是“符合题材”，而是“能从截图反推回参考图”。下列做法一律判失败：

• 只根据题材词生成通用幻想物件，没有说明每个主要部件对应的参考图来源。
• 只把卡牌贴图放进模型，却让书本封面、书脊、扣件、页块完全来自主观设计。
• 先做一个看似完整的模型，再事后解释它“风格上参考了贴图”。
• 验收图无法和参考图并排指出：轮廓、部件、材质、颜色、图案分别哪里相似。

建模规则

默认输出 createXModel(options): THREE.Group 风格的程序化 factory。

• 主形体必须是几何：用可读的函数拆出封面、书脊、页块、卡槽、底座、边框、扣件、铰链等。
• 细节必须有体积：边框、浮雕、页层、孔洞、铆钉、卡槽压边、磨损边不能只画在贴图里。
• 材质要分层：使用 MeshStandardMaterial / MeshPhysicalMaterial 表达 roughness、metalness、clearcoat、bumpMap；不要靠单张 diffuse 图撑质感。
• 贴图只做局部：卡面、徽记、文字、纹理噪声、磨损斑可以用 CanvasTexture 或裁图；不能把参考图整张铺到平面上。
• 节点要命名：复杂模型给重要对象设置稳定 name，并在 root.userData.sculptRuntime.nodes 或等价结构里暴露给宿主。
• 动画要预留：需要开合、翻页、旋转、发光、悬浮时，用 pivot/group 表达，不要靠改世界坐标硬摆。