@needle-tools/gltf-build-pipeline 2.16.0-next.fc19d36 → 3.0.0-alpha

package/CHANGELOG.md

@@ -4,6 +4,31 @@ All notable changes to this package will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
+## [3.0.0-alpha] - 2026-05-26
+
+### Breaking
+- CLI now requires JWT authentication via `--auth-token`
+- The package ships as a CLI-only right now
+
+### Added
+- **Job cache**: file-level cache that skips an entire transform when the same input + config was already processed
+- **Audio compression**: external audio references are re-encoded to Opus/OGG; supported input formats are WAV, FLAC, and AIFF (lossy formats pass through unchanged)
+- **PMREM standalone CLI command**: `needle-gltf pmrem <input>` converts EXR and Radiance HDR files to PMREM KTX2
+- **Multiple file inputs**: `transform` now accepts comma-separated paths (e.g. `needle-gltf transform a.glb,b.glb out/`)
+- Auth surfaces clean "token expired" message when the JWT `exp` claim is past
+
+### Fixed
+- Cache restore now also restores external files (KTX2, PMREM) alongside the main GLB
+- PMREM NaN generation that caused artifacts in certain EXR files
+- xxHash WASM init race condition, now resolved with `ensureHashReady` gate
+- LOD file detection no longer matches against directory names
+- toktx: probes `ktx` binary to match what the compression step actually runs
+- `getConfig` now returns a fresh copy instead of a shared mutable reference
+- `stats` tolerates undefined errors/warnings in `addFrom`
+- Material-only GLBs are no longer incorrectly pruned
+- `createOpaqueExtension` return type fixed, downstream casts removed
+- `stats` command exits with code 0
+
 ## [2.15.0] - 2026-03-20
 - add: EXR environment map compression (PMREM / FASTHDR) for Needle Engine, supporting both Unity and Blender exports
 - fix: cache hashing stability (circular reference handling)

package/README.md

@@ -14,10 +14,10 @@ Includes support for generating LOD quality level for textures and meshes. Use w
 In general all files that have been processed by this package are valid glTF/GLB files.    
 The glTF Build Pipeline package is meant to be used as a last step before delivery.   
 That means:
-- files are meant to be loaded e.g. in a web runtime like three.js 
+- files are meant to be loaded by [Needle Engine](https://needle.tools) (and other three.js based runtimes)
 - files are not to be opened in Blender again to be further edited    
 
-To load progressively enhanced glTF files in any three.js based engine see examples at [@needle-tools/gltf-progressive](https://www.npmjs.com/package/@needle-tools/gltf-progressive)
+To load progressively enhanced glTF files in Needle Engine or another three.js based runtime, see examples at [@needle-tools/gltf-progressive](https://www.npmjs.com/package/@needle-tools/gltf-progressive)
 
 ### Installation
 
@@ -26,6 +26,45 @@ To load progressively enhanced glTF files in any three.js based engine see examp
 ### Commands
 - `help` - use help to view options
 
+### Platform support
+
+The bundled `basisu` encoder (used for HDR / EXR → KTX2 HDR) supports:
+
+| OS      | Arch                  | Status |
+|---------|-----------------------|--------|
+| Linux   | x64                   | Supported |
+| Linux   | arm64                 | Not supported |
+| macOS   | arm64 (Apple Silicon) | Supported |
+| macOS   | x64 (Intel)           | Not supported |
+| Windows | x64                   | Supported |
+
+### Configuration
+
+The pipeline reads an optional `needle.config.json` from the working directory (or any parent directory). Configure pipeline behaviour under the `gltf` key:
+
+```json
+{
+  "gltf": {
+    "usecase": "product",
+    "textures": { "lods": true },
+    "meshes":   { "lods": true },
+    "audio":    { "enabled": true, "bitrate": 64 },
+    "exr":      { "enabled": true }
+  }
+}
+```
+
+The `gltf` value may also be a string shorthand for `usecase` — `"gltf": "product"` is equivalent to `"gltf": { "usecase": "product" }`.
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `usecase` | `"default" \| "product" \| "world"` | `"default"` | High-level optimisation profile. |
+| `textures.lods` | `boolean` | `true` | Generate progressive texture LODs. |
+| `meshes.lods` | `boolean` | `true` | Generate progressive mesh LODs. |
+| `audio.enabled` | `boolean` | `true` | Compress externally referenced lossless audio files (`.wav`, `.flac`, `.aiff`/`.aif`) to Opus in an `.ogg` container, rewriting the URIs in the glTF. Lossy formats (`.mp3`, `.ogg`, `.m4a`, `.aac`) pass through unchanged to avoid compounding compression artifacts. Requires `ffmpeg` with `libopus` on `PATH`; when missing the build logs a warning and leaves the audio files untouched. |
+| `audio.bitrate` | `number` (kbps) | `128` | Opus encoding bitrate. 96 is near-transparent for most music; 128 matches YouTube's music tier and is the safe "won't sound bad" default. Drop to 48–64 for known mono/UI-only assets. |
+| `exr.enabled` | `boolean` | `true` | Convert EXR textures to KTX2 HDR via PMREM. When `false`, EXR textures (bundled and externally referenced) are left as-is so a downstream step can handle them. |
+
 # Contact
 
 For licensing questions please contact us.