Sync fork develop with upstream: 0.23.0, glass against frames, specular AA, project layout (#1366), plus the headset rendering PRs for testing

.github/workflows/ci-build-test.yml

@@ -91,7 +91,7 @@ jobs:
       - name: Run renderer tests (non-async suites)
         # The sweep takes 26-30 minutes on the hosted macOS runners and grows with
         # every render suite; leave headroom so a slow runner is not a red build.
-        timeout-minutes: 45
+        timeout-minutes: 60
         env:
           CI: true
           UNTOLD_PSNR_THRESHOLD: "33.5"   # tweak per suite/scene

BuildChecks/MetalKernelsStaleCheck/checkStaleKernels.swift

@@ -0,0 +1,72 @@
+//
+//  checkStaleKernels.swift
+//  MetalKernelsStaleCheck
+//
+// Copyright (C) Untold Engine Studios
+//
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+// SwiftPM does not compile UntoldEngineKernels.metal; the engine target ships prebuilt
+// .metallib resources instead (see buildkernels.sh and Package.swift), so an edit to the
+// .metal source has no effect on `swift build` and produces no warning on its own.
+// UntoldEngineKernels.metal #includes every file in ../Shaders, so the compiled kernel
+// actually depends on all of them too — the hash below covers the kernels file and every
+// Shaders/*.metal file for that reason, not just the file SwiftPM excludes by name. This
+// plugin runs on every build plan and compares that hash against the one buildkernels.sh
+// stamped the last time it rebuilt the metallibs, so a stale shader binary is surfaced
+// instead of running silently.
+
+import CryptoKit
+import Foundation
+import PackagePlugin
+
+@main
+struct MetalKernelsStaleCheck: BuildToolPlugin {
+    /// `Target.directoryURL` needs PackageDescription 6.1; this package is on 6.0, so
+    /// `.directory` (deprecated `Path`) is the only way to locate the target on this
+    /// tools version. SwiftPM invokes this method through the `BuildToolPlugin`
+    /// existential at runtime rather than our code calling it directly, so marking it
+    /// deprecated silences the unavoidable warning here without anyone needing to call
+    /// a deprecated entry point themselves.
+    @available(*, deprecated)
+    func createBuildCommands(context _: PluginContext, target: Target) async throws -> [Command] {
+        let engineDir = URL(fileURLWithPath: target.directory.string)
+        let kernelsDir = engineDir.appending(path: "UntoldEngineKernels")
+        let shadersDir = engineDir.appending(path: "Shaders")
+        let metalSource = kernelsDir.appending(path: "UntoldEngineKernels.metal")
+        let hashFile = kernelsDir.appending(path: ".metalsource.sha256")
+
+        guard let kernelsData = try? Data(contentsOf: metalSource) else {
+            return []
+        }
+
+        let shaderFileNames = (try? FileManager.default.contentsOfDirectory(atPath: shadersDir.path))?
+            .filter { $0.hasSuffix(".metal") }
+            .sorted() ?? []
+
+        var combined = kernelsData
+        for name in shaderFileNames {
+            guard let data = try? Data(contentsOf: shadersDir.appending(path: name)) else { return [] }
+            combined.append(data)
+        }
+
+        let currentHash = SHA256.hash(data: combined).map { String(format: "%02x", $0) }.joined()
+        let storedHash = (try? String(contentsOf: hashFile, encoding: .utf8))?
+            .trimmingCharacters(in: .whitespacesAndNewlines)
+
+        if storedHash != currentHash {
+            Diagnostics.warning("""
+            UntoldEngineKernels.metal or one of the Shaders/*.metal files it includes has \
+            changed since the shipped .metallib resources were built (or \
+            \(hashFile.lastPathComponent) is missing). `swift build` does not recompile \
+            Metal shaders, so this build is running against stale shader binaries. Run \
+            ./buildkernels.sh from the package root, then commit the updated .metallib \
+            files and \(hashFile.lastPathComponent).
+            """)
+        }
+
+        return []
+    }
+}

CHANGELOG.md

@@ -1,4 +1,29 @@
 # Changelog
+## v0.23.0 - 2026-10-12
+### 🐞 Fixes
+- [Patch] Start a slot of objects as no reference (#1313) (6456434…)
+- [Bugfix] Export the material a slot linked to the object shows, not the mesh's default (#1320) (6b7b664…)
+- [Bugfix] Test occlusion from the camera the depth pyramid was built with (#1323) (45823f6…)
+- [Bugfix] Keep a model's hidden parts hidden at its coarse LOD levels (#1324) (c33fca8…)
+- [Bugfix] Detect pip --break-system-packages support in make testrenderer (#1328) (23d66a7…)
+- [Bugfix] Use single-bounce reflectance for IBL diffuse energy conservation (#1329) (a2b154d…)
+- [Bugfix] Report animation clips that match zero joints on the bound skeleton (#1330) (1085580…)
+- [Bugfix] Shade each XR eye from its own position (#1285) (0b2863d…)
+- [Bugfix] Glass keeps its place against its frame and in a headset (#1331) (144863a…)
+### 📚 Docs
+- [Docs] Add a getting-started tutorial for Jolt Physics in XR (#1327) (e544326…)
+### 🚀 Features
+- [Feature] Bake procedural Blender materials into repeating textures (#1307) (e8ed7ad…)
+- [Feature] Glass: a material's transmission shows what is behind it and keeps its reflections (#1308) (da580ee…)
+- [Feature] Select LOD levels by the size of the entity on screen (#1322) (6446393…)
+- [Feature] Specular anti-aliasing in the model pass (#1332) (99de731…)
+### ⚡ Performance
+- [Performance] The render passes read the scene through a snapshot (#1321) (8b695d6…)
+### ✨ Enhancement
+- [Enhancement] Add animation playback helpers for synchronized gameplay (#1316) (ec141a0…)
+### 🧹 Chores / Tests
+- Remove hardcoded AWS/CloudFront streaming URLs from demos and tests (#1317) (4ae99ca…)
+- [Test] Keep the reader of the component release test reading for the whole run (#1312) (9f3c637…)
 ## v0.22.0 - 2026-10-04
 ### 🐞 Fixes
 - [Patch] Remember failed texture writes per export, not per Blender session (#1263) (fa706bf…)

Package.swift

@@ -100,6 +100,11 @@ let package = Package(
             exclude: ["LICENSE.md", "README.md"],
             publicHeadersPath: "include"
         ),
+        .plugin(
+            name: "MetalKernelsStaleCheck",
+            capability: .buildTool(),
+            path: "BuildChecks/MetalKernelsStaleCheck"
+        ),
         .target(
             name: "UntoldEngine",
             dependencies: ["CShaderTypes"],
@@ -130,7 +135,8 @@ let package = Package(
 
                 // iOS UI stack (only if some targets import UIKit)
                 .linkedFramework("UIKit", .when(platforms: [.iOS])),
-            ]
+            ],
+            plugins: ["MetalKernelsStaleCheck"]
         ),
 
         // The cook's mesh work. A module of its own so that UntoldEngine does not import

README.md

@@ -1,7 +1,7 @@
 
 <h1 align="center">
   <a href="https://github.com/untoldengine/UntoldEngine">
-    <img src="docs/images/untoldenginewhite.png" alt="Logo" width="600">
+    <img src="docs/images/untoldengine-logo.png" alt="Untold Engine Logo" width="600">
   </a>
 </h1>
 
@@ -39,7 +39,7 @@ and input, so you can build your own interactive spatial and XR worlds.
 Creator & Lead Developer:  
 https://www.haroldserrano.com
 
-[![CoolSaber demo](docs/images/coolsaber-thumbnail.png)](https://youtu.be/4JWZf_NFddY)
+[![State of the Engine 2026](docs/images/state-of-the-engine-2026-thumbnail.png)](https://youtu.be/AnN2NBRKl8E)
 
 ---
 
@@ -64,6 +64,21 @@ workflow, product experience, and customer-specific behavior.
 
 ---
 
+## Try the Untold Editor
+
+The Untold Editor is a companion app for building scenes visually — placing
+entities, setting up lighting and cameras, and authoring `.untoldscene` files
+that load straight into your app with `loadUntoldScene(named:)`. It's
+optional — nothing in Untold Engine requires it — but it's the fastest way to
+get a scene on screen without hand-writing setup code.
+
+The Editor is now stable enough for regular use. Grab the latest build from
+the [Releases page](https://github.com/untoldengine/UntoldEditor/releases).
+
+![untold-editor](docs/images/editor-main-highlight.png)
+
+---
+
 ## Watch It in Action — Apple Vision Pro Demos
 
 | Demo | Description |
@@ -100,7 +115,7 @@ Clone the repository and launch the Starter Demo:
 ```bash
 git clone https://github.com/untoldengine/UntoldEngine.git
 cd UntoldEngine
-git checkout v0.22.0
+git checkout v0.23.0
 swift run StarterDemo
 ```
 
@@ -122,21 +137,6 @@ Engine as a package dependency.
 
 ---
 
-## Try the Untold Editor
-
-The Untold Editor is a companion app for building scenes visually — placing
-entities, setting up lighting and cameras, and authoring `.untoldscene` files
-that load straight into your app with `loadUntoldScene(named:)`. It's
-optional — nothing in Untold Engine requires it — but it's the fastest way to
-get a scene on screen without hand-writing setup code.
-
-The Editor is now stable enough for regular use. Grab the latest build from
-the [Releases page](https://github.com/untoldengine/UntoldEditor/releases).
-
-![untold-editor](docs/images/editor-main-highlight.png)
-
----
-
 ## Getting Started
 
 To create your own XR, 3D, or spatial visualization app using Untold Engine,
@@ -159,20 +159,23 @@ start with the documentation path that matches where you are:
 If your team is evaluating Untold Engine and needs an engine capability that is
 not currently available, see [Commercial Use, Sponsored Features, and Support](COMMERCIAL.md).
 
-## Core Direction
+## Our Direction
+
+### Vision — Why We Exist
+
+> An engine that empowers creativity and never stands in its way.
 
-**Vision:** An engine that empowers creativity and never stands in its way.
+### Mission — What We Commit To
 
-**Mission:** Build a reliable engine that lets developers focus on creating,
-not troubleshooting the tools they depend on.
+> Build a reliable engine that lets developers focus on creating, not troubleshooting the tools they depend on.
 
-Untold Engine is built around three focused goals:
+### Engineering Principles — How We Operate
 
-- **Spatial Engine First** — Designed for spatial computing applications. LOD, geometry streaming, and static batching exist to support large, real-world-scale environments where presence and performance both matter.
+**Reliability · Testing · Simplicity · Compatibility · Developer Experience · Performance**
 
-- **XR / visionOS Support** — Spatial input, AR workflows, and Vision Pro support are functional today and expanding with each release.
+These principles guide how we design, build, test, and maintain Untold Engine.
 
-- **Metal-First Architecture** — The rendering layer stays close to Metal to maintain performance, shader control, and pipeline flexibility without abstraction layers getting in the way.
+Read our [Engineering Principles](docs/Contributor/EngineeringPrinciples.md) for the standards that guide our development decisions.
 
 ---
 
@@ -219,6 +222,7 @@ Untold Engine is built around three focused goals:
 - [Async Loading](docs/API/UsingAsyncLoading.md)
 - [Spatial Input](docs/API/UsingSpatialInput.md)
 - [XR Immersion Modes](docs/API/UsingXRImmersionMode.md)
+- [The Vision Pro Rendering Profile, As Measured](docs/API/VisionProRenderingProfile.md)
 - [Light Portals](docs/API/UsingLightPortals.md)
 - [Rendering Extensions](docs/API/UsingRenderingExtensions.md)
 - [Rendering Extension Examples](Examples/RenderingExtensions/README.md)