dsh-plugin-three2game

AI 用 Three.js 代码生成 3D 模型 → 3D 相机预览 → 导出通用 3D 格式（DSH 插件，工作台形态）。

模型 / 场景两个概念对应对齐界面插件的「组件 / 界面」：

| 概念 | 文件 | 说明 | |---|---|---| | 模型 | models/<id>/model.js（export function createModel(ctx)） | 可复用 3D 资产，被场景引用 | | 场景 | scenes/<id>.json（实例 + position/rotation/scale） | 多个模型组合摆放 |

AI 写模型/场景代码，headless Chrome 校验，导出走 three.js 官方 exporter： GLB（默认）/ glTF / OBJ / STL / PLY（Y-up、米制、底部中心原点、正面 +Z）， 另有「导出独立网页」（单文件离线 HTML）与 three2game_capture 截图自查。

安装到 DSH

从 npm（发布后）

dsh plugin --profile web add dsh-plugin-three2game

本包声明了 dsh.bundle.patch（cordis.patch.yml），插件管理器把它当组合包安装并自动插入 id: three2game 行；需要 chromePath 时在 profile patch 里用同 id 覆盖。

本地 link（开发）

npm install
npm run build            # link: 安装直接跑 lib/ 产物，必须先构建
dsh plugin --profile web add link:/home/luckyfeng/Desktop/project/dsh-plugins/three2game/dsh-plugin

本地 link 不会自动启用组合包，需要往 ~/.dsh/profiles/web/cordis.patch.yml 的 - insert: 列表插入：

- insert:
    - id: three2game
      name: "dsh-plugin-three2game"
      config:
        chromePath: "/path/to/chrome-headless-shell"   # 可选

（已在独立 DSH_HOME 的 web profile 里用打包产物实测：health / 项目列表 / client 进入 boot manifest 全通。）

命令

npm install
npm run build            # lib/runtime.js + lib/viewer.js + lib/client.js + lib/index.mjs（Host 打包）+ lib/bin/*
npm test                 # 8 组测试（含真 headless Chrome）
npm run build:runtime    # 只重建 lib/runtime.js / lib/viewer.js（改 src/preview 后）
npm run build:client     # 只重建 lib/client.js（改 src/client 后）
npm run build:host       # 只重打 Host 半（改 src/host 后）

# 源码直跑（开发态）
node bin/three2game.mjs <projectDir> <modelId> --mode check
node bin/three2game.mjs <projectDir> <modelId> --mode export --formats glb

# 发布产物直跑（和 npm 包内一致）
node lib/bin/three2game.mjs <projectDir> <modelId> --mode check

可选参数：--formats glb,gltf,obj,stl,ply、--out <dir>、--chrome-path <path>。

发布（npm）

npm run build            # prepublishOnly 也会自动跑 build + test
npm pack --dry-run       # 检查 tarball：只有 lib/、skill/、cordis.patch.yml、README.md、package.json
npm publish

发布包不含 src/、test/、spec/：Host 半在构建时由 esbuild 打成 lib/index.mjs （CLI 打成 lib/bin/three2game.mjs），runtime/观看器/客户端分别是 lib/runtime.js、 lib/viewer.js、lib/client.js 构建产物；资源由 src/host/root.mjs 按「向上找 package.json」 定位包根，打包前后路径一致。改动 Host 源码后记得重新 npm run build 再发布。

目录

src/host/                  Host 半：路由 / 注册表 / headless 渲染 / 工具 / 会话注入
src/preview/               浏览器端 3D runtime（three.js，iframe 与 headless 共用）
src/client/                DSH Web 客户端工作台（React，esbuild 打包）
src/shared/constants.mjs   三方共用常量（格式 / 路径 / 默认值）
src/host/root.mjs          包根定位（skill/、lib/ 的基准；打包前后一致）
skill/                     AI 规范正文（运行时按包根读取，随 npm 包发布）
bin/                       CLI 源码（开发态直跑；发布时打包进 lib/bin/）
lib/                       构建产物（提交，profile link 安装直接使用）：
  index.mjs                Host 半打包入口（package.json exports["."]）
  bin/three2game.mjs       CLI 打包产物
  client.js                Client bundle（exports["./client"]）
  runtime.js               iframe / headless 共用 3D runtime
  viewer.js                「导出独立网页」内联观看器
cordis.patch.yml           组合包 patch（npm 安装后自动启用插件行）
test/                      node:test + headless 集成 + fixtures