img2threejs-reconstruction

name	img2threejs-reconstruction
description	BoardGame 项目内参考图生成 Three.js 程序化模型流程。用于 img2threejs、图生模型、参考图重建、Three.js 游戏资产原型、书本/棋盘/卡牌/道具 3D 模型任务；在动手写模型前先拆参考图结构并建立“参考图区域到模型部件/材质”的追踪表，禁止把参考图当整面贴图贴皮，也禁止脱离参考图生成泛主题模型。

Img2threejs Reconstruction

这个 skill 用于 BoardGame 项目里把参考图片转成可用的 Three.js 程序化模型原型。它是项目 workflow，不是全局 skill；只写 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 表达，不要靠改世界坐标硬摆。

书本类资产门禁

当目标是打开的书、法术书、牌册、规则书或类似 overlay 资产时，额外检查：

• 书页不是上下翻的平板页，除非用户明确要这个动画；摊开态应优先表现左右页、书沟、页块厚度和轻微曲面。
• 页块必须有厚度和层次：外侧页边、薄页叠层、翘边、书沟阴影至少要有几何或 bump 表达。
• 封面和书脊要有结构：凸边、扣件、铆钉、绑带、锁扣、书脊弧度不能只靠颜色。
• 如果书本用于游戏主场景 overlay，模型高度和视角必须让出地图可见区域；不要默认做满屏展示道具。
• 一页多张卡牌时，卡位应是槽位/压边/阴影/轻微厚度组合，不是把卡图直接贴在纸面上。

验收

完成后必须回到用户目标位点验收，不只看 build 通过。

• 运行构建或 dev server，至少确认无运行时报错。
• 必须生成或汇报参考图追踪表，逐项说明模型主体与贴图/参考图的关系；没有关系的部件必须明说是临时占位或概念补全。
• 截 2-3 个角度：参考图主视角、低角度看厚度、局部细节视角。
• 至少提供一张“参考图/模型结果”对照验收图或文字对照，能看出主要轮廓、部件和材质来源。
• AI 自己核图时检查：轮廓、厚度、体积、材质分区、贴图是否只是辅助、卡牌/页面是否空白、是否像贴皮。
• 用户要看图时走 .codex/skill/screenshot-delivery/SKILL.md；不要把 view_image 或路径当作已经给用户打开。
• 若只是临时原型，汇报必须说清“临时原型/候选资产”，不得说成正式接入游戏。

失败反模式

出现以下任一情况，默认判定为跑偏，先停下来重做结构拆解：

• 先创建一个盒子或平面，再把参考图铺上去，宣称“图生模型”完成。
• 没有部件清单和几何策略就开始堆细节。
• 只追求正面截图相似，侧面一看没有厚度。
• 用截图、缩略图、联系表当正式贴图源。
• 把下载/导入的 .gltf、.obj、.fbx 或外部模型包说成 img2threejs 产物。
• 只修颜色、光照、相机，却没有解决页块、书脊、铰链、卡槽等形体缺失。
• 参考图只提供卡牌/牌背/局部插画，却输出一个完整书本并宣称“参考贴图生成”，但无法说明书本主体和参考图的对应关系。