compress-gltf-tools

一个 Node 20+ 模型处理项目，用来在 Node 环境里直接处理 glTF / GLB 资源。

目前支持：

• glTF 模型压缩
• 压缩纹理转换：ASTC / PVRTC / ETC / S3TC / fallback
• 资源转 Base64
• glTF 打包成 GLB
• 一次输出多个纹理变体

安装

npm install @g1sir8b/compress-gltf-tools

基本用法

import { processModel } from '@g1sir8b/compress-gltf-tools';

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

示例：

'/demo/assets/building/task_building_6.gltf'

options

处理选项对象。

rootDir

项目根目录，主要给内部处理中间目录和相对路径计算使用。

注意：

• 它现在不会再影响最终输出目录结构
• 它更像“当前项目根路径”的参考值

常见写法：

rootDir: process.cwd()

outDir

最终输出目录。

注意：

• 这里就是最终输出位置
• 不会再自动拼上输入模型原本的目录层级

例如输入：

 /demo/assets/building/task_building_6.gltf

如果设置：

outDir: './output'

那么输出会直接写到：

./output

compress 模型压缩配置

用于控制模型几何压缩。

compress: {
  enabled: true,
  excludes: [],
  quantization: {}
}

字段说明：

• enabled：是否开启模型压缩
• excludes：排除规则，命中的文件不做模型压缩
• quantization：量化参数，传给模型压缩器

quantization 示例：

quantization: {
  POSITION: 13,
  NORMAL: 8,
  TEXCOORD: 10
}

compressTextures 纹理压缩配置

用于把纹理转换成压缩纹理格式，或者输出 fallback 版本。

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 子字段

这些编码器配置结构基本一致：

astc: {
  enabled: true,
  formatOpaque: 'ASTC_8x5',
  formatTransparent: 'ASTC_6x6',
  quality: 'astcmedium',
  excludes: []
}

字段说明：

• enabled：是否启用该纹理格式输出
• formatOpaque：不透明纹理使用的压缩格式
• formatTransparent：透明纹理使用的压缩格式
• quality：该编码器自己的质量参数
• excludes：排除规则

fallback 子字段

fallback: {
  useRGBA4444: true,
  useRGB565: true,
  excludes: []
}

字段说明：

• useRGBA4444：透明图走 fallback 时是否标记为 RGBA4444
• useRGB565：不透明图走 fallback 时是否标记为 RGB565
• excludes：排除规则

补充说明：

• 当前 fallback 分支沿用老项目逻辑
• 它会输出 fallback 版本并写入 Sein_textureImprove 标记
• 但不会真正把 PNG 重新编码成低位格式图片

glb 配置

用于控制是否把 glTF 打包成 GLB。

glb: {
  enabled: true,
  excludes: []
}

字段说明：

• enabled：是否输出 GLB
• excludes：排除规则，命中的资源保持分离

base64 配置

用于把小资源直接转成 Base64 内联。

base64: {
  enabled: true,
  threshold: 1000,
  includeModel: false,
  excludes: []
}

字段说明：

• enabled：是否开启 Base64 内联
• threshold：小于这个字节数的资源才会转 Base64
• includeModel：是否允许把 glTF / GLB 本体也转成 Base64
• excludes：排除规则

processors 配置

用于在写出资源前，自定义处理资源内容。

processors: [
  {
    test: /\\.bin$/,
    async process({ data, filePath }) {
      return data;
    }
  }
]

字段说明：

• test：匹配规则，命中的文件会进入这个处理器
• process：处理函数，接收 { data, filePath }

其中：

• data：当前资源的二进制内容，类型是 Buffer
• filePath：当前资源路径

返回值必须是：

• Promise<Buffer>

排除规则 excludes

很多地方都支持 excludes。

它可以是：

• RegExp
• (filePath: string) => boolean

示例：

excludes: [
  /normal/i,
  filePath => filePath.endsWith('.mp3')
]

返回值说明

processModel 返回：

{
  inputPath,
  outDir,
  entries,
  assets,
  uploadFiles
}

inputPath

本次处理的输入模型绝对路径。

outDir

本次实际使用的输出目录绝对路径。

entries

模型主输出列表。每个元素代表一个模型变体。

单个元素结构：

{
  name,
  variant,
  type,
  required,
  url,
  outputPath
}

字段说明：

• name：模型名，不带扩展名
• variant：变体名，例如 normal / astc / fallback
• type：输出类型，gltf 或 glb
• required：该变体依赖的纹理扩展
• url：输出文件名或相对路径
• outputPath：实际输出文件绝对路径

assets

附属资源输出列表，比如：

• .bin
• .png
• .ktx
• 被内联成 Base64 的资源

单个元素结构：

{
  sourcePath,
  distPath,
  outputPath,
  url,
  inlined
}

字段说明：

• sourcePath：原始资源路径
• distPath：相对输出路径
• outputPath：实际输出文件绝对路径
• url：相对输出路径，或者 Base64 字符串
• inlined：是否被内联成 Base64

uploadFiles

专门整理好的“待上传文件数组”。

特点：

• 只包含真实写到磁盘的文件
• 不包含被 Base64 内联的资源
• 适合你后续直接遍历上传 OSS

单个元素结构：

{
  sourcePath,
  relativePath,
  outputPath,
  fileName,
  mimeType,
  size
}

字段说明：

• sourcePath：原始来源文件路径
• relativePath：输出相对路径，可直接作为上传 key 的基础值
• outputPath：本地输出文件绝对路径
• fileName：输出文件名
• mimeType：文件 MIME 类型
• size：文件大小，单位字节

示例：

for (const file of result.uploadFiles) {
  console.log(file.relativePath, file.outputPath);
}

处理后的 generator

处理后的 glTF 资产会统一写入：

"generator": "XOSMO Toolkit"

额外说明

• 如果输入是 .glb，不会走 glTF 贴图引用改写流程
• 如果同时开启纹理压缩，会按配置输出多个变体
• 某些压缩纹理格式在磁盘上不一定比原图更小，但它们的目标主要是运行时显存和采样性能