[Release] Preparing release 0.12.1

untoldengine · untoldengine · commit fd635a32621d · 2026-04-09T00:30:44.000-07:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,4 +1,17 @@
 # Changelog
+## v0.12.1 - 2026-04-09
+### 🐞 Fixes
+- [Patch] Fixed exporter UV issues (4e5da7f…)
+- [Patch] Fixed texture encoding in exporter (5313ee7…)
+- [Patch] Improved the exporting speed. (7f14373…)
+- [Patch] Fixed grayscale textures rendering red in engine (a0c0f00…)
+- [Patch] Fixed 16-bit sRGB textures saving with wrong view transform (fe33c36…)
+- [Patch] Ignore exr textures during export (e9981ac…)
+- [Patch] Implemented LZ4 compression (7095b8d…)
+- [Patch] Added ASTC texture pipeline to engine. (6cd4dda…)
+### 📚 Docs
+- [Docs] Updated logo image (d4a5faf…)
+- [Docs] Added LZ4 documentation (bf231ab…)
 ## v0.12.0 - 2026-04-06
 ### 🐞 Fixes
 - [Patch] improved the tile-streaming system (c09bb2c…)
diff --git a/README.md b/README.md
@@ -65,43 +65,23 @@ http://www.haroldserrano.com
 
 The fastest way to experience Untold Engine is to run the demo project.
 
-Clone the repository, run the engine and load a USDZ file:
+Clone the repository and launch the demo:
 
 ```bash
 git clone https://github.com/untoldengine/UntoldEngine.git
 cd UntoldEngine
 swift run untolddemo
 ```
 
-Legacy alias (prints deprecation warning):
+The demo UI lets you see the engine in action right away. Using the `Remote Scene` drop-down menu, you can choose a scene to stream directly into the demo through the engine's **Asset Remote Streaming** support.
 
-```bash
-swift run DemoGame
-```
-
-This will:
-
-- Build the engine using **Swift Package Manager**
-- Compile the demo project
-- Launch the demo so you can see the engine running immediately
-
-No additional setup is required.
-
----
-
-## 🧪 Sandbox
-
-The sandbox is the quickest place to get a feel for Untold Engine without the demo HUD and demo-specific wiring.
+## I want to try my own USDZ
 
-Use it when you want to try engine APIs directly, such as `setEntityMeshAsync(...)`, `loadTiledScene(...)`, or other one-off rendering and scene-loading experiments.
+Untold Engine uses its own native asset format: `.untold`.
 
-Run it with:
-
-```bash
-swift run sandbox
-```
+To try your own `USDZ` file, first convert it to `.untold` using the `Tools` section in the demo UI.
 
-The sandbox target lives in `Sources/Sandbox` and includes a minimal `AppDelegate`, `main.swift`, and `GameScene.swift`. The intended workflow is to edit `GameScene.swift`, add the quick test you want to run, and relaunch the app.
+After the export is complete, open the Local Scene `Browse` drop-down menu, choose `.untold`, then browse for and select your exported `.untold` file.
 
 ---
 
@@ -185,6 +165,7 @@ Untold Engine aims to support applications such as:
 - [Streaming Cache Lifecycle](docs/Architecture/streamingCacheLifecycle.md)
 - [Texture Streaming System](docs/Architecture/textureStreamingSystem.md)
 - [Out of Core](docs/Architecture/outOfCore.md)
+- [Asset Remote Streaming](docs/Architecture/asset_remote_streaming.md)
 
 ---
 
diff --git a/Sources/DemoGame/DemoHUD.swift b/Sources/DemoGame/DemoHUD.swift
@@ -114,7 +114,7 @@
                         Text("Local Scene")
                             .foregroundStyle(.secondary)
                             .frame(width: 92, alignment: .leading)
