初始化

README.md

@@ -0,0 +1,435 @@
+# compress-gltf-tools
+
+这是从当前仓库里提取出来的一个 Node 20+ 模型处理子项目，用来在 Node 环境里直接处理 glTF / GLB 资源。
+
+目前支持：
+
+- glTF 模型压缩
+- 压缩纹理转换：ASTC / PVRTC / ETC / S3TC / fallback
+- 资源转 Base64
+- glTF 打包成 GLB
+- 一次输出多个纹理变体
+
+## 安装
+
+```bash
+cd node-model-tools
+npm install
+```
+
+## 构建
+
+```bash
+npm run build
+```
+
+## 基本用法
+
+```ts
+import { processModel } from './dist';
+
+const result = await processModel('../demo/assets/building/task_building_6.gltf', {
+  rootDir: '..',
+  outDir: './output',
+  compress: {
+    enabled: true
+  },
+  compressTextures: {
+    enabled: true,
+    quality: 'medium',
+    astc: { enabled: true },
+    pvrtc: { enabled: true },
+    fallback: { useRGBA4444: true, useRGB565: true }
+  },
+  glb: {
+    enabled: false
+  },
+  base64: {
+    enabled: false,
+    includeModel: false,
+    threshold: 1000
+  }
+});
+
+console.log(result.entries);
+console.log(result.assets);
+console.log(result.uploadFiles);
+```
+
+## `processModel(inputPath, options)` 参数说明
+
+### `inputPath`
+
+要处理的模型文件路径。
+
+- 支持 `.gltf`
+- 支持 `.glb`
+
+示例：
+
+```ts
+'../demo/assets/building/task_building_6.gltf'
+```
+
+### `options`
+
+处理选项对象。
+
+#### `rootDir`
+
+项目根目录，主要给内部处理中间目录和相对路径计算使用。
+
+注意：
+
+- 它现在不会再影响最终输出目录结构
+- 它更像“当前项目根路径”的参考值
+
+常见写法：
+
+```ts
+rootDir: process.cwd()
+```
+
+#### `outDir`
+
+最终输出目录。
+
+注意：
+
+- 这里就是最终输出位置
+- 不会再自动拼上输入模型原本的目录层级
+
+例如输入：
+
+```txt
+../demo/assets/building/task_building_6.gltf
+```
+
+如果设置：
+
+```ts
+outDir: './output'
+```
+
+那么输出会直接写到：
+
+```txt
+./output
+```
+
+## `compress` 模型压缩配置
+
+用于控制模型几何压缩。
+
+```ts
+compress: {
+  enabled: true,
+  excludes: [],
+  quantization: {}
+}
+```
+
+字段说明：
+
+- `enabled`：是否开启模型压缩
+- `excludes`：排除规则，命中的文件不做模型压缩
+- `quantization`：量化参数，传给模型压缩器
+
+`quantization` 示例：
+
+```ts
+quantization: {
+  POSITION: 13,
+  NORMAL: 8,
+  TEXCOORD: 10
+}
+```
+
+## `compressTextures` 纹理压缩配置
+
+用于把纹理转换成压缩纹理格式，或者输出 fallback 版本。
+
+```ts
+compressTextures: {
+  enabled: true,
+  quality: 'medium',
+  excludes: [],
+  astc: { enabled: true },
+  pvrtc: { enabled: true },
+  etc: { enabled: false },
+  s3tc: { enabled: false },
+  fallback: {
+    useRGBA4444: true,
+    useRGB565: true
+  }
+}
+```
+
+字段说明：
+
+- `enabled`：是否开启纹理压缩链路
+- `quality`：整体质量档位，可选 `high` / `medium` / `low`
+- `excludes`：排除规则，命中的纹理不参与压缩
+- `astc`：ASTC 配置
+- `pvrtc`：PVRTC 配置
+- `etc`：ETC 配置
+- `s3tc`：S3TC 配置
+- `fallback`：fallback 配置
+
+### `astc / pvrtc / etc / s3tc` 子字段
+
+这些编码器配置结构基本一致：
+
+```ts
+astc: {
+  enabled: true,
+  formatOpaque: 'ASTC_8x5',
+  formatTransparent: 'ASTC_6x6',
+  quality: 'astcmedium',
+  excludes: []
+}
+```
+
+字段说明：
+
+- `enabled`：是否启用该纹理格式输出
+- `formatOpaque`：不透明纹理使用的压缩格式
+- `formatTransparent`：透明纹理使用的压缩格式
+- `quality`：该编码器自己的质量参数
+- `excludes`：排除规则
+
+### `fallback` 子字段
+
+```ts
+fallback: {
+  useRGBA4444: true,
+  useRGB565: true,
+  excludes: []
+}
+```
+
+字段说明：
+
+- `useRGBA4444`：透明图走 fallback 时是否标记为 `RGBA4444`
+- `useRGB565`：不透明图走 fallback 时是否标记为 `RGB565`
+- `excludes`：排除规则
+
+补充说明：
+
+- 当前 fallback 分支沿用老项目逻辑
+- 它会输出 fallback 版本并写入 `Sein_textureImprove` 标记
+- 但不会真正把 PNG 重新编码成低位格式图片
+
+## `glb` 配置
+
+用于控制是否把 glTF 打包成 GLB。
+
+```ts
+glb: {
+  enabled: true,
+  excludes: []
+}
+```
+
+字段说明：
+
+- `enabled`：是否输出 GLB
+- `excludes`：排除规则，命中的资源保持分离
+
+## `base64` 配置
+
+用于把小资源直接转成 Base64 内联。
+
+```ts
+base64: {
+  enabled: true,
+  threshold: 1000,
+  includeModel: false,
+  excludes: []
+}
+```
+
+字段说明：
+
+- `enabled`：是否开启 Base64 内联
+- `threshold`：小于这个字节数的资源才会转 Base64
+- `includeModel`：是否允许把 glTF / GLB 本体也转成 Base64
+- `excludes`：排除规则
+
+## `processors` 配置
+
+用于在写出资源前，自定义处理资源内容。
+
+```ts
+processors: [
+  {
+    test: /\\.bin$/,
+    async process({ data, filePath }) {
+      return data;
+    }
+  }
+]
+```
+
+字段说明：
+
+- `test`：匹配规则，命中的文件会进入这个处理器
+- `process`：处理函数，接收 `{ data, filePath }`
+
+其中：
+
+- `data`：当前资源的二进制内容，类型是 `Buffer`
+- `filePath`：当前资源路径
+
+返回值必须是：
+
+- `Promise<Buffer>`
+
+## 排除规则 `excludes`
+
+很多地方都支持 `excludes`。
+
+它可以是：
+
+- `RegExp`
+- `(filePath: string) => boolean`
+
+示例：
+
+```ts
+excludes: [
+  /normal/i,
+  filePath => filePath.endsWith('.mp3')
+]
+```
+
+## 返回值说明
+
+`processModel` 返回：
+
+```ts
+{
+  inputPath,
+  outDir,
+  entries,
+  assets,
+  uploadFiles
+}
+```
+
+### `inputPath`
+
+本次处理的输入模型绝对路径。
+
+### `outDir`
+
+本次实际使用的输出目录绝对路径。
+
+### `entries`
+
+模型主输出列表。每个元素代表一个模型变体。
+
+单个元素结构：
+
+```ts
+{
+  name,
+  variant,
+  type,
+  required,
+  url,
+  outputPath
+}
+```
+
+字段说明：
+
+- `name`：模型名，不带扩展名
+- `variant`：变体名，例如 `normal` / `astc` / `fallback`
+- `type`：输出类型，`gltf` 或 `glb`
+- `required`：该变体依赖的纹理扩展
+- `url`：输出文件名或相对路径
+- `outputPath`：实际输出文件绝对路径
+
+### `assets`
+
+附属资源输出列表，比如：
+
+- `.bin`
+- `.png`
+- `.ktx`
+- 被内联成 Base64 的资源
+
+单个元素结构：
+
+```ts
+{
+  sourcePath,
+  distPath,
+  outputPath,
+  url,
+  inlined
+}
+```
+
+字段说明：
+
+- `sourcePath`：原始资源路径
+- `distPath`：相对输出路径
+- `outputPath`：实际输出文件绝对路径
+- `url`：相对输出路径，或者 Base64 字符串
+- `inlined`：是否被内联成 Base64
+
+### `uploadFiles`
+
+专门整理好的“待上传文件数组”。
+
+特点：
+
+- 只包含真实写到磁盘的文件
+- 不包含被 Base64 内联的资源
+- 适合你后续直接遍历上传 OSS
+
+单个元素结构：
+
+```ts
+{
+  sourcePath,
+  relativePath,
+  outputPath,
+  fileName,
+  mimeType,
+  size
+}
+```
+
+字段说明：
+
+- `sourcePath`：原始来源文件路径
+- `relativePath`：输出相对路径，可直接作为上传 key 的基础值
+- `outputPath`：本地输出文件绝对路径
+- `fileName`：输出文件名
+- `mimeType`：文件 MIME 类型
+- `size`：文件大小，单位字节
+
+示例：
+
+```ts
+for (const file of result.uploadFiles) {
+  console.log(file.relativePath, file.outputPath);
+}
+```
+
+## 处理后的 generator
+
+处理后的 glTF 资产会统一写入：
+
+```json
+"generator": "XOSMO Toolkit"
+```
+
+## 额外说明
+
+- 如果输入是 `.glb`，不会走 glTF 贴图引用改写流程
+- 如果同时开启纹理压缩，会按配置输出多个变体
+- 某些压缩纹理格式在磁盘上不一定比原图更小，但它们的目标主要是运行时显存和采样性能