Back to Details

glb-compressor-library

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

glb-compressor Library

glb-compressor Library

Programmatic API for multi-phase GLB/glTF compression. Skinned-model-aware pipeline with gltfpack-first strategy and meshopt WASM fallback.
用于多阶段GLB/glTF压缩的可编程API。采用gltfpack优先策略并以meshopt WASM作为备选方案的蒙皮模型识别处理流水线。

Quick Start

Quick Start

ts
import { compress, init, PRESETS } from 'glb-compressor';

await init(); // Pre-warm WASM (optional, called automatically)
const glbBytes = await Bun.file('model.glb').bytes();
const result = await compress(glbBytes, { preset: 'aggressive' });
await Bun.write('out.glb', result.buffer);
ts
import { compress, init, PRESETS } from 'glb-compressor';

await init(); // Pre-warm WASM (optional, called automatically)
const glbBytes = await Bun.file('model.glb').bytes();
const result = await compress(glbBytes, { preset: 'aggressive' });
await Bun.write('out.glb', result.buffer);

Package Exports

Package Exports

ts
import { ... } from 'glb-compressor';        // Library API
import { ... } from 'glb-compressor/server';  // Server (guarded by import.meta.main)
import { ... } from 'glb-compressor/cli';     // CLI entry
Conditional exports: 
"bun"
field for Bun runtime, 
"node"
for Node.js.
ts
import { ... } from 'glb-compressor';        // Library API
import { ... } from 'glb-compressor/server';  // Server (guarded by import.meta.main)
import { ... } from 'glb-compressor/cli';     // CLI entry
条件导出：针对Bun运行时的
"bun"
字段，针对Node.js的
"node"
字段。

Core API

Core API

init(): Promise<void>

init(): Promise<void>

Pre-warm Draco + Meshopt WASM and configure glTF-Transform I/O. Called automatically by 
compress()
, but can be called at boot to eliminate cold-start latency. Safe to call multiple times (shared promise).
预加载Draco + Meshopt WASM并配置glTF-Transform输入输出。会被
compress()
自动调用，但也可在启动时调用以消除冷启动延迟。支持多次调用（共享同一个Promise）。

compress(input, options?): Promise<CompressResult>

compress(input, options?): Promise<CompressResult>

Main entry point. Runs the full 6-phase pipeline.
Parameters:
ParamTypeDescription
input
Uint8Array
Raw GLB file bytes
options.preset
CompressPreset
'default'
| 
'balanced'
| 
'aggressive'
| 
'max'
options.simplifyRatio
number
Additional simplification in 
(0, 1)
options.onLog
(msg) => void
Progress callback (used by SSE)
options.quiet
boolean
Suppress console output
Returns: 
CompressResult
ts
interface CompressResult {
	buffer: Uint8Array; // Compressed GLB binary
	method: string; // 'gltfpack' | 'meshopt'
	originalSize?: number; // Input byte count
}
主入口方法。运行完整的6阶段处理流水线。
Parameters:
ParamTypeDescription
input
Uint8Array
原始GLB文件字节数据
options.preset
CompressPreset
'default'
| 
'balanced'
| 
'aggressive'
| 
'max'
options.simplifyRatio
number
额外的简化比例，取值范围
(0, 1)
options.onLog
(msg) => void
进度回调函数（用于SSE）
options.quiet
boolean
抑制控制台输出
Returns: 
CompressResult
ts
interface CompressResult {
	buffer: Uint8Array; // Compressed GLB binary
	method: string; // 'gltfpack' | 'meshopt'
	originalSize?: number; // Input byte count
}

getHasGltfpack(): boolean

getHasGltfpack(): boolean

Whether the 
gltfpack
binary was found during initialization.
初始化过程中是否找到
gltfpack
二进制文件。

In This Reference

In This Reference

FilePurpose
api.mdFull API surface: types, constants, utilities
transforms.mdCustom glTF-Transform transforms for a-la-carte use
FilePurpose
api.md完整API覆盖：类型、常量、工具函数
transforms.md可单独使用的自定义glTF-Transform转换操作

Reading Order

Reading Order

TaskFiles to Read
Basic compressionThis file only
Custom pipeline / advancedThis file + transforms.md
Full type referenceThis file + api.md
TaskFiles to Read
基础压缩操作仅需阅读本文档
自定义流水线 / 高级用法本文档 + transforms.md
完整类型参考本文档 + api.md

Pipeline Phases

Pipeline Phases

  1. Cleanup - dedup, prune, remove unused UVs (+ flatten/join/weld for static)
  2. Geometry - merge by distance, remove degenerate faces, auto-decimate
  3. GPU - instancing, vertex reorder, sparse encoding
  4. Animation - resample keyframes, remove static tracks, normalize weights
  5. Textures - compress to WebP via sharp (max 1024x1024)
  6. Final - gltfpack (preferred) or meshopt WASM (fallback)
  1. 清理阶段 - 去重、裁剪、移除未使用的UV（静态模型额外执行合并/连接/焊接操作）
  2. 几何处理阶段 - 按距离合并网格、移除退化面、自动简化
  3. GPU优化阶段 - 实例化、顶点重排序、稀疏编码
  4. 动画处理阶段 - 重采样关键帧、移除静态轨道、归一化权重
  5. 纹理处理阶段 - 通过sharp压缩为WebP格式（最大分辨率1024x1024）
  6. 最终压缩阶段 - 使用gltfpack（优先选择）或meshopt WASM（备选方案）

Skinned Model Awareness

Skinned Model Awareness

When skins are detected, the pipeline automatically skips destructive transforms: flatten, join, weld, mergeByDistance, reorder, quantize, and auto-decimate. This prevents broken skeletons, weight denormalization, and mesh clipping.
当检测到蒙皮模型时，处理流水线会自动跳过破坏性转换操作：合并、连接、焊接、按距离合并、重排序、量化和自动简化。这可防止骨骼损坏、权重归一化失效以及网格裁剪问题。

Presets

Presets

ts
type CompressPreset = 'default' | 'balanced' | 'aggressive' | 'max';
PresetSkinned behaviorStatic behavior
default
-vp 20 -kn
-vp 16
balanced
+ animation quant (
-at 14 -ar 10 -as 14 -af 24
)		Same + 
-vp 16
aggressive
+ stronger quant (
-at 12 -ar 8 -as 12 -af 15
)		Same + 
-vp 14
max
+ supercompression (
-cz
), simplify (
-si 0.95
)		Same
ts
type CompressPreset = 'default' | 'balanced' | 'aggressive' | 'max';
Preset蒙皮模型处理行为静态模型处理行为
default
-vp 20 -kn
-vp 16
balanced
+ 动画量化（
-at 14 -ar 10 -as 14 -af 24
）		同默认 + 
-vp 16
aggressive
+ 更强的量化（
-at 12 -ar 8 -as 12 -af 15
）		同默认 + 
-vp 14
max
+ 超级压缩（
-cz
）、简化（
-si 0.95
）		同默认

Anti-Patterns

Anti-Patterns

  • Don't flatten/join/weld/quantize skinned models.
  • Don't import from 
    cli/
    or 
    server/
    - lib is the dependency root.
  • Don't bypass 
    mod.ts
    barrel for public API additions.
  • 不要对蒙皮模型执行合并/连接/焊接/量化操作。
  • 不要从
    cli/
    或
    server/
    导入模块 - 库的依赖根目录为lib。
  • 不要绕过
    mod.ts
    入口文件来添加公共API。