-                        Menu("Select") {
+                        Menu("Browse") {
                             Button("Asset (.untold)", action: openLocalAssetPicker)
                             Button("Tiled Scene (.json)", action: openLocalTiledScenePicker)
                         }
diff --git a/Sources/UntoldEngine/AssetFormat/NativeTexFormat.swift b/Sources/UntoldEngine/AssetFormat/NativeTexFormat.swift
@@ -166,19 +166,19 @@ public enum NativeTexValidationError: Error, Sendable, Equatable {
 
 extension NativeTexHeader: UntoldBinaryEncodable, UntoldBinaryDecodable {
     public func encode(to writer: UntoldBinaryWriter) {
-        writer.writeBytes(magic)               // offset  0 – 7   (8 bytes)
-        writer.writeUInt32LE(version)          // offset  8 – 11  (4 bytes)
-        writer.writeUInt32LE(flags)            // offset 12 – 15  (4 bytes)
-        writer.writeUInt32LE(width)            // offset 16 – 19  (4 bytes)
-        writer.writeUInt32LE(height)           // offset 20 – 23  (4 bytes)
-        writer.writeUInt32LE(mipCount)         // offset 24 – 27  (4 bytes)
-        writer.writeUInt32LE(pixelFormat)      // offset 28 – 31  (4 bytes)
-        writer.writeUInt8(blockWidth)          // offset 32       (1 byte)
-        writer.writeUInt8(blockHeight)         // offset 33       (1 byte)
-        writer.writeBytes(reserved)            // offset 34 – 35  (2 bytes)
-        writer.writeUInt32LE(payloadOffset)    // offset 36 – 39  (4 bytes)
+        writer.writeBytes(magic) // offset  0 – 7   (8 bytes)
+        writer.writeUInt32LE(version) // offset  8 – 11  (4 bytes)
+        writer.writeUInt32LE(flags) // offset 12 – 15  (4 bytes)
+        writer.writeUInt32LE(width) // offset 16 – 19  (4 bytes)
+        writer.writeUInt32LE(height) // offset 20 – 23  (4 bytes)
+        writer.writeUInt32LE(mipCount) // offset 24 – 27  (4 bytes)
+        writer.writeUInt32LE(pixelFormat) // offset 28 – 31  (4 bytes)
+        writer.writeUInt8(blockWidth) // offset 32       (1 byte)
+        writer.writeUInt8(blockHeight) // offset 33       (1 byte)
+        writer.writeBytes(reserved) // offset 34 – 35  (2 bytes)
+        writer.writeUInt32LE(payloadOffset) // offset 36 – 39  (4 bytes)
         writer.writeUInt32LE(totalPayloadSize) // offset 40 – 43  (4 bytes)
-        for word in reserved1 {               // offset 44 – 63  (5 × 4 = 20 bytes)
+        for word in reserved1 { // offset 44 – 63  (5 × 4 = 20 bytes)
             writer.writeUInt32LE(word)
         }
         // Total: 64 bytes
diff --git a/Sources/UntoldEngine/RuntimeAssets/NativeTextureLoader.swift b/Sources/UntoldEngine/RuntimeAssets/NativeTextureLoader.swift
@@ -116,7 +116,7 @@ public final class NativeTextureLoader: @unchecked Sendable {
         )
         desc.mipmapLevelCount = mipCount
         desc.storageMode = .private
-        desc.usage = .shaderRead  // ASTC blocks cannot be reinterpreted; no .pixelFormatView needed
+        desc.usage = .shaderRead // ASTC blocks cannot be reinterpreted; no .pixelFormatView needed
 
         guard let texture = device.makeTexture(descriptor: desc) else {
             throw NativeTexLoadError.textureAllocationFailed
@@ -148,7 +148,7 @@ public final class NativeTextureLoader: @unchecked Sendable {
             let mipH = Int(mip.heightPx)
             let blocksWide = (mipW + blockW - 1) / blockW
             let blocksHigh = (mipH + blockH - 1) / blockH
-            let bytesPerRow = blocksWide * 16      // each ASTC block is always 16 bytes
+            let bytesPerRow = blocksWide * 16 // each ASTC block is always 16 bytes
             let bytesPerImage = bytesPerRow * blocksHigh
 
             // Slice the mip payload out of the memory-mapped file data.
@@ -191,7 +191,7 @@ public final class NativeTextureLoader: @unchecked Sendable {
 
         blitEncoder.endEncoding()
         commandBuffer.commit()
-        commandBuffer.waitUntilCompleted()  // synchronous for Phase 2; async upload in a later phase
+        commandBuffer.waitUntilCompleted() // synchronous for Phase 2; async upload in a later phase
 
         if let error = commandBuffer.error {
             throw NativeTexLoadError.gpuUploadFailed(error)
diff --git a/Sources/UntoldEngine/Systems/TextureStreamingSystem.swift b/Sources/UntoldEngine/Systems/TextureStreamingSystem.swift
@@ -672,9 +672,9 @@ public class TextureStreamingSystem: @unchecked Sendable {
             // Both figures are multiplied by 4/3 to account for the full mip chain.
             let bytesPerPixel: Int
             if case .utex = item.slot.source {
-                bytesPerPixel = 1   // ASTC: ≤ 1 byte/pixel for all block sizes
+                bytesPerPixel = 1 // ASTC: ≤ 1 byte/pixel for all block sizes
             } else {
-                bytesPerPixel = 4   // RGBA8
+                bytesPerPixel = 4 // RGBA8
             }
             let newBytes = newDim * newDim * bytesPerPixel * 4 / 3
             let oldBytes = oldDim * oldDim * bytesPerPixel * 4 / 3
@@ -788,7 +788,7 @@ public class TextureStreamingSystem: @unchecked Sendable {
                 // ASTC .utex textures: select the starting mip by dimension instead of
                 // MPS resampling (compressed ASTC blocks cannot be resampled in-place).
                 // Both upgrade and downgrade reload from the file at the target tier.
-                if case .utex(let url) = item.slot.source {
+                if case let .utex(url) = item.slot.source {
                     texture = capturedNativeLoader?.loadTexture(
                         from: url,
                         targetMaxDimension: item.targetMaxDimension,
diff --git a/Tests/UntoldEngineTests/NativeFormatTests.swift b/Tests/UntoldEngineTests/NativeFormatTests.swift
@@ -544,7 +544,6 @@ extension NativeFormatTests {
 // MARK: - LZ4 compression tests
 
 extension NativeFormatTests {
-
     // MARK: Helpers
 
     /// Compress `input` with COMPRESSION_LZ4_RAW — the same algorithm the runtime uses to decompress.
@@ -598,10 +597,10 @@ extension NativeFormatTests {
         let originalIndexData = indexWriter.data
 
         let compressedVertex = lz4Compress(originalVertexData)
-        let compressedIndex  = lz4Compress(originalIndexData)
+        let compressedIndex = lz4Compress(originalIndexData)
 
         let vertexUncompressedSize: UInt64 = inflateVertexUncompressedSize
-            ? UInt64(originalVertexData.count) + 1000  // deliberately wrong
+            ? UInt64(originalVertexData.count) + 1000 // deliberately wrong
             : UInt64(originalVertexData.count)
 
         let entity = UntoldEntityRecordV1(
@@ -653,21 +652,21 @@ extension NativeFormatTests {
 
         // (storedBytes, compressionType, uncompressedSize, elementCount)
         let specs: [(UntoldChunkType, Data, UntoldCompressionType, UInt64, UInt32)] = [
-            (.stringTable,   stringTable.data,      .none, UInt64(stringTable.data.count),                0),
-            (.entityTable,   encodeChunk([entity]),  .none, UInt64(encodeChunk([entity]).count),           1),
-            (.meshTable,     encodeChunk([mesh]),    .none, UInt64(encodeChunk([mesh]).count),             1),
-            (.materialTable, encodeChunk([material]),.none, UInt64(encodeChunk([material]).count),         1),
-            (.textureTable,  encodeChunk([texture]), .none, UInt64(encodeChunk([texture]).count),          1),
-            (.vertexData,    compressedVertex,       .lz4,  vertexUncompressedSize,                        0),
-            (.indexData,     compressedIndex,        .lz4,  UInt64(originalIndexData.count),               0),
+            (.stringTable, stringTable.data, .none, UInt64(stringTable.data.count), 0),
+            (.entityTable, encodeChunk([entity]), .none, UInt64(encodeChunk([entity]).count), 1),
+            (.meshTable, encodeChunk([mesh]), .none, UInt64(encodeChunk([mesh]).count), 1),
+            (.materialTable, encodeChunk([material]), .none, UInt64(encodeChunk([material]).count), 1),
+            (.textureTable, encodeChunk([texture]), .none, UInt64(encodeChunk([texture]).count), 1),
+            (.vertexData, compressedVertex, .lz4, vertexUncompressedSize, 0),
+            (.indexData, compressedIndex, .lz4, UInt64(originalIndexData.count), 0),
         ]
 
         header.chunkCount = UInt32(specs.count)
 
         // Compute chunk table size (matches UntoldChunkEntryV1 binary layout: 2×u32 + 3×u64 + 2×u32 = 40 bytes)
         let chunkEntrySize = MemoryLayout<UInt32>.size * 2
-                           + MemoryLayout<UInt64>.size * 3
-                           + MemoryLayout<UInt32>.size * 2
+            + MemoryLayout<UInt64>.size * 3
+            + MemoryLayout<UInt32>.size * 2
         let headerWriter2 = UntoldBinaryWriter()
         header.encode(to: headerWriter2)
         let headerSize = headerWriter2.data.count
@@ -708,26 +707,26 @@ extension NativeFormatTests {
         let decoded = try reader.readAsset(from: fileData)
 
         let decompressedVertex = try reader.readChunkData(.vertexData, from: fileData, entries: decoded.chunks)
-        let decompressedIndex  = try reader.readChunkData(.indexData,  from: fileData, entries: decoded.chunks)
+        let decompressedIndex = try reader.readChunkData(.indexData, from: fileData, entries: decoded.chunks)
 
         XCTAssertEqual(decompressedVertex, originalVertexData, "Decompressed vertex data must match original")
-        XCTAssertEqual(decompressedIndex,  originalIndexData,  "Decompressed index data must match original")
+        XCTAssertEqual(decompressedIndex, originalIndexData, "Decompressed index data must match original")
     }
 
     func testLZ4CompressedChunkReportsCorrectSizeMetadata() throws {
         let (fileData, originalVertexData, originalIndexData) = makeLZ4CompressedFile()
         let decoded = try UntoldReader().readAsset(from: fileData)
 
         let vertexEntry = try XCTUnwrap(decoded.chunks.first { $0.chunkType == .vertexData })
-        let indexEntry  = try XCTUnwrap(decoded.chunks.first { $0.chunkType == .indexData  })
+        let indexEntry = try XCTUnwrap(decoded.chunks.first { $0.chunkType == .indexData })
 
-        XCTAssertEqual(vertexEntry.compressionType,   .lz4)
-        XCTAssertEqual(vertexEntry.uncompressedSize,  UInt64(originalVertexData.count))
+        XCTAssertEqual(vertexEntry.compressionType, .lz4)
+        XCTAssertEqual(vertexEntry.uncompressedSize, UInt64(originalVertexData.count))
         XCTAssertLessThanOrEqual(vertexEntry.compressedSize, vertexEntry.uncompressedSize + 64,
-            "LZ4 compressed size should not wildly exceed original for small inputs")
+                                 "LZ4 compressed size should not wildly exceed original for small inputs")
 
-        XCTAssertEqual(indexEntry.compressionType,    .lz4)
-        XCTAssertEqual(indexEntry.uncompressedSize,   UInt64(originalIndexData.count))
+        XCTAssertEqual(indexEntry.compressionType, .lz4)
+        XCTAssertEqual(indexEntry.uncompressedSize, UInt64(originalIndexData.count))
     }
 
     func testLZ4CompressionOutputSizeMismatchIsRejected() throws {
diff --git a/Tests/UntoldEngineTests/NativeTexFormatTests.swift b/Tests/UntoldEngineTests/NativeTexFormatTests.swift
@@ -91,7 +91,7 @@ final class NativeTexFormatTests: XCTestCase {
     // MARK: - Mip entry roundtrip
 
     func testMipEntryRoundtrip() throws {
-        let original = NativeTexMipEntry(byteOffset: 256, byteSize: 16_384, widthPx: 1024, heightPx: 512)
+        let original = NativeTexMipEntry(byteOffset: 256, byteSize: 16384, widthPx: 1024, heightPx: 512)
         let decoded = try NativeTexMipEntry.decode(from: UntoldBinaryReader(data: encode(original)))
         XCTAssertEqual(decoded, original)
     }
@@ -114,7 +114,9 @@ final class NativeTexFormatTests: XCTestCase {
 
         let writer = UntoldBinaryWriter()
         header.encode(to: writer)
-        for mip in mips { mip.encode(to: writer) }
+        for mip in mips {
+            mip.encode(to: writer)
+        }
         let data = writer.data
 
         let (decodedHeader, decodedMips) = try NativeTexReader().read(from: data)
@@ -131,7 +133,7 @@ final class NativeTexFormatTests: XCTestCase {
 
     func testReaderRejectsInvalidMagic() throws {
         var data = makeMinimalContainer(mipCount: 1)
-        data[0] = 0xFF  // corrupt first byte of magic
+        data[0] = 0xFF // corrupt first byte of magic
 
         XCTAssertThrowsError(try NativeTexReader().read(from: data)) { error in
             XCTAssertEqual(error as? NativeTexValidationError, .invalidMagic)
@@ -178,7 +180,7 @@ final class NativeTexFormatTests: XCTestCase {
         var header = makeHeader()
         header.mipCount = 1
         header.payloadOffset = payloadOffset
-        header.totalPayloadSize = 100  // deliberately small
+        header.totalPayloadSize = 100 // deliberately small
 
         let overflowMip = NativeTexMipEntry(byteOffset: 0, byteSize: 9999, widthPx: 64, heightPx: 64)
 
@@ -218,7 +220,7 @@ final class NativeTexFormatTests: XCTestCase {
             width: 1024,
             height: 512,
             mipCount: 10,
-            pixelFormat: 186,  // MTLPixelFormat.astc_4x4_sRGB
+            pixelFormat: 186, // MTLPixelFormat.astc_4x4_sRGB
             blockWidth: 4,
             blockHeight: 4,
             payloadOffset: NativeTexFormat.payloadOffset(mipCount: 10),
@@ -242,7 +244,7 @@ final class NativeTexFormatTests: XCTestCase {
     /// so NativeTexReader can parse it without payload-bounds failures.
     private func makeMinimalContainer(mipCount: Int) -> Data {
         var header = makeHeader()
-        let mipByteSize: UInt32 = 16  // one ASTC block per mip (smallest valid payload)
+        let mipByteSize: UInt32 = 16 // one ASTC block per mip (smallest valid payload)
         let payloadOffset = NativeTexFormat.payloadOffset(mipCount: mipCount)
         header.mipCount = UInt32(mipCount)
         header.payloadOffset = payloadOffset
diff --git a/docs/images/engine-highlight-1.png b/docs/images/engine-highlight-1.png

Original file line number	Diff line number	Diff line change
`@@ -114,7 +114,7 @@`
`114`	`114`	`Text("Local Scene")`
`115`	`115`	`.foregroundStyle(.secondary)`
`116`	`116`	`.frame(width: 92, alignment: .leading)`
`117`		`- Menu("Select") {`
	`117`	`+ Menu("Browse") {`
`118`	`118`	`Button("Asset (.untold)", action: openLocalAssetPicker)`
`119`	`119`	`Button("Tiled Scene (.json)", action: openLocalTiledScenePicker)`
`120`	`120`	`}`