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

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 `.wav` audio files 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.