Add FILAMENT_DEBUG_COMMANDS_HISTOGRAM compile flag

BUGS=[486200381]

.github/workflows/postsubmit-main.yml

@@ -6,6 +6,8 @@ on:
       - main
 
 jobs:
+  # Update the renderdiff goldens in filament-assets. This will add or merge the new goldens from
+  # a branch on filament-assets.
   update-renderdiff-goldens:
     name: update-renderdiff-goldens
     runs-on: 'ubuntu-24.04-4core'
@@ -16,8 +18,8 @@ jobs:
       - uses: ./.github/actions/linux-prereq
       - id: get_commit_msg
         uses: ./.github/actions/get-commit-msg
-      - name: Prerequisites
-        run: pip install tifffile numpy
+      - name: Build diffimg
+        run: ./build.sh release diffimg
       - name: Run update script
         env:
           GH_TOKEN: ${{ secrets.FILAMENTBOT_TOKEN }}
@@ -35,6 +37,7 @@ jobs:
                   --merge-to-main --filament-tag=${COMMIT_HASH} --golden-repo-token=${GH_TOKEN}
           fi
 
+  # Update the /docs (offiicla github-hosted Filament site) if necessary
   update-docs:
     name: update-docs
     runs-on: 'ubuntu-24.04-4core'
@@ -57,3 +60,40 @@ jobs:
           git config --global user.name "Filament Bot"
           git config --global credential.helper cache
           bash docs_src/build/postsubmit.sh ${COMMIT_HASH} ${GH_TOKEN}
+
+  # Produce a json that describes the android artifact sizes, and will push that json to a folder in
+  # filament-assets
+  update-sizeguard:
+    name: update-sizeguard
+    runs-on: 'ubuntu-24.04-16core'
+    steps:
+      - uses: actions/checkout@v4.1.6
+        with:
+          fetch-depth: 0
+      - uses: ./.github/actions/linux-prereq
+      - uses: actions/setup-java@v3
+        with:
+          distribution: 'temurin'
+          java-version: '17'
+      - id: get_commit_msg
+        uses: ./.github/actions/get-commit-msg
+      - name: Build and generate size report
+        run: |
+          cd build/android && printf "y" | ./build.sh release all
+          cd ../..
+          COMMIT_HASH="${{ steps.get_commit_msg.outputs.hash }}"
+          python3 test/sizeguard/dump_artifact_size.py out/*.tgz out/*.aar > "${COMMIT_HASH}.json"
+      - name: Push to filament-assets
+        env:
+          GH_TOKEN: ${{ secrets.FILAMENTBOT_TOKEN }}
+        run: |
+          COMMIT_HASH="${{ steps.get_commit_msg.outputs.hash }}"
+          git config --global user.email "filament.bot@gmail.com"
+          git config --global user.name "Filament Bot"
+          git clone https://x-access-token:${GH_TOKEN}@github.com/google/filament-assets.git filament-assets
+          mkdir -p filament-assets/sizeguard
+          mv "${COMMIT_HASH}.json" filament-assets/sizeguard/
+          cd filament-assets
+          git add sizeguard/"${COMMIT_HASH}.json"
+          git commit -m "Update sizeguard for filament@${COMMIT_HASH}" || echo "No changes to commit"
+          git push https://x-access-token:${GH_TOKEN}@github.com/google/filament-assets.git main

.github/workflows/presubmit.yml

@@ -67,7 +67,16 @@ jobs:
         # Only build 1 64 bit target during presubmit to cut down build times during presubmit
         # Continuous builds will build everything
         run: |
-          cd build/android && printf "y" | ./build.sh presubmit arm64-v8a
+          pushd .
+          cd build/android && printf "y" | ./build.sh presubmit-with-archive arm64-v8a
+          popd
+      - name: Check artifact sizes
+        run: |
+          python3 test/sizeguard/dump_artifact_size.py out/*.aar > current_size.json
+          python3 test/sizeguard/check_size.py current_size.json \
+              --target-branch origin/main \
+              --threshold 20480 \
+              --artifacts filament-android-release.aar/jni/arm64-v8a/libfilament-jni.so
 
   build-ios:
     name: build-iOS
@@ -125,7 +134,6 @@ jobs:
         uses: ./.github/actions/get-commit-msg
       - name: Prerequisites
         run: |
-          pip install tifffile numpy
           # Must have at least clang-16 for a webgpu/dawn build.
           sudo xcode-select -s /Applications/Xcode_16.2.app/Contents/Developer
         shell: bash
@@ -139,6 +147,9 @@ jobs:
           set -eux
           GOLDEN_BRANCH=$(echo "${COMMIT_MESSAGE}" | python3 ${TEST_DIR}/src/commit_msg.py)
           bash ${TEST_DIR}/generate.sh
+          # Build diffimg tool
+          ./build.sh release diffimg
+
           python3 ${TEST_DIR}/src/golden_manager.py \
                   --branch=${GOLDEN_BRANCH} \
                   --output=${GOLDEN_OUTPUT_DIR}
@@ -149,7 +160,9 @@ jobs:
           python3 ${TEST_DIR}/src/compare.py \
               --src=${GOLDEN_OUTPUT_DIR} \
               --dest=${RENDER_OUTPUT_DIR} \
-              --out=${DIFF_OUTPUT_DIR} 2>&1 | tee compare_output.txt
+              --out=${DIFF_OUTPUT_DIR} \
+              --diffimg="$(pwd)/out/cmake-release/tools/diffimg/diffimg" \
+              --test="${TEST_DIR}/tests/presubmit.json" 2>&1 | tee compare_output.txt
 
           if grep "Failed" compare_output.txt > /dev/null; then
              DELIMITER="EOF_FILE_CONTENT_$(date +%s)" # Using timestamp to make it more unique

.github/workflows/release.yml

@@ -163,9 +163,7 @@ jobs:
           mv out/filamat-android-release.aar out/filamat-${TAG}-android.aar
           mv out/gltfio-android-release.aar out/gltfio-${TAG}-android.aar
           mv out/filament-utils-android-release.aar out/filament-utils-${TAG}-android.aar
-          cd out/android-release/filament
-          tar -czf ../../filament-${TAG}-android-native.tgz .
-          cd ../../..
+          mv out/filament-android-release-linux.tgz out/filament-${TAG}-android-native.tgz
       - name: Sign sample-gltf-viewer
         run: |
           echo "${APK_KEYSTORE_BASE64}" > filament.jks.base64

CMakeLists.txt

@@ -65,6 +65,8 @@ option(FILAMENT_SUPPORTS_WEBP_TEXTURES "Enable webp texture support for Filament
 # On the regular filament build (where size is of less concern), we enable GTAO by default.
 option(FILAMENT_DISABLE_GTAO "Disable GTAO" OFF)
 
+option(FILAMENT_BUILD_TESTING "Build tests" ON)
+
 set(FILAMENT_NDK_VERSION "" CACHE STRING
     "Android NDK version or version prefix to be used when building for Android."
 )
@@ -877,6 +879,7 @@ add_subdirectory(${LIBRARIES}/gltfio)
 add_subdirectory(${LIBRARIES}/ibl)
 add_subdirectory(${LIBRARIES}/iblprefilter)
 add_subdirectory(${LIBRARIES}/image)
+add_subdirectory(${LIBRARIES}/imagediff)
 add_subdirectory(${LIBRARIES}/ktxreader)
 add_subdirectory(${LIBRARIES}/math)
 add_subdirectory(${LIBRARIES}/mathio)
@@ -903,6 +906,8 @@ add_subdirectory(${EXTERNAL}/getopt)
 add_subdirectory(${EXTERNAL}/perfetto/tnt)
 add_subdirectory(${EXTERNAL}/basisu/tnt)
 
+# imageio-lite is needed for viewer
+add_subdirectory(${LIBRARIES}/imageio-lite)
 
 # Note that this has to be placed after mikktspace in order for combine_static_libs to work.
 add_subdirectory(${LIBRARIES}/geometry)
@@ -971,6 +976,7 @@ if (IS_HOST_PLATFORM)
 
     add_subdirectory(${TOOLS}/cmgen)
     add_subdirectory(${TOOLS}/cso-lut)
+    add_subdirectory(${TOOLS}/diffimg)
     add_subdirectory(${TOOLS}/filamesh)
     add_subdirectory(${TOOLS}/glslminifier)
     add_subdirectory(${TOOLS}/matc)

NEW_RELEASE_NOTES.md

@@ -7,5 +7,4 @@ appropriate header in [RELEASE_NOTES.md](./RELEASE_NOTES.md).
 
 ## Release notes for next branch cut
 
-- engine: fix shader compilation failure in TAA material
-- engine: fix stereo & parallel shader compilation
+- engine: fix crash when using variance shadow maps

README.md

@@ -31,7 +31,7 @@ repositories {
 }
 
 dependencies {
-    implementation 'com.google.android.filament:filament-android:1.69.1'
+    implementation 'com.google.android.filament:filament-android:1.69.3'
 }
 ```
 
@@ -39,19 +39,18 @@ Here are all the libraries available in the group `com.google.android.filament`:
 
 | Artifact      | Description   |
 | ------------- | ------------- |
-| [![filament-android](https://maven-badges.herokuapp.com/maven-central/com.google.android.filament/filament-android/badge.svg?subject=filament-android)](https://maven-badges.herokuapp.com/maven-central/com.google.android.filament/filament-android)  | The Filament rendering engine itself. |
-| [![filament-android-debug](https://maven-badges.herokuapp.com/maven-central/com.google.android.filament/filament-android-debug/badge.svg?subject=filament-android-debug)](https://maven-badges.herokuapp.com/maven-central/com.google.android.filament/filament-android-debug)  | Debug version of `filament-android`. |
-| [![gltfio-android](https://maven-badges.herokuapp.com/maven-central/com.google.android.filament/gltfio-android/badge.svg?subject=gltfio-android)](https://maven-badges.herokuapp.com/maven-central/com.google.android.filament/gltfio-android) | A glTF 2.0 loader for Filament, depends on `filament-android`. |
-| [![filament-utils-android](https://maven-badges.herokuapp.com/maven-central/com.google.android.filament/filament-utils-android/badge.svg?subject=filament-utils-android)](https://maven-badges.herokuapp.com/maven-central/com.google.android.filament/filament-utils-android) | KTX loading, Kotlin math, and camera utilities, depends on `gltfio-android`. |
-| [![filamat-android](https://maven-badges.herokuapp.com/maven-central/com.google.android.filament/filamat-android/badge.svg?subject=filamat-android)](https://maven-badges.herokuapp.com/maven-central/com.google.android.filament/filamat-android) | A runtime material builder/compiler. This library is large but contains a full shader compiler/validator/optimizer and supports both OpenGL and Vulkan. |
-| [![filamat-android-lite](https://maven-badges.herokuapp.com/maven-central/com.google.android.filament/filamat-android-lite/badge.svg?subject=filamat-android-lite)](https://maven-badges.herokuapp.com/maven-central/com.google.android.filament/filamat-android-lite) | A much smaller alternative to `filamat-android` that can only generate OpenGL shaders. It does not provide validation or optimizations. |
+| [![filament-android](https://img.shields.io/maven-central/v/com.google.android.filament/filament-android?label=filament-android&color=green)](https://mvnrepository.com/artifact/com.google.android.filament/filament-android)  | The Filament rendering engine itself. |
+| [![filament-android-debug](https://img.shields.io/maven-central/v/com.google.android.filament/filament-android-debug?label=filament-android-debug&color=green)](https://mvnrepository.com/artifact/com.google.android.filament/filament-android-debug)  | Debug version of `filament-android`. |
+| [![gltfio-android](https://img.shields.io/maven-central/v/com.google.android.filament/gltfio-android?label=gltfio-android&color=green)](https://mvnrepository.com/artifact/com.google.android.filament/gltfio-android) | A glTF 2.0 loader for Filament, depends on `filament-android`. |
+| [![filament-utils-android](https://img.shields.io/maven-central/v/com.google.android.filament/filament-utils-android?label=filament-utils-android&color=green)](https://mvnrepository.com/artifact/com.google.android.filament/filament-utils-android) | KTX loading, Kotlin math, and camera utilities, depends on `gltfio-android`. |
+| [![filamat-android](https://img.shields.io/maven-central/v/com.google.android.filament/filamat-android?label=filamat-android&color=green)](https://mvnrepository.com/artifact/com.google.android.filament/filamat-android) | A runtime material builder/compiler. This library is large but contains a full shader compiler/validator/optimizer and supports both OpenGL and Vulkan. |
 
 ### iOS
 
 iOS projects can use CocoaPods to install the latest release:
 
 ```shell
-pod 'Filament', '~> 1.69.1'
+pod 'Filament', '~> 1.69.3'
 ```
 
 ## Documentation
@@ -89,7 +88,8 @@ pod 'Filament', '~> 1.69.1'
 - OpenGL ES 3.0+ for Android and iOS
 - Metal for macOS and iOS
 - Vulkan 1.0 for Android, Linux, macOS, and Windows
-- WebGL 2.0 for all platforms
+- WebGPU for Android, Linux, macOS, and Windows
+- WebGL 2.0 for all browsers supporting it
 
 ### Rendering
 
@@ -124,7 +124,7 @@ pod 'Filament', '~> 1.69.1'
 
 - HDR bloom
 - Depth of field bokeh
-- Multiple tone mappers: generic (customizable), ACES, filmic, etc.
+- Multiple tone mappers: PBR Neutral, AgX, generic (customizable), ACES, filmic, etc.
 - Color and tone management: luminance scaling, gamut mapping
 - Color grading: exposure, night adaptation, white balance, channel mixer,
   shadows/mid-tones/highlights, ASC CDL, contrast, saturation, etc.
@@ -158,15 +158,16 @@ pod 'Filament', '~> 1.69.1'
   - [x] KHR_draco_mesh_compression
   - [x] KHR_lights_punctual
   - [x] KHR_materials_clearcoat
+  - [x] KHR_materials_dispersion
   - [x] KHR_materials_emissive_strength
   - [x] KHR_materials_ior
   - [x] KHR_materials_pbrSpecularGlossiness
   - [x] KHR_materials_sheen
+  - [x] KHR_materials_specular
   - [x] KHR_materials_transmission
   - [x] KHR_materials_unlit
   - [x] KHR_materials_variants
   - [x] KHR_materials_volume
-  - [x] KHR_materials_specular
   - [x] KHR_mesh_quantization
   - [x] KHR_texture_basisu
   - [x] KHR_texture_transform
@@ -331,7 +332,7 @@ and tools.
   - `filamesh`:               Mesh converter
   - `glslminifier`:           Minifies GLSL source code
   - `matc`:                   Material compiler
-  - `filament-matp`:          Material parser
+  - `matedit`:                Material editor for compiled materials
   - `matinfo`                 Displays information about materials compiled with `matc`
   - `mipgen`                  Generates a series of miplevels from a source image
   - `normal-blending`:        Tool to blend normal maps

RELEASE_NOTES.md

@@ -7,6 +7,17 @@ A new header is inserted each time a *tag* is created.
 Instead, if you are authoring a PR for the main branch, add your release note to
 [NEW_RELEASE_NOTES.md](./NEW_RELEASE_NOTES.md).
 
+## v1.69.4
+
+
+## v1.69.3
+
+
+## v1.69.2
+
+- engine: fix shader compilation failure in TAA material
+- engine: fix stereo & parallel shader compilation
+
 ## v1.69.1
 
 

android/buildSrc/README.md

@@ -0,0 +1,120 @@
+# Filament Tools Gradle Plugin
+
+## About
+
+The **Filament Tools Gradle Plugin** helps integrate Filament into your Android project. It
+automates the use of Filament's command-line tools (`matc`, `cmgen`, and `filamesh`).
+
+This plugin handles:
+- **Material Compilation**: Compiles `.mat` material definitions into `.filamat` binaries.
+- **IBL Generation**: Generates Image-Based Lighting assets from HDR environment maps.
+- **Mesh Compilation**: Converts models into Filament's efficient `.filamesh` binary format. *Note:
+  This tool is no longer recommended; instead, use glTF and Filament's `gltfio` library for model
+  loading.*
+
+The plugin hooks directly into the Android build lifecycle (via `preBuild`) and supports incremental
+builds, so assets are only recompiled when source files change.
+
+## Usage
+
+Apply the plugin in your module's `build.gradle` file and configure the `filament` block. You can
+specify inputs and outputs for any combination of materials, IBLs, or meshes. If a path is not
+configured, the corresponding task will be disabled.
+
+### Example Configuration
+
+```groovy
+plugins {
+    id 'filament-plugin'
+}
+
+filament {
+    materialInputDir = project.layout.projectDirectory.dir("src/main/materials")
+    materialOutputDir = project.layout.projectDirectory.dir("src/main/assets/materials")
+
+    iblInputFile = project.layout.projectDirectory.file("path/to/environment.hdr")
+    iblOutputDir = project.layout.projectDirectory.dir("src/main/assets/envs")
+
+    meshInputFile = project.layout.projectDirectory.file("path/to/model.obj")
+    meshOutputDir = project.layout.projectDirectory.dir("src/main/assets/models")
+}
+```
+
+### Configuration Details
+
+- **materialInputDir**: The directory containing your source material definitions (`.mat` files).
+- **materialOutputDir**: The directory where the compiled material files (`.filamat`) will be
+  generated.
+- **iblInputFile**: The source high-dynamic-range image file (e.g., `.hdr` or `.exr`) used to
+  generate Image Based Lighting assets.
+- **iblOutputDir**: The directory where the generated IBL assets (typically `.ktx` files) will be
+  placed.
+- **meshInputFile**: The source mesh file (e.g., `.obj`) to be compiled.
+- **meshOutputDir**: The directory where the compiled mesh file (`.filamesh`) will be generated.
+
+Automatically adds tasks to your Android build to compile materials, generate an IBL, and compile a
+mesh. The plugin hooks into `preBuild` to ensure assets are generated before the application is
+built.
+
+### Configuration Flags
+
+You can control specific compilation options using Gradle properties (e.g., in `gradle.properties`
+or via command line `-P`).
+
+- **`com.google.android.filament.exclude-vulkan`**  When set to `true`, the Vulkan backend is
+  excluded from the compiled materials. This can be useful to reduce the size of the generated
+  assets if your application does not target Vulkan.  *Default: `false` (Vulkan is included)*
+
+- **`com.google.android.filament.include-webgpu`**  When set to `true`, the WebGPU backend is
+  included in the compiled materials. Use this if you intend to use the materials in a context
+  supporting WebGPU.  *Default: `false`*
+
+## Tools Configuration
+
+The Filament Tools plugin requires some binary tools to be available: `matc`, `cmgen`, and
+`filamesh`.
+
+There are three ways to configure Filament tools:
+
+1. **Point to a local path directly**
+
+```groovy
+filament {
+    matc {
+        path = "/path/to/matc"
+    }
+
+    cmgen {
+        path = "/path/to/cmgen"
+    }
+
+    filamesh {
+        path = "/path/to/filamesh"
+    }
+}
+```
+
+2. **Point to a Maven artifact**
+
+```groovy
+filament {
+    matc {
+        // The minor version (the middle number) must match the Filament dependency's.
+        artifact = 'com.google.android.filament:matc:1.68.5'
+    }
+
+    cmgen {
+        artifact = 'com.google.android.filament:cmgen:1.68.5'
+    }
+}
+```
+
+*Note that the `filamesh` artifact is not hosted on Maven Central, so it must be provided locally or
+via another mechanism if needed.*
+
+Gradle will automatically handle downloading the tool appropriate for your machine (MacOS/Linux/Windows) from Maven.
+
+3. **Set the `com.google.android.filament.tools-dir` Gradle property**
+
+This will override any other configuration. Gradle will attempt to locate the tools under
+`<tools-dir>/bin` (e.g., `.../bin/matc`, `.../bin/cmgen`, `.../bin/filamesh`).

android/buildSrc/build.gradle

@@ -4,13 +4,18 @@ plugins {
 
 gradlePlugin {
     plugins {
-        create("filament-tools-plugin") {
-            id = "filament-tools-plugin"
-            implementationClass = "FilamentToolsPlugin"
+        create("filament-plugin") {
+            id = "filament-plugin"
+            implementationClass = "com.google.android.filament.gradle.FilamentPlugin"
         }
     }
 }
 
 repositories {
     mavenCentral()
+    gradlePluginPortal()
+}
+
+dependencies {
+    implementation "com.google.gradle:osdetector-gradle-plugin:1.7.3"
 }

android/buildSrc/src/main/groovy/FilamentPlugin.groovy

@@ -1,359 +0,0 @@
-// This plugin accepts the following parameters:
-//
-// com.google.android.filament.tools-dir
-//     Path to the Filament distribution/install directory for desktop.
-//     This directory must contain bin/matc.
-//
-// com.google.android.filament.exclude-vulkan
-//     When set, support for Vulkan will be excluded.
-//
-// Example:
-//     ./gradlew -Pcom.google.android.filament.tools-dir=../../dist-release assembleDebug
-
-import org.gradle.api.DefaultTask
-import org.gradle.api.GradleException
-import org.gradle.api.Plugin
-import org.gradle.api.Project
-import org.gradle.api.provider.ProviderFactory
-import org.gradle.api.file.DirectoryProperty
-import org.gradle.api.file.FileSystemOperations
-import org.gradle.api.file.FileType
-import org.gradle.api.file.RegularFileProperty
-import org.gradle.api.logging.LogLevel
-import org.gradle.api.logging.Logger
-import org.gradle.api.provider.Property
-import org.gradle.api.tasks.Input
-import org.gradle.api.tasks.InputDirectory
-import org.gradle.api.tasks.InputFile
-import org.gradle.api.tasks.Optional
-import org.gradle.api.tasks.OutputDirectory
-import org.gradle.api.tasks.TaskAction
-import org.gradle.api.tasks.incremental.InputFileDetails
-import org.gradle.api.model.ObjectFactory
-import org.gradle.internal.os.OperatingSystem
-import org.gradle.process.ExecOperations
-import org.gradle.work.ChangeType
-import org.gradle.work.Incremental
-import org.gradle.work.InputChanges
-
-import java.nio.file.Paths
-
-import javax.inject.Inject
-
-abstract class TaskWithBinary extends DefaultTask {
-    private final String binaryName
-    private Property<String> binaryPath = null
-
-    TaskWithBinary(String name) {
-        binaryName = name
-    }
-
-    @Inject abstract ObjectFactory getObjects()
-    @Inject abstract ProviderFactory getProviders()
-
-    @Input
-    Property<String> getBinary() {
-        if (binaryPath == null) {
-            def tool = ["/bin/${binaryName}.exe", "/bin/${binaryName}"]
-            def fullPath = tool.collect { path ->
-                def filamentToolsPath = providers
-                        .gradleProperty("com.google.android.filament.tools-dir")
-                        .forUseAtConfigurationTime().get()
-                def directory = objects.fileProperty()
-                        .fileValue(new File(filamentToolsPath)).getAsFile().get()
-                Paths.get(directory.absolutePath, path).toFile()
-            }
-
-            binaryPath = objects.property(String.class)
-            binaryPath.set(
-                    (OperatingSystem.current().isWindows() ? fullPath[0] : fullPath[1]).toString())
-        }
-        return binaryPath
-    }
-}
-
-class LogOutputStream extends ByteArrayOutputStream {
-    private final Logger logger
-    private final LogLevel level
-
-    LogOutputStream(Logger logger, LogLevel level) {
-        this.logger = logger
-        this.level = level
-    }
-
-    @Override
-    void flush() {
-        logger.log(level, toString())
-        reset()
-    }
-}
-
-// Custom task to compile material files using matc
-// This task handles incremental builds
-abstract class MaterialCompiler extends TaskWithBinary {
-    @Incremental
-    @InputDirectory
-    abstract DirectoryProperty getInputDir()
-
-    @OutputDirectory
-    abstract DirectoryProperty getOutputDir()
-
-    @Inject abstract FileSystemOperations getFs()
-    @Inject abstract ExecOperations getExec()
-    @Inject abstract ObjectFactory getObjects()
-    @Inject abstract ProviderFactory getProviders()
-
-    MaterialCompiler() {
-        super("matc")
-    }
-
-    @TaskAction
-    void execute(InputChanges inputs) {
-        if (!inputs.incremental) {
-            fs.delete({
-                delete(objects.fileTree().from(outputDir).matching { include '*.filamat' })
-            })
-        }
-
-        inputs.getFileChanges(inputDir).each { InputFileDetails change ->
-            if (change.fileType == FileType.DIRECTORY) return
-
-            def file = change.file
-
-            if (change.changeType == ChangeType.REMOVED) {
-                getOutputFile(file).delete()
-            } else {
-                def out = new LogOutputStream(logger, LogLevel.LIFECYCLE)
-                def err = new LogOutputStream(logger, LogLevel.ERROR)
-
-                def header = ("Compiling material " + file + "\n").getBytes()
-                out.write(header)
-                out.flush()
-
-                if (!new File(binary.get()).exists()) {
-                    throw new GradleException("Could not find ${binary.get()}." +
-                            " Ensure Filament has been built/installed before building this app.")
-                }
-
-                def matcArgs = []
-                def exclude_vulkan = providers
-                        .gradleProperty("com.google.android.filament.exclude-vulkan")
-                        .forUseAtConfigurationTime().present
-                if (!exclude_vulkan) {
-                    matcArgs += ['-a', 'vulkan']
-                }
-                def include_webgpu = providers
-                        .gradleProperty("com.google.android.filament.include-webgpu")
-                        .forUseAtConfigurationTime().present
-                if (include_webgpu) {
-                    matcArgs += ['-a', 'webgpu', '--variant-filter=stereo']
-                }
-
-                def mat_no_opt = providers
-                        .gradleProperty("com.google.android.filament.matnopt")
-                        .forUseAtConfigurationTime().present
-                if (mat_no_opt) {
-                    matcArgs += ['-g']
-                }
-
-                matcArgs += ['-a', 'opengl', '-p', 'mobile', '-o', getOutputFile(file), file]
-
-                exec.exec {
-                    standardOutput out
-                    errorOutput err
-                    executable "${binary.get()}"
-                    args matcArgs
-                }
-            }
-        }
-    }
-
-    File getOutputFile(final File file) {
-        return outputDir.file(file.name[0..file.name.lastIndexOf('.')] + 'filamat').get().asFile
-    }
-}
-
-// Custom task to process IBLs using cmgen
-// This task handles incremental builds
-abstract class IblGenerator extends TaskWithBinary {
-    @Input
-    @Optional
-    abstract Property<String> getCmgenArgs()
-
-    @Incremental
-    @InputFile
-    abstract RegularFileProperty getInputFile()
-
-    @OutputDirectory
-    abstract DirectoryProperty getOutputDir()
-
-    @Inject abstract FileSystemOperations getFs()
-    @Inject abstract ExecOperations getExec()
-    @Inject abstract ObjectFactory getObjects()
-
-    IblGenerator() {
-        super("cmgen")
-    }
-
-    @TaskAction
-    void execute(InputChanges inputs) {
-        if (!inputs.incremental) {
-            fs.delete({
-                delete(objects.fileTree().from(outputDir).matching { include '*' })
-            })
-        }
-
-        inputs.getFileChanges(inputFile).each { InputFileDetails change ->
-            if (change.fileType == FileType.DIRECTORY) return
-
-            def file = change.file
-
-            if (change.changeType == ChangeType.REMOVED) {
-                getOutputFile(file).delete()
-            } else {
-                def out = new LogOutputStream(logger, LogLevel.LIFECYCLE)
-                def err = new LogOutputStream(logger, LogLevel.ERROR)
-
-                def header = ("Generating IBL " + file + "\n").getBytes()
-                out.write(header)
-                out.flush()
-
-                if (!new File(binary.get()).exists()) {
-                    throw new GradleException("Could not find ${binary.get()}." +
-                            " Ensure Filament has been built/installed before building this app.")
-                }
-
-                def outputPath = outputDir.get().asFile
-                def commandArgs = cmgenArgs.getOrNull()
-                if (commandArgs == null) {
-                    commandArgs =
-                            '-q -x ' + outputPath + ' --format=rgb32f ' +
-                                    '--extract-blur=0.08 --extract=' + outputPath.absolutePath
-                }
-                commandArgs = commandArgs + " " + file
-
-                exec.exec {
-                    standardOutput out
-                    errorOutput err
-                    executable "${binary.get()}"
-                    args(commandArgs.split())
-                }
-            }
-        }
-    }
-
-    File getOutputFile(final File file) {
-        return outputDir.file(file.name[0..file.name.lastIndexOf('.') - 1]).get().asFile
-    }
-}
-
-// Custom task to compile mesh files using filamesh
-// This task handles incremental builds
-abstract class MeshCompiler extends TaskWithBinary {
-    @Incremental
-    @InputFile
-    abstract RegularFileProperty getInputFile()
-
-    @OutputDirectory
-    abstract DirectoryProperty getOutputDir()
-
-    @Inject abstract FileSystemOperations getFs()
-    @Inject abstract ExecOperations getExec()
-
-    MeshCompiler() {
-        super("filamesh")
-    }
-
-    @TaskAction
-    void execute(InputChanges inputs) {
-        if (!inputs.incremental) {
-            fs.delete({
-                delete(objects.fileTree().from(outputDir).matching { include '*.filamesh' })
-            })
-        }
-
-        inputs.getFileChanges(inputFile).each { InputFileDetails change ->
-            if (change.fileType == FileType.DIRECTORY) return
-
-            def file = change.file
-
-            if (change.changeType == ChangeType.REMOVED) {
-                getOutputFile(file).delete()
-            } else {
-                def out = new LogOutputStream(logger, LogLevel.LIFECYCLE)
-                def err = new LogOutputStream(logger, LogLevel.ERROR)
-
-                def header = ("Compiling mesh " + file + "\n").getBytes()
-                out.write(header)
-                out.flush()
-
-                if (!new File(binary.get()).exists()) {
-                    throw new GradleException("Could not find ${binary.get()}." +
-                            " Ensure Filament has been built/installed before building this app.")
-                }
-
-                exec.exec {
-                    standardOutput out
-                    errorOutput err
-                    executable "${binary.get()}"
-                    args(file, getOutputFile(file))
-                }
-            }
-        }
-    }
-
-    File getOutputFile(final File file) {
-        return outputDir.file(file.name[0..file.name.lastIndexOf('.')] + 'filamesh').get().asFile
-    }
-}
-
-class FilamentToolsPluginExtension {
-    DirectoryProperty materialInputDir
-    DirectoryProperty materialOutputDir
-
-    String cmgenArgs
-    RegularFileProperty iblInputFile
-    DirectoryProperty iblOutputDir
-
-    RegularFileProperty meshInputFile
-    DirectoryProperty meshOutputDir
-}
-
-class FilamentToolsPlugin implements Plugin<Project> {
-    void apply(Project project) {
-        def extension = project.extensions.create('filamentTools', FilamentToolsPluginExtension)
-        extension.materialInputDir = project.objects.directoryProperty()
-        extension.materialOutputDir = project.objects.directoryProperty()
-        extension.iblInputFile = project.objects.fileProperty()
-        extension.iblOutputDir = project.objects.directoryProperty()
-        extension.meshInputFile = project.objects.fileProperty()
-        extension.meshOutputDir = project.objects.directoryProperty()
-
-        project.tasks.register("filamentCompileMaterials", MaterialCompiler) {
-            enabled =
-                    extension.materialInputDir.isPresent() &&
-                    extension.materialOutputDir.isPresent()
-            inputDir.set(extension.materialInputDir.getOrNull())
-            outputDir.set(extension.materialOutputDir.getOrNull())
-        }
-
-        project.preBuild.dependsOn "filamentCompileMaterials"
-
-        project.tasks.register("filamentGenerateIbl", IblGenerator) {
-            enabled = extension.iblInputFile.isPresent() && extension.iblOutputDir.isPresent()
-            cmgenArgs = extension.cmgenArgs
-            inputFile = extension.iblInputFile.getOrNull()
-            outputDir = extension.iblOutputDir.getOrNull()
-        }
-
-        project.preBuild.dependsOn "filamentGenerateIbl"
-
-        project.tasks.register("filamentCompileMesh", MeshCompiler) {
-            enabled = extension.meshInputFile.isPresent() && extension.meshOutputDir.isPresent()
-            inputFile = extension.meshInputFile.getOrNull()
-            outputDir = extension.meshOutputDir.getOrNull()
-        }
-
-        project.preBuild.dependsOn "filamentCompileMesh"
-    }
-}

android/buildSrc/src/main/groovy/com/google/android/filament/gradle/FilamentExtension.groovy

@@ -0,0 +1,57 @@
+/*
+ * Copyright (C) 2026 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.google.android.filament.gradle
+
+import org.gradle.api.Action
+import org.gradle.api.Project
+import org.gradle.api.file.DirectoryProperty
+import org.gradle.api.file.RegularFileProperty
+import org.gradle.api.provider.Property
+
+class FilamentExtension {
+    final ToolsLocator tools
+    final DirectoryProperty materialInputDir
+    final DirectoryProperty materialOutputDir
+    final Property<String> cmgenArgs
+    final RegularFileProperty iblInputFile
+    final DirectoryProperty iblOutputDir
+    final RegularFileProperty meshInputFile
+    final DirectoryProperty meshOutputDir
+
+    FilamentExtension(Project project) {
+        this.tools = new ToolsLocator(project)
+        this.materialInputDir = project.objects.directoryProperty()
+        this.materialOutputDir = project.objects.directoryProperty()
+        this.cmgenArgs = project.objects.property(String)
+        this.iblInputFile = project.objects.fileProperty()
+        this.iblOutputDir = project.objects.directoryProperty()
+        this.meshInputFile = project.objects.fileProperty()
+        this.meshOutputDir = project.objects.directoryProperty()
+    }
+
+    void matc(Action<ToolsLocator.ToolConfig> action) {
+        action.execute(tools.matc)
+    }
+
+    void cmgen(Action<ToolsLocator.ToolConfig> action) {
+        action.execute(tools.cmgen)
+    }
+
+    void filamesh(Action<ToolsLocator.ToolConfig> action) {
+        action.execute(tools.filamesh)
+    }
+}

android/buildSrc/src/main/groovy/com/google/android/filament/gradle/FilamentPlugin.groovy

@@ -0,0 +1,59 @@
+/*
+ * Copyright (C) 2026 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.google.android.filament.gradle
+
+import org.gradle.api.Plugin
+import org.gradle.api.Project
+
+class FilamentPlugin implements Plugin<Project> {
+    @Override
+    void apply(Project project) {
+        project.pluginManager.apply("com.google.osdetector")
+
+        FilamentExtension extension = project.extensions.create("filament", FilamentExtension, project)
+
+        project.afterEvaluate {
+            extension.tools.resolve(project)
+
+            project.tasks.register("filamentCompileMaterials", MaterialCompileTask) {
+                enabled = extension.materialInputDir.isPresent() && extension.materialOutputDir.isPresent()
+                inputDir.set(extension.materialInputDir.getOrNull())
+                outputDir.set(extension.materialOutputDir.getOrNull())
+                matcTool.from(extension.tools.matcToolFiles)
+            }
+
+            project.tasks.register("filamentGenerateIbl", IblGenerateTask) {
+                enabled = extension.iblInputFile.isPresent() && extension.iblOutputDir.isPresent()
+                cmgenArgs = extension.cmgenArgs
+                inputFile.set(extension.iblInputFile.getOrNull())
+                outputDir.set(extension.iblOutputDir.getOrNull())
+                cmgenTool.from(extension.tools.cmgenToolFiles)
+            }
+
+            project.tasks.register("filamentCompileMesh", MeshCompileTask) {
+                enabled = extension.meshInputFile.isPresent() && extension.meshOutputDir.isPresent()
+                inputFile = extension.meshInputFile.getOrNull()
+                outputDir = extension.meshOutputDir.getOrNull()
+                filameshTool.from(extension.tools.filameshToolFiles)
+            }
+
+            project.preBuild.dependsOn "filamentCompileMaterials"
+            project.preBuild.dependsOn "filamentGenerateIbl"
+            project.preBuild.dependsOn "filamentCompileMesh"
+        }
+    }
+}

android/buildSrc/src/main/groovy/com/google/android/filament/gradle/IblGenerateTask.groovy

@@ -0,0 +1,126 @@
+/*
+ * Copyright (C) 2026 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.google.android.filament.gradle
+
+import org.gradle.api.DefaultTask
+import org.gradle.api.GradleException
+import org.gradle.api.file.ConfigurableFileCollection
+import org.gradle.api.file.DirectoryProperty
+import org.gradle.api.file.FileSystemOperations
+import org.gradle.api.file.FileType
+import org.gradle.api.file.RegularFileProperty
+import org.gradle.api.model.ObjectFactory
+import org.gradle.api.provider.Property
+import org.gradle.api.tasks.Input
+import org.gradle.api.tasks.InputFile
+import org.gradle.api.tasks.InputFiles
+import org.gradle.api.tasks.Optional
+import org.gradle.api.tasks.OutputDirectory
+import org.gradle.api.tasks.TaskAction
+import org.gradle.process.ExecOperations
+import org.gradle.work.ChangeType
+import org.gradle.work.Incremental
+import org.gradle.work.InputChanges
+import org.gradle.api.tasks.incremental.InputFileDetails
+import javax.inject.Inject
+
+abstract class IblGenerateTask extends DefaultTask {
+
+    @Input
+    @Optional
+    abstract Property<String> getCmgenArgs()
+
+    @Incremental
+    @InputFile
+    abstract RegularFileProperty getInputFile()
+
+    @OutputDirectory
+    abstract DirectoryProperty getOutputDir()
+
+    @InputFiles
+    abstract ConfigurableFileCollection getCmgenTool()
+
+    @Inject
+    abstract FileSystemOperations getFileSystemOperations()
+
+    @Inject
+    abstract ExecOperations getExecOperations()
+
+    @Inject
+    abstract ObjectFactory getObjectFactory()
+
+    @TaskAction
+    void execute(InputChanges inputs) {
+        if (cmgenTool.empty) {
+            throw new IllegalStateException(
+                "cmgen executable not configured. Please configure the 'cmgen' block in the " +
+                "'filament' extension or set the 'com.google.android.filament.tools-dir' " +
+                "property."
+            )
+        }
+
+        File cmgen = getCmgenTool().singleFile
+        if (!cmgen.exists()) {
+            throw new IllegalStateException("cmgen executable does not exist: ${cmgen.absolutePath}")
+        }
+
+        if (!cmgen.canExecute()) {
+            cmgen.setExecutable(true)
+        }
+
+        if (!inputs.incremental) {
+            getFileSystemOperations().delete {
+                delete(getObjectFactory().fileTree().from(getOutputDir()).matching { include '*' })
+            }
+        }
+
+        inputs.getFileChanges(getInputFile()).each { InputFileDetails change ->
+            if (change.fileType == FileType.DIRECTORY) return
+
+            def file = change.file
+
+            if (change.changeType == ChangeType.REMOVED) {
+                computeOutputFile(file).delete()
+            } else {
+                println "Generating IBL: ${file.name}"
+
+                def outputPath = getOutputDir().get().asFile
+                def commandArgs = getCmgenArgs().getOrNull()
+                if (commandArgs == null) {
+                    // Default args if not provided
+                    commandArgs = '-q -x ' + outputPath + ' --format=rgb32f ' +
+                                  '--extract-blur=0.08 --extract=' + outputPath.absolutePath
+                }
+
+                def argsList = commandArgs.split(' ').toList()
+                argsList.add(file.absolutePath)
+
+                getExecOperations().exec { spec ->
+                    spec.executable(cmgen)
+                    spec.args(argsList)
+                }
+            }
+        }
+    }
+
+    File computeOutputFile(final File file) {
+        String name = file.name
+        int dotIndex = name.lastIndexOf('.')
+        String baseName = dotIndex > 0 ? name.substring(0, dotIndex) : name
+        return getOutputDir().file(baseName).get().asFile
+    }
+}

android/buildSrc/src/main/groovy/com/google/android/filament/gradle/MaterialCompileTask.groovy

@@ -0,0 +1,147 @@
+/*
+ * Copyright (C) 2026 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.google.android.filament.gradle
+
+import org.gradle.api.artifacts.component.ModuleComponentIdentifier
+import org.gradle.api.DefaultTask
+import org.gradle.api.file.ConfigurableFileCollection
+import org.gradle.api.file.DirectoryProperty
+import org.gradle.api.file.FileSystemOperations
+import org.gradle.api.file.FileType
+import org.gradle.api.model.ObjectFactory
+import org.gradle.api.provider.ProviderFactory
+import org.gradle.api.tasks.InputDirectory
+import org.gradle.api.tasks.InputFiles
+import org.gradle.api.tasks.OutputDirectory
+import org.gradle.api.tasks.PathSensitive
+import org.gradle.api.tasks.PathSensitivity
+import org.gradle.api.tasks.SkipWhenEmpty
+import org.gradle.api.tasks.TaskAction
+import org.gradle.process.ExecOperations
+import org.gradle.work.ChangeType
+import org.gradle.work.Incremental
+import org.gradle.work.InputChanges
+import javax.inject.Inject
+
+abstract class MaterialCompileTask extends DefaultTask {
+
+    @Incremental
+    @InputDirectory
+    @PathSensitive(PathSensitivity.RELATIVE)
+    abstract DirectoryProperty getInputDir()
+
+    @OutputDirectory
+    abstract DirectoryProperty getOutputDir()
+
+    @InputFiles
+    @PathSensitive(PathSensitivity.NONE)
+    abstract ConfigurableFileCollection getMatcTool()
+
+    @Inject
+    abstract ExecOperations getExecOperations()
+
+    @Inject
+    abstract FileSystemOperations getFileSystemOperations()
+
+    @Inject
+    abstract ObjectFactory getObjectFactory()
+
+    @Inject
+    abstract ProviderFactory getProviderFactory()
+
+    @TaskAction
+    void compile(InputChanges inputs) {
+        if (matcTool.empty) {
+            throw new IllegalStateException(
+                "matc executable not configured. Please configure the 'matc' block in the " +
+                "'filament' extension or set the 'com.google.android.filament.tools-dir' " +
+                "property."
+            )
+        }
+
+        File matc = matcTool.singleFile
+        if (!matc.exists()) {
+            throw new IllegalStateException("matc executable does not exist: ${matc.absolutePath}")
+        }
+
+        if (!matc.canExecute()) {
+            matc.setExecutable(true)
+        }
+
+        if (!inputs.incremental) {
+            getFileSystemOperations().delete {
+                delete(getObjectFactory().fileTree().from(getOutputDir()).matching {
+                    include '*.filamat'
+                })
+            }
+        }
+
+        def pf = getProviderFactory()
+        def excludeVulkanProperty = pf.gradleProperty("com.google.android.filament.exclude-vulkan")
+        def includeWebGpuProperty = pf.gradleProperty("com.google.android.filament.include-webgpu")
+        def matNoOptProperty = pf.gradleProperty("com.google.android.filament.matnopt")
+        def excludeVulkan = excludeVulkanProperty.orNull == "true"
+        def includeWebGpu = includeWebGpuProperty.orNull == "true"
+        def matNoOpt = matNoOptProperty.orNull == "true"
+
+        inputs.getFileChanges(getInputDir()).each { change ->
+            if (change.fileType == FileType.DIRECTORY) return
+
+            File file = change.file
+            File outputFile = computeOutputFile(file)
+
+            if (change.changeType == ChangeType.REMOVED) {
+                outputFile.delete()
+            } else {
+                println "Compiling material: ${file.name}"
+
+                def args = []
+                if (!excludeVulkan) {
+                    args += ['-a', 'vulkan']
+                }
+
+                if (includeWebGpu) {
+                    args += ['-a', 'webgpu', '--variant-filter=stereo']
+                }
+
+                if (matNoOpt) {
+                    args += ['-g']
+                }
+
+                args += [
+                    '-a', 'opengl', '-p', 'mobile',
+                    '-o', outputFile.absolutePath,
+                    file.absolutePath
+                ]
+
+                getExecOperations().exec { spec ->
+                    spec.executable(matc)
+                    spec.args(args)
+                }
+            }
+        }
+    }
+
+    File computeOutputFile(File inputFile) {
+        String baseName = inputFile.name
+        int dotIndex = baseName.lastIndexOf('.')
+        if (dotIndex > 0) {
+            baseName = baseName.substring(0, dotIndex)
+        }
+        return getOutputDir().file("${baseName}.filamat").get().asFile
+    }
+}

android/buildSrc/src/main/groovy/com/google/android/filament/gradle/MeshCompileTask.groovy

@@ -0,0 +1,115 @@
+/*
+ * Copyright (C) 2026 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.google.android.filament.gradle
+
+import org.gradle.api.DefaultTask
+import org.gradle.api.file.ConfigurableFileCollection
+import org.gradle.api.file.DirectoryProperty
+import org.gradle.api.file.FileSystemOperations
+import org.gradle.api.file.FileType
+import org.gradle.api.file.RegularFileProperty
+import org.gradle.api.model.ObjectFactory
+import org.gradle.api.tasks.InputFile
+import org.gradle.api.tasks.InputFiles
+import org.gradle.api.tasks.OutputDirectory
+import org.gradle.api.tasks.PathSensitive
+import org.gradle.api.tasks.PathSensitivity
+import org.gradle.api.tasks.TaskAction
+import org.gradle.process.ExecOperations
+import org.gradle.work.ChangeType
+import org.gradle.work.Incremental
+import org.gradle.work.InputChanges
+import javax.inject.Inject
+
+abstract class MeshCompileTask extends DefaultTask {
+
+    @Incremental
+    @InputFile
+    @PathSensitive(PathSensitivity.RELATIVE)
+    abstract RegularFileProperty getInputFile()
+
+    @OutputDirectory
+    abstract DirectoryProperty getOutputDir()
+
+    @InputFiles
+    @PathSensitive(PathSensitivity.NONE)
+    abstract ConfigurableFileCollection getFilameshTool()
+
+    @Inject
+    abstract ExecOperations getExecOperations()
+
+    @Inject
+    abstract FileSystemOperations getFileSystemOperations()
+
+    @Inject
+    abstract ObjectFactory getObjectFactory()
+
+    @TaskAction
+    void compile(InputChanges inputs) {
+        if (filameshTool.empty) {
+            throw new IllegalStateException(
+                "filamesh executable not configured. Please configure the 'filamesh' block in the " +
+                "'filament' extension or set the 'com.google.android.filament.tools-dir' " +
+                "property."
+            )
+        }
+
+        File filamesh = filameshTool.singleFile
+        if (!filamesh.exists()) {
+            throw new IllegalStateException("filamesh executable does not exist: ${filamesh.absolutePath}")
+        }
+
+        if (!filamesh.canExecute()) {
+            filamesh.setExecutable(true)
+        }
+
+        if (!inputs.incremental) {
+            getFileSystemOperations().delete {
+                delete(getObjectFactory().fileTree().from(getOutputDir()).matching {
+                    include '*.filamesh'
+                })
+            }
+        }
+
+        inputs.getFileChanges(inputFile).each { change ->
+            if (change.fileType == FileType.DIRECTORY) return
+
+            File file = change.file
+            File outputFile = computeOutputFile(file)
+
+            if (change.changeType == ChangeType.REMOVED) {
+                outputFile.delete()
+            } else {
+                println "Compiling mesh: ${file.name}"
+
+                getExecOperations().exec { spec ->
+                    spec.executable(filamesh)
+                    spec.args(file.absolutePath, outputFile.absolutePath)
+                }
+            }
+        }
+    }
+
+    File computeOutputFile(File inputFile) {
+        String baseName = inputFile.name
+        int dotIndex = baseName.lastIndexOf('.')
+        if (dotIndex > 0) {
+            baseName = baseName.substring(0, dotIndex)
+        }
+        return getOutputDir().file("${baseName}.filamesh").get().asFile
+    }
+}

android/buildSrc/src/main/groovy/com/google/android/filament/gradle/ToolsLocator.groovy

@@ -0,0 +1,113 @@
+/*
+ * Copyright (C) 2026 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.google.android.filament.gradle
+
+import org.gradle.api.Action
+import org.gradle.api.Project
+import org.gradle.api.artifacts.Configuration
+import org.gradle.api.file.FileCollection
+import org.gradle.internal.os.OperatingSystem
+
+import java.nio.file.Paths
+
+class ToolsLocator {
+    static class ToolConfig {
+        String artifact
+        String path
+        FileCollection files
+    }
+
+    final ToolConfig matc = new ToolConfig()
+    final ToolConfig cmgen = new ToolConfig()
+    final ToolConfig filamesh = new ToolConfig()
+    private final Project project
+
+    ToolsLocator(Project project) {
+        this.project = project
+    }
+
+    void resolve(Project project) {
+        resolveTool(matc, "matc")
+        resolveTool(cmgen, "cmgen")
+        resolveTool(filamesh, "filamesh")
+    }
+
+    /**
+     * Resolves a specific tool by its name and sets the {@link ToolConfig#files} property of the
+     * provided {@link ToolConfig} object. It first attempts to locate the tool based on a Gradle
+     * property `com.google.android.filament.tools-dir` if present, otherwise it resolves the tool
+     * through a Gradle configuration.
+     *
+     * @param tool The {@link ToolConfig} object whose {@code files} property will be set.
+     * @param name The name of the tool (e.g., "matc", "cmgen").
+     */
+    private void resolveTool(ToolConfig tool, String name) {
+        // Find the OS classifier, e.g. 'osx-aarch_64'.
+        def classifier =
+                project.extensions.getByType(com.google.gradle.osdetector.OsDetector).classifier
+
+        // If com.google.android.filament.tools-dir is set, we'll use it as the tool's base path.
+        def toolsDirProp = project.providers.gradleProperty("com.google.android.filament.tools-dir")
+        if (toolsDirProp.isPresent()) {
+            def toolsDir = toolsDirProp.get()
+            def path = OperatingSystem.current().isWindows() ?
+                "${toolsDir}/bin/${name}.exe" :
+                "${toolsDir}/bin/${name}"
+            tool.files = project.files(path)
+            return
+        }
+
+        // If an explicit path for the tool is provided in ToolConfig
+        // (e.g. matc { path = 'path/to/tool' }), use it directly.
+        if (tool.path) {
+            tool.files = project.files(tool.path)
+            return
+        }
+
+        // Otherwise, if an artifact is provided
+        // (e.g. matc { artifact = 'com.google.android.filament:matc:1.68.5' }), resolve it.
+        if (tool.artifact) {
+            String depString = tool.artifact
+
+            // In Gradle, a configuration is a named, manageable group of dependencies.
+            // Resolve the tool artifact using a detached configuration. A detached configuration
+            // is a temporary, isolated configuration that is not part of the project's regular
+            // configuration hierarchy.
+            Configuration config = project.configurations.detachedConfiguration()
+            config.setTransitive(false) // We only want the tool itself, not its dependencies
+
+            def dep = project.dependencies.create("${depString}:${classifier}@exe")
+            config.dependencies.add(dep)
+
+            // A Gradle Configuration implements FileCollection. When treated as a FileCollection,
+            // it represents the resolved files of its dependencies.
+            tool.files = config
+        }
+    }
+
+    FileCollection getMatcToolFiles() {
+        return matc.files ?: project.files()
+    }
+
+    FileCollection getCmgenToolFiles() {
+        return cmgen.files ?: project.files()
+    }
+
+    FileCollection getFilameshToolFiles() {
+        return filamesh.files ?: project.files()
+    }
+}

android/filament-android/src/main/cpp/Camera.cpp

@@ -18,6 +18,7 @@
 
 #include <filament/Camera.h>
 
+
 #include <utils/Entity.h>
 
 #include <math/mat4.h>
@@ -40,6 +41,13 @@ Java_com_google_android_filament_Camera_nSetProjectionFov(JNIEnv*, jclass ,
     camera->setProjection(fovInDegrees, aspect, near, far, (Camera::Fov) fov);
 }
 
+extern "C" JNIEXPORT jdouble JNICALL
+Java_com_google_android_filament_Camera_nGetFieldOfViewInDegrees(JNIEnv*, jclass,
+        jlong nativeCamera, jint direction) {
+    Camera *camera = (Camera *) nativeCamera;
+    return camera->getFieldOfViewInDegrees((Camera::Fov) direction);
+}
+
 extern "C" JNIEXPORT void JNICALL
 Java_com_google_android_filament_Camera_nSetLensProjection(JNIEnv*, jclass,
         jlong nativeCamera, jdouble focalLength, jdouble aspect, jdouble near, jdouble far) {
@@ -62,6 +70,21 @@ Java_com_google_android_filament_Camera_nSetCustomProjection(JNIEnv *env, jclass
     env->ReleaseDoubleArrayElements(inProjectionForCulling_, inProjectionForCulling, JNI_ABORT);
 }
 
+extern "C" JNIEXPORT void JNICALL
+Java_com_google_android_filament_Camera_nSetCustomEyeProjection(JNIEnv *env, jclass,
+        jlong nativeCamera, jdoubleArray inProjection_, jint count, jdoubleArray inProjectionForCulling_,
+        jdouble near, jdouble far) {
+    Camera *camera = (Camera *) nativeCamera;
+    jdouble *inProjection = env->GetDoubleArrayElements(inProjection_, NULL);
+    jdouble *inProjectionForCulling = env->GetDoubleArrayElements(inProjectionForCulling_, NULL);
+    camera->setCustomEyeProjection(
+            reinterpret_cast<const filament::math::mat4 *>(inProjection), (size_t) count,
+            *reinterpret_cast<const filament::math::mat4 *>(inProjectionForCulling),
+            near, far);
+    env->ReleaseDoubleArrayElements(inProjection_, inProjection, JNI_ABORT);
+    env->ReleaseDoubleArrayElements(inProjectionForCulling_, inProjectionForCulling, JNI_ABORT);
+}
+
 extern "C" JNIEXPORT void JNICALL
 Java_com_google_android_filament_Camera_nSetScaling(JNIEnv* env, jclass,
         jlong nativeCamera, jdouble x, jdouble y) {
@@ -76,6 +99,17 @@ Java_com_google_android_filament_Camera_nSetShift(JNIEnv* env, jclass,
     camera->setShift({(double)x, (double)y});
 }
 
+extern "C" JNIEXPORT void JNICALL
+Java_com_google_android_filament_Camera_nGetShift(JNIEnv* env, jclass,
+        jlong nativeCamera, jdoubleArray out_) {
+    Camera *camera = (Camera *) nativeCamera;
+    jdouble *out = env->GetDoubleArrayElements(out_, NULL);
+    filament::math::double2 s = camera->getShift();
+    out[0] = s.x;
+    out[1] = s.y;
+    env->ReleaseDoubleArrayElements(out_, out, 0);
+}
+
 extern "C" JNIEXPORT void JNICALL
 Java_com_google_android_filament_Camera_nLookAt(JNIEnv*, jclass, jlong nativeCamera,
         jdouble eye_x, jdouble eye_y, jdouble eye_z, jdouble center_x, jdouble center_y,
@@ -115,6 +149,15 @@ Java_com_google_android_filament_Camera_nSetModelMatrixFp64(JNIEnv *env, jclass,
     env->ReleaseDoubleArrayElements(in_, in, JNI_ABORT);
 }
 
+extern "C" JNIEXPORT void JNICALL
+Java_com_google_android_filament_Camera_nSetEyeModelMatrix(JNIEnv *env, jclass,
+        jlong nativeCamera, jint eyeId, jdoubleArray model_) {
+    Camera* camera = (Camera *) nativeCamera;
+    jdouble *model = env->GetDoubleArrayElements(model_, NULL);
+    camera->setEyeModelMatrix((uint8_t)eyeId, *reinterpret_cast<const filament::math::mat4*>(model));
+    env->ReleaseDoubleArrayElements(model_, model, JNI_ABORT);
+}
+
 extern "C" JNIEXPORT void JNICALL
 Java_com_google_android_filament_Camera_nGetProjectionMatrix(JNIEnv *env, jclass,
         jlong nativeCamera, jdoubleArray out_) {
@@ -280,3 +323,5 @@ Java_com_google_android_filament_Camera_nComputeEffectiveFov(JNIEnv*, jclass,
         jdouble fovInDegrees, jdouble focusDistance) {
     return Camera::computeEffectiveFov(fovInDegrees, focusDistance);
 }
+
+

android/filament-android/src/main/cpp/Material.cpp

@@ -96,6 +96,14 @@ Java_com_google_android_filament_Material_nGetBlendingMode(JNIEnv*, jclass,
     return (jint) material->getBlendingMode();
 }
 
+extern "C"
+JNIEXPORT jint JNICALL
+Java_com_google_android_filament_Material_nGetTransparencyMode(JNIEnv*, jclass,
+        jlong nativeMaterial) {
+    Material* material = (Material*) nativeMaterial;
+    return (jint) material->getTransparencyMode();
+}
+
 
 extern "C"
 JNIEXPORT jint JNICALL

android/filament-android/src/main/cpp/MaterialInstance.cpp

@@ -564,3 +564,19 @@ Java_com_google_android_filament_MaterialInstance_nGetDepthFunc(JNIEnv* env, jcl
     MaterialInstance* instance = (MaterialInstance*)nativeMaterialInstance;
     return (jint)instance->getDepthFunc();
 }
+
+extern "C"
+JNIEXPORT void JNICALL
+Java_com_google_android_filament_MaterialInstance_nSetTransparencyMode(JNIEnv*, jclass,
+        jlong nativeMaterialInstance, jint mode) {
+    MaterialInstance* instance = (MaterialInstance*) nativeMaterialInstance;
+    instance->setTransparencyMode((MaterialInstance::TransparencyMode) mode);
+}
+
+extern "C"
+JNIEXPORT jint JNICALL
+Java_com_google_android_filament_MaterialInstance_nGetTransparencyMode(JNIEnv*, jclass,
+        jlong nativeMaterialInstance) {
+    MaterialInstance* instance = (MaterialInstance*) nativeMaterialInstance;
+    return (jint) instance->getTransparencyMode();
+}

android/filament-android/src/main/cpp/RenderableManager.cpp

@@ -366,6 +366,13 @@ Java_com_google_android_filament_RenderableManager_nSetPriority(JNIEnv*, jclass,
     rm->setPriority((RenderableManager::Instance) i, (uint8_t) priority);
 }
 
+extern "C" JNIEXPORT jint JNICALL
+Java_com_google_android_filament_RenderableManager_nGetPriority(JNIEnv*, jclass,
+        jlong nativeRenderableManager, jint i) {
+    RenderableManager *rm = (RenderableManager *) nativeRenderableManager;
+    return (jint) rm->getPriority((RenderableManager::Instance) i);
+}
+
 extern "C" JNIEXPORT void JNICALL
 Java_com_google_android_filament_RenderableManager_nSetChannel(JNIEnv*, jclass,
         jlong nativeRenderableManager, jint i, jint channel) {
@@ -373,6 +380,13 @@ Java_com_google_android_filament_RenderableManager_nSetChannel(JNIEnv*, jclass,
     rm->setChannel((RenderableManager::Instance) i, (uint8_t) channel);
 }
 
+extern "C" JNIEXPORT jint JNICALL
+Java_com_google_android_filament_RenderableManager_nGetChannel(JNIEnv*, jclass,
+        jlong nativeRenderableManager, jint i) {
+    RenderableManager *rm = (RenderableManager *) nativeRenderableManager;
+    return (jint) rm->getChannel((RenderableManager::Instance) i);
+}
+
 extern "C" JNIEXPORT void JNICALL
 Java_com_google_android_filament_RenderableManager_nSetCulling(JNIEnv*, jclass,
         jlong nativeRenderableManager, jint i, jboolean enabled) {
@@ -380,6 +394,13 @@ Java_com_google_android_filament_RenderableManager_nSetCulling(JNIEnv*, jclass,
     rm->setCulling((RenderableManager::Instance) i, enabled);
 }
 
+extern "C" JNIEXPORT jboolean JNICALL
+Java_com_google_android_filament_RenderableManager_nIsCullingEnabled(JNIEnv*, jclass,
+        jlong nativeRenderableManager, jint i) {
+    RenderableManager *rm = (RenderableManager *) nativeRenderableManager;
+    return (jboolean) rm->isCullingEnabled((RenderableManager::Instance) i);
+}
+
 extern "C" JNIEXPORT void JNICALL
 Java_com_google_android_filament_RenderableManager_nSetFogEnabled(JNIEnv*, jclass,
         jlong nativeRenderableManager, jint i, jboolean enabled) {
@@ -429,6 +450,13 @@ Java_com_google_android_filament_RenderableManager_nIsShadowReceiver(JNIEnv*, jc
     return (jboolean) rm->isShadowReceiver((RenderableManager::Instance) i);
 }
 
+extern "C" JNIEXPORT jboolean JNICALL
+Java_com_google_android_filament_RenderableManager_nIsScreenSpaceContactShadowsEnabled(JNIEnv*, jclass,
+        jlong nativeRenderableManager, jint i) {
+    RenderableManager *rm = (RenderableManager *) nativeRenderableManager;
+    return (jboolean) rm->isScreenSpaceContactShadowsEnabled((RenderableManager::Instance) i);
+}
+
 extern "C" JNIEXPORT void JNICALL
 Java_com_google_android_filament_RenderableManager_nGetAxisAlignedBoundingBox(JNIEnv* env,
         jclass, jlong nativeRenderableManager, jint i, jfloatArray center_,
@@ -500,6 +528,13 @@ Java_com_google_android_filament_RenderableManager_nSetBlendOrderAt(JNIEnv*, jcl
             (uint16_t) blendOrder);
 }
 
+extern "C" JNIEXPORT jint JNICALL
+Java_com_google_android_filament_RenderableManager_nGetBlendOrderAt(JNIEnv*, jclass,
+        jlong nativeRenderableManager, jint i, jint primitiveIndex) {
+    RenderableManager *rm = (RenderableManager *) nativeRenderableManager;
+    return (jint) rm->getBlendOrderAt((RenderableManager::Instance) i, (size_t) primitiveIndex);
+}
+
 extern "C" JNIEXPORT void JNICALL
 Java_com_google_android_filament_RenderableManager_nSetGlobalBlendOrderEnabledAt(JNIEnv*, jclass,
         jlong nativeRenderableManager, jint i, jint primitiveIndex, jboolean enabled) {
@@ -508,6 +543,13 @@ Java_com_google_android_filament_RenderableManager_nSetGlobalBlendOrderEnabledAt
             (bool) enabled);
 }
 
+extern "C" JNIEXPORT jboolean JNICALL
+Java_com_google_android_filament_RenderableManager_nIsGlobalBlendOrderEnabledAt(JNIEnv*, jclass,
+        jlong nativeRenderableManager, jint i, jint primitiveIndex) {
+    RenderableManager *rm = (RenderableManager *) nativeRenderableManager;
+    return (jboolean) rm->isGlobalBlendOrderEnabledAt((RenderableManager::Instance) i, (size_t) primitiveIndex);
+}
+
 extern "C" JNIEXPORT jint JNICALL
 Java_com_google_android_filament_RenderableManager_nGetEnabledAttributesAt(JNIEnv*, jclass,
         jlong nativeRenderableManager, jint i, jint primitiveIndex) {

android/filament-android/src/main/cpp/Texture.cpp

@@ -173,6 +173,13 @@ Java_com_google_android_filament_Texture_nBuilderSwizzle(JNIEnv *, jclass ,
             (Texture::Swizzle)r, (Texture::Swizzle)g, (Texture::Swizzle)b, (Texture::Swizzle)a);
 }
 
+extern "C" JNIEXPORT void JNICALL
+Java_com_google_android_filament_Texture_nBuilderSamples(JNIEnv*, jclass,
+        jlong nativeBuilder, jint samples) {
+    Texture::Builder *builder = (Texture::Builder *) nativeBuilder;
+    builder->samples((uint8_t) samples);
+}
+
 extern "C"
 JNIEXPORT void JNICALL
 Java_com_google_android_filament_Texture_nBuilderImportTexture(JNIEnv*, jclass, jlong nativeBuilder, jlong id) {

android/filament-android/src/main/cpp/View.cpp

@@ -76,6 +76,12 @@ Java_com_google_android_filament_View_nSetVisibleLayers(JNIEnv*, jclass, jlong n
     view->setVisibleLayers((uint8_t) select, (uint8_t) value);
 }
 
+extern "C" JNIEXPORT jint JNICALL
+Java_com_google_android_filament_View_nGetVisibleLayers(JNIEnv*, jclass, jlong nativeView) {
+    View* view = (View*) nativeView;
+    return view->getVisibleLayers();
+}
+
 extern "C" JNIEXPORT void JNICALL
 Java_com_google_android_filament_View_nSetShadowingEnabled(JNIEnv*, jclass, jlong nativeView, jboolean enabled) {
     View* view = (View*) nativeView;
@@ -440,6 +446,18 @@ Java_com_google_android_filament_View_nIsShadowingEnabled(JNIEnv *, jclass, jlon
     return (jboolean)view->isShadowingEnabled();
 }
 
+extern "C" JNIEXPORT void JNICALL
+Java_com_google_android_filament_View_nSetFrustumCullingEnabled(JNIEnv*, jclass, jlong nativeView, jboolean enabled) {
+    View* view = (View*) nativeView;
+    view->setFrustumCullingEnabled(enabled);
+}
+
+extern "C" JNIEXPORT jboolean JNICALL
+Java_com_google_android_filament_View_nIsFrustumCullingEnabled(JNIEnv*, jclass, jlong nativeView) {
+    View* view = (View*) nativeView;
+    return (jboolean)view->isFrustumCullingEnabled();
+}
+
 extern "C"
 JNIEXPORT void JNICALL
 Java_com_google_android_filament_View_nSetScreenSpaceRefractionEnabled(JNIEnv *, jclass,

android/filament-android/src/main/java/com/google/android/filament/Asserts.java

@@ -136,4 +136,13 @@ final class Asserts {
             throw new ArrayIndexOutOfBoundsException("Array length must be at least 4");
         }
     }
+
+    @NonNull @Size(min = 2)
+    static double[] assertDouble2(@Nullable double[] out) {
+        if (out == null) out = new double[2];
+        else if (out.length < 2) {
+            throw new ArrayIndexOutOfBoundsException("Array length must be at least 2");
+        }
+        return out;
+    }
 }

android/filament-android/src/main/java/com/google/android/filament/Camera.java

@@ -343,6 +343,27 @@ public class Camera {
         nSetScaling(getNativeObject(), xscaling, yscaling);
     }
 
+    /**
+     * Sets a custom projection matrix for each eye.
+     *
+     * @param inProjection              An array of projection matrices, one for each eye.
+     *                                  Must have at least 16 * count elements.
+     * @param count                     Number of eyes to set.
+     * @param inProjectionForCulling    Custom projection matrix for culling, must encompass all eyes.
+     * @param near                      Distance to the near plane.
+     * @param far                       Distance to the far plane.
+     */
+    public void setCustomEyeProjection(
+            @NonNull double[] inProjection, int count,
+            @NonNull @Size(min = 16) double[] inProjectionForCulling,
+            double near, double far) {
+        Asserts.assertMat4dIn(inProjectionForCulling);
+        if (inProjection.length < 16 * count) {
+            throw new IllegalArgumentException("inProjection array too small for the given count");
+        }
+        nSetCustomEyeProjection(getNativeObject(), inProjection, count, inProjectionForCulling, near, far);
+    }
+
     /**
      * Sets an additional matrix that scales the projection matrix.
      *
@@ -399,6 +420,31 @@ public class Camera {
         nSetShift(getNativeObject(), xshift, yshift);
     }
 
+    /**
+     * Returns the shift amount used to translate the projection matrix.
+     *
+     * @param out A 2-double array where the shift will be stored, or null.
+     * @return A 2-double array containing the x and y shift.
+     */
+    @NonNull @Size(min = 2)
+    public double[] getShift(@Nullable @Size(min = 2) double[] out) {
+        out = Asserts.assertDouble2(out);
+        nGetShift(getNativeObject(), out);
+        return out;
+    }
+
+    /**
+     * Returns the camera's field of view in degrees.
+     *
+     * @param direction The direction of the FOV (VERTICAL or HORIZONTAL).
+     * @return The field of view in degrees.
+     */
+    public double getFieldOfViewInDegrees(@NonNull Fov direction) {
+        return nGetFieldOfViewInDegrees(getNativeObject(), direction.ordinal());
+    }
+
+
+
     /**
      * Sets the camera's model matrix.
      * <p>
@@ -745,6 +791,17 @@ public class Camera {
         return mEntity;
     }
 
+    /**
+     * Sets the model matrix for a specific eye.
+     *
+     * @param eyeId The index of the eye.
+     * @param model The model matrix for the eye.
+     */
+    public void setEyeModelMatrix(int eyeId, @NonNull @Size(min = 16) double[] model) {
+        Asserts.assertMat4dIn(model);
+        nSetEyeModelMatrix(getNativeObject(), eyeId, model);
+    }
+
     /**
      * Helper to compute the effective focal length taking into account the focus distance
      *
@@ -784,8 +841,13 @@ public class Camera {
     private static native void nSetCustomProjection(long nativeCamera, double[] inProjection, double[] inProjectionForCulling, double near, double far);
     private static native void nSetScaling(long nativeCamera, double x, double y);
     private static native void nSetShift(long nativeCamera, double x, double y);
+    private static native void nGetShift(long nativeCamera, double[] out);
     private static native void nSetModelMatrix(long nativeCamera, float[] in);
     private static native void nSetModelMatrixFp64(long nativeCamera, double[] in);
+    private static native void nSetEyeModelMatrix(long nativeCamera, int eyeId, double[] model);
+    private static native void nSetCustomEyeProjection(long nativeCamera, double[] inProjection, int count, double[] inProjectionForCulling, double near, double far);
+    private static native double nGetFieldOfViewInDegrees(long nativeCamera, int direction);
+
     private static native void nLookAt(long nativeCamera, double eyeX, double eyeY, double eyeZ, double centerX, double centerY, double centerZ, double upX, double upY, double upZ);
     private static native double nGetNear(long nativeCamera);
     private static native double nGetCullingFar(long nativeCamera);

android/filament-android/src/main/java/com/google/android/filament/Material.java

@@ -54,6 +54,7 @@ public class Material {
         static final CullingMode[] sCullingModeValues = CullingMode.values();
         static final VertexBuffer.VertexAttribute[] sVertexAttributeValues =
                 VertexBuffer.VertexAttribute.values();
+        static final TransparencyMode[] sTransparencyModeValues = TransparencyMode.values();
     }
 
     private long mNativeObject;
@@ -160,6 +161,31 @@ public class Material {
         SCREEN,
     }
 
+    /**
+     * How transparent objects are handled
+     *
+     * @see
+     * <a href="https://google.github.io/filament/Materials.html#materialdefinitions/materialblock/blendingandtransparency:transparencymode">
+     * Blending and transparency: transparencyMode</a>
+     */
+    public enum TransparencyMode {
+        /** The transparent object is drawn honoring the raster state. */
+        DEFAULT,
+
+        /**
+         * The transparent object is first drawn in the depth buffer,
+         * then in the color buffer, honoring the culling mode, but ignoring the depth test function.
+         */
+        TWO_PASSES_ONE_SIDE,
+
+        /**
+         * The transparent object is drawn twice in the color buffer,
+         * first with back faces only, then with front faces; the culling
+         * mode is ignored. Can be combined with two-sided lighting.
+         */
+        TWO_PASSES_TWO_SIDES
+    }
+
     /**
      * Supported refraction modes
      *
@@ -587,6 +613,18 @@ public class Material {
         return EnumCache.sBlendingModeValues[nGetBlendingMode(getNativeObject())];
     }
 
+    /**
+     * Returns the transparency mode of this material.
+     * This value only makes sense when the blending mode is transparent or fade.
+     *
+     * @see
+     * <a href="https://google.github.io/filament/Materials.html#materialdefinitions/materialblock/blendingandtransparency:transparencymode">
+     * Blending and transparency: transparencyMode</a>
+     */
+    public TransparencyMode getTransparencyMode() {
+        return EnumCache.sTransparencyModeValues[nGetTransparencyMode(getNativeObject())];
+    }
+
     /**
      * Returns the refraction mode of this material.
      *
@@ -1130,6 +1168,7 @@ public class Material {
     private static native int nGetShading(long nativeMaterial);
     private static native int nGetInterpolation(long nativeMaterial);
     private static native int nGetBlendingMode(long nativeMaterial);
+    private static native int nGetTransparencyMode(long nativeMaterial);
     private static native int nGetVertexDomain(long nativeMaterial);
     private static native int nGetCullingMode(long nativeMaterial);
     private static native boolean nIsColorWriteEnabled(long nativeMaterial);

android/filament-android/src/main/java/com/google/android/filament/MaterialInstance.java

@@ -537,6 +537,14 @@ public class MaterialInstance {
         nSetDoubleSided(getNativeObject(), doubleSided);
     }
 
+    /**
+     * Sets the transparency mode for this material instance.
+     * @see Material.TransparencyMode
+     */
+    public void setTransparencyMode(@NonNull Material.TransparencyMode mode) {
+        nSetTransparencyMode(getNativeObject(), mode.ordinal());
+    }
+
     /**
      * Returns whether double-sided lighting is enabled when the parent Material has double-sided
      * capability.
@@ -545,6 +553,14 @@ public class MaterialInstance {
         return nIsDoubleSided(getNativeObject());
     }
 
+    /**
+     * Returns the transparency mode.
+     */
+    @NonNull
+    public Material.TransparencyMode getTransparencyMode() {
+        return Material.EnumCache.sTransparencyModeValues[nGetTransparencyMode(getNativeObject())];
+    }
+
     /**
      * Overrides the default triangle culling state that was set on the material.
      *
@@ -982,4 +998,6 @@ public class MaterialInstance {
     private static native boolean nIsStencilWriteEnabled(long nativeMaterialInstance);
     private static native boolean nIsDepthCullingEnabled(long nativeMaterialInstance);
     private static native int nGetDepthFunc(long nativeMaterialInstance);
+    private static native void nSetTransparencyMode(long nativeMaterialInstance, int mode);
+    private static native int nGetTransparencyMode(long nativeMaterialInstance);
 }

android/filament-android/src/main/java/com/google/android/filament/RenderableManager.java

@@ -346,8 +346,8 @@ public class RenderableManager {
          *
          * @return Builder reference for chaining calls.
          *
-         * @see Builder::blendOrder()
-         * @see Builder::priority()
+         * @see Builder#blendOrder()
+         * @see Builder#priority()
          * @see RenderableManager::setBlendOrderAt()
          */
         @NonNull
@@ -725,6 +725,10 @@ public class RenderableManager {
         nSetPriority(mNativeObject, i, priority);
     }
 
+    public int getPriority(@EntityInstance int i) {
+        return nGetPriority(mNativeObject, i);
+    }
+
     /**
      * Changes the channel of a renderable
      *
@@ -734,6 +738,10 @@ public class RenderableManager {
         nSetChannel(mNativeObject, i, channel);
     }
 
+    public int getChannel(@EntityInstance int i) {
+        return nGetChannel(mNativeObject, i);
+    }
+
     /**
      * Changes whether or not frustum culling is on.
      *
@@ -743,6 +751,10 @@ public class RenderableManager {
         nSetCulling(mNativeObject, i, enabled);
     }
 
+    public boolean isCullingEnabled(@EntityInstance int i) {
+        return nIsCullingEnabled(mNativeObject, i);
+    }
+
     /**
      * Changes whether or not the large-scale fog is applied to this renderable
      * @see Builder#fog
@@ -812,6 +824,10 @@ public class RenderableManager {
         nSetScreenSpaceContactShadows(mNativeObject, i, enabled);
     }
 
+    public boolean isScreenSpaceContactShadowsEnabled(@EntityInstance int i) {
+        return nIsScreenSpaceContactShadowsEnabled(mNativeObject, i);
+    }
+
     /**
      * Checks if the renderable can cast shadows.
      *
@@ -932,6 +948,10 @@ public class RenderableManager {
         nSetBlendOrderAt(mNativeObject, instance, primitiveIndex, blendOrder);
     }
 
+    public int getBlendOrderAt(@EntityInstance int instance, @IntRange(from = 0) int primitiveIndex) {
+        return nGetBlendOrderAt(mNativeObject, instance, primitiveIndex);
+    }
+
     /**
      * Changes whether the blend order is global or local to this Renderable (by default).
      *
@@ -946,6 +966,10 @@ public class RenderableManager {
         nSetGlobalBlendOrderEnabledAt(mNativeObject, instance, primitiveIndex, enabled);
     }
 
+    public boolean isGlobalBlendOrderEnabledAt(@EntityInstance int instance, @IntRange(from = 0) int primitiveIndex) {
+        return nIsGlobalBlendOrderEnabledAt(mNativeObject, instance, primitiveIndex);
+    }
+
     /**
      * Retrieves the set of enabled attribute slots in the given primitive's VertexBuffer.
      */
@@ -1013,8 +1037,11 @@ public class RenderableManager {
     private static native void nSetAxisAlignedBoundingBox(long nativeRenderableManager, int i, float cx, float cy, float cz, float ex, float ey, float ez);
     private static native void nSetLayerMask(long nativeRenderableManager, int i, int select, int value);
     private static native void nSetPriority(long nativeRenderableManager, int i, int priority);
+    private static native int nGetPriority(long nativeRenderableManager, int i);
     private static native void nSetChannel(long nativeRenderableManager, int i, int channel);
+    private static native int nGetChannel(long nativeRenderableManager, int i);
     private static native void nSetCulling(long nativeRenderableManager, int i, boolean enabled);
+    private static native boolean nIsCullingEnabled(long nativeRenderableManager, int i);
     private static native void nSetFogEnabled(long nativeRenderableManager, int i, boolean enabled);
     private static native boolean nGetFogEnabled(long nativeRenderableManager, int i);
     private static native void nSetLightChannel(long nativeRenderableManager, int i, int channel, boolean enable);
@@ -1022,6 +1049,7 @@ public class RenderableManager {
     private static native void nSetCastShadows(long nativeRenderableManager, int i, boolean enabled);
     private static native void nSetReceiveShadows(long nativeRenderableManager, int i, boolean enabled);
     private static native void nSetScreenSpaceContactShadows(long nativeRenderableManager, int i, boolean enabled);
+    private static native boolean nIsScreenSpaceContactShadowsEnabled(long nativeRenderableManager, int i);
     private static native boolean nIsShadowCaster(long nativeRenderableManager, int i);
     private static native boolean nIsShadowReceiver(long nativeRenderableManager, int i);
     private static native void nGetAxisAlignedBoundingBox(long nativeRenderableManager, int i, float[] center, float[] halfExtent);
@@ -1032,6 +1060,8 @@ public class RenderableManager {
     private static native long nGetMaterialInstanceAt(long nativeRenderableManager, int i, int primitiveIndex);
     private static native void nSetGeometryAt(long nativeRenderableManager, int i, int primitiveIndex, int primitiveType, long nativeVertexBuffer, long nativeIndexBuffer, int offset, int count);
     private static native void nSetBlendOrderAt(long nativeRenderableManager, int i, int primitiveIndex, int blendOrder);
+    private static native int nGetBlendOrderAt(long nativeRenderableManager, int i, int primitiveIndex);
     private static native void nSetGlobalBlendOrderEnabledAt(long nativeRenderableManager, int i, int primitiveIndex, boolean enabled);
+    private static native boolean nIsGlobalBlendOrderEnabledAt(long nativeRenderableManager, int i, int primitiveIndex);
     private static native int nGetEnabledAttributesAt(long nativeRenderableManager, int i, int primitiveIndex);
 }

android/filament-android/src/main/java/com/google/android/filament/Texture.java

@@ -795,6 +795,17 @@ public class Texture {
             return this;
         }
 
+        /**
+         * Specifies the number of samples for multisample anti-aliasing.
+         * @param samples number of samples, must be at least 1. Default is 1.
+         * @return This Builder, for chaining calls.
+         */
+        @NonNull
+        public Builder samples(@IntRange(from = 1) int samples) {
+            nBuilderSamples(mNativeBuilder, samples);
+            return this;
+        }
+
         /**
          * Specifies the texture's internal format.
          * <p>The internal format specifies how texels are stored (which may be different from how
@@ -1370,6 +1381,7 @@ public class Texture {
     private static native void nBuilderFormat(long nativeBuilder, int format);
     private static native void nBuilderUsage(long nativeBuilder, int flags);
     private static native void nBuilderSwizzle(long nativeBuilder, int r, int g, int b, int a);
+    private static native void nBuilderSamples(long nativeBuilder, int samples);
     private static native void nBuilderImportTexture(long nativeBuilder, long id);
     private static native void nBuilderExternal(long nativeBuilder);
     private static native long nBuilderBuild(long nativeBuilder, long nativeEngine);

android/filament-android/src/main/java/com/google/android/filament/View.java

@@ -350,6 +350,26 @@ public class View {
         nSetVisibleLayers(getNativeObject(), select & 0xFF, values & 0xFF);
     }
 
+    /**
+     * Returns the visible layers.
+     *
+     * @return a bitmask specifying which layer is visible.
+     */
+    public int getVisibleLayers() {
+        return nGetVisibleLayers(getNativeObject());
+    }
+
+    /**
+     * Enables or disables a specific layer.
+     *
+     * @param layer     Index of the layer to enable or disable, must be between 0 and 7.
+     * @param enabled   True to enable the layer, false to disable it.
+     */
+    public void setLayerEnabled(@IntRange(from = 0, to = 7) int layer, boolean enabled) {
+        int mask = 1 << layer;
+        setVisibleLayers(mask, enabled ? mask : 0);
+    }
+
     /**
      * Enables or disables shadow mapping. Enabled by default.
      *
@@ -368,6 +388,22 @@ public class View {
         return nIsShadowingEnabled(getNativeObject());
     }
 
+    /**
+     * Enables or disables frustum culling. Enabled by default.
+     *
+     * @param enabled true enables frustum culling, false disables it.
+     */
+    public void setFrustumCullingEnabled(boolean enabled) {
+        nSetFrustumCullingEnabled(getNativeObject(), enabled);
+    }
+
+    /**
+     * @return whether frustum culling is enabled
+     */
+    public boolean isFrustumCullingEnabled() {
+        return nIsFrustumCullingEnabled(getNativeObject());
+    }
+
     /**
      * Enables or disables screen space refraction. Enabled by default.
      *
@@ -1322,6 +1358,9 @@ public class View {
     private static native boolean nHasCamera(long nativeView);
     private static native void nSetViewport(long nativeView, int left, int bottom, int width, int height);
     private static native void nSetVisibleLayers(long nativeView, int select, int value);
+    private static native int nGetVisibleLayers(long nativeView);
+    private static native void nSetFrustumCullingEnabled(long nativeView, boolean enabled);
+    private static native boolean nIsFrustumCullingEnabled(long nativeView);
     private static native void nSetShadowingEnabled(long nativeView, boolean enabled);
     private static native void nSetRenderTarget(long nativeView, long nativeRenderTarget);
     private static native void nSetSampleCount(long nativeView, int count);
@@ -1406,65 +1445,59 @@ public class View {
      * by lowering the resolution of a View, or to increase the quality when the
      * rendering is faster than the target frame rate.
      *
-     * This structure can be used to specify the minimum scale factor used when
+     * <p>This structure can be used to specify the minimum scale factor used when
      * lowering the resolution of a View, and the maximum scale factor used when
      * increasing the resolution for higher quality rendering. The scale factors
      * can be controlled on each X and Y axis independently. By default, all scale
-     * factors are set to 1.0.
+     * factors are set to 1.0.</p>
      *
-     * enabled:   enable or disables dynamic resolution on a View
+     * <ul>
+     * <li>enabled:   enable or disables dynamic resolution on a View</li>
      *
-     * homogeneousScaling: by default the system scales the major axis first. Set this to true
-     *                     to force homogeneous scaling.
+     * <li>homogeneousScaling: by default the system scales the major axis first. Set this to true
+     *                     to force homogeneous scaling.</li>
      *
-     * minScale:  the minimum scale in X and Y this View should use
+     * <li>minScale:  the minimum scale in X and Y this View should use</li>
      *
-     * maxScale:  the maximum scale in X and Y this View should use
+     * <li>maxScale:  the maximum scale in X and Y this View should use</li>
      *
-     * quality:   upscaling quality.
-     *            LOW: 1 bilinear tap, Medium: 4 bilinear taps, High: 9 bilinear taps (tent)
+     * <li>quality:   upscaling quality.
+     *            LOW: 1 bilinear tap, Medium: 4 bilinear taps, High: 9 bilinear taps (tent)</li>
+     * </ul>
      *
-     * \note
+     * <p>Note:
      * Dynamic resolution is only supported on platforms where the time to render
      * a frame can be measured accurately. On platforms where this is not supported,
-     * Dynamic Resolution can't be enabled unless minScale == maxScale.
+     * Dynamic Resolution can't be enabled unless <code>minScale == maxScale</code>.</p>
      *
-     * @see Renderer::FrameRateOptions
+     * @see Renderer.FrameRateOptions
      *
      */
     public static class DynamicResolutionOptions {
-        /**
-         * minimum scale factors in x and y
-         */
+        /** minimum scale factors in x and y */
         public float minScale = 0.5f;
-        /**
-         * maximum scale factors in x and y
-         */
+        /** maximum scale factors in x and y */
         public float maxScale = 1.0f;
-        /**
-         * sharpness when QualityLevel::MEDIUM or higher is used [0 (disabled), 1 (sharpest)]
-         */
+        /** sharpness when QualityLevel::MEDIUM or higher is used [0 (disabled), 1 (sharpest)] */
         public float sharpness = 0.9f;
-        /**
-         * enable or disable dynamic resolution
-         */
+        /** enable or disable dynamic resolution */
         public boolean enabled = false;
-        /**
-         * set to true to force homogeneous scaling
-         */
+        /** set to true to force homogeneous scaling */
         public boolean homogeneousScaling = false;
         /**
          * Upscaling quality
-         * LOW:    bilinear filtered blit. Fastest, poor quality
-         * MEDIUM: Qualcomm Snapdragon Game Super Resolution (SGSR) 1.0
-         * HIGH:   AMD FidelityFX FSR1 w/ mobile optimizations
-         * ULTRA:  AMD FidelityFX FSR1
+         * <ul>
+         * <li>LOW:    bilinear filtered blit. Fastest, poor quality</li>
+         * <li>MEDIUM: Qualcomm Snapdragon Game Super Resolution (SGSR) 1.0</li>
+         * <li>HIGH:   AMD FidelityFX FSR1 w/ mobile optimizations</li>
+         * <li>ULTRA:  AMD FidelityFX FSR1</li>
+         * </ul>
          *      FSR1 and SGSR require a well anti-aliased (MSAA or TAA), noise free scene.
          *      Avoid FXAA and dithering.
          *
-         * The default upscaling quality is set to LOW.
+         * <p>The default upscaling quality is set to LOW.</p>
          *
-         * caveat: currently, 'quality' is always set to LOW if the View is TRANSLUCENT.
+         * <p>caveat: currently, <code>quality</code> is always set to LOW if the View is TRANSLUCENT.</p>
          */
         @NonNull
         public QualityLevel quality = QualityLevel.LOW;
@@ -1473,134 +1506,98 @@ public class View {
     /**
      * Options to control the bloom effect
      *
-     * enabled:     Enable or disable the bloom post-processing effect. Disabled by default.
+     * <ul>
+     * <li>enabled:     Enable or disable the bloom post-processing effect. Disabled by default.</li>
      *
-     * levels:      Number of successive blurs to achieve the blur effect, the minimum is 3 and the
+     * <li>levels:      Number of successive blurs to achieve the blur effect, the minimum is 3 and the
      *              maximum is 12. This value together with resolution influences the spread of the
      *              blur effect. This value can be silently reduced to accommodate the original
-     *              image size.
+     *              image size.</li>
      *
-     * resolution:  Resolution of bloom's minor axis. The minimum value is 2^levels and the
+     * <li>resolution:  Resolution of bloom's minor axis. The minimum value is 2^levels and the
      *              the maximum is lower of the original resolution and 4096. This parameter is
      *              silently clamped to the minimum and maximum.
      *              It is highly recommended that this value be smaller than the target resolution
-     *              after dynamic resolution is applied (horizontally and vertically).
+     *              after dynamic resolution is applied (horizontally and vertically).</li>
      *
-     * strength:    how much of the bloom is added to the original image. Between 0 and 1.
+     * <li>strength:    how much of the bloom is added to the original image. Between 0 and 1.</li>
      *
-     * blendMode:   Whether the bloom effect is purely additive (false) or mixed with the original
-     *              image (true).
+     * <li>blendMode:   Whether the bloom effect is purely additive (false) or mixed with the original
+     *              image (true).</li>
      *
-     * threshold:   When enabled, a threshold at 1.0 is applied on the source image, this is
-     *              useful for artistic reasons and is usually needed when a dirt texture is used.
+     * <li>threshold:   When enabled, a threshold at 1.0 is applied on the source image, this is
+     *              useful for artistic reasons and is usually needed when a dirt texture is used.</li>
      *
-     * dirt:        A dirt/scratch/smudges texture (that can be RGB), which gets added to the
+     * <li>dirt:        A dirt/scratch/smudges texture (that can be RGB), which gets added to the
      *              bloom effect. Smudges are visible where bloom occurs. Threshold must be
-     *              enabled for the dirt effect to work properly.
+     *              enabled for the dirt effect to work properly.</li>
      *
-     * dirtStrength: Strength of the dirt texture.
+     * <li>dirtStrength: Strength of the dirt texture.</li>
+     * </ul>
      */
     public static class BloomOptions {
         public enum BlendMode {
-            /**
-             * Bloom is modulated by the strength parameter and added to the scene
-             */
+            /** Bloom is modulated by the strength parameter and added to the scene */
             ADD,
-            /**
-             * Bloom is interpolated with the scene using the strength parameter
-             */
+            /** Bloom is interpolated with the scene using the strength parameter */
             INTERPOLATE,
         }
 
-        /**
-         * user provided dirt texture
-         */
+        /** user provided dirt texture */
         @Nullable
         public Texture dirt = null;
-        /**
-         * strength of the dirt texture
-         */
+        /** strength of the dirt texture */
         public float dirtStrength = 0.2f;
-        /**
-         * bloom's strength between 0.0 and 1.0
-         */
+        /** bloom's strength between 0.0 and 1.0 */
         public float strength = 0.10f;
-        /**
-         * resolution of vertical axis (2^levels to 2048)
-         */
+        /** resolution of vertical axis (2^levels to 2048) */
         public int resolution = 384;
-        /**
-         * number of blur levels (1 to 11)
-         */
+        /** number of blur levels (1 to 11) */
         public int levels = 6;
-        /**
-         * how the bloom effect is applied
-         */
+        /** how the bloom effect is applied */
         @NonNull
         public BloomOptions.BlendMode blendMode = BloomOptions.BlendMode.ADD;
-        /**
-         * whether to threshold the source
-         */
+        /** whether to threshold the source */
         public boolean threshold = true;
-        /**
-         * enable or disable bloom
-         */
+        /** enable or disable bloom */
         public boolean enabled = false;
-        /**
-         * limit highlights to this value before bloom [10, +inf]
-         */
+        /** limit highlights to this value before bloom [10, +inf] */
         public float highlight = 1000.0f;
         /**
          * Bloom quality level.
-         * LOW (default): use a more optimized down-sampling filter, however there can be artifacts
-         *      with dynamic resolution, this can be alleviated by using the homogenous mode.
-         * MEDIUM: Good balance between quality and performance.
-         * HIGH: In this mode the bloom resolution is automatically increased to avoid artifacts.
+         * <ul>
+         * <li>LOW (default): use a more optimized down-sampling filter, however there can be artifacts
+         *      with dynamic resolution, this can be alleviated by using the homogenous mode.</li>
+         * <li>MEDIUM: Good balance between quality and performance.</li>
+         * <li>HIGH: In this mode the bloom resolution is automatically increased to avoid artifacts.
          *      This mode can be significantly slower on mobile, especially at high resolution.
-         *      This mode greatly improves the anamorphic bloom.
+         *      This mode greatly improves the anamorphic bloom.</li>
+         * </ul>
          */
         @NonNull
         public QualityLevel quality = QualityLevel.LOW;
-        /**
-         * enable screen-space lens flare
-         */
+        /** enable screen-space lens flare */
         public boolean lensFlare = false;
-        /**
-         * enable starburst effect on lens flare
-         */
+        /** enable starburst effect on lens flare */
         public boolean starburst = true;
-        /**
-         * amount of chromatic aberration
-         */
+        /** amount of chromatic aberration */
         public float chromaticAberration = 0.005f;
-        /**
-         * number of flare "ghosts"
-         */
+        /** number of flare "ghosts" */
         public int ghostCount = 4;
-        /**
-         * spacing of the ghost in screen units [0, 1[
-         */
+        /** spacing of the ghost in screen units [0, 1[ */
         public float ghostSpacing = 0.6f;
-        /**
-         * hdr threshold for the ghosts
-         */
+        /** hdr threshold for the ghosts */
         public float ghostThreshold = 10.0f;
-        /**
-         * thickness of halo in vertical screen units, 0 to disable
-         */
+        /** thickness of halo in vertical screen units, 0 to disable */
         public float haloThickness = 0.1f;
-        /**
-         * radius of halo in vertical screen units [0, 0.5]
-         */
+        /** radius of halo in vertical screen units [0, 0.5] */
         public float haloRadius = 0.4f;
-        /**
-         * hdr threshold for the halo
-         */
+        /** hdr threshold for the halo */
         public float haloThreshold = 10.0f;
     }
 
     /**
-     * Options to control large-scale fog in the scene. Materials can enable the `linearFog` property,
+     * Options to control large-scale fog in the scene. Materials can enable the <code>linearFog</code> property,
      * which uses a simplified, linear equation for fog calculation; in this mode, the heightFalloff
      * is ignored as well as the mipmap selection in IBL or skyColor mode.
      */
@@ -1614,12 +1611,12 @@ public class View {
          * This can be used to exclude the skybox, which is desirable if it already contains clouds or
          * fog. The default value is +infinity which applies the fog to everything.
          *
-         * Note: The SkyBox is typically at a distance of 1e19 in world space (depending on the near
-         * plane distance and projection used though).
+         * <p>Note: The SkyBox is typically at a distance of 1e19 in world space (depending on the near
+         * plane distance and projection used though).</p>
          */
         public float cutOffDistance = Float.POSITIVE_INFINITY;
         /**
-         * fog's maximum opacity between 0 and 1. Ignored in `linearFog` mode.
+         * fog's maximum opacity between 0 and 1. Ignored in <code>linearFog</code> mode.
          */
         public float maximumOpacity = 1.0f;
         /**
@@ -1631,11 +1628,11 @@ public class View {
          * It can be expressed as 1/H, where H is the altitude change in world units [m] that causes a
          * factor 2.78 (e) change in fog density.
          *
-         * A falloff of 0 means the fog density is constant everywhere and may result is slightly
-         * faster computations.
+         * <p>A falloff of 0 means the fog density is constant everywhere and may result is slightly
+         * faster computations.</p>
          *
-         * In `linearFog` mode, only use to compute the slope of the linear equation. Completely
-         * ignored if set to 0.
+         * <p>In <code>linearFog</code> mode, only use to compute the slope of the linear equation. Completely
+         * ignored if set to 0.</p>
          */
         public float heightFalloff = 1.0f;
         /**
@@ -1645,11 +1642,11 @@ public class View {
          *  above one are allowed but could create a non energy-conservative fog (this is dependant
          *  on the IBL's intensity as well).
          *
-         *  We assume that our fog has no absorption and therefore all the light it scatters out
+         *  <p>We assume that our fog has no absorption and therefore all the light it scatters out
          *  becomes ambient light in-scattering and has lost all directionality, i.e.: scattering is
-         *  isotropic. This somewhat simulates Rayleigh scattering.
+         *  isotropic. This somewhat simulates Rayleigh scattering.</p>
          *
-         *  This value is used as a tint instead, when fogColorFromIbl is enabled.
+         *  <p>This value is used as a tint instead, when fogColorFromIbl is enabled.</p>
          *
          *  @see #fogColorFromIbl
          */
@@ -1660,20 +1657,20 @@ public class View {
          * light is absorbed and out-scattered per unit of distance. Each unit of extinction reduces
          * the incoming light to 37% of its original value.
          *
-         * Note: The extinction factor is related to the fog density, it's usually some constant K times
+         * <p>Note: The extinction factor is related to the fog density, it's usually some constant K times
          * the density at sea level (more specifically at fog height). The constant K depends on
-         * the composition of the fog/atmosphere.
+         * the composition of the fog/atmosphere.</p>
          *
-         * For historical reason this parameter is called `density`.
+         * <p>For historical reason this parameter is called <code>density</code>.</p>
          *
-         * In `linearFog` mode this is the slope of the linear equation if heightFalloff is set to 0.
+         * <p>In <code>linearFog</code> mode this is the slope of the linear equation if heightFalloff is set to 0.
          * Otherwise, heightFalloff affects the slope calculation such that it matches the slope of
-         * the standard equation at the camera height.
+         * the standard equation at the camera height.</p>
          */
         public float density = 0.1f;
         /**
          * Distance in world units [m] from the camera where the Sun in-scattering starts.
-         * Ignored in `linearFog` mode.
+         * Ignored in <code>linearFog</code> mode.
          */
         public float inScatteringStart = 0.0f;
         /**
@@ -1681,16 +1678,16 @@ public class View {
          * is scattered (by the fog) towards the camera.
          * Size of the Sun in-scattering (>0 to activate). Good values are >> 1 (e.g. ~10 - 100).
          * Smaller values result is a larger scattering size.
-         * Ignored in `linearFog` mode.
+         * Ignored in <code>linearFog</code> mode.
          */
         public float inScatteringSize = -1.0f;
         /**
-         * The fog color will be sampled from the IBL in the view direction and tinted by `color`.
+         * The fog color will be sampled from the IBL in the view direction and tinted by <code>color</code>.
          * Depending on the scene this can produce very convincing results.
          *
-         * This simulates a more anisotropic phase-function.
+         * <p>This simulates a more anisotropic phase-function.</p>
          *
-         * `fogColorFromIbl` is ignored when skyTexture is specified.
+         * <p><code>fogColorFromIbl</code> is ignored when skyTexture is specified.</p>
          *
          * @see #skyColor
          */
@@ -1703,11 +1700,11 @@ public class View {
          * level with a strong gaussian filter or even an irradiance filter and then generate mip
          * levels as usual. How blurred the base level is somewhat of an artistic decision.
          *
-         * This simulates a more anisotropic phase-function.
+         * <p>This simulates a more anisotropic phase-function.</p>
          *
-         * `fogColorFromIbl` is ignored when skyTexture is specified.
+         * <p><code>fogColorFromIbl</code> is ignored when skyTexture is specified.</p>
          *
-         * In `linearFog` mode mipmap level 0 is always used.
+         * <p>In <code>linearFog</code> mode mipmap level 0 is always used.</p>
          *
          * @see Texture
          * @see #fogColorFromIbl
@@ -1723,9 +1720,9 @@ public class View {
     /**
      * Options to control Depth of Field (DoF) effect in the scene.
      *
-     * cocScale can be used to set the depth of field blur independently of the camera
+     * <p>cocScale can be used to set the depth of field blur independently of the camera
      * aperture, e.g. for artistic reasons. This can be achieved by setting:
-     *      cocScale = cameraAperture / desiredDoFAperture
+     *      cocScale = cameraAperture / desiredDoFAperture</p>
      *
      * @see Camera
      */
@@ -1736,59 +1733,24 @@ public class View {
             MEDIAN,
         }
 
-        /**
-         * circle of confusion scale factor (amount of blur)
-         */
+        /** circle of confusion scale factor (amount of blur) */
         public float cocScale = 1.0f;
-        /**
-         * width/height aspect ratio of the circle of confusion (simulate anamorphic lenses)
-         */
+        /** width/height aspect ratio of the circle of confusion (simulate anamorphic lenses) */
         public float cocAspectRatio = 1.0f;
-        /**
-         * maximum aperture diameter in meters (zero to disable rotation)
-         */
+        /** maximum aperture diameter in meters (zero to disable rotation) */
         public float maxApertureDiameter = 0.01f;
-        /**
-         * enable or disable depth of field effect
-         */
+        /** enable or disable depth of field effect */
         public boolean enabled = false;
-        /**
-         * filter to use for filling gaps in the kernel
-         */
+        /** filter to use for filling gaps in the kernel */
         @NonNull
         public DepthOfFieldOptions.Filter filter = DepthOfFieldOptions.Filter.MEDIAN;
-        /**
-         * perform DoF processing at native resolution
-         */
+        /** perform DoF processing at native resolution */
         public boolean nativeResolution = false;
-        /**
-         * Number of of rings used by the gather kernels. The number of rings affects quality
-         * and performance. The actual number of sample per pixel is defined
-         * as (ringCount * 2 - 1)^2. Here are a few commonly used values:
-         *       3 rings :   25 ( 5x 5 grid)
-         *       4 rings :   49 ( 7x 7 grid)
-         *       5 rings :   81 ( 9x 9 grid)
-         *      17 rings : 1089 (33x33 grid)
-         *
-         * With a maximum circle-of-confusion of 32, it is never necessary to use more than 17 rings.
-         *
-         * Usually all three settings below are set to the same value, however, it is often
-         * acceptable to use a lower ring count for the "fast tiles", which improves performance.
-         * Fast tiles are regions of the screen where every pixels have a similar
-         * circle-of-confusion radius.
-         *
-         * A value of 0 means default, which is 5 on desktop and 3 on mobile.
-         *
-         * @{
-         */
+        /** number of kernel rings for foreground tiles */
         public int foregroundRingCount = 0;
-        /**
-         * number of kernel rings for background tiles
-         */
+        /** number of kernel rings for background tiles */
         public int backgroundRingCount = 0;
-        /**
-         * number of kernel rings for fast tiles
-         */
+        /** number of kernel rings for fast tiles */
         public int fastGatherRingCount = 0;
         /**
          * maximum circle-of-confusion in pixels for the foreground, must be in [0, 32] range.
@@ -1806,26 +1768,16 @@ public class View {
      * Options to control the vignetting effect.
      */
     public static class VignetteOptions {
-        /**
-         * high values restrict the vignette closer to the corners, between 0 and 1
-         */
+        /** high values restrict the vignette closer to the corners, between 0 and 1 */
         public float midPoint = 0.5f;
-        /**
-         * controls the shape of the vignette, from a rounded rectangle (0.0), to an oval (0.5), to a circle (1.0)
-         */
+        /** controls the shape of the vignette, from a rounded rectangle (0.0), to an oval (0.5), to a circle (1.0) */
         public float roundness = 0.5f;
-        /**
-         * softening amount of the vignette effect, between 0 and 1
-         */
+        /** softening amount of the vignette effect, between 0 and 1 */
         public float feather = 0.5f;
-        /**
-         * color of the vignette effect, alpha is currently ignored
-         */
+        /** color of the vignette effect, alpha is currently ignored */
         @NonNull @Size(min = 4)
         public float[] color = {0.0f, 0.0f, 0.0f, 1.0f};
-        /**
-         * enables or disables the vignette effect
-         */
+        /** enables or disables the vignette effect */
         public boolean enabled = false;
     }
 
@@ -1839,11 +1791,11 @@ public class View {
         /**
          * Sets the quality of the HDR color buffer.
          *
-         * A quality of HIGH or ULTRA means using an RGB16F or RGBA16F color buffer. This means
+         * <p>A quality of HIGH or ULTRA means using an RGB16F or RGBA16F color buffer. This means
          * colors in the LDR range (0..1) have a 10 bit precision. A quality of LOW or MEDIUM means
          * using an R11G11B10F opaque color buffer or an RGBA16F transparent color buffer. With
          * R11G11B10F colors in the LDR range have a precision of either 6 bits (red and green
-         * channels) or 5 bits (blue channel).
+         * channels) or 5 bits (blue channel).</p>
          */
         @NonNull
         public QualityLevel hdrColorBuffer = QualityLevel.HIGH;
@@ -1855,72 +1807,44 @@ public class View {
      */
     public static class AmbientOcclusionOptions {
         public enum AmbientOcclusionType {
-            /**
-             * use Scalable Ambient Occlusion
-             */
+            /** use Scalable Ambient Occlusion */
             SAO,
-            /**
-             * use Ground Truth-Based Ambient Occlusion
-             */
+            /** use Ground Truth-Based Ambient Occlusion */
             GTAO,
         }
 
-        /**
-         * Type of ambient occlusion algorithm.
-         */
+        /** Type of ambient occlusion algorithm. */
         @NonNull
         public AmbientOcclusionOptions.AmbientOcclusionType aoType = AmbientOcclusionOptions.AmbientOcclusionType.SAO;
-        /**
-         * Ambient Occlusion radius in meters, between 0 and ~10.
-         */
+        /** Ambient Occlusion radius in meters, between 0 and ~10. */
         public float radius = 0.3f;
-        /**
-         * Controls ambient occlusion's contrast. Must be positive.
-         */
+        /** Controls ambient occlusion's contrast. Must be positive. */
         public float power = 1.0f;
         /**
          * Self-occlusion bias in meters. Use to avoid self-occlusion.
          * Between 0 and a few mm. No effect when aoType set to GTAO
          */
         public float bias = 0.0005f;
-        /**
-         * How each dimension of the AO buffer is scaled. Must be either 0.5 or 1.0.
-         */
+        /** How each dimension of the AO buffer is scaled. Must be either 0.5 or 1.0. */
         public float resolution = 0.5f;
-        /**
-         * Strength of the Ambient Occlusion effect.
-         */
+        /** Strength of the Ambient Occlusion effect. */
         public float intensity = 1.0f;
-        /**
-         * depth distance that constitute an edge for filtering
-         */
+        /** depth distance that constitute an edge for filtering */
         public float bilateralThreshold = 0.05f;
-        /**
-         * affects # of samples used for AO and params for filtering
-         */
+        /** affects # of samples used for AO and params for filtering */
         @NonNull
         public QualityLevel quality = QualityLevel.LOW;
-        /**
-         * affects AO smoothness. Recommend setting to HIGH when aoType set to GTAO.
-         */
+        /** affects AO smoothness. Recommend setting to HIGH when aoType set to GTAO. */
         @NonNull
         public QualityLevel lowPassFilter = QualityLevel.MEDIUM;
-        /**
-         * affects AO buffer upsampling quality
-         */
+        /** affects AO buffer upsampling quality */
         @NonNull
         public QualityLevel upsampling = QualityLevel.LOW;
-        /**
-         * enables or disables screen-space ambient occlusion
-         */
+        /** enables or disables screen-space ambient occlusion */
         public boolean enabled = false;
-        /**
-         * enables bent normals computation from AO, and specular AO
-         */
+        /** enables bent normals computation from AO, and specular AO */
         public boolean bentNormals = false;
-        /**
-         * min angle in radian to consider. No effect when aoType set to GTAO.
-         */
+        /** min angle in radian to consider. No effect when aoType set to GTAO. */
         public float minHorizonAngleRad = 0.0f;
         /**
          * Screen Space Cone Tracing (SSCT) options
@@ -2006,12 +1930,10 @@ public class View {
      * @see #setMultiSampleAntiAliasingOptions
      */
     public static class MultiSampleAntiAliasingOptions {
-        /**
-         * enables or disables msaa
-         */
+        /** enables or disables msaa */
         public boolean enabled = false;
         /**
-         * sampleCount number of samples to use for multi-sampled anti-aliasing.\n
+         * sampleCount number of samples to use for multi-sampled anti-aliasing.<br>
          *              0: treated as 1
          *              1: no anti-aliasing
          *              n: sample count. Effective sample could be different depending on the
@@ -2030,106 +1952,75 @@ public class View {
      * shaders to be recompiled. These options should be changed or set during initialization.
      * `filterWidth`, `feedback` and `jitterPattern`, however, can be changed at any time.
      *
-     * `feedback` of 0.1 effectively accumulates a maximum of 19 samples in steady state.
-     * see "A Survey of Temporal Antialiasing Techniques" by Lei Yang and all for more information.
+     * <p><code>feedback</code> of 0.1 effectively accumulates a maximum of 19 samples in steady state.
+     * see "A Survey of Temporal Antialiasing Techniques" by Lei Yang and all for more information.</p>
      *
      * @see #setTemporalAntiAliasingOptions
      */
     public static class TemporalAntiAliasingOptions {
         public enum BoxType {
-            /**
-             * use an AABB neighborhood
-             */
+            /** use an AABB neighborhood */
             AABB,
-            /**
-             * use both AABB and variance
-             */
+            /** use both AABB and variance */
             AABB_VARIANCE,
         }
 
         public enum BoxClipping {
-            /**
-             * Accurate box clipping
-             */
+            /** Accurate box clipping */
             ACCURATE,
-            /**
-             * clamping
-             */
+            /** clamping */
             CLAMP,
-            /**
-             * no rejections (use for debugging)
-             */
+            /** no rejections (use for debugging) */
             NONE,
         }
 
         public enum JitterPattern {
+            /** 4-samples, rotated grid sampling */
             RGSS_X4,
+            /** 4-samples, uniform grid in helix sequence */
             UNIFORM_HELIX_X4,
+            /** 8-samples of halton 2,3 */
             HALTON_23_X8,
+            /** 16-samples of halton 2,3 */
             HALTON_23_X16,
+            /** 32-samples of halton 2,3 */
             HALTON_23_X32,
         }
 
-        /**
-         * @deprecated has no effect.
-         */
+        /** @deprecated has no effect. */
         public float filterWidth = 1.0f;
-        /**
-         * history feedback, between 0 (maximum temporal AA) and 1 (no temporal AA).
-         */
+        /** history feedback, between 0 (maximum temporal AA) and 1 (no temporal AA). */
         public float feedback = 0.12f;
-        /**
-         * texturing lod bias (typically -1 or -2)
-         */
+        /** texturing lod bias (typically -1 or -2) */
         public float lodBias = -1.0f;
-        /**
-         * post-TAA sharpen, especially useful when upscaling is true.
-         */
+        /** post-TAA sharpen, especially useful when upscaling is true. */
         public float sharpness = 0.0f;
-        /**
-         * enables or disables temporal anti-aliasing
-         */
+        /** enables or disables temporal anti-aliasing */
         public boolean enabled = false;
-        /**
-         * Upscaling factor. Disables Dynamic Resolution. [BETA]
-         */
+        /** Upscaling factor. Disables Dynamic Resolution. [BETA] */
         public float upscaling = 1.0f;
-        /**
-         * whether to filter the history buffer
-         */
+        /** whether to filter the history buffer */
         public boolean filterHistory = true;
-        /**
-         * whether to apply the reconstruction filter to the input
-         */
+        /** whether to apply the reconstruction filter to the input */
         public boolean filterInput = true;
-        /**
-         * whether to use the YcoCg color-space for history rejection
-         */
+        /** whether to use the YcoCg color-space for history rejection */
         public boolean useYCoCg = false;
-        /**
-         * set to true for HDR content
-         */
+        /** set to true for HDR content */
         public boolean hdr = true;
-        /**
-         * type of color gamut box
-         */
+        /** type of color gamut box */
         @NonNull
         public TemporalAntiAliasingOptions.BoxType boxType = TemporalAntiAliasingOptions.BoxType.AABB;
-        /**
-         * clipping algorithm
-         */
+        /** clipping algorithm */
         @NonNull
         public TemporalAntiAliasingOptions.BoxClipping boxClipping = TemporalAntiAliasingOptions.BoxClipping.ACCURATE;
+        /** Jitter Pattern */
         @NonNull
         public TemporalAntiAliasingOptions.JitterPattern jitterPattern = TemporalAntiAliasingOptions.JitterPattern.HALTON_23_X16;
+        /** High values increases ghosting artefact, lower values increases jittering, range [0.75, 1.25] */
         public float varianceGamma = 1.0f;
-        /**
-         * adjust the feedback dynamically to reduce flickering
-         */
+        /** adjust the feedback dynamically to reduce flickering */
         public boolean preventFlickering = false;
-        /**
-         * whether to apply history reprojection (debug option)
-         */
+        /** whether to apply history reprojection (debug option) */
         public boolean historyReprojection = true;
     }
 
@@ -2138,30 +2029,22 @@ public class View {
      * @see #setScreenSpaceReflectionsOptions
      */
     public static class ScreenSpaceReflectionsOptions {
-        /**
-         * ray thickness, in world units
-         */
+        /** ray thickness, in world units */
         public float thickness = 0.1f;
-        /**
-         * bias, in world units, to prevent self-intersections
-         */
+        /** bias, in world units, to prevent self-intersections */
         public float bias = 0.01f;
-        /**
-         * maximum distance, in world units, to raycast
-         */
+        /** maximum distance, in world units, to raycast */
         public float maxDistance = 3.0f;
-        /**
-         * stride, in texels, for samples along the ray.
-         */
+        /** stride, in texels, for samples along the ray. */
         public float stride = 2.0f;
         public boolean enabled = false;
     }
 
     /**
      * Options for the  screen-space guard band.
-     * A guard band can be enabled to avoid some artifacts towards the edge of the screen when
+     * <p>A guard band can be enabled to avoid some artifacts towards the edge of the screen when
      * using screen-space effects such as SSAO. Enabling the guard band reduces performance slightly.
-     * Currently the guard band can only be enabled or disabled.
+     * Currently the guard band can only be enabled or disabled.</p>
      */
     public static class GuardBandOptions {
         public boolean enabled = false;
@@ -2174,13 +2057,9 @@ public class View {
      * @see #setSampleCount
      */
     public enum AntiAliasing {
-        /**
-         * no anti aliasing performed as part of post-processing
-         */
+        /** no anti aliasing performed as part of post-processing */
         NONE,
-        /**
-         * FXAA is a low-quality but very efficient type of anti-aliasing. (default).
-         */
+        /** FXAA is a low-quality but very efficient type of anti-aliasing. (default). */
         FXAA,
     }
 
@@ -2188,13 +2067,9 @@ public class View {
      * List of available post-processing dithering techniques.
      */
     public enum Dithering {
-        /**
-         * No dithering
-         */
+        /** No dithering */
         NONE,
-        /**
-         * Temporal dithering (default)
-         */
+        /** Temporal dithering (default) */
         TEMPORAL,
     }
 
@@ -2203,21 +2078,13 @@ public class View {
      * @see #setShadowType
      */
     public enum ShadowType {
-        /**
-         * percentage-closer filtered shadows (default)
-         */
+        /** percentage-closer filtered shadows (default) */
         PCF,
-        /**
-         * variance shadows
-         */
+        /** variance shadows */
         VSM,
-        /**
-         * PCF with contact hardening simulation
-         */
+        /** PCF with contact hardening simulation */
         DPCF,
-        /**
-         * PCF with soft shadows and contact hardening
-         */
+        /** PCF with soft shadows and contact hardening */
         PCSS,
         PCFd,
     }
@@ -2225,14 +2092,14 @@ public class View {
     /**
      * View-level options for VSM Shadowing.
      * @see #setVsmShadowOptions
-     * @warning This API is still experimental and subject to change.
+     * <b>Warning:</b> This API is still experimental and subject to change.
      */
     public static class VsmShadowOptions {
         /**
          * Sets the number of anisotropic samples to use when sampling a VSM shadow map. If greater
          * than 0, mipmaps will automatically be generated each frame for all lights.
          *
-         * The number of anisotropic samples = 2 ^ vsmAnisotropy.
+         * <p>The number of anisotropic samples = 2 ^ vsmAnisotropy.</p>
          */
         public int anisotropy = 0;
         /**
@@ -2266,7 +2133,7 @@ public class View {
     /**
      * View-level options for DPCF and PCSS Shadowing.
      * @see #setSoftShadowOptions
-     * @warning This API is still experimental and subject to change.
+     * <b>Warning:</b> This API is still experimental and subject to change.
      */
     public static class SoftShadowOptions {
         /**

android/filament-utils-android/CMakeLists.txt

@@ -22,6 +22,10 @@ add_library(image STATIC IMPORTED)
 set_target_properties(image PROPERTIES IMPORTED_LOCATION
         ${FILAMENT_DIR}/lib/${ANDROID_ABI}/libimage.a)
 
+add_library(imageio-lite STATIC IMPORTED)
+set_target_properties(imageio-lite PROPERTIES IMPORTED_LOCATION
+        ${FILAMENT_DIR}/lib/${ANDROID_ABI}/libimageio-lite.a)
+
 add_library(ktxreader STATIC IMPORTED)
 set_target_properties(ktxreader PROPERTIES IMPORTED_LOCATION
         ${FILAMENT_DIR}/lib/${ANDROID_ABI}/libktxreader.a)
@@ -30,6 +34,10 @@ add_library(viewer STATIC IMPORTED)
 set_target_properties(viewer PROPERTIES IMPORTED_LOCATION
         ${FILAMENT_DIR}/lib/${ANDROID_ABI}/libviewer.a)
 
+add_library(imagediff STATIC IMPORTED)
+set_target_properties(imagediff PROPERTIES IMPORTED_LOCATION
+        ${FILAMENT_DIR}/lib/${ANDROID_ABI}/libimagediff.a)
+
 add_library(civetweb STATIC IMPORTED)
 set_target_properties(civetweb PROPERTIES IMPORTED_LOCATION
         ${FILAMENT_DIR}/lib/${ANDROID_ABI}/libcivetweb.a)
@@ -57,6 +65,7 @@ add_library(filament-utils-jni SHARED
         src/main/cpp/IBLPrefilterContext.cpp
         src/main/cpp/Utils.cpp
         src/main/cpp/Manipulator.cpp
+        src/main/cpp/ImageDiff.cpp
         src/main/cpp/RemoteServer.cpp
 
         ${IMAGEIO_DIR}/include/imageio/ImageDecoder.h
@@ -74,6 +83,7 @@ target_include_directories(filament-utils-jni PRIVATE
         ${FILAMENT_DIR}/include
         ../../filament/backend/include
         ${IMAGEIO_DIR}/include
+        ../../libs/imagediff/include
         ../../libs/utils/include)
 
 set_target_properties(filament-utils-jni PROPERTIES LINK_DEPENDS ${VERSION_SCRIPT})
@@ -85,10 +95,13 @@ target_link_libraries(filament-utils-jni
         PRIVATE camutils
         PRIVATE iblprefilter
         PRIVATE image
+        PRIVATE imageio-lite
         PRIVATE filament-jni
         PRIVATE ktxreader
         PRIVATE viewer
+        PRIVATE imagediff
         PRIVATE log
         PRIVATE utils
         PRIVATE perfetto        # needed only when FILAMENT_ENABLE_PERFETTO is defined
+        PRIVATE jnigraphics     # needed for AndroidBitmap_* functions in ImageDiff
 )

android/filament-utils-android/src/main/cpp/AutomationEngine.cpp

@@ -71,8 +71,10 @@ Java_com_google_android_filament_utils_AutomationEngine_nStartBatchMode(JNIEnv*
 extern "C" JNIEXPORT void JNICALL
 Java_com_google_android_filament_utils_AutomationEngine_nTick(JNIEnv* env, jclass klass,
         jlong nativeAutomation, jlong nativeEngine,
-        jlong view, jlongArray materials, jlong renderer, jfloat deltaTime) {
+        jlong view, jlongArray materials, jlong renderer, jlong nativeIbl, jint sunlightEntity,
+        jintArray assetLights, jlong nativeLm, jlong scene, jfloat deltaTime) {
     using MaterialPointer = MaterialInstance*;
+
     jsize materialCount = 0;
     jlong* longMaterials = nullptr;
     MaterialPointer* ptrMaterials = nullptr;
@@ -84,12 +86,28 @@ Java_com_google_android_filament_utils_AutomationEngine_nTick(JNIEnv* env, jclas
             ptrMaterials[i] = (MaterialPointer) longMaterials[i];
         }
     }
+
+    jsize lightCount = 0;
+    jint* intLights = nullptr;
+    if (assetLights) {
+        lightCount = env->GetArrayLength(assetLights);
+        intLights = env->GetIntArrayElements(assetLights, nullptr);
+    }
+
+    static_assert(sizeof(jint) == sizeof(Entity));
+
     AutomationEngine* automation = (AutomationEngine*) nativeAutomation;
     AutomationEngine::ViewerContent content = {
         .view = (View*) view,
         .renderer = (Renderer*) renderer,
         .materials = ptrMaterials,
         .materialCount = (size_t) materialCount,
+        .lightManager = (LightManager*) nativeLm,
+        .scene = (Scene*) scene,
+        .indirectLight = (IndirectLight*) nativeIbl,
+        .sunlight = (Entity&) sunlightEntity,
+        .assetLights = (Entity*) intLights,
+        .assetLightCount = (size_t) lightCount,
     };
     Engine* engine = (Engine*)nativeEngine;
     automation->tick(engine, content, deltaTime);
@@ -97,6 +115,9 @@ Java_com_google_android_filament_utils_AutomationEngine_nTick(JNIEnv* env, jclas
         env->ReleaseLongArrayElements(materials, longMaterials, 0);
         delete[] ptrMaterials;
     }
+    if (intLights) {
+        env->ReleaseIntArrayElements(assetLights, intLights, 0);
+    }
 }
 
 extern "C" JNIEXPORT void JNICALL
@@ -228,6 +249,18 @@ Java_com_google_android_filament_utils_AutomationEngine_nShouldClose(JNIEnv*, jc
     return automation->shouldClose();
 }
 
+extern "C" JNIEXPORT jint JNICALL
+Java_com_google_android_filament_utils_AutomationEngine_nGetTestCount(JNIEnv*, jclass, jlong native) {
+    AutomationEngine* automation = (AutomationEngine*) native;
+    return (jint) automation->testCount();
+}
+
+extern "C" JNIEXPORT jint JNICALL
+Java_com_google_android_filament_utils_AutomationEngine_nGetCurrentTest(JNIEnv*, jclass, jlong native) {
+    AutomationEngine* automation = (AutomationEngine*) native;
+    return (jint) automation->currentTest();
+}
+
 extern "C" JNIEXPORT void JNICALL
 Java_com_google_android_filament_utils_AutomationEngine_nDestroy(JNIEnv*, jclass, jlong native) {
     AutomationEngine* automation = (AutomationEngine*) native;

android/filament-utils-android/src/main/cpp/ImageDiff.cpp

@@ -0,0 +1,217 @@
+/*
+ * Copyright (C) 2026 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#include <jni.h>
+#include <android/bitmap.h>
+
+#include <imagediff/ImageDiff.h>
+#include <utils/Log.h>
+
+#include <vector>
+
+using namespace imagediff;
+using namespace utils;
+
+namespace {
+
+struct BitmapLock {
+    JNIEnv* env;
+    jobject bitmap;
+    void* pixels;
+    AndroidBitmapInfo info;
+
+    BitmapLock(JNIEnv* env, jobject bitmap) : env(env), bitmap(bitmap), pixels(nullptr) {
+        if (!bitmap) return;
+        if (AndroidBitmap_getInfo(env, bitmap, &info) < 0) {
+            return;
+        }
+        if (AndroidBitmap_lockPixels(env, bitmap, &pixels) < 0) {
+            pixels = nullptr;
+        }
+    }
+
+    ~BitmapLock() {
+        if (pixels) {
+            AndroidBitmap_unlockPixels(env, bitmap);
+        }
+    }
+
+    bool isValid() const { return pixels != nullptr; }
+
+    imagediff::Bitmap toBitmap() const {
+        return {
+            .width = (uint32_t) info.width,
+            .height = (uint32_t) info.height,
+            .stride = (size_t) info.stride,
+            .data = pixels
+        };
+    }
+};
+
+} // namespace
+
+
+
+// Helper to convert C++ ImageDiffResult to Java Result
+jobject createResult(JNIEnv* env, ImageDiffResult const& result, bool generateDiff) {
+    // Create Result class/objects
+    jclass resultClass = env->FindClass("com/google/android/filament/utils/ImageDiff$Result");
+    jmethodID resultCtor = env->GetMethodID(resultClass, "<init>", "()V");
+    jobject resultObj = env->NewObject(resultClass, resultCtor);
+    jfieldID statusField = env->GetFieldID(resultClass, "status", "Lcom/google/android/filament/utils/ImageDiff$Result$Status;");
+    jfieldID failingCountField = env->GetFieldID(resultClass, "failingPixelCount", "J");
+    jfieldID maxDiffField = env->GetFieldID(resultClass, "maxDiffFound", "[F");
+    jfieldID diffImageField = env->GetFieldID(resultClass, "diffImage", "Landroid/graphics/Bitmap;");
+
+    // Map Status enum
+    jclass statusEnum = env->FindClass("com/google/android/filament/utils/ImageDiff$Result$Status");
+    jobject statusObj = nullptr;
+    jfieldID enumField = nullptr;
+    switch (result.status) {
+        case ImageDiffResult::Status::PASSED:
+            enumField = env->GetStaticFieldID(statusEnum, "PASSED", "Lcom/google/android/filament/utils/ImageDiff$Result$Status;");
+            break;
+        case ImageDiffResult::Status::SIZE_MISMATCH:
+             enumField = env->GetStaticFieldID(statusEnum, "SIZE_MISMATCH", "Lcom/google/android/filament/utils/ImageDiff$Result$Status;");
+            break;
+        case ImageDiffResult::Status::PIXEL_DIFFERENCE:
+             enumField = env->GetStaticFieldID(statusEnum, "PIXEL_DIFFERENCE", "Lcom/google/android/filament/utils/ImageDiff$Result$Status;");
+            break;
+    }
+    statusObj = env->GetStaticObjectField(statusEnum, enumField);
+    env->SetObjectField(resultObj, statusField, statusObj);
+
+    env->SetLongField(resultObj, failingCountField, (jlong) result.failingPixelCount);
+
+    jfloatArray maxDiffArray = env->NewFloatArray(4);
+    env->SetFloatArrayRegion(maxDiffArray, 0, 4, result.maxDiffFound);
+    env->SetObjectField(resultObj, maxDiffField, maxDiffArray);
+
+    if (generateDiff && result.diffImage.getWidth() > 0) {
+        jclass bitmapClass = env->FindClass("android/graphics/Bitmap");
+        jmethodID createBitmap = env->GetStaticMethodID(bitmapClass, "createBitmap", 
+            "(IILandroid/graphics/Bitmap$Config;)Landroid/graphics/Bitmap;");
+        
+        jclass configClass = env->FindClass("android/graphics/Bitmap$Config");
+        jfieldID argb8888 = env->GetStaticFieldID(configClass, "ARGB_8888", "Landroid/graphics/Bitmap$Config;");
+        jobject configObj = env->GetStaticObjectField(configClass, argb8888);
+
+        uint32_t width = result.diffImage.getWidth();
+        uint32_t height = result.diffImage.getHeight();
+        jobject diffBitmap = env->CallStaticObjectMethod(bitmapClass, createBitmap, (jint)width, (jint)height, configObj);
+        
+        if (diffBitmap) {
+            void* diffPixels;
+            if (AndroidBitmap_lockPixels(env, diffBitmap, &diffPixels) == 0) {
+                float const* src = result.diffImage.getPixelRef();
+                uint8_t* dst = (uint8_t*) diffPixels;
+                uint32_t channels = result.diffImage.getChannels(); // usually 4
+                
+                for (size_t i = 0; i < width * height; ++i) {
+                    for (int c = 0; c < 4; ++c) {
+                        float v = 0.0f;
+                        if (c < channels) v = src[i * channels + c];
+                        if (c == 3 && channels < 4) v = 1.0f; // Alpha 1.0 if missing
+                        dst[i * 4 + c] = (uint8_t) std::min(255.0f, std::max(0.0f, v * 255.0f));
+                    }
+                }
+                AndroidBitmap_unlockPixels(env, diffBitmap);
+                env->SetObjectField(resultObj, diffImageField, diffBitmap);
+            }
+        }
+    }
+    
+    return resultObj;
+}
+
+extern "C" JNIEXPORT jobject JNICALL
+Java_com_google_android_filament_utils_ImageDiff_nCompareBasic(JNIEnv* env, jclass,
+        jobject refBitmap, jobject candBitmap, jint mode, jint swizzle, jint channelMask,
+        jfloat maxAbsDiff, jfloat maxFailingPixelsFraction, jobject maskBitmap) {
+
+    BitmapLock refArg(env, refBitmap);
+    BitmapLock candArg(env, candBitmap);
+    BitmapLock maskArg(env, maskBitmap);
+
+    if (!refArg.isValid() || !candArg.isValid()) {
+         ImageDiffResult emptyResult; 
+         emptyResult.status = ImageDiffResult::Status::SIZE_MISMATCH; // or ERROR
+         return createResult(env, emptyResult, false);
+    }
+
+    ImageDiffConfig config;
+    config.mode = (ImageDiffConfig::Mode) mode;
+    config.swizzle = (ImageDiffConfig::Swizzle) swizzle;
+    config.channelMask = (uint8_t) channelMask;
+    config.maxAbsDiff = maxAbsDiff;
+    config.maxFailingPixelsFraction = maxFailingPixelsFraction;
+
+    imagediff::Bitmap const* maskPtr = nullptr;
+    imagediff::Bitmap maskVal;
+    if (maskBitmap && maskArg.isValid()) {
+         maskVal = maskArg.toBitmap();
+         maskPtr = &maskVal;
+    }
+
+    bool generateDiff = true;
+    ImageDiffResult result = compare(refArg.toBitmap(), candArg.toBitmap(), config, maskPtr, generateDiff);
+
+    return createResult(env, result, generateDiff);
+}
+
+extern "C" JNIEXPORT jobject JNICALL
+Java_com_google_android_filament_utils_ImageDiff_nCompareJson(JNIEnv* env, jclass,
+        jobject refBitmap, jobject candBitmap, jstring jsonConfig, jobject maskBitmap) {
+        
+    BitmapLock refArg(env, refBitmap);
+    BitmapLock candArg(env, candBitmap);
+    BitmapLock maskArg(env, maskBitmap);
+
+    if (!refArg.isValid() || !candArg.isValid()) {
+         ImageDiffResult emptyResult; 
+         emptyResult.status = ImageDiffResult::Status::SIZE_MISMATCH; // or ERROR
+         return createResult(env, emptyResult, false);
+    }
+
+    ImageDiffConfig config;
+    const char* nativeJson = env->GetStringUTFChars(jsonConfig, 0);
+    size_t length = env->GetStringUTFLength(jsonConfig);
+    
+    bool parsed = parseConfig(nativeJson, length, &config);
+    env->ReleaseStringUTFChars(jsonConfig, nativeJson);
+
+    if (!parsed) {
+        // Fallback to default or error?
+        // We could log error.
+        utils::slog.e << "ImageDiff JNI: Failed to parse JSON config" << utils::io::endl;
+        ImageDiffResult errResult;
+        errResult.status = ImageDiffResult::Status::PIXEL_DIFFERENCE; // assume fail
+        return createResult(env, errResult, false);
+    }
+
+    imagediff::Bitmap const* maskPtr = nullptr;
+    imagediff::Bitmap maskVal;
+    if (maskBitmap && maskArg.isValid()) {
+         maskVal = maskArg.toBitmap();
+         maskPtr = &maskVal;
+    }
+
+    bool generateDiff = true;
+    ImageDiffResult result = compare(refArg.toBitmap(), candArg.toBitmap(), config, maskPtr, generateDiff);
+
+    return createResult(env, result, generateDiff);
+}
+

android/filament-utils-android/src/main/java/com/google/android/filament/utils/AutomationEngine.java

@@ -178,7 +178,12 @@ public class AutomationEngine {
         }
         long nativeView = content.view.getNativeObject();
         long nativeRenderer = content.renderer.getNativeObject();
-        nTick(mNativeObject, engine.getNativeObject(), nativeView, nativeMaterialInstances, nativeRenderer, deltaTime);
+        long nativeIbl = content.indirectLight == null ? 0 : content.indirectLight.getNativeObject();
+        long nativeLm = content.lightManager == null ? 0 : content.lightManager.getNativeObject();
+        long nativeScene = content.scene == null ? 0 : content.scene.getNativeObject();
+        nTick(mNativeObject, engine.getNativeObject(), nativeView, nativeMaterialInstances,
+                nativeRenderer, nativeIbl, content.sunlight, content.assetLights, nativeLm,
+                nativeScene, deltaTime);
     }
 
     /**
@@ -271,6 +276,9 @@ public class AutomationEngine {
      */
     public boolean shouldClose() { return nShouldClose(mNativeObject); }
 
+    public int getTestCount() { return nGetTestCount(mNativeObject); }
+    public int getCurrentTest() { return nGetCurrentTest(mNativeObject); }
+
     @Override
     protected void finalize() throws Throwable {
         nDestroy(mNativeObject);
@@ -284,7 +292,8 @@ public class AutomationEngine {
     private static native void nStartRunning(long nativeObject);
     private static native void nStartBatchMode(long nativeObject);
     private static native void nTick(long nativeObject, long nativeEngine,
-            long view, long[] materials, long renderer, float deltaTime);
+            long view, long[] materials, long renderer, long ibl, int sunlight, int[] assetLights,
+            long lightManager, long scene, float deltaTime);
     private static native void nApplySettings(long nativeObject, long nativeEngine,
             String jsonSettings, long view,
             long[] materials, long ibl, int sunlight, int[] assetLights, long lightManager,
@@ -295,5 +304,7 @@ public class AutomationEngine {
     private static native void nSignalBatchMode(long nativeObject);
     private static native void nStopRunning(long nativeObject);
     private static native boolean nShouldClose(long nativeObject);
+    private static native int nGetTestCount(long nativeObject);
+    private static native int nGetCurrentTest(long nativeObject);
     private static native void nDestroy(long nativeObject);
 }

android/filament-utils-android/src/main/java/com/google/android/filament/utils/ImageDiff.java

@@ -0,0 +1,91 @@
+/*
+ * Copyright (C) 2026 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.google.android.filament.utils;
+
+import androidx.annotation.NonNull;
+import androidx.annotation.Nullable;
+import android.graphics.Bitmap;
+
+public class ImageDiff {
+    public enum Mode {
+        LEAF, AND, OR
+    }
+
+    public enum Swizzle {
+        RGBA, BGRA
+    }
+
+    public static class Config {
+        @NonNull
+        public Mode mode = Mode.LEAF;
+        @NonNull
+        public Swizzle swizzle = Swizzle.RGBA;
+        public int channelMask = 0xF;
+        public float maxAbsDiff = 0.0f;
+        public float maxFailingPixelsFraction = 0.0f;
+        // Children not supported in this simple wrapper for now, can be added if needed
+    }
+
+    public static class Result {
+        public enum Status {
+            PASSED,
+            SIZE_MISMATCH,
+            PIXEL_DIFFERENCE
+        }
+
+        public Status status;
+        public long failingPixelCount;
+        public float[] maxDiffFound; // [R, G, B, A]
+        public Bitmap diffImage; // Null if not generated
+    }
+
+    /**
+     * Compares two bitmaps using a configuration object.
+     *
+     * @param reference Golden image
+     * @param candidate Actual image
+     * @param config    Comparison configuration
+     * @param mask      Optional mask (grayscale)
+     * @return Result of comparison
+     */
+    @NonNull
+    public static Result compareBasic(@NonNull Bitmap reference, @NonNull Bitmap candidate,
+            @NonNull Config config, @Nullable Bitmap mask) {
+        return nCompareBasic(reference, candidate, config.mode.ordinal(), config.swizzle.ordinal(),
+                config.channelMask, config.maxAbsDiff, config.maxFailingPixelsFraction, mask);
+    }
+
+    /**
+     * Compares two bitmaps using a JSON configuration string.
+     *
+     * @param reference Golden image
+     * @param candidate Actual image
+     * @param jsonConfig Comparison configuration in JSON format
+     * @param mask      Optional mask (grayscale)
+     * @return Result of comparison
+     */
+    @NonNull
+    public static Result compare(@NonNull Bitmap reference, @NonNull Bitmap candidate,
+            @NonNull String jsonConfig, @Nullable Bitmap mask) {
+        return nCompareJson(reference, candidate, jsonConfig, mask);
+    }
+
+    private static native Result nCompareBasic(Bitmap reference, Bitmap candidate, int mode, int swizzle,
+            int channelMask, float maxAbsDiff, float maxFailingPixelsFraction, Bitmap mask);
+
+    private static native Result nCompareJson(Bitmap reference, Bitmap candidate, String jsonConfig, Bitmap mask);
+}

android/gradle.properties

@@ -1,5 +1,5 @@
 GROUP=com.google.android.filament
-VERSION_NAME=1.69.1
+VERSION_NAME=1.69.3
 
 POM_DESCRIPTION=Real-time physically based rendering engine for Android.
 

android/samples/sample-gltf-viewer/build.gradle

@@ -1,7 +1,7 @@
 plugins {
     id 'com.android.application'
     id 'kotlin-android'
-    id 'filament-tools-plugin'
+    id 'filament-plugin'
 }
 
 project.ext.isSample = true
@@ -10,7 +10,7 @@ kotlin {
     jvmToolchain(versions.jdk)
 }
 
-filamentTools {
+filament {
     cmgenArgs = "-q --format=ktx --size=256 --extract-blur=0.1 --deploy=src/main/assets/envs/default_env"
     iblInputFile = project.layout.projectDirectory.file("../../../third_party/environments/lightroom_14b.hdr")
     iblOutputDir = project.layout.projectDirectory.dir("src/main/assets/envs")

android/samples/sample-hello-camera/build.gradle

@@ -1,7 +1,7 @@
 plugins {
     id 'com.android.application'
     id 'kotlin-android'
-    id 'filament-tools-plugin'
+    id 'filament-plugin'
 }
 
 project.ext.isSample = true
@@ -10,7 +10,7 @@ kotlin {
     jvmToolchain(versions.jdk)
 }
 
-filamentTools {
+filament {
     materialInputDir = project.layout.projectDirectory.dir("src/main/materials")
     materialOutputDir = project.layout.projectDirectory.dir("src/main/assets/materials")
 }

android/samples/sample-hello-triangle/build.gradle

@@ -1,7 +1,7 @@
 plugins {
     id 'com.android.application'
     id 'kotlin-android'
-    id 'filament-tools-plugin'
+    id 'filament-plugin'
 }
 
 project.ext.isSample = true
@@ -10,7 +10,7 @@ kotlin {
     jvmToolchain(versions.jdk)
 }
 
-filamentTools {
+filament {
     materialInputDir = project.layout.projectDirectory.dir("src/main/materials")
     materialOutputDir = project.layout.projectDirectory.dir("src/main/assets/materials")
 }

android/samples/sample-image-based-lighting/build.gradle

@@ -1,7 +1,7 @@
 plugins {
     id 'com.android.application'
     id 'kotlin-android'
-    id 'filament-tools-plugin'
+    id 'filament-plugin'
 }
 
 project.ext.isSample = true
@@ -10,7 +10,7 @@ kotlin {
     jvmToolchain(versions.jdk)
 }
 
-filamentTools {
+filament {
     materialInputDir = project.layout.projectDirectory.dir("src/main/materials")
     materialOutputDir = project.layout.projectDirectory.dir("src/main/assets/materials")
 

android/samples/sample-lit-cube/build.gradle

@@ -1,7 +1,7 @@
 plugins {
     id 'com.android.application'
     id 'kotlin-android'
-    id 'filament-tools-plugin'
+    id 'filament-plugin'
 }
 
 project.ext.isSample = true
@@ -10,7 +10,7 @@ kotlin {
     jvmToolchain(versions.jdk)
 }
 
-filamentTools {
+filament {
     materialInputDir = project.layout.projectDirectory.dir("src/main/materials")
     materialOutputDir = project.layout.projectDirectory.dir("src/main/assets/materials")
 }

android/samples/sample-material-builder/build.gradle

@@ -1,7 +1,7 @@
 plugins {
     id 'com.android.application'
     id 'kotlin-android'
-    id 'filament-tools-plugin'
+    id 'filament-plugin'
 }
 
 project.ext.isSample = true
@@ -10,7 +10,7 @@ kotlin {
     jvmToolchain(versions.jdk)
 }
 
-filamentTools {
+filament {
     meshInputFile = project.layout.projectDirectory.file("../../../third_party/models/shader_ball/shader_ball.obj")
     meshOutputDir = project.layout.projectDirectory.dir("src/main/assets/models")
 

android/samples/sample-material-instance-stress/build.gradle

@@ -1,7 +1,7 @@
 plugins {
     id 'com.android.application'
     id 'kotlin-android'
-    id 'filament-tools-plugin'
+    id 'filament-plugin'
 }
 
 project.ext.isSample = true
@@ -10,7 +10,7 @@ kotlin {
     jvmToolchain(versions.jdk)
 }
 
-filamentTools {
+filament {
     materialInputDir = project.layout.projectDirectory.dir("src/main/materials")
     materialOutputDir = project.layout.projectDirectory.dir("src/main/assets/materials")
 }

android/samples/sample-multi-view/build.gradle

@@ -1,7 +1,7 @@
 plugins {
     id 'com.android.application'
     id 'kotlin-android'
-    id 'filament-tools-plugin'
+    id 'filament-plugin'
 }
 
 project.ext.isSample = true
@@ -10,7 +10,7 @@ kotlin {
     jvmToolchain(versions.jdk)
 }
 
-filamentTools {
+filament {
     materialInputDir = project.layout.projectDirectory.dir("src/main/materials")
     materialOutputDir = project.layout.projectDirectory.dir("src/main/assets/materials")
 }

android/samples/sample-page-curl/build.gradle

@@ -1,7 +1,7 @@
 plugins {
     id 'com.android.application'
     id 'kotlin-android'
-    id 'filament-tools-plugin'
+    id 'filament-plugin'
 }
 
 project.ext.isSample = true
@@ -10,7 +10,7 @@ kotlin {
     jvmToolchain(versions.jdk)
 }
 
-filamentTools {
+filament {
     iblInputFile = project.layout.projectDirectory.file("../../../third_party/environments/studio_small_02_2k.hdr")
     iblOutputDir = project.layout.projectDirectory.dir("src/main/assets/envs")
     materialInputDir = project.layout.projectDirectory.dir("src/main/materials")

android/samples/sample-render-validation/build.gradle

@@ -0,0 +1,55 @@
+plugins {
+    id 'com.android.application'
+    id 'kotlin-android'
+    id 'filament-plugin'
+}
+
+project.ext.isSample = true
+
+kotlin {
+    jvmToolchain(versions.jdk)
+}
+
+filament {
+    cmgenArgs = "-q --format=ktx --size=256 --extract-blur=0.1 --deploy=src/main/assets/envs/default_env"
+    iblInputFile = project.layout.projectDirectory.file("../../../third_party/environments/lightroom_14b.hdr")
+    iblOutputDir = project.layout.projectDirectory.dir("src/main/assets/envs")
+}
+
+// don't forget to update MainACtivity.kt when/if changing this.
+tasks.register('copyDamagedHelmetGltf', Copy) {
+    from file("../../../third_party/models/DamagedHelmet/DamagedHelmet.glb")
+    into file("src/main/assets/models")
+    rename {String fileName -> "helmet.glb"}
+}
+
+preBuild.dependsOn copyDamagedHelmetGltf
+
+clean.doFirst {
+    delete "src/main/assets"
+}
+
+android {
+    namespace 'com.google.android.filament.validation'
+
+    compileSdkVersion versions.compileSdk
+    defaultConfig {
+        applicationId "com.google.android.filament.validation"
+        minSdkVersion versions.minSdk
+        targetSdkVersion versions.targetSdk
+    }
+
+    compileOptions {
+        sourceCompatibility versions.jdk
+        targetCompatibility versions.jdk
+    }
+}
+
+dependencies {
+    implementation deps.kotlin
+    implementation 'androidx.constraintlayout:constraintlayout:2.1.4'
+    implementation deps.coroutines.core
+    implementation project(':filament-android')
+    implementation project(':gltfio-android')
+    implementation project(':filament-utils-android')
+}

android/samples/sample-render-validation/src/main/AndroidManifest.xml

@@ -0,0 +1,28 @@
+<?xml version="1.0" encoding="utf-8"?>
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+
+    <uses-permission android:name="android.permission.INTERNET" />
+    <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
+    <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
+    <uses-permission android:name="android.permission.MANAGE_EXTERNAL_STORAGE" />
+
+    <application
+        android:allowBackup="true"
+        android:label="Filament Validation"
+        android:supportsRtl="true"
+        android:largeHeap="true"
+        android:requestLegacyExternalStorage="true"
+        android:theme="@android:style/Theme.NoTitleBar">
+        <activity
+            android:name=".MainActivity"
+            android:exported="true"
+            android:configChanges="orientation|screenSize|screenLayout|keyboardHidden"
+            android:screenOrientation="fullSensor">
+            <intent-filter>
+                <action android:name="android.intent.action.MAIN" />
+                <category android:name="android.intent.category.LAUNCHER" />
+            </intent-filter>
+        </activity>
+    </application>
+
+</manifest>

android/samples/sample-render-validation/src/main/java/com/google/android/filament/validation/MainActivity.kt

@@ -0,0 +1,350 @@
+/*
+ * Copyright (C) 2026 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.google.android.filament.validation
+
+import android.app.Activity
+import android.graphics.Bitmap
+import android.os.Bundle
+import android.util.Log
+import android.view.Choreographer
+import android.view.SurfaceView
+import android.view.View
+import android.view.WindowManager
+import android.widget.ImageView
+import android.widget.LinearLayout
+import android.widget.ScrollView
+import android.widget.TextView
+import com.google.android.filament.utils.ModelViewer
+import com.google.android.filament.utils.Utils
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.launch
+import kotlinx.coroutines.withContext
+import com.google.android.filament.utils.KTX1Loader
+import com.google.android.filament.IndirectLight
+import com.google.android.filament.Skybox
+import android.graphics.Color
+import java.io.File
+import java.io.FileOutputStream
+import java.net.HttpURLConnection
+import java.net.URL
+import java.nio.ByteBuffer
+import android.widget.ArrayAdapter
+import android.widget.Button
+import android.widget.Spinner
+import android.widget.AdapterView
+
+class MainActivity : Activity(), ValidationRunner.Callback {
+
+    companion object {
+        init {
+            Utils.init()
+            System.loadLibrary("filament-utils-jni")
+        }
+        private const val TAG = "FilamentValidation"
+    }
+
+    private lateinit var surfaceView: SurfaceView
+    private lateinit var choreographer: Choreographer
+    private lateinit var modelViewer: ModelViewer
+    private lateinit var statusTextView: TextView
+    private lateinit var resultsContainer: LinearLayout
+    private lateinit var inputManager: ValidationInputManager
+    private var currentInput: ValidationInputManager.ValidationInput? = null
+    private lateinit var modeSpinner: Spinner
+    private lateinit var runButton: Button
+    private var resultManager: ValidationResultManager? = null
+
+    private var validationRunner: ValidationRunner? = null
+
+    // Frame callback
+    private val frameScheduler = object : Choreographer.FrameCallback {
+        override fun doFrame(frameTimeNanos: Long) {
+            choreographer.postFrameCallback(this)
+            modelViewer.render(frameTimeNanos)
+            validationRunner?.onFrame(frameTimeNanos)
+        }
+    }
+
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+        setContentView(R.layout.activity_main)
+
+        // SurfaceView container
+        surfaceView = findViewById(R.id.surface_view)
+        surfaceView.holder.setFixedSize(512, 512)
+
+        statusTextView = findViewById(R.id.status_text)
+        modeSpinner = findViewById(R.id.mode_spinner)
+        runButton = findViewById(R.id.run_button)
+        resultsContainer = findViewById(R.id.results_container)
+
+        // Setup Spinner
+        val modes = arrayOf("Run Validation", "Generate Goldens")
+        val adapter = ArrayAdapter(this, android.R.layout.simple_spinner_item, modes)
+        adapter.setDropDownViewResource(android.R.layout.simple_spinner_dropdown_item)
+        modeSpinner.adapter = adapter
+
+        // Setup Run Button
+        runButton.setOnClickListener {
+            currentInput?.let { input ->
+                val generateGoldens = modeSpinner.selectedItemPosition == 1
+                val newInput = input.copy(generateGoldens = generateGoldens)
+                startValidation(newInput)
+            }
+        }
+
+        window.addFlags(WindowManager.LayoutParams.FLAG_KEEP_SCREEN_ON)
+
+        choreographer = Choreographer.getInstance()
+        modelViewer = ModelViewer(surfaceView)
+        inputManager = ValidationInputManager(this)
+
+        // Initialize IBL
+        createIndirectLight()
+
+        handleIntent()
+    }
+
+    private fun createIndirectLight() {
+        try {
+            val engine = modelViewer.engine
+            val scene = modelViewer.scene
+            val iblName = "default_env"
+
+            fun readAsset(path: String): ByteBuffer {
+                val input = assets.open(path)
+                val bytes = input.readBytes()
+                return ByteBuffer.wrap(bytes)
+            }
+
+            readAsset("envs/$iblName/${iblName}_ibl.ktx").let {
+                val bundle = KTX1Loader.createIndirectLight(engine, it)
+                scene.indirectLight = bundle.indirectLight
+                modelViewer.indirectLightCubemap = bundle.cubemap
+                scene.indirectLight!!.intensity = 30_000.0f
+            }
+
+            readAsset("envs/$iblName/${iblName}_skybox.ktx").let {
+                val bundle = KTX1Loader.createSkybox(engine, it)
+                scene.skybox = bundle.skybox
+                modelViewer.skyboxCubemap = bundle.cubemap
+            }
+            Log.i(TAG, "IBL loaded successfully")
+        } catch (e: Exception) {
+            Log.e(TAG, "Failed to load IBL", e)
+            statusTextView.text = "Warning: Failed to load IBL"
+        }
+    }
+
+    private fun handleIntent() {
+        statusTextView.text = "Resolving configuration..."
+        CoroutineScope(Dispatchers.Main).launch {
+            try {
+                val input = inputManager.resolveConfig(intent)
+                currentInput = input
+
+                // Sync spinner with intent
+                modeSpinner.setSelection(if (input.generateGoldens) 1 else 0)
+
+                startValidation(input)
+            } catch (e: Exception) {
+                Log.e(TAG, "Failed to resolve config", e)
+                statusTextView.text = "Error: ${e.message}"
+            }
+        }
+    }
+
+    private fun startValidation(input: ValidationInputManager.ValidationInput) {
+        try {
+            resultsContainer.removeAllViews()
+            Log.i(TAG, "Starting validation with config: ${input.config.name}")
+            Log.i(TAG, "Output dir: ${input.outputDir.absolutePath}")
+
+            resultManager = ValidationResultManager(input.outputDir)
+
+            validationRunner = ValidationRunner(this, modelViewer, input.config, resultManager!!)
+            validationRunner?.callback = this
+            validationRunner?.generateGoldens = input.generateGoldens
+            validationRunner?.start()
+
+            // Sync spinner in case it was called programmatically or changed implicitly
+            modeSpinner.setSelection(if (input.generateGoldens) 1 else 0)
+
+        } catch (e: Exception) {
+            Log.e(TAG, "Failed to start validation", e)
+            statusTextView.text = "Error: ${e.message}"
+        }
+    }
+
+    override fun onResume() {
+        super.onResume()
+        choreographer.postFrameCallback(frameScheduler)
+    }
+
+    override fun onPause() {
+        super.onPause()
+        choreographer.removeFrameCallback(frameScheduler)
+    }
+
+    override fun onDestroy() {
+        super.onDestroy()
+        choreographer.removeFrameCallback(frameScheduler)
+    }
+
+    private var currentRenderedBitmap: Bitmap? = null
+    private var currentGoldenBitmap: Bitmap? = null
+    private var currentDiffBitmap: Bitmap? = null
+
+    override fun onTestFinished(result: ValidationResult) {
+        runOnUiThread {
+            val status = "Test ${result.testName} finished: ${if(result.passed) "PASS" else "FAIL"}"
+            statusTextView.text = status
+            Log.i(TAG, status)
+
+            // Container for this result
+            val resultContainer = LinearLayout(this)
+            resultContainer.orientation = LinearLayout.VERTICAL
+            resultContainer.setPadding(0, 10, 0, 20)
+
+            // Header
+            val resultView = TextView(this)
+            resultView.text = "${result.testName}: ${if(result.passed) "PASS" else "FAIL"} (Diff: ${result.diffMetric})"
+            resultView.setTextColor(if(result.passed) Color.GREEN else Color.RED)
+            resultView.textSize = 16f
+            resultView.setTypeface(null, android.graphics.Typeface.BOLD)
+            resultContainer.addView(resultView)
+
+            // Images Row
+            val imagesRow = LinearLayout(this)
+            imagesRow.orientation = LinearLayout.HORIZONTAL
+
+            fun addImage(label: String, bitmap: Bitmap?) {
+                if (bitmap != null) {
+                    val container = LinearLayout(this)
+                    container.orientation = LinearLayout.VERTICAL
+                    container.setPadding(0, 0, 10, 0)
+
+                    val labelView = TextView(this)
+                    labelView.text = label
+                    labelView.textSize = 12f
+                    container.addView(labelView)
+
+                    val iv = ImageView(this)
+                    iv.setImageBitmap(bitmap) // Use the same bitmap (or copy if needed, but same is usually fine for UI)
+                    iv.layoutParams = LinearLayout.LayoutParams(250, 250) // Smaller thumbnails
+                    iv.scaleType = ImageView.ScaleType.FIT_CENTER
+                    iv.setBackgroundColor(0xFF404040.toInt())
+                    container.addView(iv)
+
+                    imagesRow.addView(container)
+                }
+            }
+
+            addImage("Rendered", currentRenderedBitmap)
+            addImage("Golden", currentGoldenBitmap)
+            if (!result.passed) {
+                addImage("Diff", currentDiffBitmap)
+            }
+
+            resultContainer.addView(imagesRow)
+            resultsContainer.addView(resultContainer)
+
+            // Clear current images for next test
+            currentRenderedBitmap = null
+            currentGoldenBitmap = null
+            currentDiffBitmap = null
+        }
+    }
+
+    override fun onAllTestsFinished() {
+        runOnUiThread {
+            statusTextView.text = "All tests finished!"
+            Log.i(TAG, "All tests finished")
+        }
+    }
+
+    override fun onStatusChanged(status: String) {
+        runOnUiThread {
+            statusTextView.text = status
+        }
+    }
+
+    override fun onImageResult(type: String, bitmap: Bitmap) {
+        runOnUiThread {
+            // Update the "live" views
+            when (type) {
+                "Rendered" -> {
+                    currentRenderedBitmap = bitmap
+                }
+                "Golden" -> {
+                    currentGoldenBitmap = bitmap
+                }
+                "Diff" -> {
+                    currentDiffBitmap = bitmap
+                }
+            }
+        }
+    }
+}
+
+/*
+ * Scripts for reference:
+ *
+ * generate_goldens.sh:
+ * --------------------
+ * #!/bin/bash
+ * set -e
+ *
+ * # Config path (on device)
+ * CONFIG_PATH=$1
+ * if [ -z "$CONFIG_PATH" ]; then
+ *     echo "Usage: $0 <device_config_path>"
+ *     echo "Example: $0 /sdcard/Android/data/com.google.android.filament.validation/files/default_test.json"
+ *     exit 1
+ * fi
+ *
+ * echo "Starting Golden Generation for $CONFIG_PATH..."
+ * adb shell am force-stop com.google.android.filament.validation
+ * adb shell am start -n com.google.android.filament.validation/.MainActivity \
+ *     -e test_config "$CONFIG_PATH" \
+ *     --ez generate_goldens true
+ *
+ * echo "Check device or logcat for progress."
+ * echo "adb logcat -s FilamentValidation:I ValidationRunner:I"
+ * echo "To pull results: ./samples/sample-render-validation/pull_goldens.sh"
+ *
+ * pull_goldens.sh:
+ * ----------------
+ * #!/bin/bash
+ * set -e
+ *
+ * # Default destination is local golden directory relative to script
+ * SCRIPT_DIR=$(cd $(dirname $0); pwd)
+ * DEST_DIR=${1:-"$SCRIPT_DIR/golden"}
+ *
+ * echo "Pulling goldens to $DEST_DIR..."
+ * mkdir -p "$DEST_DIR"
+ *
+ * # Path on device
+ * DEVICE_GOLDEN_DIR="/storage/emulated/0/Android/data/com.google.android.filament.validation/files/golden/."
+ *
+ * adb pull "$DEVICE_GOLDEN_DIR" "$DEST_DIR"
+ *
+ * echo "Done."
+ * ls -l "$DEST_DIR"
+ */

android/samples/sample-render-validation/src/main/java/com/google/android/filament/validation/TestConfig.kt

@@ -0,0 +1,186 @@
+/*
+ * Copyright (C) 2026 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.google.android.filament.validation
+
+import org.json.JSONArray
+import org.json.JSONObject
+import java.io.File
+import java.io.IOException
+
+data class RenderTestConfig(
+    val name: String,
+    val backends: List<String>,
+    val models: Map<String, String>, // name -> path
+    val tests: List<TestConfig>
+)
+
+data class TestConfig(
+    val name: String,
+    val description: String?,
+    val backends: List<String>,
+    val models: Set<String>,
+    val rendering: JSONObject,
+    val tolerance: JSONObject?
+)
+
+
+// See test/renderdiff/FORMAT.md for the full specification matched by this parser.
+class ConfigParser {
+    companion object {
+        fun parseFromPath(path: String): RenderTestConfig {
+            val file = File(path)
+            val jsonTxt = removeComments(file.readText())
+            val json = JSONObject(jsonTxt)
+            return parseRenderTestConfig(json, file.parentFile)
+        }
+
+        private fun removeComments(json: String): String {
+            return json.lines().joinToString("\n") { it.substringBefore("//") }
+        }
+
+        private fun parseRenderTestConfig(json: JSONObject, baseDir: File?): RenderTestConfig {
+            val name = json.getString("name")
+            val backends = json.getJSONArray("backends").toList<String>()
+            
+            val modelSearchPaths = json.optJSONArray("model_search_paths")?.toList<String>() ?: emptyList()
+            val models = mutableMapOf<String, String>()
+            
+            baseDir?.let { dir ->
+                modelSearchPaths.forEach { searchPath ->
+                    val searchDir = File(dir, searchPath)
+                    if (searchDir.exists()) {
+                        searchDir.walkTopDown().filter { it.isFile && (it.extension == "glb" || it.extension == "gltf") }.forEach { file ->
+                            models[file.nameWithoutExtension] = file.absolutePath
+                        }
+                    }
+                }
+            }
+
+            // Explicit models map override
+            val modelsJson = json.optJSONObject("models")
+            if (modelsJson != null) {
+                val keys = modelsJson.keys()
+                while (keys.hasNext()) {
+                    val name = keys.next()
+                    val path = modelsJson.getString(name)
+                    // Resolve path relative to baseDir if not absolute
+                    val file = File(path)
+                    if (file.isAbsolute) {
+                        models[name] = path
+                    } else if (baseDir != null) {
+                        models[name] = File(baseDir, path).absolutePath
+                    } else {
+                        models[name] = path
+                    }
+                }
+            }
+
+
+            val presetsJson = json.optJSONArray("presets")
+            val presets = mutableMapOf<String, PresetConfig>()
+            if (presetsJson != null) {
+                for (i in 0 until presetsJson.length()) {
+                    val p = parsePreset(presetsJson.getJSONObject(i), models.keys)
+                    presets[p.name] = p
+                }
+            }
+
+            val testsJson = json.getJSONArray("tests")
+            val tests = mutableListOf<TestConfig>()
+            for (i in 0 until testsJson.length()) {
+                tests.add(parseTestConfig(testsJson.getJSONObject(i), models.keys, presets, backends))
+            }
+
+            return RenderTestConfig(name, backends, models, tests)
+        }
+
+        private fun parsePreset(json: JSONObject, existingModels: Set<String>): PresetConfig {
+            val name = json.getString("name")
+            val rendering = json.getJSONObject("rendering")
+            val models = json.optJSONArray("models")?.toList<String>() ?: emptyList()
+            
+            // Validate models
+            models.forEach { if (!existingModels.contains(it)) throw IllegalArgumentException("Model $it not found") }
+
+            val tolerance = json.optJSONObject("tolerance")
+            return PresetConfig(name, rendering, models, tolerance)
+        }
+
+        private fun parseTestConfig(
+            json: JSONObject, 
+            existingModels: Set<String>, 
+            presets: Map<String, PresetConfig>, 
+            defaultBackends: List<String>
+        ): TestConfig {
+            val name = json.getString("name")
+            val description = json.optString("description")
+            val backends = json.optJSONArray("backends")?.toList<String>() ?: defaultBackends
+            
+            val applyPresets = json.optJSONArray("apply_presets")?.toList<String>() ?: emptyList()
+            
+            val rendering = JSONObject()
+            val combinedModels = mutableSetOf<String>()
+            var lastTolerance: JSONObject? = null
+
+            applyPresets.forEach { presetName ->
+                val preset = presets[presetName] ?: throw IllegalArgumentException("Unknown preset $presetName")
+                // Merge rendering (flat copy)
+                val keys = preset.rendering.keys()
+                while(keys.hasNext()) {
+                    val k = keys.next()
+                    rendering.put(k, preset.rendering.get(k))
+                }
+                combinedModels.addAll(preset.models)
+                if (preset.tolerance != null) lastTolerance = preset.tolerance
+            }
+
+            val testRendering = json.optJSONObject("rendering")
+            if (testRendering != null) {
+                val keys = testRendering.keys()
+                while(keys.hasNext()) {
+                    val k = keys.next()
+                    rendering.put(k, testRendering.get(k))
+                }
+            }
+
+            val testModels = json.optJSONArray("models")?.toList<String>() ?: emptyList()
+            combinedModels.addAll(testModels)
+            
+             // Validate models
+            combinedModels.forEach { if (!existingModels.contains(it)) throw IllegalArgumentException("Model $it not found") }
+
+            val tolerance = json.optJSONObject("tolerance") ?: lastTolerance
+
+            return TestConfig(name, description, backends, combinedModels, rendering, tolerance)
+        }
+    }
+}
+
+data class PresetConfig(
+    val name: String,
+    val rendering: JSONObject,
+    val models: List<String>,
+    val tolerance: JSONObject?
+)
+
+private inline fun <reified T> JSONArray.toList(): List<T> {
+    val list = mutableListOf<T>()
+    for (i in 0 until length()) {
+        list.add(get(i) as T)
+    }
+    return list
+}

android/samples/sample-render-validation/src/main/java/com/google/android/filament/validation/ValidationInputManager.kt

@@ -0,0 +1,170 @@
+/*
+ * Copyright (C) 2026 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.google.android.filament.validation
+
+import android.content.Context
+import android.content.Intent
+import android.util.Log
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.withContext
+import org.json.JSONObject
+import java.io.File
+import java.io.FileOutputStream
+import java.net.HttpURLConnection
+import java.net.URL
+
+/**
+ * Handles the retrieval and preparation of test configuration and assets.
+ * Supports loading from:
+ * 1. Intent extras (local path or URL)
+ * 2. Default embedded assets (fallback)
+ */
+class ValidationInputManager(private val context: Context) {
+
+    companion object {
+        private const val TAG = "ValidationInputManager"
+    }
+
+    data class ValidationInput(
+        val config: RenderTestConfig,
+        val outputDir: File,
+        val generateGoldens: Boolean
+    )
+
+    /**
+     * Resolves the test configuration based on the provided intent extras.
+     * This may involve extracting assets or downloading files.
+     */
+    suspend fun resolveConfig(intent: Intent): ValidationInput = withContext(Dispatchers.IO) {
+        val testConfigPath = intent.getStringExtra("test_config")
+        val urlConfig = intent.getStringExtra("url_config")
+        val urlModelsBase = intent.getStringExtra("url_models_base")
+        val generateGoldens = intent.getBooleanExtra("generate_goldens", false)
+        val outputPath = intent.getStringExtra("output_path")
+
+        val outputDir = if (outputPath != null) {
+            File(outputPath).apply { mkdirs() }
+        } else {
+            File(context.getExternalFilesDir(null), "validation_results").apply { mkdirs() }
+        }
+
+        val config = when {
+            urlConfig != null -> downloadConfig(urlConfig, urlModelsBase)
+            testConfigPath != null -> ConfigParser.parseFromPath(testConfigPath)
+            else -> extractDefaultAssets()
+        }
+
+        return@withContext ValidationInput(config, outputDir, generateGoldens)
+    }
+
+    private suspend fun extractDefaultAssets(): RenderTestConfig {
+        Log.i(TAG, "Extracting default assets...")
+        val filesDir = context.getExternalFilesDir(null) ?: context.filesDir
+        val assetManager = context.assets
+
+        // Copy default_test.json
+        val configDir = File(filesDir, "config")
+        configDir.mkdirs()
+        val configOut = File(configDir, "default_test.json")
+
+        assetManager.open("default_test.json").use { input ->
+            FileOutputStream(configOut).use { output ->
+                input.copyTo(output)
+            }
+        }
+
+        // Copy DamagedHelmet.glb
+        val modelsDir = File(filesDir, "models")
+        modelsDir.mkdirs()
+        val modelOut = File(modelsDir, "DamagedHelmet.glb")
+
+        assetManager.open("DamagedHelmet.glb").use { input ->
+            FileOutputStream(modelOut).use { output ->
+                input.copyTo(output)
+            }
+        }
+
+        // Update config to point to relative path (standardizing on relative for portability where possible)
+        // or absolute. Here we use relative as per previous logic.
+        val configJson = JSONObject(configOut.readText())
+        val models = configJson.getJSONObject("models")
+
+        // Ensure the default model points to the extracted file
+        // We can use absolute path to be safe since we know where it is now.
+        models.put("DamagedHelmet", modelOut.absolutePath)
+
+        configOut.writeText(configJson.toString(2))
+
+        return ConfigParser.parseFromPath(configOut.absolutePath)
+    }
+
+    private suspend fun downloadConfig(urlConfig: String, urlModelsBase: String?): RenderTestConfig {
+        Log.i(TAG, "Downloading config from $urlConfig")
+        val filesDir = context.getExternalFilesDir(null) ?: context.filesDir
+        val configDir = File(filesDir, "config")
+        configDir.mkdirs()
+
+        val modelsDir = File(filesDir, "models")
+        modelsDir.mkdirs()
+
+        val configName = "downloaded_config.json"
+        val configFile = File(configDir, configName)
+
+        downloadFile(urlConfig, configFile)
+
+        if (urlModelsBase != null) {
+            val configJson = JSONObject(configFile.readText())
+            val models = configJson.optJSONObject("models")
+            if (models != null) {
+                val keys = models.keys()
+                while (keys.hasNext()) {
+                    val key = keys.next()
+                    val modelPath = models.getString(key)
+                    val fileName = File(modelPath).name
+                    val modelFile = File(modelsDir, fileName)
+                    val modelUrl = "$urlModelsBase/$fileName"
+
+                    Log.i(TAG, "Downloading model: $fileName from $modelUrl")
+                    downloadFile(modelUrl, modelFile)
+
+                    // Update config to point to absolute path
+                    models.put(key, modelFile.absolutePath)
+                }
+                configFile.writeText(configJson.toString())
+            }
+        }
+
+        return ConfigParser.parseFromPath(configFile.absolutePath)
+    }
+
+    private fun downloadFile(urlStr: String, destFile: File) {
+        val url = URL(urlStr)
+        val connection = url.openConnection() as HttpURLConnection
+        connection.connect()
+
+        if (connection.responseCode != HttpURLConnection.HTTP_OK) {
+             throw Exception("Server returned HTTP ${connection.responseCode} for $urlStr")
+        }
+
+        destFile.parentFile?.mkdirs()
+        connection.inputStream.use { input ->
+            FileOutputStream(destFile).use { output ->
+                input.copyTo(output)
+            }
+        }
+    }
+}

android/samples/sample-render-validation/src/main/java/com/google/android/filament/validation/ValidationResultManager.kt

@@ -0,0 +1,109 @@
+/*
+ * Copyright (C) 2026 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.google.android.filament.validation
+
+import android.graphics.Bitmap
+import android.util.Log
+import java.io.File
+import java.io.FileOutputStream
+import java.util.zip.ZipEntry
+import java.util.zip.ZipOutputStream
+import org.json.JSONArray
+import org.json.JSONObject
+
+data class ValidationResult(
+    val testName: String,
+    val passed: Boolean,
+    val diffMetric: Float = 0f
+)
+
+class ValidationResultManager(private val outputDir: File) {
+
+    companion object {
+        private const val TAG = "ValidationResultManager"
+    }
+
+    private val results = mutableListOf<ValidationResult>()
+
+    init {
+        if (!outputDir.exists()) {
+            outputDir.mkdirs()
+        }
+    }
+
+    fun addResult(result: ValidationResult) {
+        results.add(result)
+    }
+
+    fun saveImage(name: String, bitmap: Bitmap) {
+        val file = File(outputDir, "$name.png")
+        try {
+            FileOutputStream(file).use { out ->
+                bitmap.compress(Bitmap.CompressFormat.PNG, 100, out)
+            }
+        } catch (e: Exception) {
+            Log.e(TAG, "Failed to save image $name", e)
+        }
+    }
+
+    fun getOutputDir(): File {
+        return outputDir
+    }
+
+    fun finalizeResults(): File? {
+        // Write results JSON
+        writeResultsJson()
+
+        // Zip results
+        val zipFile = File(outputDir, "results.zip")
+        try {
+            ZipOutputStream(FileOutputStream(zipFile)).use { zos ->
+                outputDir.walkTopDown().filter { it.isFile && it.name != "results.zip" }.forEach { file ->
+                    val entryName = file.relativeTo(outputDir).path
+                    zos.putNextEntry(ZipEntry(entryName))
+                    file.inputStream().use { it.copyTo(zos) }
+                    zos.closeEntry()
+                }
+            }
+            Log.i(TAG, "Zipped results to ${zipFile.absolutePath}")
+            return zipFile
+        } catch (e: Exception) {
+            Log.e(TAG, "Failed to zip results", e)
+            return null
+        }
+    }
+
+    private fun writeResultsJson() {
+        val jsonArray = JSONArray()
+        for (result in results) {
+            val jsonObject = JSONObject()
+            jsonObject.put("test_name", result.testName)
+            jsonObject.put("passed", result.passed)
+            jsonObject.put("diff_metric", result.diffMetric)
+            jsonArray.put(jsonObject)
+        }
+
+        val jsonFile = File(outputDir, "results.json")
+        try {
+            FileOutputStream(jsonFile).use { out ->
+                out.write(jsonArray.toString(4).toByteArray())
+            }
+        } catch (e: Exception) {
+            Log.e(TAG, "Failed to write results.json", e)
+        }
+    }
+}

android/samples/sample-render-validation/src/main/java/com/google/android/filament/validation/ValidationRunner.kt

@@ -0,0 +1,319 @@
+/*
+ * Copyright (C) 2026 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.google.android.filament.validation
+
+import android.content.Context
+import android.graphics.Bitmap
+import android.util.Log
+import com.google.android.filament.utils.AutomationEngine
+import com.google.android.filament.utils.ImageDiff
+import com.google.android.filament.utils.ModelViewer
+import org.json.JSONObject
+import java.io.File
+import java.io.FileOutputStream
+import java.nio.ByteBuffer
+
+class ValidationRunner(
+    private val context: Context,
+    private val modelViewer: ModelViewer,
+    private val config: RenderTestConfig,
+    private val resultManager: ValidationResultManager
+) {
+
+    private var currentState = State.IDLE
+    private var currentTestIndex = 0
+    private var currentModelIndex = 0
+    private var currentEngine: AutomationEngine? = null
+    private var currentTestConfig: TestConfig? = null
+    private var currentModelName: String? = null
+
+    private var loadStartFence: com.google.android.filament.Fence? = null
+    private var loadStartTime = 0L
+    private var frameCounter = 0
+
+    enum class State {
+        IDLE,
+        LOADING_MODEL,
+        WAITING_FOR_FENCE,
+        WAITING_FOR_RESOURCES,
+        WARMUP,
+        RUNNING_TEST,
+        COMPARING
+    }
+
+    interface Callback {
+        fun onTestFinished(result: ValidationResult)
+        fun onAllTestsFinished()
+        fun onStatusChanged(status: String)
+        fun onImageResult(type: String, bitmap: Bitmap)
+    }
+
+    var callback: Callback? = null
+    var generateGoldens: Boolean = false
+
+    fun start() {
+        if (config.tests.isEmpty()) {
+            callback?.onAllTestsFinished()
+            return
+        }
+        currentTestIndex = 0
+        currentModelIndex = 0
+        startTest(config.tests[0])
+    }
+
+    private fun startTest(test: TestConfig) {
+        currentTestConfig = test
+        if (test.models.isEmpty()) {
+            nextTest()
+            return
+        }
+        currentModelIndex = 0
+        startModel(test.models.elementAt(0))
+    }
+
+    private fun startModel(modelName: String) {
+        currentModelName = modelName
+        val modelPath = config.models[modelName]
+        if (modelPath == null) {
+            Log.e("ValidationRunner", "Model $modelName not found")
+            nextModel()
+            return
+        }
+
+        currentState = State.LOADING_MODEL
+        callback?.onStatusChanged("Loading $modelName for ${currentTestConfig?.name}")
+
+        // Load model on main thread (required by ModelViewer)
+        loadModel(modelPath)
+    }
+
+    private fun loadModel(path: String) {
+        // Assume called on Main Thread
+        modelViewer.destroyModel()
+        try {
+            Log.i("ValidationRunner", "Reading model file: $path")
+            val bytes = File(path).readBytes()
+            Log.i("ValidationRunner", "Loading GLB buffer... (${bytes.size} bytes)")
+            val buffer = ByteBuffer.wrap(bytes)
+            modelViewer.loadModelGlb(buffer)
+            Log.i("ValidationRunner", "Model loaded. initializing fence.")
+            modelViewer.transformToUnitCube()
+            loadStartFence = modelViewer.engine.createFence()
+            loadStartTime = System.nanoTime()
+            currentState = State.WAITING_FOR_FENCE
+            frameCounter = 0 // Reset for fence timeout tracking
+            Log.i("ValidationRunner", "State set to WAITING_FOR_FENCE")
+        } catch (e: Exception) {
+             Log.e("ValidationRunner", "Failed to load $path", e)
+             nextModel()
+        }
+    }
+
+    fun onFrame(frameTimeNanos: Long) {
+        if (frameCounter % 60 == 0) {
+             Log.i("ValidationRunner", "onFrame: $currentState (frame: $frameCounter)")
+        }
+
+        when (currentState) {
+            State.IDLE -> {}
+            State.WAITING_FOR_FENCE -> {
+                frameCounter++
+                if (frameCounter > 600) {
+                     Log.w("ValidationRunner", "Fence timed out after 600 frames! Forcing proceed.")
+                     modelViewer.engine.destroyFence(loadStartFence!!)
+                     loadStartFence = null
+                     currentState = State.WAITING_FOR_RESOURCES
+                     return
+                }
+
+                loadStartFence?.let { fence ->
+                     if (fence.wait(com.google.android.filament.Fence.Mode.FLUSH, 0) ==
+                            com.google.android.filament.Fence.FenceStatus.CONDITION_SATISFIED) {
+                         modelViewer.engine.destroyFence(fence)
+                         loadStartFence = null
+
+                         // Compile materials (simplified)
+                         modelViewer.scene.forEach { entity ->
+                             // ... existing material compilation logic ...
+                         }
+
+                         currentState = State.WAITING_FOR_RESOURCES
+                     }
+                }
+            }
+            State.WAITING_FOR_RESOURCES -> {
+                 val progress = modelViewer.progress
+                 if (progress >= 1.0f) {
+                     Log.i("ValidationRunner", "Resources loaded. Starting warmup.")
+                     frameCounter = 0
+                     currentState = State.WARMUP
+                 }
+            }
+            State.WARMUP -> {
+                frameCounter++
+                if (frameCounter > 5) { // 5 frames warmup
+                     startAutomation()
+                }
+            }
+            State.RUNNING_TEST -> {
+                 // Log.i("ValidationRunner", "Running test...")
+                 currentEngine?.let { engine ->
+                    val content = AutomationEngine.ViewerContent()
+                    content.view = modelViewer.view
+                    content.renderer = modelViewer.renderer
+                    content.scene = modelViewer.scene
+                    content.lightManager = modelViewer.engine.lightManager
+
+                    // Tick
+                    val deltaTime = 1.0f / 60.0f
+                    engine.tick(modelViewer.engine, content, deltaTime)
+
+                    frameCounter++
+                    if (engine.shouldClose()) {
+                        Log.i("ValidationRunner", "Finishing test (frames: $frameCounter)")
+                        // Test finished (for this spec)
+                        currentState = State.COMPARING
+                        captureAndCompare()
+                    }
+                }
+            }
+            State.COMPARING -> {} // Busy
+            State.LOADING_MODEL -> {}
+        }
+    }
+
+    private fun startAutomation() {
+        val test = currentTestConfig!!
+        val specJson = JSONObject()
+        specJson.put("name", test.name)
+        specJson.put("base", test.rendering)
+        val fullSpec = "[${specJson.toString()}]"
+
+        currentEngine = AutomationEngine(fullSpec)
+        val options = AutomationEngine.Options()
+        options.sleepDuration = 0.0f // Minimal sleep, let frames drive it
+        options.minFrameCount = 5 // Ensure some frames pass
+        currentEngine?.setOptions(options)
+
+        // Use batch mode to ensure shouldClose() works reliably
+        currentEngine?.startBatchMode()
+        currentEngine?.signalBatchMode() // Start immediately
+
+        frameCounter = 0
+        currentState = State.RUNNING_TEST
+    }
+
+
+    private fun captureAndCompare() {
+        callback?.onStatusChanged("Comparing ${currentTestConfig?.name}...")
+        modelViewer.debugGetNextFrameCallback { bitmap ->
+            compareCapturedImage(bitmap)
+        }
+    }
+
+    private fun compareCapturedImage(bitmap: Bitmap) {
+         val testName = currentTestConfig!!.name
+         val modelName = currentModelName!!
+         val backend = currentTestConfig?.backends?.firstOrNull() ?: "opengl"
+         val testFullName = "${testName}.${backend}.${modelName}"
+
+         // Golden path
+         val modelFile = File(config.models.get(modelName)!!)
+         val goldenFile = modelFile.parentFile!!.parentFile!!.resolve("golden/${testFullName}.png")
+
+         Thread {
+             try {
+                val flipped = bitmap
+
+                callback?.onImageResult("Rendered", flipped)
+
+                var passed = false
+                var diffMetric = 0f
+
+                if (generateGoldens) {
+                    goldenFile.parentFile?.mkdirs()
+                    FileOutputStream(goldenFile).use { out ->
+                        flipped.compress(Bitmap.CompressFormat.PNG, 100, out)
+                    }
+                    passed = true // Generating goldens always passes if successful
+                    callback?.onStatusChanged("Golden generated")
+                } else {
+                    if (goldenFile.exists()) {
+                        val golden = android.graphics.BitmapFactory.decodeFile(goldenFile.absolutePath)
+                        if (golden != null) {
+                            callback?.onImageResult("Golden", golden)
+
+                            val tol = currentTestConfig?.tolerance ?: org.json.JSONObject()
+                            val tolJson = tol.toString()
+                            val result = ImageDiff.compare(golden, flipped, tolJson, null)
+                            passed = (result.status == ImageDiff.Result.Status.PASSED)
+                            diffMetric = result.failingPixelCount.toFloat()
+
+                             if (!passed) {
+                                if (result.diffImage != null) {
+                                    callback?.onImageResult("Diff", result.diffImage!!)
+                                    resultManager.saveImage("${testFullName}_diff", result.diffImage!!)
+                                }
+                             }
+                        } else {
+                            callback?.onStatusChanged("Failed to load golden")
+                        }
+                    } else {
+                        Log.w("ValidationRunner", "Golden not found: ${goldenFile.absolutePath}")
+                        callback?.onStatusChanged("Golden not found")
+                    }
+                }
+
+                // Save output
+                resultManager.saveImage(testFullName, flipped)
+
+                val result = ValidationResult(testFullName, passed, diffMetric)
+                resultManager.addResult(result)
+                callback?.onTestFinished(result)
+
+                android.os.Handler(android.os.Looper.getMainLooper()).post {
+                    nextModel()
+                }
+
+             } catch (e: Exception) {
+                 Log.e("ValidationRunner", "Comparison failed", e)
+                 android.os.Handler(android.os.Looper.getMainLooper()).post { nextModel() }
+             }
+         }.start()
+    }
+
+    private fun nextModel() {
+        currentModelIndex++
+        if (currentTestConfig != null && currentModelIndex < currentTestConfig!!.models.size) {
+            startModel(currentTestConfig!!.models.elementAt(currentModelIndex))
+        } else {
+            nextTest()
+        }
+    }
+
+
+    private fun nextTest() {
+        currentTestIndex++
+        if (currentTestIndex < config.tests.size) {
+            startTest(config.tests[currentTestIndex])
+        } else {
+            currentState = State.IDLE
+            resultManager.finalizeResults()
+            callback?.onAllTestsFinished()
+        }
+    }
+}

android/samples/sample-render-validation/src/main/res/layout/activity_main.xml

@@ -0,0 +1,81 @@
+<?xml version="1.0" encoding="utf-8"?>
+<androidx.constraintlayout.widget.ConstraintLayout 
+    xmlns:android="http://schemas.android.com/apk/res/android"
+    xmlns:app="http://schemas.android.com/apk/res-auto"
+    android:layout_width="match_parent"
+    android:layout_height="match_parent">
+
+    <FrameLayout
+        android:id="@+id/surface_container"
+        android:layout_width="0dp"
+        android:layout_height="0dp"
+        app:layout_constraintDimensionRatio="1:1"
+        app:layout_constraintTop_toTopOf="parent"
+        app:layout_constraintStart_toStartOf="parent"
+        app:layout_constraintEnd_toEndOf="parent">
+
+        <SurfaceView
+            android:id="@+id/surface_view"
+            android:layout_width="match_parent"
+            android:layout_height="match_parent" />
+    </FrameLayout>
+
+    <ScrollView
+        android:layout_width="0dp"
+        android:layout_height="0dp"
+        app:layout_constraintTop_toBottomOf="@id/surface_container"
+        app:layout_constraintBottom_toBottomOf="parent"
+        app:layout_constraintStart_toStartOf="parent"
+        app:layout_constraintEnd_toEndOf="parent">
+
+        <LinearLayout
+            android:layout_width="match_parent"
+            android:layout_height="wrap_content"
+            android:orientation="vertical"
+            android:padding="20dp">
+
+            <TextView
+                android:id="@+id/status_text"
+                android:layout_width="match_parent"
+                android:layout_height="wrap_content"
+                android:text="Initializing..."
+                android:textSize="14sp" />
+
+            <LinearLayout
+                android:layout_width="match_parent"
+                android:layout_height="wrap_content"
+                android:orientation="horizontal"
+                android:paddingTop="10dp"
+                android:paddingBottom="10dp">
+
+                <Spinner
+                    android:id="@+id/mode_spinner"
+                    android:layout_width="wrap_content"
+                    android:layout_height="wrap_content" />
+
+                <Button
+                    android:id="@+id/run_button"
+                    android:layout_width="wrap_content"
+                    android:layout_height="wrap_content"
+                    android:text="Run" />
+            </LinearLayout>
+
+            <TextView
+                android:layout_width="match_parent"
+                android:layout_height="wrap_content"
+                android:text="Test Results"
+                android:textSize="18sp"
+                android:paddingTop="20dp"
+                android:paddingBottom="10dp" />
+
+            <LinearLayout
+                android:id="@+id/results_container"
+                android:layout_width="match_parent"
+                android:layout_height="wrap_content"
+                android:orientation="vertical" />
+
+
+        </LinearLayout>
+    </ScrollView>
+
+</androidx.constraintlayout.widget.ConstraintLayout>

android/samples/sample-render-validation/src/main/res/layout/image_container.xml

@@ -0,0 +1,20 @@
+<?xml version="1.0" encoding="utf-8"?>
+<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
+    android:layout_width="wrap_content"
+    android:layout_height="wrap_content"
+    android:orientation="vertical"
+    android:padding="5dp">
+
+    <TextView
+        android:id="@+id/image_label"
+        android:layout_width="wrap_content"
+        android:layout_height="wrap_content"
+        android:text="Label" />
+
+    <ImageView
+        android:id="@+id/image_view"
+        android:layout_width="300px"
+        android:layout_height="300px"
+        android:scaleType="fitCenter"
+        android:background="#404040" />
+</LinearLayout>

android/samples/sample-stream-test/build.gradle

@@ -1,7 +1,7 @@
 plugins {
     id 'com.android.application'
     id 'kotlin-android'
-    id 'filament-tools-plugin'
+    id 'filament-plugin'
 }
 
 project.ext.isSample = true
@@ -10,7 +10,7 @@ kotlin {
     jvmToolchain(versions.jdk)
 }
 
-filamentTools {
+filament {
     materialInputDir = project.layout.projectDirectory.dir("src/main/materials")
     materialOutputDir = project.layout.projectDirectory.dir("src/main/assets/materials")
 }

android/samples/sample-texture-target/build.gradle

@@ -1,7 +1,7 @@
 plugins {
     id 'com.android.application'
     id 'kotlin-android'
-    id 'filament-tools-plugin'
+    id 'filament-plugin'
 }
 
 project.ext.isSample = true
@@ -10,7 +10,7 @@ kotlin {
     jvmToolchain(versions.jdk)
 }
 
-filamentTools {
+filament {
     materialInputDir = project.layout.projectDirectory.dir("src/main/materials")
     materialOutputDir = project.layout.projectDirectory.dir("src/main/assets/materials")
 }

android/samples/sample-texture-view/build.gradle

@@ -1,7 +1,7 @@
 plugins {
     id 'com.android.application'
     id 'kotlin-android'
-    id 'filament-tools-plugin'
+    id 'filament-plugin'
 }
 
 project.ext.isSample = true
@@ -10,7 +10,7 @@ kotlin {
     jvmToolchain(versions.jdk)
 }
 
-filamentTools {
+filament {
     materialInputDir = project.layout.projectDirectory.dir("src/main/materials")
     materialOutputDir = project.layout.projectDirectory.dir("src/main/assets/materials")
 }

android/samples/sample-textured-object/build.gradle

@@ -1,7 +1,7 @@
 plugins {
     id 'com.android.application'
     id 'kotlin-android'
-    id 'filament-tools-plugin'
+    id 'filament-plugin'
 }
 
 project.ext.isSample = true
@@ -10,7 +10,7 @@ kotlin {
     jvmToolchain(versions.jdk)
 }
 
-filamentTools {
+filament {
     materialInputDir = project.layout.projectDirectory.dir("src/main/materials")
     materialOutputDir = project.layout.projectDirectory.dir("src/main/assets/materials")
 

android/samples/sample-transparent-view/build.gradle

@@ -1,7 +1,7 @@
 plugins {
     id 'com.android.application'
     id 'kotlin-android'
-    id 'filament-tools-plugin'
+    id 'filament-plugin'
 }
 
 project.ext.isSample = true
@@ -10,7 +10,7 @@ kotlin {
     jvmToolchain(versions.jdk)
 }
 
-filamentTools {
+filament {
     materialInputDir = project.layout.projectDirectory.dir("src/main/materials")
     materialOutputDir = project.layout.projectDirectory.dir("src/main/assets/materials")
 }

android/settings.gradle

@@ -21,5 +21,6 @@ include ':samples:sample-texture-view'
 include ':samples:sample-texture-target'
 include ':samples:sample-textured-object'
 include ':samples:sample-transparent-view'
+include ':samples:sample-render-validation'
 
 rootProject.name = 'filament'

build/common/build-common.sh

@@ -39,6 +39,11 @@ if [[ "$TARGET" == "presubmit-with-test" ]]; then
     RUN_TESTS=-u
 fi
 
+if [[ "$TARGET" == "presubmit-with-archive" ]]; then
+    BUILD_RELEASE=release
+    GENERATE_ARCHIVES=-a
+fi
+
 if [[ "$TARGET" == "debug" ]]; then
     BUILD_DEBUG=debug
     GENERATE_ARCHIVES=-a

docs/dup/intro.html

@@ -181,22 +181,21 @@ important for <code>matc</code> (material compiler).</p>
 }
 
 dependencies {
-    implementation 'com.google.android.filament:filament-android:1.68.5'
+    implementation 'com.google.android.filament:filament-android:1.69.3'
 }
 </code></pre>
 <p>Here are all the libraries available in the group <code>com.google.android.filament</code>:</p>
 <div class="table-wrapper"><table><thead><tr><th>Artifact</th><th>Description</th></tr></thead><tbody>
-<tr><td><a href="https://maven-badges.herokuapp.com/maven-central/com.google.android.filament/filament-android"><img src="https://maven-badges.herokuapp.com/maven-central/com.google.android.filament/filament-android/badge.svg?subject=filament-android" alt="filament-android" /></a></td><td>The Filament rendering engine itself.</td></tr>
-<tr><td><a href="https://maven-badges.herokuapp.com/maven-central/com.google.android.filament/filament-android-debug"><img src="https://maven-badges.herokuapp.com/maven-central/com.google.android.filament/filament-android-debug/badge.svg?subject=filament-android-debug" alt="filament-android-debug" /></a></td><td>Debug version of <code>filament-android</code>.</td></tr>
-<tr><td><a href="https://maven-badges.herokuapp.com/maven-central/com.google.android.filament/gltfio-android"><img src="https://maven-badges.herokuapp.com/maven-central/com.google.android.filament/gltfio-android/badge.svg?subject=gltfio-android" alt="gltfio-android" /></a></td><td>A glTF 2.0 loader for Filament, depends on <code>filament-android</code>.</td></tr>
-<tr><td><a href="https://maven-badges.herokuapp.com/maven-central/com.google.android.filament/filament-utils-android"><img src="https://maven-badges.herokuapp.com/maven-central/com.google.android.filament/filament-utils-android/badge.svg?subject=filament-utils-android" alt="filament-utils-android" /></a></td><td>KTX loading, Kotlin math, and camera utilities, depends on <code>gltfio-android</code>.</td></tr>
-<tr><td><a href="https://maven-badges.herokuapp.com/maven-central/com.google.android.filament/filamat-android"><img src="https://maven-badges.herokuapp.com/maven-central/com.google.android.filament/filamat-android/badge.svg?subject=filamat-android" alt="filamat-android" /></a></td><td>A runtime material builder/compiler. This library is large but contains a full shader compiler/validator/optimizer and supports both OpenGL and Vulkan.</td></tr>
-<tr><td><a href="https://maven-badges.herokuapp.com/maven-central/com.google.android.filament/filamat-android-lite"><img src="https://maven-badges.herokuapp.com/maven-central/com.google.android.filament/filamat-android-lite/badge.svg?subject=filamat-android-lite" alt="filamat-android-lite" /></a></td><td>A much smaller alternative to <code>filamat-android</code> that can only generate OpenGL shaders. It does not provide validation or optimizations.</td></tr>
+<tr><td><a href="https://mvnrepository.com/artifact/com.google.android.filament/filament-android"><img src="https://img.shields.io/maven-central/v/com.google.android.filament/filament-android?label=filament-android&amp;color=green" alt="filament-android" /></a></td><td>The Filament rendering engine itself.</td></tr>
+<tr><td><a href="https://mvnrepository.com/artifact/com.google.android.filament/filament-android-debug"><img src="https://img.shields.io/maven-central/v/com.google.android.filament/filament-android-debug?label=filament-android-debug&amp;color=green" alt="filament-android-debug" /></a></td><td>Debug version of <code>filament-android</code>.</td></tr>
+<tr><td><a href="https://mvnrepository.com/artifact/com.google.android.filament/gltfio-android"><img src="https://img.shields.io/maven-central/v/com.google.android.filament/gltfio-android?label=gltfio-android&amp;color=green" alt="gltfio-android" /></a></td><td>A glTF 2.0 loader for Filament, depends on <code>filament-android</code>.</td></tr>
+<tr><td><a href="https://mvnrepository.com/artifact/com.google.android.filament/filament-utils-android"><img src="https://img.shields.io/maven-central/v/com.google.android.filament/filament-utils-android?label=filament-utils-android&amp;color=green" alt="filament-utils-android" /></a></td><td>KTX loading, Kotlin math, and camera utilities, depends on <code>gltfio-android</code>.</td></tr>
+<tr><td><a href="https://mvnrepository.com/artifact/com.google.android.filament/filamat-android"><img src="https://img.shields.io/maven-central/v/com.google.android.filament/filamat-android?label=filamat-android&amp;color=green" alt="filamat-android" /></a></td><td>A runtime material builder/compiler. This library is large but contains a full shader compiler/validator/optimizer and supports both OpenGL and Vulkan.</td></tr>
 </tbody></table>
 </div>
 <h3 id="ios"><a class="header" href="#ios">iOS</a></h3>
 <p>iOS projects can use CocoaPods to install the latest release:</p>
-<pre><code class="language-shell">pod 'Filament', '~&gt; 1.68.5'
+<pre><code class="language-shell">pod 'Filament', '~&gt; 1.69.3'
 </code></pre>
 <h2 id="documentation"><a class="header" href="#documentation">Documentation</a></h2>
 <ul>
@@ -230,7 +229,8 @@ sheet for the standard material model.</li>
 <li>OpenGL ES 3.0+ for Android and iOS</li>
 <li>Metal for macOS and iOS</li>
 <li>Vulkan 1.0 for Android, Linux, macOS, and Windows</li>
-<li>WebGL 2.0 for all platforms</li>
+<li>WebGPU for Android, Linux, macOS, and Windows</li>
+<li>WebGL 2.0 for all browsers supporting it</li>
 </ul>
 <h3 id="rendering"><a class="header" href="#rendering">Rendering</a></h3>
 <ul>
@@ -265,7 +265,7 @@ sheet for the standard material model.</li>
 <ul>
 <li>HDR bloom</li>
 <li>Depth of field bokeh</li>
-<li>Multiple tone mappers: generic (customizable), ACES, filmic, etc.</li>
+<li>Multiple tone mappers: PBR Neutral, AgX, generic (customizable), ACES, filmic, etc.</li>
 <li>Color and tone management: luminance scaling, gamut mapping</li>
 <li>Color grading: exposure, night adaptation, white balance, channel mixer,
 shadows/mid-tones/highlights, ASC CDL, contrast, saturation, etc.</li>
@@ -332,6 +332,8 @@ KHR_lights_punctual</li>
 <li><input disabled="" type="checkbox" checked=""/>
 KHR_materials_clearcoat</li>
 <li><input disabled="" type="checkbox" checked=""/>
+KHR_materials_dispersion</li>
+<li><input disabled="" type="checkbox" checked=""/>
 KHR_materials_emissive_strength</li>
 <li><input disabled="" type="checkbox" checked=""/>
 KHR_materials_ior</li>
@@ -340,6 +342,8 @@ KHR_materials_pbrSpecularGlossiness</li>
 <li><input disabled="" type="checkbox" checked=""/>
 KHR_materials_sheen</li>
 <li><input disabled="" type="checkbox" checked=""/>
+KHR_materials_specular</li>
+<li><input disabled="" type="checkbox" checked=""/>
 KHR_materials_transmission</li>
 <li><input disabled="" type="checkbox" checked=""/>
 KHR_materials_unlit</li>
@@ -348,8 +352,6 @@ KHR_materials_variants</li>
 <li><input disabled="" type="checkbox" checked=""/>
 KHR_materials_volume</li>
 <li><input disabled="" type="checkbox" checked=""/>
-KHR_materials_specular</li>
-<li><input disabled="" type="checkbox" checked=""/>
 KHR_mesh_quantization</li>
 <li><input disabled="" type="checkbox" checked=""/>
 KHR_texture_basisu</li>
@@ -501,7 +503,7 @@ and tools.</p>
 <li><code>filamesh</code>:               Mesh converter</li>
 <li><code>glslminifier</code>:           Minifies GLSL source code</li>
 <li><code>matc</code>:                   Material compiler</li>
-<li><code>filament-matp</code>:          Material parser</li>
+<li><code>matedit</code>:                Material editor for compiled materials</li>
 <li><code>matinfo</code>                 Displays information about materials compiled with <code>matc</code></li>
 <li><code>mipgen</code>                  Generates a series of miplevels from a source image</li>
 <li><code>normal-blending</code>:        Tool to blend normal maps</li>

docs/release/cocoapods.html

@@ -195,6 +195,30 @@ for inspection.</li>
 <p><strong>Tip:</strong> To view all defined subspecs, grep the podspec file:
 <code>grep "spec.subspec" ios/CocoaPods/Filament.podspec</code></p>
 </blockquote>
+<h2 id="testing-a-podspec-locally"><a class="header" href="#testing-a-podspec-locally">Testing a Podspec Locally</a></h2>
+<p>Before pushing a new version to the CocoaPods trunk, you should verify the podspec in a sample project.</p>
+<h3 id="using-the-sample-project"><a class="header" href="#using-the-sample-project">Using the Sample Project</a></h3>
+<p>Filament includes a dedicated sample project located in <code>ios/samples/HelloCocoaPods</code>. To test your
+local changes:</p>
+<ol>
+<li><strong>Modify the Podfile</strong>: Add a <code>:podspec</code> directive pointing to your local <code>.podspec</code> file.</li>
+</ol>
+<pre><code class="language-ruby">platform :ios, '13.0'
+
+target 'HelloCocoaPods' do
+    # Use the local development podspec
+    pod 'Filament', :podspec =&gt; '../../CocoaPods/Filament.podspec'
+end
+</code></pre>
+<ol start="2">
+<li><strong>Sync Dependencies</strong>: Run the installation command from the sample directory:</li>
+</ol>
+<pre><code class="language-bash">pod install
+</code></pre>
+<ol start="3">
+<li><strong>Verify the Build</strong>: Open the generated <code>HelloCocoaPods.xcworkspace</code> in Xcode. Build and run the
+target to ensure the headers are found and the binaries link correctly.</li>
+</ol>
 
                     </main>
 

docs/release/maven.html

@@ -199,17 +199,21 @@ Sonatype's <a href="https://central.sonatype.org/">Central Publisher Portal</a>.
 <p>The new Central Publisher Portal does not officially support Gradle. However, Sonatype provides a
 staging API compatibility service, which works with Filament's Gradle setup.</p>
 <hr />
-<h3 id="1-upload-to-the-staging-api-compatibility-service"><a class="header" href="#1-upload-to-the-staging-api-compatibility-service">1. Upload to the Staging API Compatibility Service</a></h3>
+<h3 id="1-upload-to-the-central-publisher-portal"><a class="header" href="#1-upload-to-the-central-publisher-portal">1. Upload to the Central Publisher Portal</a></h3>
+<p>To upload the artifacts, it is important to run both of these Gradle tasks together in a single
+command. This ensures the staging repository is created and closed automatically.</p>
 <pre><code class="language-bash">cd android
-./gradlew publishToSonatype
+./gradlew publishToSonatype closeSonatypeStagingRepository
 </code></pre>
-<h3 id="2-move-the-repository-to-the-central-publisher-portal"><a class="header" href="#2-move-the-repository-to-the-central-publisher-portal">2. Move the Repository to the Central Publisher Portal</a></h3>
-<p>We have a script to automate this. It reads the <code>sonatypeUsername</code> and <code>sonatypePassword</code> from your
-<code>~/.gradle/gradle.properties</code> file.</p>
+<h4 id="troubleshooting-manual-staging"><a class="header" href="#troubleshooting-manual-staging">Troubleshooting: Manual Staging</a></h4>
+<p>If you ran <code>publishToSonatype</code> by itself, the repository will remain open and won't appear in the
+portal correctly. You can fix this by running our automation script, which uses the
+<code>sonatypeUsername</code> and <code>sonatypePassword</code> from your ~/.gradle/gradle.properties file:</p>
 <pre><code class="language-bash">python3 build/common/close-sonatype-staging-repository.py
 </code></pre>
-<h3 id="3-publish-the-release-on-sonatype"><a class="header" href="#3-publish-the-release-on-sonatype">3. Publish the Release on Sonatype</a></h3>
-<p>Navigate to <a href="https://central.sonatype.com/publishing/deployments">Maven Central Repository Deployments</a>.</p>
+<h3 id="2-publish-the-release-on-sonatype"><a class="header" href="#2-publish-the-release-on-sonatype">2. Publish the Release on Sonatype</a></h3>
+<p>Once the upload is successful, you must manually trigger the final release. Navigate to <a href="https://central.sonatype.com/publishing/deployments">Maven
+Central Repository Deployments</a>.</p>
 <p>Here, you should see a new deployment with a <strong>Validated</strong> status and all your artifacts listed. Click
 the <strong>Publish</strong> button to publish the artifacts. It typically takes around 5 minutes after clicking
 <strong>Publish</strong> for the artifacts to go live.</p>

docs/wip/sky/BUILDING.md

@@ -0,0 +1,40 @@
+# Building Skybox Assets
+
+This directory contains the source code for the Simulated Skybox sample. The assets (material and textures) are pre-built in the `assets/` directory.
+
+If you need to modify the material or regenerate the moon textures, you can use the scripts provided in the `tools/` directory.
+
+## Prerequisites
+
+- **Filament**: You must have a built version of Filament. The scripts assume a standard CMake build output structure (e.g., `out/cmake-release`).
+- **Python 3**: Required for texture generation.
+- **Python Dependencies**: `numpy`, `Pillow` (automatically installed if missing, via pip).
+
+## Rebuilding the Material
+
+If you modify `simulated_skybox.mat`, you must recompile it into a `.filamat` file.
+
+```bash
+# Run from the sample root or tools directory
+./tools/build_material.sh
+```
+
+This will update `assets/simulated_skybox.filamat`.
+
+## Regenerating Moon Textures
+
+If you want to change the moon's resolution, bump scale, or blur, you can regenerate the textures.
+
+```bash
+# Run from the sample root or tools directory
+./tools/generate_moon_assets.sh [size]
+```
+
+Example:
+```bash
+./tools/generate_moon_assets.sh 512
+```
+
+This will download raw NASA data (if not present) and generate:
+- `assets/moon_disk.png`
+- `assets/moon_normal.png`

docs/wip/sky/README.md

@@ -0,0 +1,76 @@
+# Analytic Skybox Sample
+
+This sample demonstrates a **fully procedural, single-pass skybox shader** capable of simulating a dynamic day-night cycle, atmospheric scattering, volumetric clouds, and water reflections. 
+
+It is designed for graphics engineers and technical artists who need a lightweight yet physically plausible environment background without relying on static HDRI textures.
+
+## Features & Performance
+
+The shader uses a "Uber-Shader" approach where all features are computed per-pixel. Features can be toggled or tuned via uniforms to balance quality vs performance.
+
+| Feature | Cost | Control | Description |
+| :--- | :---: | :--- | :--- |
+| **Atmosphere** | 🟡 **Medium** | `turbidity`, `rayleigh`, `mie` | Analytic Rayleigh & Mie scattering. Physically based colors. |
+| **Sun Disk** | 🟢 **Low** | `sunHalo` (Radius, Limb) | Analytic sphere intersection with limb darkening. Conservation of energy (Lux). |
+| **Moon & Earthshine** | 🟢 **Low** | `sunHalo2`, `moonIntensity` | Resolved moon disk with geometric phases and dynamic Earthshine. |
+| **Stars** | 🟢 **Low** | `starControl` (Density) | High-frequency procedural noise. Occluded by clouds/moon. |
+| **Clouds** | 🔴 **High** | `cloudControl` (Coverage, Density) | 4-Octave 3D Fractal Brownian Motion (FBM). Dominates the cost when enabled. |
+| **Heat Shimmer** | 🟡 **Medium** | `shimmerControl` | UV perturbation near the horizon to simulate mirages. |
+| **Water Reflection** | 🟣 **Very High** | `waterControl` | **Renders the sky twice**. Includes procedural waves (FBM) and fresnel. |
+
+> **Note**: Rendering water (`V.y < 0`) is significantly more expensive (~2.5x) than the sky because it requires re-evaluating the atmospheric scattering and cloud noise for the reflection vector.
+
+## Shader Techniques
+
+### 1. Analytic Atmospheric Scattering
+Based on the **Hoffman & Preetham** model. It solves the single-scattering integral analytically for air molecules (Rayleigh) and aerosols (Mie).
+- **Rayleigh**: Produces the deep blue sky and red sunset colors.
+- **Mie**: Produces the white halo around the sun and general haziness.
+- **Optimization**: Uses a simplified optical depth approximation ("Air Mass") to avoid expensive ray-marching.
+
+### 2. Procedural Clouds (3D Noise)
+Clouds are rendered as a spherical shell at a specific altitude.
+- **Technique**: Ray-sphere intersection finds the entry point, then **3D FBM Noise** determines density.
+- **Lighting**: Uses a "Silver Lining" approximation (strong forward scattering) and Beers-Lambert attenuation for dark underbellies.
+- **Animation**: The noise coordinate logic helps simulate wind drift and shape evolution over time.
+
+### 3. Infinite Water Ocean
+When looking below the horizon, the shader switches to "Water Mode".
+- **Geometry**: A flat plane at $y=0$.
+- **Waves**: Generated using **Derivative-Based Noise** (or Finite Difference). This creates slope vectors that perturb the normal without needing actual geometry.
+- **Reflection**: A ray is cast from the water surface back into the sky ($R = \text{reflect}(V, N)$). The sky function is called again with $R$ to get the reflected color.
+
+### 4. Dynamic Tone Mapping
+Applies a custom tone mapping curve that varies with Sun Elevation.
+- **Noon**: Linear/Gamma (Standard).
+- **Sunset**: Higher contrast curve to compress the dynamic range and enhance the rich sunset oranges/purples.
+
+## Integration
+
+To use this in your own Filament application:
+
+1.  **Compile the Material**:
+    Use `matc` to compile `simulated_skybox.mat` into a `.filamat` file.
+    ```bash
+    matc -p mobile -a opengl -o assets/simulated_skybox.filamat simulated_skybox.mat
+    ```
+
+2.  **Load in JavaScript/C++**:
+    Create a Skybox entity and assign the material.
+
+    ```javascript
+    // JavaScript Example
+    const material = engine.createMaterial('assets/simulated_skybox.filamat');
+    const skybox = engine.createSkybox(material);
+    scene.setSkybox(skybox);
+    ```
+
+3.  **Update Uniforms**:
+    The shader requires specific uniforms (Sun Direction, Time, etc.) to be updated every frame. See `SimulatedSkybox.js` for a reference implementation of the uniform buffer management.
+
+## References
+
+*   **Hoffman & Preetham (2002)**: *"Real-time Light-Atmosphere Interactions"*
+*   **Henyey & Greenstein (1941)**: *"Diffuse radiation in the galaxy"* (Mie Phase Function)
+*   **Kasten & Young (1989)**: *"Revised optical air mass tables"*
+*   **Three.js / Sky.js**: Empirical adjustments for "Golden Hour" aesthetics.

docs/wip/sky/SimulatedSkybox.js

@@ -16,18 +16,37 @@ class SimulatedSkybox {
     this.ozone = 0.0;
     this.msFactors = [0.1, 0.5, 0.0];
     this.contrast = 1.0;
-    this.nightColor = [0.0, 0.0003, 0.00075];
+    this.nightColor = [0.0, 3.0e-9, 7.5e-9];
     this.shimmerControl = [0.0, 20.0, 0.1];
     this.cloudControl = [0.0, 0.1, 8000.0, 0.0];
     this.cloudControl2 = [0.0, 0.0, 0.0, 0.0];
     this.waterControl = [50.0, 1.0, 1.0, 4.0]; // x=Strength, y=Speed, z=DerivativeTrick, w=Octaves
-    this.starControl = [1.0, 1.0]; // x=Density (0-1), y=Enabled (0-1)
+    this.starControl = [0.001, 1.0, 350.0, 0.01]; // x=Density, y=Enabled, z=Frequency, w=PixelScale
+    this.starIntensity = 1.0;
+    this.focalLength = 24.0;
+    this.height = 1000.0;
     this.planetRadius = 6360.0;
 
     // Sun Halo
     // x=cos(rad), y=limbDarkening, z=intensity, w=enabled
+    // Sun Halo
     this.sunHalo = [Math.cos(0.5 * Math.PI / 180.0), 0.5, 1.0, 1.0];
 
+    // Moon Parameters (Mapped to Secondary Sun)
+    this.moonDirection = [-0.2, 0.8, -0.2]; // Default Moon Pos
+    this.moonIntensity = 1.0; // Scale Factor (1.0 = Physical Peak)
+    // x=cos(rad), y=sin(rad) [Precision Fix], z=intensity, w=enabled
+    this.moonHalo = [Math.cos(0.5 * Math.PI / 180.0), Math.sin(0.5 * Math.PI / 180.0), 1.0, 0.0]; // Disabled by default
+
+    this.moonTextureObj = null;
+    this.moonNormalObj = null;
+    this.milkyWayTextureObj = null;
+
+    // Milky Way Parameters
+    // x=Intensity, y=Saturation, z=Unused
+    this.milkyWayControl = [1.0, 1.2, 0.05];
+    this.milkyWayEnabled = true;
+    this.milkyWayRotation = [1, 0, 0, 0, 1, 0, 0, 0, 1]; // Identity by default
     this.initEntity();
   }
 
@@ -44,6 +63,184 @@ class SimulatedSkybox {
     rcm.setMaterialInstanceAt(instance, 0, this.materialInstance);
 
     console.log("Material loaded and bound.");
+
+    // Load Moon Texture
+    try {
+      const texUrl = 'assets/moon_disk.png';
+      const Texture = Filament.Texture;
+      const TextureSampler = Filament.TextureSampler;
+      const PixelDataFormat = Filament.PixelDataFormat;
+      const PixelDataType = Filament.PixelDataType;
+      const TextureUsage = Filament.Texture$Usage;
+      const TextureFormat = Filament.Texture$InternalFormat;
+      const MinFilter = Filament.MinFilter;
+      const MagFilter = Filament.MagFilter;
+      const WrapMode = Filament.WrapMode;
+      const texResponse = await fetch(texUrl);
+      const texBlob = await texResponse.blob();
+      const bitmap = await createImageBitmap(texBlob);
+
+      const width = bitmap.width;
+      const height = bitmap.height;
+
+      this.moonTextureObj = Texture.Builder()
+        .width(width)
+        .height(height)
+        .levels(0xff)
+        .format(TextureFormat.SRGB8_A8)
+        .usage(TextureUsage.SAMPLEABLE.value | TextureUsage.UPLOADABLE.value | TextureUsage.GEN_MIPMAPPABLE.value)
+        .build(this.engine);
+
+      // Extract Data using a Canvas
+      const canvas = document.createElement('canvas');
+      canvas.width = width;
+      canvas.height = height;
+      const ctx = canvas.getContext('2d');
+      ctx.drawImage(bitmap, 0, 0);
+      const imageData = ctx.getImageData(0, 0, width, height);
+
+      // Use RGBA data directly (Uint8ClampedArray)
+      // Filament supports RGBA upload for RGB/SRGB internal formats (drops alpha).
+      // This matches Canvas layout (Top-Down, RGBA) and is 4-byte aligned.
+      const pbd = Filament.PixelBuffer(
+        new Uint8Array(imageData.data.buffer), // Wrap buffer to ensure Uint8Array
+        PixelDataFormat.RGBA,
+        PixelDataType.UBYTE
+      );
+
+      this.moonTextureObj.setImage(this.engine, 0, pbd);
+      this.moonTextureObj.generateMipmaps(this.engine);
+
+      const sampler = new TextureSampler(
+        MinFilter.LINEAR,
+        MagFilter.LINEAR,
+        WrapMode.CLAMP_TO_EDGE
+      );
+
+      this.materialInstance.setTextureParameter('moonTexture', this.moonTextureObj, sampler);
+
+    } catch (e) {
+      console.error("Failed to load moon texture:", e);
+    }
+
+    // Load Moon Normal
+    try {
+      const texUrl = 'assets/moon_normal.png';
+      const Texture = Filament.Texture;
+      const TextureSampler = Filament.TextureSampler;
+      const PixelDataFormat = Filament.PixelDataFormat;
+      const PixelDataType = Filament.PixelDataType;
+      const TextureUsage = Filament.Texture$Usage;
+      const TextureFormat = Filament.Texture$InternalFormat;
+      const MinFilter = Filament.MinFilter;
+      const MagFilter = Filament.MagFilter;
+      const WrapMode = Filament.WrapMode;
+      const texResponse = await fetch(texUrl);
+      const texBlob = await texResponse.blob();
+      const bitmap = await createImageBitmap(texBlob);
+
+      const width = bitmap.width;
+      const height = bitmap.height;
+
+      this.moonNormalObj = Texture.Builder()
+        .width(width)
+        .height(height)
+        .levels(0xff)
+        .format(TextureFormat.RGBA8)
+        .usage(TextureUsage.SAMPLEABLE.value | TextureUsage.UPLOADABLE.value | TextureUsage.GEN_MIPMAPPABLE.value)
+        .build(this.engine);
+
+      // Extract Data using a Canvas
+      const canvas = document.createElement('canvas');
+      canvas.width = width;
+      canvas.height = height;
+      const ctx = canvas.getContext('2d');
+      ctx.drawImage(bitmap, 0, 0);
+      const imageData = ctx.getImageData(0, 0, width, height);
+
+      // Use RGBA data directly
+      const pbd = Filament.PixelBuffer(
+        new Uint8Array(imageData.data.buffer),
+        PixelDataFormat.RGBA,
+        PixelDataType.UBYTE
+      );
+
+      this.moonNormalObj.setImage(this.engine, 0, pbd);
+      this.moonNormalObj.generateMipmaps(this.engine);
+
+      const sampler = new TextureSampler(
+        MinFilter.LINEAR_MIPMAP_LINEAR,
+        MagFilter.LINEAR,
+        WrapMode.CLAMP_TO_EDGE
+      );
+
+      this.materialInstance.setTextureParameter('moonNormal', this.moonNormalObj, sampler);
+
+    } catch (e) {
+      console.error("Failed to load moon normal:", e);
+    }
+
+    // Load Milky Way Texture
+    try {
+      const texUrl = 'assets/milkyway.png';
+      const Texture = Filament.Texture;
+      const TextureSampler = Filament.TextureSampler;
+      const PixelDataFormat = Filament.PixelDataFormat;
+      const PixelDataType = Filament.PixelDataType;
+      const TextureUsage = Filament.Texture$Usage;
+      const TextureFormat = Filament.Texture$InternalFormat;
+      const MinFilter = Filament.MinFilter;
+      const MagFilter = Filament.MagFilter;
+      const WrapMode = Filament.WrapMode;
+      const texResponse = await fetch(texUrl);
+      const texBlob = await texResponse.blob();
+      const bitmap = await createImageBitmap(texBlob);
+
+      const width = bitmap.width;
+      const height = bitmap.height;
+
+      this.milkyWayTextureObj = Texture.Builder()
+        .width(width)
+        .height(height)
+        .levels(0xff)
+        .format(TextureFormat.SRGB8_A8)
+        .usage(TextureUsage.SAMPLEABLE.value | TextureUsage.UPLOADABLE.value | TextureUsage.GEN_MIPMAPPABLE.value)
+        .build(this.engine);
+
+      // Extract Data using a Canvas
+      const canvas = document.createElement('canvas');
+      canvas.width = width;
+      canvas.height = height;
+      const ctx = canvas.getContext('2d');
+      ctx.drawImage(bitmap, 0, 0);
+      try {
+        const imageData = ctx.getImageData(0, 0, width, height);
+
+        // Use RGBA data directly
+        const pbd = Filament.PixelBuffer(
+          new Uint8Array(imageData.data.buffer),
+          PixelDataFormat.RGBA,
+          PixelDataType.UBYTE
+        );
+
+        this.milkyWayTextureObj.setImage(this.engine, 0, pbd);
+        this.milkyWayTextureObj.generateMipmaps(this.engine);
+
+        const sampler = new TextureSampler(
+          MinFilter.LINEAR_MIPMAP_LINEAR,
+          MagFilter.LINEAR,
+          WrapMode.REPEAT // Equirectangular wraps horizontally
+        );
+
+        this.materialInstance.setTextureParameter('milkyWayTexture', this.milkyWayTextureObj, sampler);
+      } catch (err) {
+        console.warn("Milky Way texture data access failed (CORS?):", err);
+      }
+
+    } catch (e) {
+      console.error("Failed to load milky way texture:", e);
+    }
+
     this.updateCoefficients();
   }
 
@@ -84,16 +281,16 @@ class SimulatedSkybox {
 
     this.ib.setBuffer(this.engine, TRIANGLE_INDICES);
 
-    // We create a dummy material first or wait? 
-    // In JS we usually can't block. We'll rely on loadMaterial being called.
-    // For now, we build the Renderable without material, then set it later.
+    // Build the Renderable without material; it will be set later by loadMaterial.
+
 
     RenderableManager.Builder(1)
       .geometry(0, PrimitiveType.TRIANGLES, this.vb, this.ib)
       .culling(false)
       .castShadows(false)
       .receiveShadows(false)
-      .priority(7) // Render behind translucent objects? 7 is skybox priority typically.
+      .priority(7) // Skybox priority
+
       .build(this.engine, this.entity);
   }
 
@@ -215,11 +412,107 @@ class SimulatedSkybox {
   }
 
   setStarControl(density, enabled) {
-    this.starControl[0] = Math.max(0.0, Math.min(1.0, density));
+    // Compensate for grid frequency reduction (350 -> 100)
+    // Fewer cells = fewer stars, so we increase density threshold.
+    // Factor ~ (350/100)^2 = 12.25
+    const compensatedDensity = density * 12.0;
+    this.starControl[0] = Math.max(0.0, Math.min(1.0, compensatedDensity));
     this.starControl[1] = enabled ? 1.0 : 0.0;
     this.updateCoefficients();
   }
 
+  setFocalLength(mm) {
+    this.focalLength = Math.max(1.0, mm);
+    this.updateStarFrequency();
+  }
+
+  setResolution(height) {
+    this.height = Math.max(1.0, height);
+    this.updateStarFrequency();
+  }
+
+  updateStarFrequency() {
+    // World-Anchored Stars
+    // z = Fixed Frequency (World Space Grid)
+    // w = Pixel Scale (Screen Space Radius)
+
+    // Fixed Frequency: Defines the "Universe" coordinate system. 
+    // Reduced to 100.0 to allow larger stars without clipping (square artifacts).
+    this.starControl[2] = 100.0;
+
+    // Pixel Scale in Radians
+    // We use linear scaling (24/f) instead of atan(fov) to ensure star size remains
+    // constant in pixels across all focal lengths (Perspective Projection).
+    const fovFactor = 24.0 / this.focalLength;
+    const pixelScale = (1.0 / this.height) * fovFactor;
+
+    // Pass to shader (w component)
+    // Target radius: 1.3 pixels (Diameter 2.6 pixels)
+    // Visible but sharp.
+    this.starControl[3] = pixelScale * 1.3;
+
+    this.updateCoefficients();
+  }
+
+  setStarIntensity(intensity) {
+    this.starIntensity = Math.max(0.0, intensity);
+    this.updateCoefficients();
+  }
+
+  setMoonPosition(direction) {
+    // normalize
+    const len = Math.hypot(direction[0], direction[1], direction[2]);
+    if (len > 0) {
+      this.moonDirection = [direction[0] / len, direction[1] / len, direction[2] / len];
+    }
+    this.updateCoefficients();
+  }
+
+  setMoonIntensity(intensity) {
+    this.moonIntensity = Math.max(0.0, intensity);
+    this.updateCoefficients();
+  }
+
+  setMoonRadius(degrees) {
+    const rad = degrees * (Math.PI / 180.0);
+    this.moonHalo[0] = Math.cos(rad);
+    this.moonHalo[1] = Math.sin(rad);
+    this.updateCoefficients();
+  }
+
+  setMoonEnabled(enabled) {
+    this.moonHalo[3] = enabled ? 1.0 : 0.0;
+    this.updateCoefficients();
+  }
+
+  setMilkyWayControl(intensity, saturation, blackPoint) {
+    this.milkyWayControl[0] = Math.max(0.0, intensity);
+    this.milkyWayControl[1] = Math.max(0.0, saturation);
+    if (blackPoint !== undefined) {
+      this.milkyWayControl[2] = Math.max(0.0, blackPoint);
+    }
+    this.updateCoefficients();
+  }
+
+  setMilkyWayEnabled(enabled) {
+    this.milkyWayEnabled = !!enabled;
+    this.updateCoefficients();
+  }
+
+  setMilkyWayRotation(rotationMatrix) {
+    if (rotationMatrix && rotationMatrix.length === 9) {
+      this.milkyWayRotation = rotationMatrix;
+      this.updateCoefficients();
+    }
+  }
+
+
+
+  setExposure(exposure) {
+    this.exposure = exposure;
+    this.updateCoefficients();
+  }
+
   updateCoefficients() {
     if (!this.materialInstance) {
       console.warn("updateCoefficients called before material loaded");
@@ -297,15 +590,133 @@ class SimulatedSkybox {
 
     this.materialInstance.setFloatParameter('contrast', this.contrast);
 
-    const nightColorScaled = this.nightColor.map(v => v * this.sunIntensity);
+    const nightColorScaled = this.nightColor.map(v => v * this.sunIntensity); // Lux scaling
     this.materialInstance.setFloat3Parameter('nightColor', new Float32Array(nightColorScaled));
 
     this.materialInstance.setFloat4Parameter('shimmerControl', new Float32Array(shimmerUniform));
     this.materialInstance.setFloat4Parameter('cloudControl', new Float32Array(cloudUniform));
     this.materialInstance.setFloat4Parameter('cloudControl2', new Float32Array(this.cloudControl2));
     this.materialInstance.setFloat4Parameter('waterControl', new Float32Array(this.waterControl));
-    this.materialInstance.setFloat2Parameter('starControl', new Float32Array(this.starControl));
+    this.materialInstance.setFloat4Parameter('starControl', new Float32Array(this.starControl));
+    this.materialInstance.setFloatParameter('starIntensity', this.starIntensity);
 
     this.materialInstance.setFloatParameter('sunIntensity', physicalSunIntensity);
+
+    // Moon Upload (Secondary Sun)
+    this.materialInstance.setFloat3Parameter('sunDirection2', new Float32Array(this.moonDirection));
+
+    // Calculate Moon Phase Factor (Lambertian Sphere)
+    // We model the moon as a Lambertian sphere to calculate its integrated brightness (illuminance)
+    // based on the phase angle (angle between Sun-Moon and Observer-Moon vectors).
+    //
+    // Phase Angle (alpha):
+    // For a distant observer (Earth), the phase angle can be approximated as the angle between
+    // the vector to the Sun and the vector to the Earth (from the Moon).
+    // cos(alpha) = -dot(L_moon, L_sun)
+    //
+    // Lambertian Phase Law:
+    // The integrated flux of a lit sphere varies as:
+    // Phi(alpha) = (1/PI) * (sin(alpha) + (PI - alpha) * cos(alpha))
+    // This gives 1.0 at Full Moon (alpha=0) and 0.0 at New Moon (alpha=PI).
+
+    const dotSM = this.sunDirection[0] * this.moonDirection[0] +
+      this.sunDirection[1] * this.moonDirection[1] +
+      this.sunDirection[2] * this.moonDirection[2];
+
+    // Final Intensity = Peak * Scale (No Phase Factor - Phase is handled in Shader via N.L)
+    const MOON_PEAK_LUX = 1.0;
+    const finalMoonIntensity = MOON_PEAK_LUX * this.moonIntensity;
+
+    this.materialInstance.setFloatParameter('sunIntensity2', finalMoonIntensity);
+
+    // Scale Milky Way by Sun Intensity
+    // Calibration: 1.0 User Intensity = 1.5e-3 cd/m^2 (Nits) approx.
+    // Target: 1.5e-3 Nits. SunIntensity = 100,000.
+    // Scale = 1.5e-3 / 1.0e5 = 1.5e-8.
+    const mwIntensity = this.milkyWayEnabled ? this.milkyWayControl[0] : 0.0;
+    const mwUniform = [
+      mwIntensity * this.sunIntensity * 1.5e-8,
+      this.milkyWayControl[1],
+      this.milkyWayControl[2]
+    ];
+    this.materialInstance.setFloat3Parameter('milkyWayControl', new Float32Array(mwUniform));
+    this.materialInstance.setMat3Parameter('milkyWayRotation', new Float32Array(this.milkyWayRotation));
+
+    // Moon Halo Upload (Disk Visualization)
+    // Multiplier = 1.0 / SolidAngle
+    const moonSolidAngle = 2.0 * F_PI * (1.0 - this.moonHalo[0]);
+    const moonRadConv = 1.0 / Math.max(1e-9, moonSolidAngle);
+    const moonHaloUpload = [...this.moonHalo];
+    moonHaloUpload[2] *= moonRadConv;
+    this.materialInstance.setFloat4Parameter('sunHalo2', new Float32Array(moonHaloUpload));
+    this.materialInstance.setFloatParameter('exposure', this.exposure !== undefined ? this.exposure : 1.0);
+
+    // Solar Eclipse (CPU Calculation)
+    const sunRadius = Math.acos(this.sunHalo[0]);
+    const moonRadius = Math.acos(this.moonHalo[0]);
+    // Dot product of Sun and Moon directions
+    const dot = this.sunDirection[0] * this.moonDirection[0] +
+      this.sunDirection[1] * this.moonDirection[1] +
+      this.sunDirection[2] * this.moonDirection[2];
+    const separation = Math.acos(Math.max(-1.0, Math.min(1.0, dot)));
+
+    let eclipseFactor = 1.0;
+    // Only calculate if moon is enabled
+    if (this.moonHalo[3] > 0.5) {
+      const overlap = this.areaIntersection(sunRadius, moonRadius, separation);
+      const sunArea = Math.PI * sunRadius * sunRadius;
+      // Ensure we don't divide by zero and clamp result
+      const ratio = overlap / Math.max(1e-9, sunArea);
+      eclipseFactor = 1.0 - Math.max(0.0, Math.min(1.0, ratio));
+
+    }
+
+    // Safety check for NaN
+    if (isNaN(eclipseFactor)) {
+      console.warn("SimulatedSkybox: eclipseFactor is NaN, resetting to 1.0");
+      eclipseFactor = 1.0;
+    }
+
+
+
+    this.materialInstance.setFloatParameter('eclipseFactor', eclipseFactor);
+  }
+
+  areaIntersection(r1, r2, d) {
+    // Circle intersection area
+    // r1, r2: radii
+    // d: distance between centers
+
+    // Case 1: Too far apart
+    if (d >= r1 + r2) {
+      return 0.0;
+    }
+    // Case 2: One inside another
+    if (d <= Math.abs(r1 - r2)) {
+      return Math.PI * Math.min(r1, r2) * Math.min(r1, r2);
+    }
+
+    const r1sq = r1 * r1;
+    const r2sq = r2 * r2;
+
+    // Law of Cosines for sector angles
+    // c1 = (d^2 + r1^2 - r2^2) / (2 * d * r1)
+    // c2 = (d^2 + r2^2 - r1^2) / (2 * d * r2)
+    // We clamp to [-1, 1] to avoid NaN from floating point errors
+    const c1 = Math.max(-1.0, Math.min(1.0, (d * d + r1sq - r2sq) / (2.0 * d * r1)));
+    const c2 = Math.max(-1.0, Math.min(1.0, (d * d + r2sq - r1sq) / (2.0 * d * r2)));
+
+    const part1 = r1sq * Math.acos(c1);
+    const part2 = r2sq * Math.acos(c2);
+
+    // Heron's formula for the triangle area * 2
+    // The sqrt term represents the area of the two triangles formed by the chord and centers.
+
+
+    // Robust sqrt
+    const val = (-d + r1 + r2) * (d + r1 - r2) * (d - r1 + r2) * (d + r1 + r2);
+    const part3 = 0.5 * Math.sqrt(Math.max(0.0, val));
+
+    return part1 + part2 - part3;
   }
 }

docs/wip/sky/assets/suncalc_global.js

@@ -0,0 +1,332 @@
+/*
+ (c) 2011-2015, Vladimir Agafonkin
+ SunCalc is a JavaScript library for calculating sun/moon position and light phases.
+ https://github.com/mourner/suncalc
+*/
+
+(function () { 'use strict';
+
+// shortcuts for easier to read formulas
+
+var PI   = Math.PI,
+    sin  = Math.sin,
+    cos  = Math.cos,
+    tan  = Math.tan,
+    asin = Math.asin,
+    atan = Math.atan2,
+    acos = Math.acos,
+    rad  = PI / 180;
+
+// sun calculations are based on https://aa.quae.nl/en/reken/zonpositie.html formulas
+
+
+// date/time constants and conversions
+
+var dayMs = 1000 * 60 * 60 * 24,
+    J1970 = 2440588,
+    J2000 = 2451545;
+
+function toJulian(date) { return date.valueOf() / dayMs - 0.5 + J1970; }
+function fromJulian(j)  { return new Date((j + 0.5 - J1970) * dayMs); }
+function toDays(date)   { return toJulian(date) - J2000; }
+
+
+// general calculations for position
+
+var e = rad * 23.4397; // obliquity of the Earth
+
+function rightAscension(l, b) { return atan(sin(l) * cos(e) - tan(b) * sin(e), cos(l)); }
+function declination(l, b)    { return asin(sin(b) * cos(e) + cos(b) * sin(e) * sin(l)); }
+
+function azimuth(H, phi, dec)  { return atan(sin(H), cos(H) * sin(phi) - tan(dec) * cos(phi)); }
+function altitude(H, phi, dec) { return asin(sin(phi) * sin(dec) + cos(phi) * cos(dec) * cos(H)); }
+
+function siderealTime(d, lw) { return rad * (280.16 + 360.9856235 * d) - lw; }
+
+function astroRefraction(h) {
+    if (h < 0) // the following formula works for positive altitudes only.
+        h = 0; // if h = -0.08901179 a div/0 would occur.
+
+    // formula 16.4 of "Astronomical Algorithms" 2nd edition by Jean Meeus (Willmann-Bell, Richmond) 1998.
+    // 1.02 / tan(h + 10.26 / (h + 5.10)) h in degrees, result in arc minutes -> converted to rad:
+    return 0.0002967 / Math.tan(h + 0.00312536 / (h + 0.08901179));
+}
+
+// general sun calculations
+
+function solarMeanAnomaly(d) { return rad * (357.5291 + 0.98560028 * d); }
+
+function eclipticLongitude(M) {
+
+    var C = rad * (1.9148 * sin(M) + 0.02 * sin(2 * M) + 0.0003 * sin(3 * M)), // equation of center
+        P = rad * 102.9372; // perihelion of the Earth
+
+    return M + C + P + PI;
+}
+
+function sunCoords(d) {
+
+    var M = solarMeanAnomaly(d),
+        L = eclipticLongitude(M);
+
+    return {
+        dec: declination(L, 0),
+        ra: rightAscension(L, 0)
+    };
+}
+
+
+var SunCalc = {};
+
+
+// calculates sun position for a given date and latitude/longitude
+
+SunCalc.getPosition = function (date, lat, lng) {
+
+    var lw  = rad * -lng,
+        phi = rad * lat,
+        d   = toDays(date),
+
+        c  = sunCoords(d),
+        H  = siderealTime(d, lw) - c.ra;
+
+    return {
+        azimuth: azimuth(H, phi, c.dec),
+        altitude: altitude(H, phi, c.dec)
+    };
+};
+
+
+// sun times configuration (angle, morning name, evening name)
+
+var times = SunCalc.times = [
+    [-0.833, 'sunrise',       'sunset'      ],
+    [-0.3,   'sunriseEnd',    'sunsetStart' ],
+    [-6,     'dawn',          'dusk'        ],
+    [-12,    'nauticalDawn',  'nauticalDusk'],
+    [-18,    'nightEnd',      'night'       ],
+    [6,      'goldenHourEnd', 'goldenHour'  ]
+];
+
+// adds a custom time to the times config
+
+SunCalc.addTime = function (angle, riseName, setName) {
+    times.push([angle, riseName, setName]);
+};
+
+
+// calculations for sun times
+
+var J0 = 0.0009;
+
+function julianCycle(d, lw) { return Math.round(d - J0 - lw / (2 * PI)); }
+
+function approxTransit(Ht, lw, n) { return J0 + (Ht + lw) / (2 * PI) + n; }
+function solarTransitJ(ds, M, L)  { return J2000 + ds + 0.0053 * sin(M) - 0.0069 * sin(2 * L); }
+
+function hourAngle(h, phi, d) { return acos((sin(h) - sin(phi) * sin(d)) / (cos(phi) * cos(d))); }
+
+// returns set time for the given sun altitude
+function getSetJ(h, lw, phi, dec, n, M, L) {
+
+    var w = hourAngle(h, phi, dec),
+        a = approxTransit(w, lw, n);
+    return solarTransitJ(a, M, L);
+}
+
+
+// calculates sun times for a given date, latitude/longitude, and, optionally,
+// the observer height (in meters) relative to the horizon
+
+SunCalc.getTimes = function (date, lat, lng, height) {
+
+    height = height || 0;
+
+    var lw = rad * -lng,
+        phi = rad * lat,
+
+        dh = observerAngle(height),
+
+        d = toDays(date),
+        n = julianCycle(d, lw),
+        ds = approxTransit(0, lw, n),
+
+        M = solarMeanAnomaly(ds),
+        L = eclipticLongitude(M),
+        dec = declination(L, 0),
+
+        Jnoon = solarTransitJ(ds, M, L);
+
+    var result = {
+        solarNoon: fromJulian(Jnoon),
+        nadir: fromJulian(Jnoon - 0.5)
+    };
+
+    var i, len, time, h0, Jset, Jrise;
+
+    for (i = 0, len = times.length; i < len; i += 1) {
+        time = times[i];
+
+        h0 = (time[0] + dh) * rad;
+
+        Jset = getSetJ(h0, lw, phi, dec, n, M, L);
+        Jrise = Jnoon - (Jset - Jnoon);
+
+        result[time[1]] = fromJulian(Jrise);
+        result[time[2]] = fromJulian(Jset);
+    }
+
+    return result;
+};
+
+// moon calculations, based on http://aa.quae.nl/en/reken/hemelpositie.html formulas
+
+function moonCoords(d) { // geocentric ecliptic coordinates of the moon
+
+    var L = rad * (218.316 + 13.176396 * d), // ecliptic longitude
+        M = rad * (134.963 + 13.064993 * d), // mean anomaly
+        F = rad * (93.272 + 13.229350 * d),  // mean distance
+
+        l  = L + rad * 6.289 * sin(M), // longitude
+        b  = rad * 5.128 * sin(F),     // latitude
+        dt = 385001 - 20905 * cos(M);  // distance to the moon in km
+
+    return {
+        ra: rightAscension(l, b),
+        dec: declination(l, b),
+        dist: dt
+    };
+}
+
+SunCalc.getMoonPosition = function (date, lat, lng) {
+
+    var lw = rad * -lng,
+        phi = rad * lat,
+        d = toDays(date),
+
+        c = moonCoords(d),
+        H = siderealTime(d, lw) - c.ra,
+        h = altitude(H, phi, c.dec),
+        // formula 14.1 of "Astronomical Algorithms" 2nd edition by Jean Meeus (Willmann-Bell, Richmond) 1998.
+        pa = atan(sin(H), tan(phi) * cos(c.dec) - sin(c.dec) * cos(H));
+
+    return {
+        azimuth: azimuth(H, phi, c.dec),
+        altitude: h + astroRefraction(h), // altitude correction for refraction,
+        distance: c.dist,
+        parallacticAngle: pa
+    };
+};
+
+
+// calculations for illumination parameters of the moon,
+// based on http://idlastro.gsfc.nasa.gov/ftp/pro/astro/mphase.pro formulas and
+// Chapter 48 of "Astronomical Algorithms" 2nd edition by Jean Meeus (Willmann-Bell, Richmond) 1998.
+
+SunCalc.getMoonIllumination = function (date) {
+
+    var d = toDays(date || new Date()),
+        s = sunCoords(d),
+        m = moonCoords(d),
+
+        sdist = 149598000, // distance from Earth to Sun in km
+
+        phi = acos(sin(s.dec) * sin(m.dec) + cos(s.dec) * cos(m.dec) * cos(s.ra - m.ra)),
+        inc = atan(sdist * sin(phi), m.dist - sdist * cos(phi)),
+        angle = atan(cos(s.dec) * sin(s.ra - m.ra), sin(s.dec) * cos(m.dec) -
+                cos(s.dec) * sin(m.dec) * cos(s.ra - m.ra));
+
+    return {
+        fraction: (1 + cos(inc)) / 2,
+        phase: 0.5 + 0.5 * inc * (angle < 0 ? -1 : 1) / Math.PI,
+        angle: angle
+    };
+};
+
+
+function hoursLater(date, h) {
+    return new Date(date.valueOf() + h * dayMs / 24);
+}
+
+// calculations for moon rise/set times are based on http://www.stargazing.net/kepler/moonrise.html article
+
+SunCalc.getMoonTimes = function (date, lat, lng, inUTC) {
+    var t = new Date(date);
+    if (inUTC) t.setUTCHours(0, 0, 0, 0);
+    else t.setHours(0, 0, 0, 0);
+
+    var hc = 0.133 * rad,
+        h0 = SunCalc.getMoonPosition(t, lat, lng).altitude - hc,
+        h1, h2, rise, set, a, b, xe, ye, d, roots, x1, x2, dx;
+
+    // go in 2-hour chunks, each time seeing if a 3-point quadratic curve crosses zero (which means rise or set)
+    for (var i = 1; i <= 24; i += 2) {
+        h1 = SunCalc.getMoonPosition(hoursLater(t, i), lat, lng).altitude - hc;
+        h2 = SunCalc.getMoonPosition(hoursLater(t, i + 1), lat, lng).altitude - hc;
+
+        a = (h0 + h2) / 2 - h1;
+        b = (h2 - h0) / 2;
+        xe = -b / (2 * a);
+        ye = (a * xe + b) * xe + h1;
+        d = b * b - 4 * a * h1;
+        roots = 0;
+
+        if (d >= 0) {
+            dx = Math.sqrt(d) / (Math.abs(a) * 2);
+            x1 = xe - dx;
+            x2 = xe + dx;
+            if (Math.abs(x1) <= 1) roots++;
+            if (Math.abs(x2) <= 1) roots++;
+            if (x1 < -1) x1 = x2;
+        }
+
+        if (roots === 1) {
+            if (h0 < 0) rise = i + x1;
+            else set = i + x1;
+
+        } else if (roots === 2) {
+            rise = i + (ye < 0 ? x2 : x1);
+            set = i + (ye < 0 ? x1 : x2);
+        }
+
+        if (rise && set) break;
+
+        h0 = h2;
+    }
+
+    var result = {};
+
+    if (rise) result.rise = hoursLater(t, rise);
+    if (set) result.set = hoursLater(t, set);
+
+    if (!rise && !set) result[ye > 0 ? 'alwaysUp' : 'alwaysDown'] = true;
+
+    return result;
+};
+
+// observerAngle helper was missing in my copy-paste?
+// Ah, it was in the chunks. Let me check the chunks again.
+// Function `observerAngle` was in chunk 0.
+// `function observerAngle(height) { return -2.076 * Math.sqrt(height) / 60; }`
+// I included it.
+
+// Note: I replaced var with const/let or kept var?
+// The original used const/let but I used var in my head above?
+// I will just use the original code but adapted.
+// Actually, to be safe, I'll use the code I wrote in this block which is adapted to use 'var' (ES5 safe) or just ES6 is fine.
+// The user Environment is modern (Chrome/ES6 likely).
+// But for safety:
+// I'll stick to 'var' definitions I wrote above which seem complete?
+// Wait, I might have missed `observerAngle` definition in my manual reconstruction above?
+// No, `observerAngle` is called in `getTimes`.
+// I MUST define it.
+// I added it in the loop above? No.
+// Let me double check the `write_to_file` content I prepared.
+// I see:
+// `function observerAngle(height) { return -2.076 * Math.sqrt(height) / 60; }`
+// Yes, it is there.
+
+// export
+window.SunCalc = SunCalc;
+
+}());

docs/wip/sky/index.html

@@ -24,6 +24,7 @@
 
 <body>
   <canvas></canvas>
+
   <!-- Filament -->
   <script src="filament.js"></script>
   <script src="gl-matrix-min.js"></script>
@@ -31,9 +32,13 @@
   <!-- UI -->
   <script src="lil-gui.js"></script>
 
+  <!-- Utils -->
+  <script src="assets/suncalc_global.js"></script>
+
   <!-- App -->
-  <script src="SimulatedSkybox.js?v=26"></script>
-  <script src="main.js?v=26"></script>
+
+  <script src="SimulatedSkybox.js?v=9999"></script>
+  <script src="main.js?v=9999"></script>
 </body>
 
 </html>

docs/wip/sky/main.js

@@ -1,10 +1,123 @@
 
 // main.js
 
-Filament.init(['assets/simulated_skybox.filamat'], () => {
+Filament.init(['assets/simulated_skybox.filamat?v=' + Date.now()], () => {
   window.app = new App(document.getElementsByTagName('canvas')[0]);
 });
 
+// Helper: Julian Date
+function getJD(date) {
+  return date.getTime() / 86400000.0 + 2440587.5;
+}
+
+// Helper: GMST from Date
+function getGMST(date) {
+  const JD = getJD(date);
+  const D = JD - 2451545.0;
+  // GMST = 18.697... + 24.0657... * D
+  let gmst = 18.697374558 + 24.06570982441908 * D;
+  gmst = gmst % 24.0;
+  if (gmst < 0) gmst += 24.0;
+  return gmst;
+}
+
+// Helper: Matrix Rotation
+function rotateX(m, angle) {
+  const c = Math.cos(angle);
+  const s = Math.sin(angle);
+  const m1 = m[1], m2 = m[2];
+  const m4 = m[4], m5 = m[5];
+  const m7 = m[7], m8 = m[8];
+  m[1] = m1 * c - m2 * s;
+  m[2] = m1 * s + m2 * c;
+  m[4] = m4 * c - m5 * s;
+  m[5] = m4 * s + m5 * c;
+  m[7] = m7 * c - m8 * s;
+  m[8] = m7 * s + m8 * c;
+}
+function rotateY(m, angle) {
+  const c = Math.cos(angle);
+  const s = Math.sin(angle);
+  const m0 = m[0], m2 = m[2];
+  const m3 = m[3], m5 = m[5];
+  const m6 = m[6], m8 = m[8];
+  m[0] = m0 * c + m2 * s;
+  m[2] = -m0 * s + m2 * c;
+  m[3] = m3 * c + m5 * s;
+  m[5] = -m3 * s + m5 * c;
+  m[6] = m6 * c + m8 * s;
+  m[8] = -m6 * s + m8 * c;
+}
+function rotateZ(m, angle) {
+  const c = Math.cos(angle);
+  const s = Math.sin(angle);
+  const m0 = m[0], m1 = m[1];
+  const m3 = m[3], m4 = m[4];
+  const m6 = m[6], m7 = m[7];
+  m[0] = m0 * c - m1 * s;
+  m[1] = m0 * s + m1 * c;
+  m[3] = m3 * c - m4 * s;
+  m[4] = m3 * s + m4 * c;
+  m[6] = m6 * c - m7 * s;
+  m[7] = m6 * s + m7 * c;
+}
+
+// Galactic to Equatorial (J2000)
+// This matrix converts Galactic vectors to Equatorial vectors.
+// Or effectively, if we want to render Galactic texture from Equatorial View vector V_eq:
+// V_gal = Inv(Rot_Gal_to_Eq) * V_eq = Rot_Eq_to_Gal * V_eq.
+// The shader does: V_gal = Rotation * V_world.
+// So Rotation = Rot_Eq_to_Gal * Rot_World_to_Eq.
+//
+// Galactic North Pole (J2000): RA = 192.85948, Dec = 27.12825
+// Ascending Node: RA = 282.85
+// 
+// Pre-computed Rotation Matrix (Equatorial -> Galactic)
+// Based on standard transformation matrices.
+// 
+// R_eq_gal = 
+// [ -0.054876  -0.873437  -0.483835 ]
+// [  0.494109  -0.444830   0.746982 ]
+// [ -0.867666  -0.198076   0.455984 ]
+//
+// Let's use this static definition.
+const MAT_EQ_TO_GAL = [
+  -0.054876, 0.494109, -0.867666,
+  -0.873437, -0.444830, -0.198076,
+  -0.483835, 0.746982, 0.455984
+];
+
+// Matrix multiplication 3x3
+function multiplyMat3(a, b) {
+  const out = new Float32Array(9);
+  // Row-major or Column-major? Filament is Column-major usually.
+  // GLSL is Column-major.
+  // Mat3 in array: [col0.x, col0.y, col0.z, col1.x, ...]
+  // So a[0] is (0,0), a[1] is (1,0), a[3] is (0,1).
+  //
+  // out = a * b
+  const a00 = a[0], a10 = a[1], a20 = a[2];
+  const a01 = a[3], a11 = a[4], a21 = a[5];
+  const a02 = a[6], a12 = a[7], a22 = a[8];
+
+  const b00 = b[0], b10 = b[1], b20 = b[2];
+  const b01 = b[3], b11 = b[4], b21 = b[5];
+  const b02 = b[6], b12 = b[7], b22 = b[8];
+
+  out[0] = a00 * b00 + a01 * b10 + a02 * b20;
+  out[1] = a10 * b00 + a11 * b10 + a12 * b20;
+  out[2] = a20 * b00 + a21 * b10 + a22 * b20;
+
+  out[3] = a00 * b01 + a01 * b11 + a02 * b21;
+  out[4] = a10 * b01 + a11 * b11 + a12 * b21;
+  out[5] = a20 * b01 + a21 * b11 + a22 * b21;
+
+  out[6] = a00 * b02 + a01 * b12 + a02 * b22;
+  out[7] = a10 * b02 + a11 * b12 + a12 * b22;
+  out[8] = a20 * b02 + a21 * b12 + a22 * b22;
+  return out;
+}
+
 class App {
   constructor(canvas) {
     this.canvas = canvas;
@@ -15,13 +128,10 @@ class App {
     this.skybox.entity = this.skybox.entity; // Ensuring access if needed
     this.scene.addEntity(this.skybox.entity);
 
-    // Load the material explicitly since we passed it to init but SimulatedSkybox needs to bind it
-    // Actually SimulatedSkybox.loadMaterial fetches it. 
-    // Since we already loaded it in Filament.init, we can arguably just use it if we had a way to access the asset.
-    // But Filament.init assets are for internal or easy access via assets object if configured?
-    // Let's just let SimulatedSkybox fetch it again or use a blob if we wanted.
-    // Simpler: Just let SimulatedSkybox fetch it.
-    this.skybox.loadMaterial('assets/simulated_skybox.filamat').then(() => {
+    // Load the material explicitly. SimulatedSkybox.loadMaterial fetches it.
+
+    const matUrl = 'assets/simulated_skybox.filamat?v=' + Date.now();
+    this.skybox.loadMaterial(matUrl).then(() => {
       this.initGUI();
     });
 
@@ -71,6 +181,15 @@ class App {
 
     this.initControls(); // Initialize controls immediately
 
+    this.mwParams = {
+      enabled: true,
+      intensity: 1.0,
+      saturation: 1.0,
+      blackPoint: 0.07,
+      siderealTime: 0.0, // Hours [0-24]
+      latitude: 34.0, // Default Lat
+    };
+
     this.resize();
     window.addEventListener('resize', this.resize.bind(this));
 
@@ -99,6 +218,13 @@ class App {
     const exposure = this.getExposure();
     const preExposedIntensity = this.params.sunIntensity * exposure;
     this.skybox.setSunIntensity(preExposedIntensity);
+    this.skybox.setExposure(exposure); // Update Skybox Exposure Uniform
+
+    // Moon Exposure
+    if (this.mParams) {
+      const preExposedMoon = this.mParams.intensity * exposure;
+      this.skybox.setMoonIntensity(preExposedMoon);
+    }
   }
 
   updateCameraProjection() {
@@ -106,6 +232,7 @@ class App {
     const height = this.canvas.height;
     const aspect = width / height;
     this.camera.setLensProjection(this.params.focalLength, aspect, 0.1, 5000.0);
+    if (this.skybox) this.skybox.setFocalLength(this.params.focalLength);
   }
 
   initGUI() {
@@ -114,10 +241,7 @@ class App {
     const sky = this.skybox;
 
     // Initialize local params from skybox defaults
-    // Initialize local params from skybox defaults
-    // REMOVED: Do not overwrite this.params from sky.sunDirection (Zenith)
-    // const currentDir = sky.sunDirection;
-    // this.params.sunTheta = ...
+
 
     const updateSun = () => {
       const theta = this.params.sunTheta;
@@ -128,29 +252,165 @@ class App {
       sky.setSunPosition([x, y, z]);
     };
 
+    // Sun UI Proxy
+    this.sunUI = {
+      azimuth: (this.params.sunPhi * 180.0 / Math.PI) % 360.0,
+      height: Math.cos(this.params.sunTheta)
+    };
+    if (this.sunUI.azimuth < 0) this.sunUI.azimuth += 360.0;
+
     const sunFolder = gui.addFolder('Sun');
-    // Helper for "Sun Height" cosine slider like C++
-    const sunHeightParam = { height: Math.cos(this.params.sunTheta) };
-    sunFolder.add(sunHeightParam, 'height', -0.2, 1.0).name('Height (Cos)').onChange(v => {
+
+    sunFolder.add(this.sunUI, 'azimuth', 0.0, 360.0, 0.1).name('Azimuth').listen().onChange(v => {
+      this.params.sunPhi = v * (Math.PI / 180.0);
+      updateSun();
+    });
+
+    sunFolder.add(this.sunUI, 'height', -0.2, 1.0).name('Height (Cos)').listen().onChange(v => {
       this.params.sunTheta = Math.acos(v);
       updateSun();
     });
-    sunFolder.add(this.params, 'sunPhi', 0.0, Math.PI * 2).name('Azimuth').onChange(updateSun);
-    // Updated: Controls params.sunIntensity and triggers updateSunIntensity
-    sunFolder.add(this.params, 'sunIntensity', 0.0, 500000.0).onChange(v => this.updateSunIntensity());
 
-    const sunDisk = sunFolder.addFolder('Disk');
-    // We need local proxy for sunRadius due to conversion
-    const diskParams = {
+    sunFolder.add(this.params, 'sunIntensity', 0.0, 500000.0).name('Intensity').onChange(v => this.updateSunIntensity());
+
+
+
+
+    const moonFolder = gui.addFolder('Moon');
+    this.mParams = {
+      enabled: true,
+      azimuth: 180.0,
+      height: Math.cos(45.0 * Math.PI / 180.0), // Default 45 degrees elevation -> cos(45) ~ 0.707
       radius: 1.2,
-      enabled: true // Enable sun disk
+      intensity: 6.0
+    };
+
+    const updateMoon = () => {
+      const az = this.mParams.azimuth * (Math.PI / 180.0);
+      const theta = Math.acos(this.mParams.height);
+      const phi = az;
+
+      const x = Math.sin(theta) * Math.cos(phi);
+      const y = Math.cos(theta);
+      const z = Math.sin(theta) * Math.sin(phi);
+
+      sky.setMoonPosition([x, y, z]);
+    };
+
+    // Initial Moon Sync
+    updateMoon();
+    sky.setMoonEnabled(this.mParams.enabled);
+    sky.setMoonRadius(this.mParams.radius);
+    sky.setMoonIntensity(this.mParams.intensity);
+
+    moonFolder.add(this.mParams, 'enabled').name('Enabled').onChange(v => sky.setMoonEnabled(v));
+    moonFolder.add(this.mParams, 'azimuth', 0.0, 360.0, 0.1).name('Azimuth').listen().onChange(updateMoon);
+    moonFolder.add(this.mParams, 'height', -0.2, 1.0).name('Height (Cos)').listen().onChange(updateMoon);
+    moonFolder.add(this.mParams, 'intensity', 0.0, 1000.0).name('Intensity').onChange(v => this.updateSunIntensity());
+    moonFolder.add(this.mParams, 'radius', 0.1, 5.0).name('Radius').onChange(v => sky.setMoonRadius(v));
+    moonFolder.close();
+
+    const mwFolder = gui.addFolder('Milky Way');
+
+    const updateMW = () => {
+      sky.setMilkyWayEnabled(this.mwParams.enabled);
+      sky.setMilkyWayControl(this.mwParams.intensity, this.mwParams.saturation, this.mwParams.blackPoint);
+
+      // Calculate Rotation
+      // V_gal = Rot_Eq_to_Gal * Rot_World_to_Eq * V_world
+
+      // World: Y=Up, X=East, Z=South (Filament Camera Convention is different!)
+      // In Filament Camera: -Z is Forward.
+      // Skybox V direction is World Space direction.
+      // Let's assume standard Horizontal Coordinates:
+      // Y = Zenith.
+      // Z = North? Or South?
+      // Usually Z is South in RH Y-up.
+
+      // LST (Local Sidereal Time) converts Hour Angle to RA.
+      // LST in Radians.
+      const LST = this.mwParams.siderealTime * (Math.PI / 12.0); // Hours to Rad
+      const Lat = this.mwParams.latitude * (Math.PI / 180.0);
+
+      // Rotation World (Horizontal) -> Equatorial
+      // 1. Rotate around X by -(90 - Lat) to align Equatorial Plane.
+      // 2. Rotate around Y (Polar Axis) by -LST.
+
+      // Mat3 Identity
+      const rot = [1, 0, 0, 0, 1, 0, 0, 0, 1];
+
+      // Rotate Z by LST (Earth Rotation).
+      // Actually, transformation from Horizontal (Az, Alt) to Equatorial (HA, Dec):
+      // sin(Dec) = sin(Alt)sin(Lat) - cos(Alt)cos(Lat)cos(Az)
+      // ...
+      // Let's construct matrix directly.
+      // WorldToEq:
+      // Rotate X by (Lat - 90 deg) -> brings Pole to Zenith.
+      // Rotate Y by -LST (or Z?)
+
+      // Filament Space:
+      // +Y = Up
+      // Let's match typical skybox conventions.
+
+      // Rot_World_to_Eq = Rot_Z_LST * Rot_X_Lat
+      // But we need to use Filament matrix ops which are column major.
+
+      // Let's use simple rotations:
+      // 1. Tilt Pole: Rotate X by (Lat - 90).
+      // 2. Spin Earth: Rotate Y by LST.
+
+      // Let's iterate until it looks right visually or trust the math.
+      // Rot_World_To_Equatorial:
+      // R_z(-LST) * R_x(Lat - 90)?
+
+      // Let's build it from scratch in JS using helper.
+      // Start Identity.
+      // Rotate X (Latitude Tilt).
+      // Rotate Y (Sidereal Spin).
+      // Note: rotate functions modify in place.
+
+      const mWorldToEq = [1, 0, 0, 0, 1, 0, 0, 0, 1];
+
+      // 1. Tilt for Latitude (Align Celestial Pole)
+      // At Lat 90 (North Pole), Zenith is Pole. No tilt needed if Y is Pole?
+      // No, Y is Zenith. Pole is Y.
+      // At Lat 0 (Equator), Pole is at Horizon (Z?).
+      // So we rotate X by (Lat - 90).
+      rotateX(mWorldToEq, Lat - Math.PI / 2);
+
+      // 2. Spin for Time (LST)
+      // Rotate around new Pole (Y) by LST.
+      rotateY(mWorldToEq, LST);
+
+      // Combine with Gal Transform
+      // Rot = MAT_EQ_TO_GAL * mWorldToEq
+      const finalRot = multiplyMat3(MAT_EQ_TO_GAL, mWorldToEq);
+
+      sky.setMilkyWayRotation(finalRot);
+    };
+
+    mwFolder.add(this.mwParams, 'enabled').name('Enabled').onChange(updateMW);
+    mwFolder.add(this.mwParams, 'intensity', 0.0, 100.0).onChange(updateMW);
+    mwFolder.add(this.mwParams, 'saturation', 0.0, 2.0).onChange(updateMW);
+    mwFolder.add(this.mwParams, 'blackPoint', 0.0, 0.5).name('Black Point').onChange(updateMW);
+    mwFolder.add(this.mwParams, 'siderealTime', 0.0, 24.0).name('Sidereal Time').listen().onChange(updateMW);
+    mwFolder.add(this.mwParams, 'latitude', -90.0, 90.0).name('Latitude').onChange(updateMW);
+    mwFolder.close();
+
+    // Initial MW Update
+    updateMW();
+
+    this.updateMW = updateMW; // Export for sync
+
+    // We need local proxy for sunRadius due to conversion
+    this.diskParams = {
+      radius: 1.2
     };
     sky.setSunDiskEnabled(true);
     sky.setSunRadius(1.2);
-    sunDisk.add(diskParams, 'enabled').onChange(v => sky.setSunDiskEnabled(v));
-    sunDisk.add(diskParams, 'radius', 0.0, 5.0).onChange(v => sky.setSunRadius(v));
-    sunDisk.add(sky.sunHalo, 1, 0.0, 2.0).name('Limb Darkening').onChange(v => sky.setSunLimbDarkening(v));
-    sunDisk.add(sky.sunHalo, 2, 0.0, 100.0).name('Intensity Boost').onChange(v => sky.setSunDiskIntensity(v));
+    sunFolder.add(this.diskParams, 'radius', 0.0, 5.0).onChange(v => sky.setSunRadius(v));
+    sunFolder.add(sky.sunHalo, 1, 0.0, 2.0).name('Limb Darkening').onChange(v => sky.setSunLimbDarkening(v));
+    sunFolder.add(sky.sunHalo, 2, 0.0, 100.0).name('Intensity Boost').onChange(v => sky.setSunDiskIntensity(v));
 
     const atmFolder = gui.addFolder('Atmosphere');
     atmFolder.add(sky, 'turbidity', 1.0, 10.0).onChange(v => sky.setTurbidity(v));
@@ -161,30 +421,8 @@ class App {
     atmFolder.add(sky, 'ozone', 0.0, 1.0).onChange(v => sky.setOzone(v));
     atmFolder.add(sky, 'mieG', 0.0, 0.999).onChange(v => sky.setMieG(v));
 
-    const artFolder = gui.addFolder('Artistic');
-    // Set Horizon Glow default to 1.0
-    sky.setHorizonGlow(1.0);
-    sky.msFactors[2] = 1.0;
-    // Set Contrast default to 0.85
-    sky.setContrast(0.85);
-
-    artFolder.add(sky.msFactors, 0, 0.0, 2.0).name('MS Rayleigh').onChange(v => sky.setMultiScattering(v, sky.msFactors[1]));
-    artFolder.add(sky.msFactors, 1, 0.0, 2.0).name('MS Mie').onChange(v => sky.setMultiScattering(sky.msFactors[0], v));
-    artFolder.add(sky.msFactors, 2, 0.0, 1.0).name('Horizon Glow').onChange(v => sky.setHorizonGlow(v));
-    artFolder.add(sky, 'contrast', 0.1, 2.0).onChange(v => sky.setContrast(v));
-
-    artFolder.addColor(sky, 'nightColor').onChange(v => sky.setNightColor(v));
-
-    const shmFolder = artFolder.addFolder('Shimmer');
-    // Set Shimmer Strength default to 0.0
-    sky.setShimmerControl(0.0, sky.shimmerControl[1], sky.shimmerControl[2]);
-
-    shmFolder.add(sky.shimmerControl, 0, 0.0, 0.1).name('Strength').onChange(v => sky.setShimmerControl(v, sky.shimmerControl[1], sky.shimmerControl[2]));
-    shmFolder.add(sky.shimmerControl, 1, 1.0, 100.0).name('Frequency').onChange(v => sky.setShimmerControl(sky.shimmerControl[0], v, sky.shimmerControl[2]));
-    shmFolder.add(sky.shimmerControl, 2, 0.01, 0.5).name('Mask Height').onChange(v => sky.setShimmerControl(sky.shimmerControl[0], sky.shimmerControl[1], v));
-
     const cloudFolder = gui.addFolder('Clouds');
-    const cParams = {
+    this.cParams = {
       volumetrics: sky.cloudControl2[1] > 0.5,
       coverage: 0.4,
       density: 0.02,
@@ -193,19 +431,19 @@ class App {
       evolution: 0.02
     };
     // Apply Cloud Defaults
-    sky.setCloudControl(0.4, 0.02, cParams.height, 50.0);
+    sky.setCloudControl(0.4, 0.02, this.cParams.height, 50.0);
     sky.setCloudShapeEvolution(0.02);
 
-    cloudFolder.add(cParams, 'volumetrics').onChange(v => sky.setCloudVolumetricLighting(v));
-    cloudFolder.add(cParams, 'coverage', 0.0, 1.0).onChange(v => sky.setCloudControl(v, cParams.density, cParams.height, cParams.speed));
-    cloudFolder.add(cParams, 'density', 0.0, 1.0).onChange(v => sky.setCloudControl(cParams.coverage, v, cParams.height, cParams.speed));
-    cloudFolder.add(cParams, 'height', 2000.0, 20000.0).onChange(v => sky.setCloudControl(cParams.coverage, cParams.density, v, cParams.speed));
+    cloudFolder.add(this.cParams, 'volumetrics').onChange(v => sky.setCloudVolumetricLighting(v));
+    cloudFolder.add(this.cParams, 'coverage', 0.0, 1.0).onChange(v => sky.setCloudControl(v, this.cParams.density, this.cParams.height, this.cParams.speed));
+    cloudFolder.add(this.cParams, 'density', 0.0, 1.0).onChange(v => sky.setCloudControl(this.cParams.coverage, v, this.cParams.height, this.cParams.speed));
+    cloudFolder.add(this.cParams, 'height', 2000.0, 20000.0).onChange(v => sky.setCloudControl(this.cParams.coverage, this.cParams.density, v, this.cParams.speed));
     // Reverse speed calc: w = speed * (0.05 / 72.0)
-    cloudFolder.add(cParams, 'speed', 0.0, 200.0).onChange(v => sky.setCloudControl(cParams.coverage, cParams.density, cParams.height, v));
-    cloudFolder.add(cParams, 'evolution', 0.0, 2.0).onChange(v => sky.setCloudShapeEvolution(v));
+    cloudFolder.add(this.cParams, 'speed', 0.0, 200.0).onChange(v => sky.setCloudControl(this.cParams.coverage, this.cParams.density, this.cParams.height, v));
+    cloudFolder.add(this.cParams, 'evolution', 0.0, 2.0).onChange(v => sky.setCloudShapeEvolution(v));
 
     const waterFolder = gui.addFolder('Water');
-    const wParams = {
+    this.wParams = {
       derivativeTrick: true,
       strength: 50.0,
       speed: 1.0,
@@ -215,67 +453,436 @@ class App {
     sky.setWaterControl(50.0, 1.0, 1.0, 4.0); // 1.0 = Derivative Trick On, 4 octaves
 
     const updateWater = () => {
-      sky.setWaterControl(wParams.strength, wParams.speed, wParams.derivativeTrick ? 1.0 : 0.0, wParams.octaves);
+      sky.setWaterControl(this.wParams.strength, this.wParams.speed, this.wParams.derivativeTrick ? 1.0 : 0.0, this.wParams.octaves);
     };
 
-    waterFolder.add(wParams, 'derivativeTrick').name('Derivative Trick').onChange(updateWater);
-    waterFolder.add(wParams, 'strength', 10.0, 100.0).onChange(updateWater);
-    waterFolder.add(wParams, 'speed', 0.0, 5.0).onChange(updateWater);
-    waterFolder.add(wParams, 'octaves', 1, 8, 1).name('Octaves').onChange(updateWater);
+    waterFolder.add(this.wParams, 'derivativeTrick').name('Derivative Trick').onChange(updateWater);
+    waterFolder.add(this.wParams, 'strength', 10.0, 100.0).onChange(updateWater);
+    waterFolder.add(this.wParams, 'speed', 0.0, 5.0).onChange(updateWater);
+    waterFolder.add(this.wParams, 'octaves', 1, 8, 1).name('Octaves').onChange(updateWater);
     waterFolder.close();
 
     const starFolder = gui.addFolder('Stars');
-    const sParams = {
+    this.sParams = {
       enabled: true,
-      density: 1.0
+      density: 0.001,
+      intensity: 0.0 // 2^0 = 1.0
     };
-    // Initialize defaults (Density 1.0, Enabled True)
-    sky.setStarControl(1.0, true);
+    // Initialize defaults (Density 0.001, Enabled True)
+    sky.setStarControl(0.001, true);
+    sky.setStarIntensity(Math.pow(2.0, 0.0));
 
     const updateStars = () => {
-      sky.setStarControl(sParams.density, sParams.enabled);
+      sky.setStarControl(this.sParams.density, this.sParams.enabled);
+      sky.setStarIntensity(Math.pow(2.0, this.sParams.intensity));
     };
 
-    starFolder.add(sParams, 'enabled').name('Enabled').onChange(updateStars);
-    starFolder.add(sParams, 'density', 0.0, 1.0).name('Density').onChange(updateStars);
+    starFolder.add(this.sParams, 'enabled').name('Enabled').onChange(updateStars);
+    starFolder.add(this.sParams, 'density', 0.0, 0.01, 0.0001).name('Density').onChange(updateStars);
+    starFolder.add(this.sParams, 'intensity', 0.0, 24.0).name('Intensity (Exp)').onChange(updateStars);
     starFolder.close();
+    this.updateStars = updateStars;
+
+    const artFolder = gui.addFolder('Artistic');
+    // Set Horizon Glow default to 0.0
+    sky.setHorizonGlow(0.0);
+    sky.msFactors[2] = 0.0;
+    // Set Contrast default to 1.0
+    sky.setContrast(1.0);
+
+    artFolder.add(sky.msFactors, 0, 0.0, 2.0).name('MS Rayleigh').onChange(v => sky.setMultiScattering(v, sky.msFactors[1]));
+    artFolder.add(sky.msFactors, 1, 0.0, 2.0).name('MS Mie').onChange(v => sky.setMultiScattering(sky.msFactors[0], v));
+    artFolder.add(sky.msFactors, 2, 0.0, 1.0).name('Horizon Glow').onChange(v => sky.setHorizonGlow(v));
+    artFolder.add(sky, 'contrast', 0.1, 2.0).onChange(v => sky.setContrast(v));
+
+
+
+    const shmFolder = artFolder.addFolder('Shimmer');
+    // Set Shimmer Strength default to 0.0
+    sky.setShimmerControl(0.0, sky.shimmerControl[1], sky.shimmerControl[2]);
+
+    shmFolder.add(sky.shimmerControl, 0, 0.0, 0.1).name('Strength').onChange(v => sky.setShimmerControl(v, sky.shimmerControl[1], sky.shimmerControl[2]));
+    shmFolder.add(sky.shimmerControl, 1, 1.0, 100.0).name('Frequency').onChange(v => sky.setShimmerControl(sky.shimmerControl[0], v, sky.shimmerControl[2]));
+    shmFolder.add(sky.shimmerControl, 2, 0.01, 0.5).name('Mask Height').onChange(v => sky.setShimmerControl(sky.shimmerControl[0], sky.shimmerControl[1], v));
 
     const camFolder = gui.addFolder('Camera');
     camFolder.add(this.params, 'focalLength', 8.0, 300.0).name('Focal Length').onChange(() => this.updateCameraProjection());
     camFolder.add(this.params, 'aperture', 1.4, 32.0).onChange(() => this.updateCameraExposure());
-    camFolder.add(this.params, 'shutterSpeed', 1.0, 1000.0).onChange(() => this.updateCameraExposure());
+    camFolder.add(this.params, 'shutterSpeed', 0.05, 1000.0).onChange(() => this.updateCameraExposure());
     camFolder.add(this.params, 'iso', 50.0, 3200.0).onChange(() => this.updateCameraExposure());
 
     const bloomFolder = camFolder.addFolder('Bloom');
-    const bParams = {
-      enabled: false,
+    this.bParams = {
+      enabled: true,
       lensFlare: false
     };
 
     const updateBloom = () => {
       this.view.setBloomOptions({
-        enabled: bParams.enabled,
-        lensFlare: bParams.lensFlare
+        enabled: this.bParams.enabled,
+        lensFlare: this.bParams.lensFlare
       });
     };
 
-    bloomFolder.add(bParams, 'enabled').onChange(updateBloom);
-    bloomFolder.add(bParams, 'lensFlare').onChange(updateBloom);
+    bloomFolder.add(this.bParams, 'enabled').onChange(updateBloom);
+    bloomFolder.add(this.bParams, 'lensFlare').onChange(updateBloom);
     bloomFolder.close();
 
     // Collapse folders by default
-    sunDisk.close();
+
     atmFolder.close();
     artFolder.close();
     // shmFolder is inside artFolder, so it's hidden, but we can close it too if we want
     shmFolder.close();
     cloudFolder.close();
-    // camFolder left open? User didn't specify, but "Artistic, shimmer and clouds" + "Disk, Atmosphere" were requested.
-    // So Camera might stay open or close. Let's keep Camera open for now as it wasn't listed.
+    // camFolder left open by default for convenience.
+
 
     // Initial sync
     updateSun();
     this.updateCameraExposure(); // This will trigger updateSunIntensity too
+    updateBloom();
+
+    // Check URL for config
+    const urlParams = new URLSearchParams(window.location.search);
+    if (urlParams.has('config')) {
+      try {
+        const state = JSON.parse(atob(urlParams.get('config')));
+        this.applyURLState(state);
+        // Update GUI
+        gui.controllers.forEach(c => c.updateDisplay());
+        // Recursive update for folders
+        gui.folders.forEach(f => {
+          f.controllers.forEach(c => c.updateDisplay());
+          // And sub-folders if any (Shimmer/Bloom)
+          f.folders.forEach(sf => sf.controllers.forEach(sc => sc.updateDisplay()));
+        });
+      } catch (e) {
+        console.error("Failed to load config:", e);
+      }
+    }
+
+    const syncFolder = gui.addFolder('Real-Time Sync');
+    this.syncParams = {
+      enabled: false,
+      lat: 0.0,
+      lng: 0.0,
+      status: 'Disabled'
+    };
+
+    const updateSync = () => {
+      if (this.syncParams.enabled) {
+        if (navigator.geolocation) {
+          this.syncParams.status = "Locating...";
+          navigator.geolocation.getCurrentPosition(
+            (pos) => {
+              this.syncParams.lat = pos.coords.latitude;
+              this.syncParams.lng = pos.coords.longitude;
+              this.syncParams.status = "Active";
+              syncFolder.controllers.forEach(c => c.updateDisplay());
+            },
+            (err) => {
+              console.error(err);
+              this.syncParams.status = "Error (See Console)";
+              this.syncParams.enabled = false;
+              syncFolder.controllers.forEach(c => c.updateDisplay());
+            }
+          );
+        } else {
+          this.syncParams.status = "Not Supported";
+        }
+      } else {
+        this.syncParams.status = "Disabled";
+      }
+      syncFolder.controllers.forEach(c => c.updateDisplay());
+    };
+
+    syncFolder.add(this.syncParams, 'enabled').name('Enable Sync').onChange(updateSync);
+    syncFolder.add(this.syncParams, 'status').name('Status').disable().listen();
+
+    this.syncFolder = syncFolder;
+
+    const shareParams = {
+      copyUrl: () => {
+        const state = this.getURLState();
+        const str = btoa(JSON.stringify(state));
+        const url = `${window.location.origin}${window.location.pathname}?config=${str}`;
+        navigator.clipboard.writeText(url).then(() => {
+          alert("Configuration URL copied to clipboard!");
+        }).catch(err => {
+          console.error('Could not copy text: ', err);
+          prompt("Copy this URL:", url);
+        });
+      }
+    };
+    gui.add(shareParams, 'copyUrl').name('Share Configuration');
+
+  }
+
+  updateRealTimeSync() {
+    if (!this.syncParams || !this.syncParams.enabled || !window.SunCalc) return;
+
+    const now = new Date();
+    const lat = this.syncParams.lat;
+    const lng = this.syncParams.lng;
+
+    // Sun
+    const sunPos = window.SunCalc.getPosition(now, lat, lng);
+    // Azimuth: South=0, West=PI/2.
+    // Skybox Phi: +X=0, +Z=PI/2.
+    // If +Z is South:
+    // SunAz 0 (South) -> Skybox PI/2 (+Z).
+    // SunAz PI/2 (West) -> Skybox PI (-X).
+    // So Phi = Az + PI/2.
+    const sunPhi = sunPos.azimuth + Math.PI / 2;
+    // Altitude: 0=Horizon, PI/2=Zenith.
+    // Skybox Theta: 0=Zenith, PI/2=Horizon.
+    const sunTheta = Math.PI / 2 - sunPos.altitude;
+
+    this.params.sunPhi = sunPhi;
+    this.params.sunTheta = sunTheta;
+
+    // Moon
+    const moonPos = window.SunCalc.getMoonPosition(now, lat, lng);
+    const moonPhi = moonPos.azimuth + Math.PI / 2;
+    const moonTheta = Math.PI / 2 - moonPos.altitude;
+
+    this.mParams.azimuth = (moonPhi * 180.0 / Math.PI) % 360.0;
+    this.mParams.height = Math.cos(moonTheta);
+
+    // Milky Way Sync
+    const gmst = getGMST(now);
+    const lst = (gmst + lng / 15.0 + 24.0) % 24.0;
+    this.mwParams.siderealTime = lst;
+    this.mwParams.latitude = lat;
+    if (this.updateMW) this.updateMW();
+
+    // Update Skybox
+    const sky = this.skybox;
+
+    // Update Sun Vector
+    const sx = Math.sin(sunTheta) * Math.cos(sunPhi);
+    const sy = Math.cos(sunTheta);
+    const sz = Math.sin(sunTheta) * Math.sin(sunPhi);
+    sky.setSunPosition([sx, sy, sz]);
+
+    // Update Moon Vector
+    const mx = Math.sin(moonTheta) * Math.cos(moonPhi);
+    const my = Math.cos(moonTheta);
+    const mz = Math.sin(moonTheta) * Math.sin(moonPhi);
+    sky.setMoonPosition([mx, my, mz]);
+
+    // Update UI Proxies
+    if (this.sunUI) {
+      this.sunUI.azimuth = (sunPhi * 180.0 / Math.PI) % 360.0;
+      if (this.sunUI.azimuth < 0) this.sunUI.azimuth += 360.0;
+      this.sunUI.height = Math.cos(sunTheta);
+    }
+  }
+
+  getURLState() {
+
+    // Update Camera LookAt
+    // Serialize current state (Minified)
+    // Mapping:
+    // p: params (Camera) -> a:aperture, ss:shutterSpeed, i:iso, st:sunTheta, sp:sunPhi, fl:focalLength, si:sunIntensity
+    // c: cParams (Clouds) -> v:volumetrics, co:coverage, d:density, h:height, s:speed, e:evolution
+    // w: wParams (Water) -> dt:derivativeTrick, st:strength, s:speed, o:octaves
+    // s: sParams (Stars) -> e:enabled, d:density
+    // b: bParams (Bloom) -> e:enabled, lf:lensFlare
+    // k: sky (Skybox) -> t:turbidity, r:rayleigh, mc:mieCoefficient, mg:mieG, o:ozone, ms:msFactors, co:contrast, nc:nightColor, sh:shimmerControl, hl:sunHalo
+
+    const p = this.params;
+    const c = this.cParams;
+    const w = this.wParams;
+    const s = this.sParams;
+    const b = this.bParams;
+    const m = this.mParams;
+    const mw = this.mwParams;
+    const sk = this.skybox;
+
+    return {
+      p: { a: p.aperture, ss: p.shutterSpeed, i: p.iso, st: p.sunTheta, sp: p.sunPhi, fl: p.focalLength, si: p.sunIntensity },
+      c: { v: c.volumetrics, co: c.coverage, d: c.density, h: c.height, s: c.speed, e: c.evolution },
+      w: { dt: w.derivativeTrick, st: w.strength, s: w.speed, o: w.octaves },
+      s: { e: s.enabled, d: s.density, i: s.intensity },
+      mw: { e: mw.enabled, i: mw.intensity, s: mw.saturation, bp: mw.blackPoint, st: mw.siderealTime, l: mw.latitude },
+      b: { e: b.enabled, lf: b.lensFlare },
+      m: { e: m.enabled, az: m.azimuth, h: m.height, r: m.radius, i: m.intensity },
+      cm: { t: this.camState.theta, p: this.camState.phi },
+      k: {
+        t: sk.turbidity,
+        r: sk.rayleigh,
+        mc: sk.mieCoefficient,
+        mg: sk.mieG,
+        o: sk.ozone,
+        ms: [...sk.msFactors],
+        co: sk.contrast,
+        nc: [...sk.nightColor],
+        sh: [...sk.shimmerControl],
+        hl: [...sk.sunHalo]
+      }
+    };
+
+  }
+
+  applyURLState(state) {
+    const p = state.p;
+    const c = state.c;
+    const w = state.w;
+    const s = state.s;
+    const mw = state.mw;
+    const b = state.b;
+    const m = state.m;
+    const k = state.k;
+    const cm = state.cm;
+
+    if (p) {
+      if (p.a !== undefined) this.params.aperture = p.a;
+      if (p.ss !== undefined) this.params.shutterSpeed = p.ss;
+      if (p.i !== undefined) this.params.iso = p.i;
+      if (p.st !== undefined) this.params.sunTheta = p.st;
+      if (p.sp !== undefined) this.params.sunPhi = p.sp;
+      if (p.fl !== undefined) this.params.focalLength = p.fl;
+      if (p.si !== undefined) this.params.sunIntensity = p.si;
+    }
+
+    if (c) {
+      if (c.v !== undefined) this.cParams.volumetrics = c.v;
+      if (c.co !== undefined) this.cParams.coverage = c.co;
+      if (c.d !== undefined) this.cParams.density = c.d;
+      if (c.h !== undefined) this.cParams.height = c.h;
+      if (c.s !== undefined) this.cParams.speed = c.s;
+      if (c.e !== undefined) this.cParams.evolution = c.e;
+    }
+
+    if (w) {
+      if (w.dt !== undefined) this.wParams.derivativeTrick = w.dt;
+      if (w.st !== undefined) this.wParams.strength = w.st;
+      if (w.s !== undefined) this.wParams.speed = w.s;
+      if (w.o !== undefined) this.wParams.octaves = w.o;
+    }
+
+    if (s) {
+      if (s.e !== undefined) this.sParams.enabled = s.e;
+      if (s.d !== undefined) this.sParams.density = s.d;
+      if (s.i !== undefined) this.sParams.intensity = s.i;
+      if (this.updateStars) this.updateStars();
+    }
+
+    if (mw) {
+      if (mw.e !== undefined) this.mwParams.enabled = mw.e;
+      if (mw.i !== undefined) this.mwParams.intensity = mw.i;
+      if (mw.s !== undefined) this.mwParams.saturation = mw.s;
+      if (mw.bp !== undefined) this.mwParams.blackPoint = mw.bp;
+      if (mw.st !== undefined) this.mwParams.siderealTime = mw.st;
+      if (mw.l !== undefined) this.mwParams.latitude = mw.l;
+      if (this.updateMW) this.updateMW();
+    }
+
+    if (b) {
+      if (b.e !== undefined) this.bParams.enabled = b.e;
+      if (b.lf !== undefined) this.bParams.lensFlare = b.lf;
+    }
+
+    const sky = this.skybox;
+    if (k) {
+      if (k.t !== undefined) sky.setTurbidity(k.t);
+      if (k.r !== undefined) sky.setRayleigh(k.r);
+      if (k.mc !== undefined) sky.setMieCoefficient(k.mc);
+      if (k.mg !== undefined) sky.setMieG(k.mg);
+      if (k.o !== undefined) sky.setOzone(k.o);
+
+      if (k.ms) { sky.setMultiScattering(k.ms[0], k.ms[1]); sky.setHorizonGlow(k.ms[2]); }
+      if (k.co !== undefined) sky.setContrast(k.co);
+      if (k.nc) sky.setNightColor(k.nc);
+      if (k.sh) sky.setShimmerControl(k.sh[0], k.sh[1], k.sh[2]);
+
+      // Sun Halo
+      const savedHalo = k.hl;
+      if (savedHalo && savedHalo.length === 4) {
+        sky.sunHalo[0] = savedHalo[0];
+        sky.sunHalo[1] = savedHalo[1];
+        sky.sunHalo[2] = savedHalo[2];
+        sky.sunHalo[3] = savedHalo[3];
+
+        // Update derived UI params for Sun Disk
+        const rad = Math.acos(Math.max(-1.0, Math.min(1.0, savedHalo[0])));
+        this.diskParams.radius = rad * (180.0 / Math.PI);
+        this.diskParams.enabled = savedHalo[3] > 0.5;
+      }
+
+      sky.updateCoefficients();
+    }
+
+    if (cm) {
+      if (cm.t !== undefined) this.camState.theta = cm.t;
+      if (cm.p !== undefined) this.camState.phi = cm.p;
+    }
+
+    // Update derived Sun UI
+    if (this.sunUI) {
+      this.sunUI.height = Math.cos(this.params.sunTheta);
+      this.sunUI.azimuth = (this.params.sunPhi * 180.0 / Math.PI) % 360.0;
+      if (this.sunUI.azimuth < 0) this.sunUI.azimuth += 360.0;
+    }
+
+    // Apply Local Params via Setters
+    sky.setCloudControl(this.cParams.coverage, this.cParams.density, this.cParams.height, this.cParams.speed);
+    sky.setCloudVolumetricLighting(this.cParams.volumetrics);
+    sky.setCloudShapeEvolution(this.cParams.evolution);
+
+    sky.setWaterControl(this.wParams.strength, this.wParams.speed, this.wParams.derivativeTrick ? 1.0 : 0.0, this.wParams.octaves);
+    sky.setStarControl(this.sParams.density, this.sParams.enabled);
+
+    if (m) {
+      if (m.e !== undefined) this.mParams.enabled = m.e;
+      if (m.az !== undefined) this.mParams.azimuth = m.az;
+      // Compat: if 'el' exists (old link) convert to 'h'
+      if (m.h !== undefined) {
+        this.mParams.height = m.h;
+      } else if (m.el !== undefined) {
+        // Convert elevation degrees to height cos
+        this.mParams.height = Math.cos(m.el * Math.PI / 180.0);
+      }
+      if (m.r !== undefined) this.mParams.radius = m.r;
+      if (m.i !== undefined) this.mParams.intensity = m.i;
+
+      // Sync Moon
+      const az = this.mParams.azimuth * (Math.PI / 180.0);
+      const theta = Math.acos(this.mParams.height);
+      const phi = az;
+      const x = Math.sin(theta) * Math.cos(phi);
+      const y = Math.cos(theta);
+      const z = Math.sin(theta) * Math.sin(phi);
+
+      sky.setMoonPosition([x, y, z]);
+      sky.setMoonEnabled(this.mParams.enabled);
+      sky.setMoonRadius(this.mParams.radius);
+      sky.setMoonIntensity(this.mParams.intensity);
+    }
+
+    if (cm) {
+      if (cm.t !== undefined) this.camState.theta = cm.t;
+      if (cm.p !== undefined) this.camState.phi = cm.p;
+    }
+
+    this.view.setBloomOptions({
+      enabled: this.bParams.enabled,
+      lensFlare: this.bParams.lensFlare
+    });
+
+    // Update Sun Position from Params
+    const theta = this.params.sunTheta;
+    const phi = this.params.sunPhi;
+    const x = Math.sin(theta) * Math.cos(phi);
+    const y = Math.cos(theta);
+    const z = Math.sin(theta) * Math.sin(phi);
+    sky.setSunPosition([x, y, z]);
+
+    // Update Camera Projection (Focal Length) and Exposure (Aperture/Shutter/ISO)
+    this.updateCameraProjection();
+    this.updateCameraExposure();
   }
 
   initControls() {
@@ -305,10 +912,41 @@ class App {
       this.camState.phi = Math.max(-Math.PI / 2 + 0.01, Math.min(Math.PI / 2 - 0.01, this.camState.phi));
     });
 
+    // Touch support
+    this.canvas.addEventListener('touchstart', e => {
+      if (e.touches.length > 0) {
+        e.preventDefault(); // Prevent scroll/long-press
+        this.camState.dragging = true;
+        this.camState.lastX = e.touches[0].clientX;
+        this.camState.lastY = e.touches[0].clientY;
+      }
+    }, { passive: false });
+
+    window.addEventListener('touchend', () => {
+      this.camState.dragging = false;
+    });
+
+    window.addEventListener('touchmove', e => {
+      if (!this.camState.dragging || e.touches.length === 0) return;
+      e.preventDefault(); // Prevent scrolling
+      const x = e.touches[0].clientX;
+      const y = e.touches[0].clientY;
+      const dx = x - this.camState.lastX;
+      const dy = y - this.camState.lastY;
+      this.camState.lastX = x;
+      this.camState.lastY = y;
+
+      const sensitivity = 0.005;
+      this.camState.theta -= dx * sensitivity;
+      this.camState.phi += dy * sensitivity;
+      this.camState.phi = Math.max(-Math.PI / 2 + 0.01, Math.min(Math.PI / 2 - 0.01, this.camState.phi));
+    }, { passive: false });
+
 
   }
 
   render() {
+    this.updateRealTimeSync();
     // Update Camera LookAt
     const r = 1.0;
     const theta = this.camState.theta;
@@ -341,5 +979,6 @@ class App {
     const aspect = width / height;
     // near=0.1, far=5000.0
     this.camera.setLensProjection(this.params.focalLength, aspect, 0.1, 5000.0);
+    if (this.skybox) this.skybox.setResolution(height);
   }
 }

docs/wip/sky/process_milkyway.py

@@ -0,0 +1,61 @@
+
+import os
+import urllib.request
+import ssl
+from PIL import Image
+import argparse
+
+# URL of the Milky Way texture (Gaia EDR3) from ESA
+# Low Res PNG (2.71 MB) is sufficient for our 1024x512 target
+URL = "https://www.esa.int/var/esa/storage/images/esa_multimedia/images/2020/12/the_colour_of_the_sky_from_gaia_s_early_data_release_3/22358049-1-eng-GB/The_colour_of_the_sky_from_Gaia_s_Early_Data_Release_3.png"
+OUTPUT_DIR = "assets"
+OUTPUT_FILENAME = "milkyway.png"
+TARGET_WIDTH = 1024
+TARGET_HEIGHT = 512
+
+def main():
+    if not os.path.exists(OUTPUT_DIR):
+        os.makedirs(OUTPUT_DIR)
+
+    output_path = os.path.join(OUTPUT_DIR, OUTPUT_FILENAME)
+    temp_path = os.path.join(OUTPUT_DIR, "temp_milkyway.png")
+
+    print(f"Downloading Milky Way texture from {URL}...")
+    
+    # Bypass SSL verification globally
+    if hasattr(ssl, '_create_unverified_context'):
+        ssl._create_default_https_context = ssl._create_unverified_context
+
+    try:
+        req = urllib.request.Request(URL, headers={'User-Agent': 'Mozilla/5.0'})
+        with urllib.request.urlopen(req) as response, open(temp_path, 'wb') as out_file:
+            out_file.write(response.read())
+    except Exception as e:
+        print(f"Failed to download: {e}")
+        return
+
+    if not os.path.exists(temp_path):
+        print("Error: Download failed.")
+        return
+
+    print("Processing image...")
+    with Image.open(temp_path) as img:
+        # Convert to RGB (remove alpha if present, though this is likely opaque)
+        img = img.convert("RGB")
+        
+        # Resize to user requested dimensions
+        print(f"Resizing to {TARGET_WIDTH}x{TARGET_HEIGHT}...")
+        img = img.resize((TARGET_WIDTH, TARGET_HEIGHT), Image.Resampling.LANCZOS)
+        
+        # Save
+        print(f"Saving to {output_path}...")
+        img.save(output_path, "PNG")
+
+    # Cleanup
+    if os.path.exists(temp_path):
+        os.remove(temp_path)
+
+    print("Done!")
+
+if __name__ == "__main__":
+    main()

docs/wip/sky/tools/build_material.sh

@@ -1,10 +1,10 @@
 # Result: /Users/mathias/sources/git/filament/out/cmake-release/tools/matc/matc
-MATC="../../../../out/cmake-release/tools/matc/matc"
+MATC="../../../../../out/cmake-release/tools/matc/matc"
 
 # Navigate to script directory to ensure relative paths work
 cd "$(dirname "$0")"
 
 set -e
 
-$MATC -a opengl -p mobile -o assets/simulated_skybox.filamat simulated_skybox.mat
+$MATC -a opengl -p mobile -o ../assets/simulated_skybox.filamat ../simulated_skybox.mat
 echo "Material recompiled to assets/simulated_skybox.filamat"

docs/wip/sky/tools/generate_moon_assets.sh

@@ -0,0 +1,21 @@
+#!/bin/bash
+set -e
+
+# Default size
+SIZE=${1:-256}
+OUTPUT_COLOR="../assets/moon_disk.png"
+OUTPUT_NORMAL="../assets/moon_normal.png"
+
+# Navigate to script directory
+cd "$(dirname "$0")"
+
+# Check dependencies
+if ! python3 -c "import numpy, PIL" 2>/dev/null; then
+    echo "Installing dependencies (numpy, Pillow)..."
+    pip3 install numpy Pillow
+fi
+
+echo "Generating Moon Asset (Size: ${SIZE}x${SIZE})..."
+python3 process_moon.py --size $SIZE --supersample 4 --blur 1.0 --output-color $OUTPUT_COLOR --output-normal $OUTPUT_NORMAL
+
+echo "Generated $OUTPUT_COLOR and $OUTPUT_NORMAL"

docs/wip/sky/tools/process_moon.py

@@ -0,0 +1,249 @@
+import argparse
+import urllib.request
+import os
+import sys
+import math
+import ssl
+from PIL import Image
+
+# Ensure numpy is available
+try:
+    import numpy as np
+except ImportError:
+    print("Error: numpy is required. Please install it with: pip install numpy")
+    sys.exit(1)
+
+# Default URLs
+COLOR_URL = "https://svs.gsfc.nasa.gov/vis/a000000/a004700/a004720/lroc_color_2k.jpg"
+DISP_URL = "https://svs.gsfc.nasa.gov/vis/a000000/a004700/a004720/ldem_4.tif"
+
+SRC_COLOR_FILENAME = "lroc_color_2k.jpg"
+SRC_DISP_FILENAME = "ldem_4.tif"
+
+def download_file(url, filename):
+    if os.path.exists(filename):
+        print(f"File {filename} already exists. Skipping download.")
+        return
+
+    print(f"Downloading {url} to {filename}...")
+    # Create unverified context to avoid potential SSL cert issues
+    context = ssl._create_unverified_context()
+    try:
+        with urllib.request.urlopen(url, context=context) as response, open(filename, 'wb') as out_file:
+            data = response.read()
+            out_file.write(data)
+        print(f"Download of {filename} complete.")
+    except Exception as e:
+        print(f"Error downloading file {filename}: {e}")
+        # Don't exit hard if it's just one file, maybe?
+        # But for this script, we likely need it.
+        sys.exit(1)
+
+def equirectangular_to_orthographic(src_img, size, mode=None):
+    """
+    Reprojects an equirectangular image to an orthographic projection (sphere view).
+    src_img: PIL Image (Equirectangular)
+    size: Output size (width, height) - usually square
+    """
+    print(f"Reprojecting to {size}x{size} Orthographic Disk...")
+    
+    width, height = size, size
+    src_w, src_h = src_img.size
+    
+    # Create coordinate grid centered at 0,0 (-1 to 1)
+    y, x = np.mgrid[size/2:-size/2:-1, -size/2:size/2] # Note: y goes high to low
+    
+    # Normalize to -1..1
+    x = x / (size / 2)
+    y = y / (size / 2)
+    
+    # Mask for points outside the circle
+    r2 = x*x + y*y
+    mask = r2 <= 1.0
+    
+    # Calculate sphere coordinates (z > 0 for front face)
+    z = np.zeros_like(r2)
+    z[mask] = np.sqrt(1.0 - r2[mask])
+    
+    # Vector P = (x, y, z) on unit sphere
+    # Lat = asin(y)
+    # Lon = atan2(x, z) 
+    
+    # Apply mask to avoid invalid calculations
+    lat = np.arcsin(y * mask)
+    lon = np.arctan2(x * mask, z * mask)
+    
+    # Map to UV [0, 1]
+    u = (lon / (2 * math.pi)) + 0.5
+    v = (lat / math.pi) + 0.5
+    
+    # Map to Source Pixels
+    u = np.clip(u, 0, 1)
+    v = np.clip(v, 0, 1)
+    
+    src_x = (u * (src_w - 1)).astype(np.int32)
+    src_y = ((1.0 - v) * (src_h - 1)).astype(np.int32) # Flip V for image coords
+    
+    # Sample pixels
+    src_array = np.array(src_img)
+    
+    # Handle dimensions
+    if len(src_array.shape) == 2:
+        # Grayscale / Single channel
+        out_channels = 1
+        src_array = src_array[:, :, np.newaxis] # Expand for consistent indexing
+    else:
+        out_channels = src_array.shape[2]
+        
+    out_array = np.zeros((height, width, out_channels), dtype=src_array.dtype)
+    
+    # Advanced indexing
+    valid_y, valid_x = np.where(mask)
+    
+    # Extract coordinates for valid pixels
+    sx = src_x[valid_y, valid_x]
+    sy = src_y[valid_y, valid_x]
+    
+    out_array[valid_y, valid_x] = src_array[sy, sx]
+    
+    # Squeeze if single channel
+    if out_channels == 1:
+        out_array = out_array.squeeze(axis=2)
+        
+    return Image.fromarray(out_array, mode or src_img.mode)
+
+def compute_normal_map(height_img, scale=1.0, blur_radius=0.0):
+    print("Computing Normal Map from Height Map...")
+    # Convert to float array
+    h = np.array(height_img).astype(np.float32)
+
+    # Apply Blur if requested
+    if blur_radius > 0:
+        try:
+            from scipy.ndimage import gaussian_filter
+            print(f"Applying Gaussian Blur (Radius: {blur_radius})...")
+            h = gaussian_filter(h, sigma=blur_radius)
+        except ImportError:
+            print("Warning: scipy not found. Skipping Gaussian Blur.")
+    
+    # Normalize height to 0..1 for consistent gradient scale regardless of input depth
+    h_min, h_max = h.min(), h.max()
+    print(f"Height Map Range: {h_min} to {h_max}")
+    if h_max > h_min:
+        h_norm = (h - h_min) / (h_max - h_min)
+    else:
+        h_norm = h
+    
+    # Gradients
+    dy, dx = np.gradient(h_norm)
+    
+    # Pre-emphasis scale
+    bump_scale = scale 
+    
+    # Normal vector components
+    # Map is Top-Down Y.
+    nx = -dx * bump_scale
+    ny = -dy * bump_scale
+    nz = np.ones_like(nx) 
+    
+    # Mask out normals where r > 0.96 (avoid edge cliff artifacts)
+    rows, cols = h.shape
+    y, x = np.ogrid[:rows, :cols]
+    center_y, center_x = rows/2.0, cols/2.0
+    # max radius is size/2
+    radius_sq = (min(rows, cols) / 2.0)**2
+    dist_sq = (x - center_x)**2 + (y - center_y)**2
+    mask = dist_sq < (radius_sq * 0.96 * 0.96)
+
+    nx[~mask] = 0
+    ny[~mask] = 0
+    nz[~mask] = 1
+    
+    # Normalize
+    len_n = np.sqrt(nx*nx + ny*ny + nz*nz)
+    # Avoid divide by zero
+    len_n[len_n == 0] = 1.0
+    
+    nx /= len_n
+    ny /= len_n
+    nz /= len_n
+    
+    # Pack to 0..255
+    # [-1, 1] -> [0, 255]
+    out_x = ((nx + 1.0) * 0.5 * 255.0).astype(np.uint8)
+    out_y = ((ny + 1.0) * 0.5 * 255.0).astype(np.uint8)
+    out_z = ((nz + 1.0) * 0.5 * 255.0).astype(np.uint8)
+    
+    out_rgb = np.dstack((out_x, out_y, out_z))
+    return Image.fromarray(out_rgb, 'RGB')
+
+def main():
+    parser = argparse.ArgumentParser(description='Process Moon Texture')
+    parser.add_argument('--size', type=int, default=256, help='Output resolution (square)')
+    parser.add_argument('--supersample', type=int, default=2, help='Internal processing resolution multiplier')
+    parser.add_argument('--blur', type=float, default=1.0, help='Gaussian blur radius for height map')
+    parser.add_argument('--bump-scale', type=float, default=60.0, help='Normal map bump scale')
+    parser.add_argument('--output-color', type=str, default='assets/moon_disk.png', help='Output color filename')
+    parser.add_argument('--output-normal', type=str, default='assets/moon_normal.png', help='Output normal filename')
+    parser.add_argument('--skip-download', action='store_true', help='Skip downloading files')
+    
+    args = parser.parse_args()
+    
+    internal_size = args.size * args.supersample
+    
+    # Ensure assets dir exists
+    os.makedirs(os.path.dirname(args.output_color) or '.', exist_ok=True)
+    
+    # 1. Download
+    if not args.skip_download:
+        download_file(COLOR_URL, SRC_COLOR_FILENAME)
+        download_file(DISP_URL, SRC_DISP_FILENAME)
+    
+    # 2. Process Color
+    print(f"Processing Color Map (Internal Size: {internal_size}x{internal_size})...")
+    try:
+        img_color = Image.open(SRC_COLOR_FILENAME).convert('RGB')
+        out_color = equirectangular_to_orthographic(img_color, internal_size)
+        
+        if args.supersample > 1:
+            print(f"Downsampling Color to {args.size}x{args.size}...")
+            out_color = out_color.resize((args.size, args.size), Image.LANCZOS)
+            
+        out_color.save(args.output_color)
+        print(f"Saved {args.output_color}")
+    except Exception as e:
+        print(f"Error processing color: {e}")
+
+    # 3. Process Normal
+    print(f"Processing Displacement Map (Internal Size: {internal_size}x{internal_size})...")
+    try:
+        from PIL import ImageFile
+        ImageFile.LOAD_TRUNCATED_IMAGES = True
+        
+        # Check if file exists
+        if not os.path.exists(SRC_DISP_FILENAME):
+            print(f"Displacement map {SRC_DISP_FILENAME} not found!")
+            return
+
+        img_disp = Image.open(SRC_DISP_FILENAME) 
+        out_disp = equirectangular_to_orthographic(img_disp, internal_size)
+        
+        # Compute Normals
+        out_normal = compute_normal_map(out_disp, scale=args.bump_scale, blur_radius=args.blur)
+        
+        if args.supersample > 1:
+            print(f"Downsampling Normal to {args.size}x{args.size}...")
+            out_normal = out_normal.resize((args.size, args.size), Image.LANCZOS)
+
+        out_normal.save(args.output_normal)
+        print(f"Saved {args.output_normal}")
+        
+    except Exception as e:
+        print(f"Error processing normal: {e}")
+        import traceback
+        traceback.print_exc()
+
+    print("Done.")
+
+if __name__ == "__main__":
+    main()

docs_src/src_mdbook/src/release/maven.md

@@ -64,25 +64,30 @@ staging API compatibility service, which works with Filament's Gradle setup.
 
 -----
 
-### 1\. Upload to the Staging API Compatibility Service
+### 1\. Upload to the Central Publisher Portal
+
+To upload the artifacts, it is important to run both of these Gradle tasks together in a single
+command. This ensures the staging repository is created and closed automatically.
 
 ```bash
 cd android
-./gradlew publishToSonatype
+./gradlew publishToSonatype closeSonatypeStagingRepository
 ```
 
-### 2\. Move the Repository to the Central Publisher Portal
+#### Troubleshooting: Manual Staging
 
-We have a script to automate this. It reads the `sonatypeUsername` and `sonatypePassword` from your
-`~/.gradle/gradle.properties` file.
+If you ran `publishToSonatype` by itself, the repository will remain open and won't appear in the
+portal correctly. You can fix this by running our automation script, which uses the
+`sonatypeUsername` and `sonatypePassword` from your ~/.gradle/gradle.properties file:
 
 ```bash
 python3 build/common/close-sonatype-staging-repository.py
 ```
 
-### 3\. Publish the Release on Sonatype
+### 2\. Publish the Release on Sonatype
 
-Navigate to [Maven Central Repository Deployments](https://central.sonatype.com/publishing/deployments).
+Once the upload is successful, you must manually trigger the final release. Navigate to [Maven
+Central Repository Deployments](https://central.sonatype.com/publishing/deployments).
 
 Here, you should see a new deployment with a **Validated** status and all your artifacts listed. Click
 the **Publish** button to publish the artifacts. It typically takes around 5 minutes after clicking

docs_src/src_raw/wip/sky/BUILDING.md

@@ -0,0 +1,40 @@
+# Building Skybox Assets
+
+This directory contains the source code for the Simulated Skybox sample. The assets (material and textures) are pre-built in the `assets/` directory.
+
+If you need to modify the material or regenerate the moon textures, you can use the scripts provided in the `tools/` directory.
+
+## Prerequisites
+
+- **Filament**: You must have a built version of Filament. The scripts assume a standard CMake build output structure (e.g., `out/cmake-release`).
+- **Python 3**: Required for texture generation.
+- **Python Dependencies**: `numpy`, `Pillow` (automatically installed if missing, via pip).
+
+## Rebuilding the Material
+
+If you modify `simulated_skybox.mat`, you must recompile it into a `.filamat` file.
+
+```bash
+# Run from the sample root or tools directory
+./tools/build_material.sh
+```
+
+This will update `assets/simulated_skybox.filamat`.
+
+## Regenerating Moon Textures
+
+If you want to change the moon's resolution, bump scale, or blur, you can regenerate the textures.
+
+```bash
+# Run from the sample root or tools directory
+./tools/generate_moon_assets.sh [size]
+```
+
+Example:
+```bash
+./tools/generate_moon_assets.sh 512
+```
+
+This will download raw NASA data (if not present) and generate:
+- `assets/moon_disk.png`
+- `assets/moon_normal.png`

docs_src/src_raw/wip/sky/README.md

@@ -0,0 +1,76 @@
+# Analytic Skybox Sample
+
+This sample demonstrates a **fully procedural, single-pass skybox shader** capable of simulating a dynamic day-night cycle, atmospheric scattering, volumetric clouds, and water reflections. 
+
+It is designed for graphics engineers and technical artists who need a lightweight yet physically plausible environment background without relying on static HDRI textures.
+
+## Features & Performance
+
+The shader uses a "Uber-Shader" approach where all features are computed per-pixel. Features can be toggled or tuned via uniforms to balance quality vs performance.
+
+| Feature | Cost | Control | Description |
+| :--- | :---: | :--- | :--- |
+| **Atmosphere** | 🟡 **Medium** | `turbidity`, `rayleigh`, `mie` | Analytic Rayleigh & Mie scattering. Physically based colors. |
+| **Sun Disk** | 🟢 **Low** | `sunHalo` (Radius, Limb) | Analytic sphere intersection with limb darkening. Conservation of energy (Lux). |
+| **Moon & Earthshine** | 🟢 **Low** | `sunHalo2`, `moonIntensity` | Resolved moon disk with geometric phases and dynamic Earthshine. |
+| **Stars** | 🟢 **Low** | `starControl` (Density) | High-frequency procedural noise. Occluded by clouds/moon. |
+| **Clouds** | 🔴 **High** | `cloudControl` (Coverage, Density) | 4-Octave 3D Fractal Brownian Motion (FBM). Dominates the cost when enabled. |
+| **Heat Shimmer** | 🟡 **Medium** | `shimmerControl` | UV perturbation near the horizon to simulate mirages. |
+| **Water Reflection** | 🟣 **Very High** | `waterControl` | **Renders the sky twice**. Includes procedural waves (FBM) and fresnel. |
+
+> **Note**: Rendering water (`V.y < 0`) is significantly more expensive (~2.5x) than the sky because it requires re-evaluating the atmospheric scattering and cloud noise for the reflection vector.
+
+## Shader Techniques
+
+### 1. Analytic Atmospheric Scattering
+Based on the **Hoffman & Preetham** model. It solves the single-scattering integral analytically for air molecules (Rayleigh) and aerosols (Mie).
+- **Rayleigh**: Produces the deep blue sky and red sunset colors.
+- **Mie**: Produces the white halo around the sun and general haziness.
+- **Optimization**: Uses a simplified optical depth approximation ("Air Mass") to avoid expensive ray-marching.
+
+### 2. Procedural Clouds (3D Noise)
+Clouds are rendered as a spherical shell at a specific altitude.
+- **Technique**: Ray-sphere intersection finds the entry point, then **3D FBM Noise** determines density.
+- **Lighting**: Uses a "Silver Lining" approximation (strong forward scattering) and Beers-Lambert attenuation for dark underbellies.
+- **Animation**: The noise coordinate logic helps simulate wind drift and shape evolution over time.
+
+### 3. Infinite Water Ocean
+When looking below the horizon, the shader switches to "Water Mode".
+- **Geometry**: A flat plane at $y=0$.
+- **Waves**: Generated using **Derivative-Based Noise** (or Finite Difference). This creates slope vectors that perturb the normal without needing actual geometry.
+- **Reflection**: A ray is cast from the water surface back into the sky ($R = \text{reflect}(V, N)$). The sky function is called again with $R$ to get the reflected color.
+
+### 4. Dynamic Tone Mapping
+Applies a custom tone mapping curve that varies with Sun Elevation.
+- **Noon**: Linear/Gamma (Standard).
+- **Sunset**: Higher contrast curve to compress the dynamic range and enhance the rich sunset oranges/purples.
+
+## Integration
+
+To use this in your own Filament application:
+
+1.  **Compile the Material**:
+    Use `matc` to compile `simulated_skybox.mat` into a `.filamat` file.
+    ```bash
+    matc -p mobile -a opengl -o assets/simulated_skybox.filamat simulated_skybox.mat
+    ```
+
+2.  **Load in JavaScript/C++**:
+    Create a Skybox entity and assign the material.
+
+    ```javascript
+    // JavaScript Example
+    const material = engine.createMaterial('assets/simulated_skybox.filamat');
+    const skybox = engine.createSkybox(material);
+    scene.setSkybox(skybox);
+    ```
+
+3.  **Update Uniforms**:
+    The shader requires specific uniforms (Sun Direction, Time, etc.) to be updated every frame. See `SimulatedSkybox.js` for a reference implementation of the uniform buffer management.
+
+## References
+
+*   **Hoffman & Preetham (2002)**: *"Real-time Light-Atmosphere Interactions"*
+*   **Henyey & Greenstein (1941)**: *"Diffuse radiation in the galaxy"* (Mie Phase Function)
+*   **Kasten & Young (1989)**: *"Revised optical air mass tables"*
+*   **Three.js / Sky.js**: Empirical adjustments for "Golden Hour" aesthetics.

docs_src/src_raw/wip/sky/SimulatedSkybox.js

@@ -16,18 +16,37 @@ class SimulatedSkybox {
     this.ozone = 0.0;
     this.msFactors = [0.1, 0.5, 0.0];
     this.contrast = 1.0;
-    this.nightColor = [0.0, 0.0003, 0.00075];
+    this.nightColor = [0.0, 3.0e-9, 7.5e-9];
     this.shimmerControl = [0.0, 20.0, 0.1];
     this.cloudControl = [0.0, 0.1, 8000.0, 0.0];
     this.cloudControl2 = [0.0, 0.0, 0.0, 0.0];
     this.waterControl = [50.0, 1.0, 1.0, 4.0]; // x=Strength, y=Speed, z=DerivativeTrick, w=Octaves
-    this.starControl = [1.0, 1.0]; // x=Density (0-1), y=Enabled (0-1)
+    this.starControl = [0.001, 1.0, 350.0, 0.01]; // x=Density, y=Enabled, z=Frequency, w=PixelScale
+    this.starIntensity = 1.0;
+    this.focalLength = 24.0;
+    this.height = 1000.0;
     this.planetRadius = 6360.0;
 
     // Sun Halo
     // x=cos(rad), y=limbDarkening, z=intensity, w=enabled
+    // Sun Halo
     this.sunHalo = [Math.cos(0.5 * Math.PI / 180.0), 0.5, 1.0, 1.0];
 
+    // Moon Parameters (Mapped to Secondary Sun)
+    this.moonDirection = [-0.2, 0.8, -0.2]; // Default Moon Pos
+    this.moonIntensity = 1.0; // Scale Factor (1.0 = Physical Peak)
+    // x=cos(rad), y=sin(rad) [Precision Fix], z=intensity, w=enabled
+    this.moonHalo = [Math.cos(0.5 * Math.PI / 180.0), Math.sin(0.5 * Math.PI / 180.0), 1.0, 0.0]; // Disabled by default
+
+    this.moonTextureObj = null;
+    this.moonNormalObj = null;
+    this.milkyWayTextureObj = null;
+
+    // Milky Way Parameters
+    // x=Intensity, y=Saturation, z=Unused
+    this.milkyWayControl = [1.0, 1.2, 0.05];
+    this.milkyWayEnabled = true;
+    this.milkyWayRotation = [1, 0, 0, 0, 1, 0, 0, 0, 1]; // Identity by default
     this.initEntity();
   }
 
@@ -44,6 +63,184 @@ class SimulatedSkybox {
     rcm.setMaterialInstanceAt(instance, 0, this.materialInstance);
 
     console.log("Material loaded and bound.");
+
+    // Load Moon Texture
+    try {
+      const texUrl = 'assets/moon_disk.png';
+      const Texture = Filament.Texture;
+      const TextureSampler = Filament.TextureSampler;
+      const PixelDataFormat = Filament.PixelDataFormat;
+      const PixelDataType = Filament.PixelDataType;
+      const TextureUsage = Filament.Texture$Usage;
+      const TextureFormat = Filament.Texture$InternalFormat;
+      const MinFilter = Filament.MinFilter;
+      const MagFilter = Filament.MagFilter;
+      const WrapMode = Filament.WrapMode;
+      const texResponse = await fetch(texUrl);
+      const texBlob = await texResponse.blob();
+      const bitmap = await createImageBitmap(texBlob);
+
+      const width = bitmap.width;
+      const height = bitmap.height;
+
+      this.moonTextureObj = Texture.Builder()
+        .width(width)
+        .height(height)
+        .levels(0xff)
+        .format(TextureFormat.SRGB8_A8)
+        .usage(TextureUsage.SAMPLEABLE.value | TextureUsage.UPLOADABLE.value | TextureUsage.GEN_MIPMAPPABLE.value)
+        .build(this.engine);
+
+      // Extract Data using a Canvas
+      const canvas = document.createElement('canvas');
+      canvas.width = width;
+      canvas.height = height;
+      const ctx = canvas.getContext('2d');
+      ctx.drawImage(bitmap, 0, 0);
+      const imageData = ctx.getImageData(0, 0, width, height);
+
+      // Use RGBA data directly (Uint8ClampedArray)
+      // Filament supports RGBA upload for RGB/SRGB internal formats (drops alpha).
+      // This matches Canvas layout (Top-Down, RGBA) and is 4-byte aligned.
+      const pbd = Filament.PixelBuffer(
+        new Uint8Array(imageData.data.buffer), // Wrap buffer to ensure Uint8Array
+        PixelDataFormat.RGBA,
+        PixelDataType.UBYTE
+      );
+
+      this.moonTextureObj.setImage(this.engine, 0, pbd);
+      this.moonTextureObj.generateMipmaps(this.engine);
+
+      const sampler = new TextureSampler(
+        MinFilter.LINEAR,
+        MagFilter.LINEAR,
+        WrapMode.CLAMP_TO_EDGE
+      );
+
+      this.materialInstance.setTextureParameter('moonTexture', this.moonTextureObj, sampler);
+
+    } catch (e) {
+      console.error("Failed to load moon texture:", e);
+    }
+
+    // Load Moon Normal
+    try {
+      const texUrl = 'assets/moon_normal.png';
+      const Texture = Filament.Texture;
+      const TextureSampler = Filament.TextureSampler;
+      const PixelDataFormat = Filament.PixelDataFormat;
+      const PixelDataType = Filament.PixelDataType;
+      const TextureUsage = Filament.Texture$Usage;
+      const TextureFormat = Filament.Texture$InternalFormat;
+      const MinFilter = Filament.MinFilter;
+      const MagFilter = Filament.MagFilter;
+      const WrapMode = Filament.WrapMode;
+      const texResponse = await fetch(texUrl);
+      const texBlob = await texResponse.blob();
+      const bitmap = await createImageBitmap(texBlob);
+
+      const width = bitmap.width;
+      const height = bitmap.height;
+
+      this.moonNormalObj = Texture.Builder()
+        .width(width)
+        .height(height)
+        .levels(0xff)
+        .format(TextureFormat.RGBA8)
+        .usage(TextureUsage.SAMPLEABLE.value | TextureUsage.UPLOADABLE.value | TextureUsage.GEN_MIPMAPPABLE.value)
+        .build(this.engine);
+
+      // Extract Data using a Canvas
+      const canvas = document.createElement('canvas');
+      canvas.width = width;
+      canvas.height = height;
+      const ctx = canvas.getContext('2d');
+      ctx.drawImage(bitmap, 0, 0);
+      const imageData = ctx.getImageData(0, 0, width, height);
+
+      // Use RGBA data directly
+      const pbd = Filament.PixelBuffer(
+        new Uint8Array(imageData.data.buffer),
+        PixelDataFormat.RGBA,
+        PixelDataType.UBYTE
+      );
+
+      this.moonNormalObj.setImage(this.engine, 0, pbd);
+      this.moonNormalObj.generateMipmaps(this.engine);
+
+      const sampler = new TextureSampler(
+        MinFilter.LINEAR_MIPMAP_LINEAR,
+        MagFilter.LINEAR,
+        WrapMode.CLAMP_TO_EDGE
+      );
+
+      this.materialInstance.setTextureParameter('moonNormal', this.moonNormalObj, sampler);
+
+    } catch (e) {
+      console.error("Failed to load moon normal:", e);
+    }
+
+    // Load Milky Way Texture
+    try {
+      const texUrl = 'assets/milkyway.png';
+      const Texture = Filament.Texture;
+      const TextureSampler = Filament.TextureSampler;
+      const PixelDataFormat = Filament.PixelDataFormat;
+      const PixelDataType = Filament.PixelDataType;
+      const TextureUsage = Filament.Texture$Usage;
+      const TextureFormat = Filament.Texture$InternalFormat;
+      const MinFilter = Filament.MinFilter;
+      const MagFilter = Filament.MagFilter;
+      const WrapMode = Filament.WrapMode;
+      const texResponse = await fetch(texUrl);
+      const texBlob = await texResponse.blob();
+      const bitmap = await createImageBitmap(texBlob);
+
+      const width = bitmap.width;
+      const height = bitmap.height;
+
+      this.milkyWayTextureObj = Texture.Builder()
+        .width(width)
+        .height(height)
+        .levels(0xff)
+        .format(TextureFormat.SRGB8_A8)
+        .usage(TextureUsage.SAMPLEABLE.value | TextureUsage.UPLOADABLE.value | TextureUsage.GEN_MIPMAPPABLE.value)
+        .build(this.engine);
+
+      // Extract Data using a Canvas
+      const canvas = document.createElement('canvas');
+      canvas.width = width;
+      canvas.height = height;
+      const ctx = canvas.getContext('2d');
+      ctx.drawImage(bitmap, 0, 0);
+      try {
+        const imageData = ctx.getImageData(0, 0, width, height);
+
+        // Use RGBA data directly
+        const pbd = Filament.PixelBuffer(
+          new Uint8Array(imageData.data.buffer),
+          PixelDataFormat.RGBA,
+          PixelDataType.UBYTE
+        );
+
+        this.milkyWayTextureObj.setImage(this.engine, 0, pbd);
+        this.milkyWayTextureObj.generateMipmaps(this.engine);
+
+        const sampler = new TextureSampler(
+          MinFilter.LINEAR_MIPMAP_LINEAR,
+          MagFilter.LINEAR,
+          WrapMode.REPEAT // Equirectangular wraps horizontally
+        );
+
+        this.materialInstance.setTextureParameter('milkyWayTexture', this.milkyWayTextureObj, sampler);
+      } catch (err) {
+        console.warn("Milky Way texture data access failed (CORS?):", err);
+      }
+
+    } catch (e) {
+      console.error("Failed to load milky way texture:", e);
+    }
+
     this.updateCoefficients();
   }
 
@@ -84,16 +281,16 @@ class SimulatedSkybox {
 
     this.ib.setBuffer(this.engine, TRIANGLE_INDICES);
 
-    // We create a dummy material first or wait? 
-    // In JS we usually can't block. We'll rely on loadMaterial being called.
-    // For now, we build the Renderable without material, then set it later.
+    // Build the Renderable without material; it will be set later by loadMaterial.
+
 
     RenderableManager.Builder(1)
       .geometry(0, PrimitiveType.TRIANGLES, this.vb, this.ib)
       .culling(false)
       .castShadows(false)
       .receiveShadows(false)
-      .priority(7) // Render behind translucent objects? 7 is skybox priority typically.
+      .priority(7) // Skybox priority
+
       .build(this.engine, this.entity);
   }
 
@@ -215,11 +412,107 @@ class SimulatedSkybox {
   }
 
   setStarControl(density, enabled) {
-    this.starControl[0] = Math.max(0.0, Math.min(1.0, density));
+    // Compensate for grid frequency reduction (350 -> 100)
+    // Fewer cells = fewer stars, so we increase density threshold.
+    // Factor ~ (350/100)^2 = 12.25
+    const compensatedDensity = density * 12.0;
+    this.starControl[0] = Math.max(0.0, Math.min(1.0, compensatedDensity));
     this.starControl[1] = enabled ? 1.0 : 0.0;
     this.updateCoefficients();
   }
 
+  setFocalLength(mm) {
+    this.focalLength = Math.max(1.0, mm);
+    this.updateStarFrequency();
+  }
+
+  setResolution(height) {
+    this.height = Math.max(1.0, height);
+    this.updateStarFrequency();
+  }
+
+  updateStarFrequency() {
+    // World-Anchored Stars
+    // z = Fixed Frequency (World Space Grid)
+    // w = Pixel Scale (Screen Space Radius)
+
+    // Fixed Frequency: Defines the "Universe" coordinate system. 
+    // Reduced to 100.0 to allow larger stars without clipping (square artifacts).
+    this.starControl[2] = 100.0;
+
+    // Pixel Scale in Radians
+    // We use linear scaling (24/f) instead of atan(fov) to ensure star size remains
+    // constant in pixels across all focal lengths (Perspective Projection).
+    const fovFactor = 24.0 / this.focalLength;
+    const pixelScale = (1.0 / this.height) * fovFactor;
+
+    // Pass to shader (w component)
+    // Target radius: 1.3 pixels (Diameter 2.6 pixels)
+    // Visible but sharp.
+    this.starControl[3] = pixelScale * 1.3;
+
+    this.updateCoefficients();
+  }
+
+  setStarIntensity(intensity) {
+    this.starIntensity = Math.max(0.0, intensity);
+    this.updateCoefficients();
+  }
+
+  setMoonPosition(direction) {
+    // normalize
+    const len = Math.hypot(direction[0], direction[1], direction[2]);
+    if (len > 0) {
+      this.moonDirection = [direction[0] / len, direction[1] / len, direction[2] / len];
+    }
+    this.updateCoefficients();
+  }
+
+  setMoonIntensity(intensity) {
+    this.moonIntensity = Math.max(0.0, intensity);
+    this.updateCoefficients();
+  }
+
+  setMoonRadius(degrees) {
+    const rad = degrees * (Math.PI / 180.0);
+    this.moonHalo[0] = Math.cos(rad);
+    this.moonHalo[1] = Math.sin(rad);
+    this.updateCoefficients();
+  }
+
+  setMoonEnabled(enabled) {
+    this.moonHalo[3] = enabled ? 1.0 : 0.0;
+    this.updateCoefficients();
+  }
+
+  setMilkyWayControl(intensity, saturation, blackPoint) {
+    this.milkyWayControl[0] = Math.max(0.0, intensity);
+    this.milkyWayControl[1] = Math.max(0.0, saturation);
+    if (blackPoint !== undefined) {
+      this.milkyWayControl[2] = Math.max(0.0, blackPoint);
+    }
+    this.updateCoefficients();
+  }
+
+  setMilkyWayEnabled(enabled) {
+    this.milkyWayEnabled = !!enabled;
+    this.updateCoefficients();
+  }
+
+  setMilkyWayRotation(rotationMatrix) {
+    if (rotationMatrix && rotationMatrix.length === 9) {
+      this.milkyWayRotation = rotationMatrix;
+      this.updateCoefficients();
+    }
+  }
+
+
+
+  setExposure(exposure) {
+    this.exposure = exposure;
+    this.updateCoefficients();
+  }
+
   updateCoefficients() {
     if (!this.materialInstance) {
       console.warn("updateCoefficients called before material loaded");
@@ -297,15 +590,133 @@ class SimulatedSkybox {
 
     this.materialInstance.setFloatParameter('contrast', this.contrast);
 
-    const nightColorScaled = this.nightColor.map(v => v * this.sunIntensity);
+    const nightColorScaled = this.nightColor.map(v => v * this.sunIntensity); // Lux scaling
     this.materialInstance.setFloat3Parameter('nightColor', new Float32Array(nightColorScaled));
 
     this.materialInstance.setFloat4Parameter('shimmerControl', new Float32Array(shimmerUniform));
     this.materialInstance.setFloat4Parameter('cloudControl', new Float32Array(cloudUniform));
     this.materialInstance.setFloat4Parameter('cloudControl2', new Float32Array(this.cloudControl2));
     this.materialInstance.setFloat4Parameter('waterControl', new Float32Array(this.waterControl));
-    this.materialInstance.setFloat2Parameter('starControl', new Float32Array(this.starControl));
+    this.materialInstance.setFloat4Parameter('starControl', new Float32Array(this.starControl));
+    this.materialInstance.setFloatParameter('starIntensity', this.starIntensity);
 
     this.materialInstance.setFloatParameter('sunIntensity', physicalSunIntensity);
+
+    // Moon Upload (Secondary Sun)
+    this.materialInstance.setFloat3Parameter('sunDirection2', new Float32Array(this.moonDirection));
+
+    // Calculate Moon Phase Factor (Lambertian Sphere)
+    // We model the moon as a Lambertian sphere to calculate its integrated brightness (illuminance)
+    // based on the phase angle (angle between Sun-Moon and Observer-Moon vectors).
+    //
+    // Phase Angle (alpha):
+    // For a distant observer (Earth), the phase angle can be approximated as the angle between
+    // the vector to the Sun and the vector to the Earth (from the Moon).
+    // cos(alpha) = -dot(L_moon, L_sun)
+    //
+    // Lambertian Phase Law:
+    // The integrated flux of a lit sphere varies as:
+    // Phi(alpha) = (1/PI) * (sin(alpha) + (PI - alpha) * cos(alpha))
+    // This gives 1.0 at Full Moon (alpha=0) and 0.0 at New Moon (alpha=PI).
+
+    const dotSM = this.sunDirection[0] * this.moonDirection[0] +
+      this.sunDirection[1] * this.moonDirection[1] +
+      this.sunDirection[2] * this.moonDirection[2];
+
+    // Final Intensity = Peak * Scale (No Phase Factor - Phase is handled in Shader via N.L)
+    const MOON_PEAK_LUX = 1.0;
+    const finalMoonIntensity = MOON_PEAK_LUX * this.moonIntensity;
+
+    this.materialInstance.setFloatParameter('sunIntensity2', finalMoonIntensity);
+
+    // Scale Milky Way by Sun Intensity
+    // Calibration: 1.0 User Intensity = 1.5e-3 cd/m^2 (Nits) approx.
+    // Target: 1.5e-3 Nits. SunIntensity = 100,000.
+    // Scale = 1.5e-3 / 1.0e5 = 1.5e-8.
+    const mwIntensity = this.milkyWayEnabled ? this.milkyWayControl[0] : 0.0;
+    const mwUniform = [
+      mwIntensity * this.sunIntensity * 1.5e-8,
+      this.milkyWayControl[1],
+      this.milkyWayControl[2]
+    ];
+    this.materialInstance.setFloat3Parameter('milkyWayControl', new Float32Array(mwUniform));
+    this.materialInstance.setMat3Parameter('milkyWayRotation', new Float32Array(this.milkyWayRotation));
+
+    // Moon Halo Upload (Disk Visualization)
+    // Multiplier = 1.0 / SolidAngle
+    const moonSolidAngle = 2.0 * F_PI * (1.0 - this.moonHalo[0]);
+    const moonRadConv = 1.0 / Math.max(1e-9, moonSolidAngle);
+    const moonHaloUpload = [...this.moonHalo];
+    moonHaloUpload[2] *= moonRadConv;
+    this.materialInstance.setFloat4Parameter('sunHalo2', new Float32Array(moonHaloUpload));
+    this.materialInstance.setFloatParameter('exposure', this.exposure !== undefined ? this.exposure : 1.0);
+
+    // Solar Eclipse (CPU Calculation)
+    const sunRadius = Math.acos(this.sunHalo[0]);
+    const moonRadius = Math.acos(this.moonHalo[0]);
+    // Dot product of Sun and Moon directions
+    const dot = this.sunDirection[0] * this.moonDirection[0] +
+      this.sunDirection[1] * this.moonDirection[1] +
+      this.sunDirection[2] * this.moonDirection[2];
+    const separation = Math.acos(Math.max(-1.0, Math.min(1.0, dot)));
+
+    let eclipseFactor = 1.0;
+    // Only calculate if moon is enabled
+    if (this.moonHalo[3] > 0.5) {
+      const overlap = this.areaIntersection(sunRadius, moonRadius, separation);
+      const sunArea = Math.PI * sunRadius * sunRadius;
+      // Ensure we don't divide by zero and clamp result
+      const ratio = overlap / Math.max(1e-9, sunArea);
+      eclipseFactor = 1.0 - Math.max(0.0, Math.min(1.0, ratio));
+
+    }
+
+    // Safety check for NaN
+    if (isNaN(eclipseFactor)) {
+      console.warn("SimulatedSkybox: eclipseFactor is NaN, resetting to 1.0");
+      eclipseFactor = 1.0;
+    }
+
+
+
+    this.materialInstance.setFloatParameter('eclipseFactor', eclipseFactor);
+  }
+
+  areaIntersection(r1, r2, d) {
+    // Circle intersection area
+    // r1, r2: radii
+    // d: distance between centers
+
+    // Case 1: Too far apart
+    if (d >= r1 + r2) {
+      return 0.0;
+    }
+    // Case 2: One inside another
+    if (d <= Math.abs(r1 - r2)) {
+      return Math.PI * Math.min(r1, r2) * Math.min(r1, r2);
+    }
+
+    const r1sq = r1 * r1;
+    const r2sq = r2 * r2;
+
+    // Law of Cosines for sector angles
+    // c1 = (d^2 + r1^2 - r2^2) / (2 * d * r1)
+    // c2 = (d^2 + r2^2 - r1^2) / (2 * d * r2)
+    // We clamp to [-1, 1] to avoid NaN from floating point errors
+    const c1 = Math.max(-1.0, Math.min(1.0, (d * d + r1sq - r2sq) / (2.0 * d * r1)));
+    const c2 = Math.max(-1.0, Math.min(1.0, (d * d + r2sq - r1sq) / (2.0 * d * r2)));
+
+    const part1 = r1sq * Math.acos(c1);
+    const part2 = r2sq * Math.acos(c2);
+
+    // Heron's formula for the triangle area * 2
+    // The sqrt term represents the area of the two triangles formed by the chord and centers.
+
+
+    // Robust sqrt
+    const val = (-d + r1 + r2) * (d + r1 - r2) * (d - r1 + r2) * (d + r1 + r2);
+    const part3 = 0.5 * Math.sqrt(Math.max(0.0, val));
+
+    return part1 + part2 - part3;
   }
 }

docs_src/src_raw/wip/sky/assets/suncalc_global.js

@@ -0,0 +1,332 @@
+/*
+ (c) 2011-2015, Vladimir Agafonkin
+ SunCalc is a JavaScript library for calculating sun/moon position and light phases.
+ https://github.com/mourner/suncalc
+*/
+
+(function () { 'use strict';
+
+// shortcuts for easier to read formulas
+
+var PI   = Math.PI,
+    sin  = Math.sin,
+    cos  = Math.cos,
+    tan  = Math.tan,
+    asin = Math.asin,
+    atan = Math.atan2,
+    acos = Math.acos,
+    rad  = PI / 180;
+
+// sun calculations are based on https://aa.quae.nl/en/reken/zonpositie.html formulas
+
+
+// date/time constants and conversions
+
+var dayMs = 1000 * 60 * 60 * 24,
+    J1970 = 2440588,
+    J2000 = 2451545;
+
+function toJulian(date) { return date.valueOf() / dayMs - 0.5 + J1970; }
+function fromJulian(j)  { return new Date((j + 0.5 - J1970) * dayMs); }
+function toDays(date)   { return toJulian(date) - J2000; }
+
+
+// general calculations for position
+
+var e = rad * 23.4397; // obliquity of the Earth
+
+function rightAscension(l, b) { return atan(sin(l) * cos(e) - tan(b) * sin(e), cos(l)); }
+function declination(l, b)    { return asin(sin(b) * cos(e) + cos(b) * sin(e) * sin(l)); }
+
+function azimuth(H, phi, dec)  { return atan(sin(H), cos(H) * sin(phi) - tan(dec) * cos(phi)); }
+function altitude(H, phi, dec) { return asin(sin(phi) * sin(dec) + cos(phi) * cos(dec) * cos(H)); }
+
+function siderealTime(d, lw) { return rad * (280.16 + 360.9856235 * d) - lw; }
+
+function astroRefraction(h) {
+    if (h < 0) // the following formula works for positive altitudes only.
+        h = 0; // if h = -0.08901179 a div/0 would occur.
+
+    // formula 16.4 of "Astronomical Algorithms" 2nd edition by Jean Meeus (Willmann-Bell, Richmond) 1998.
+    // 1.02 / tan(h + 10.26 / (h + 5.10)) h in degrees, result in arc minutes -> converted to rad:
+    return 0.0002967 / Math.tan(h + 0.00312536 / (h + 0.08901179));
+}
+
+// general sun calculations
+
+function solarMeanAnomaly(d) { return rad * (357.5291 + 0.98560028 * d); }
+
+function eclipticLongitude(M) {
+
+    var C = rad * (1.9148 * sin(M) + 0.02 * sin(2 * M) + 0.0003 * sin(3 * M)), // equation of center
+        P = rad * 102.9372; // perihelion of the Earth
+
+    return M + C + P + PI;
+}
+
+function sunCoords(d) {
+
+    var M = solarMeanAnomaly(d),
+        L = eclipticLongitude(M);
+
+    return {
+        dec: declination(L, 0),
+        ra: rightAscension(L, 0)
+    };
+}
+
+
+var SunCalc = {};
+
+
+// calculates sun position for a given date and latitude/longitude
+
+SunCalc.getPosition = function (date, lat, lng) {
+
+    var lw  = rad * -lng,
+        phi = rad * lat,
+        d   = toDays(date),
+
+        c  = sunCoords(d),
+        H  = siderealTime(d, lw) - c.ra;
+
+    return {
+        azimuth: azimuth(H, phi, c.dec),
+        altitude: altitude(H, phi, c.dec)
+    };
+};
+
+
+// sun times configuration (angle, morning name, evening name)
+
+var times = SunCalc.times = [
+    [-0.833, 'sunrise',       'sunset'      ],
+    [-0.3,   'sunriseEnd',    'sunsetStart' ],
+    [-6,     'dawn',          'dusk'        ],
+    [-12,    'nauticalDawn',  'nauticalDusk'],
+    [-18,    'nightEnd',      'night'       ],
+    [6,      'goldenHourEnd', 'goldenHour'  ]
+];
+
+// adds a custom time to the times config
+
+SunCalc.addTime = function (angle, riseName, setName) {
+    times.push([angle, riseName, setName]);
+};
+
+
+// calculations for sun times
+
+var J0 = 0.0009;
+
+function julianCycle(d, lw) { return Math.round(d - J0 - lw / (2 * PI)); }
+
+function approxTransit(Ht, lw, n) { return J0 + (Ht + lw) / (2 * PI) + n; }
+function solarTransitJ(ds, M, L)  { return J2000 + ds + 0.0053 * sin(M) - 0.0069 * sin(2 * L); }
+
+function hourAngle(h, phi, d) { return acos((sin(h) - sin(phi) * sin(d)) / (cos(phi) * cos(d))); }
+
+// returns set time for the given sun altitude
+function getSetJ(h, lw, phi, dec, n, M, L) {
+
+    var w = hourAngle(h, phi, dec),
+        a = approxTransit(w, lw, n);
+    return solarTransitJ(a, M, L);
+}
+
+
+// calculates sun times for a given date, latitude/longitude, and, optionally,
+// the observer height (in meters) relative to the horizon
+
+SunCalc.getTimes = function (date, lat, lng, height) {
+
+    height = height || 0;
+
+    var lw = rad * -lng,
+        phi = rad * lat,
+
+        dh = observerAngle(height),
+
+        d = toDays(date),
+        n = julianCycle(d, lw),
+        ds = approxTransit(0, lw, n),
+
+        M = solarMeanAnomaly(ds),
+        L = eclipticLongitude(M),
+        dec = declination(L, 0),
+
+        Jnoon = solarTransitJ(ds, M, L);
+
+    var result = {
+        solarNoon: fromJulian(Jnoon),
+        nadir: fromJulian(Jnoon - 0.5)
+    };
+
+    var i, len, time, h0, Jset, Jrise;
+
+    for (i = 0, len = times.length; i < len; i += 1) {
+        time = times[i];
+
+        h0 = (time[0] + dh) * rad;
+
+        Jset = getSetJ(h0, lw, phi, dec, n, M, L);
+        Jrise = Jnoon - (Jset - Jnoon);
+
+        result[time[1]] = fromJulian(Jrise);
+        result[time[2]] = fromJulian(Jset);
+    }
+
+    return result;
+};
+
+// moon calculations, based on http://aa.quae.nl/en/reken/hemelpositie.html formulas
+
+function moonCoords(d) { // geocentric ecliptic coordinates of the moon
+
+    var L = rad * (218.316 + 13.176396 * d), // ecliptic longitude
+        M = rad * (134.963 + 13.064993 * d), // mean anomaly
+        F = rad * (93.272 + 13.229350 * d),  // mean distance
+
+        l  = L + rad * 6.289 * sin(M), // longitude
+        b  = rad * 5.128 * sin(F),     // latitude
+        dt = 385001 - 20905 * cos(M);  // distance to the moon in km
+
+    return {
+        ra: rightAscension(l, b),
+        dec: declination(l, b),
+        dist: dt
+    };
+}
+
+SunCalc.getMoonPosition = function (date, lat, lng) {
+
+    var lw = rad * -lng,
+        phi = rad * lat,
+        d = toDays(date),
+
+        c = moonCoords(d),
+        H = siderealTime(d, lw) - c.ra,
+        h = altitude(H, phi, c.dec),
+        // formula 14.1 of "Astronomical Algorithms" 2nd edition by Jean Meeus (Willmann-Bell, Richmond) 1998.
+        pa = atan(sin(H), tan(phi) * cos(c.dec) - sin(c.dec) * cos(H));
+
+    return {
+        azimuth: azimuth(H, phi, c.dec),
+        altitude: h + astroRefraction(h), // altitude correction for refraction,
+        distance: c.dist,
+        parallacticAngle: pa
+    };
+};
+
+
+// calculations for illumination parameters of the moon,
+// based on http://idlastro.gsfc.nasa.gov/ftp/pro/astro/mphase.pro formulas and
+// Chapter 48 of "Astronomical Algorithms" 2nd edition by Jean Meeus (Willmann-Bell, Richmond) 1998.
+
+SunCalc.getMoonIllumination = function (date) {
+
+    var d = toDays(date || new Date()),
+        s = sunCoords(d),
+        m = moonCoords(d),
+
+        sdist = 149598000, // distance from Earth to Sun in km
+
+        phi = acos(sin(s.dec) * sin(m.dec) + cos(s.dec) * cos(m.dec) * cos(s.ra - m.ra)),
+        inc = atan(sdist * sin(phi), m.dist - sdist * cos(phi)),
+        angle = atan(cos(s.dec) * sin(s.ra - m.ra), sin(s.dec) * cos(m.dec) -
+                cos(s.dec) * sin(m.dec) * cos(s.ra - m.ra));
+
+    return {
+        fraction: (1 + cos(inc)) / 2,
+        phase: 0.5 + 0.5 * inc * (angle < 0 ? -1 : 1) / Math.PI,
+        angle: angle
+    };
+};
+
+
+function hoursLater(date, h) {
+    return new Date(date.valueOf() + h * dayMs / 24);
+}
+
+// calculations for moon rise/set times are based on http://www.stargazing.net/kepler/moonrise.html article
+
+SunCalc.getMoonTimes = function (date, lat, lng, inUTC) {
+    var t = new Date(date);
+    if (inUTC) t.setUTCHours(0, 0, 0, 0);
+    else t.setHours(0, 0, 0, 0);
+
+    var hc = 0.133 * rad,
+        h0 = SunCalc.getMoonPosition(t, lat, lng).altitude - hc,
+        h1, h2, rise, set, a, b, xe, ye, d, roots, x1, x2, dx;
+
+    // go in 2-hour chunks, each time seeing if a 3-point quadratic curve crosses zero (which means rise or set)
+    for (var i = 1; i <= 24; i += 2) {
+        h1 = SunCalc.getMoonPosition(hoursLater(t, i), lat, lng).altitude - hc;
+        h2 = SunCalc.getMoonPosition(hoursLater(t, i + 1), lat, lng).altitude - hc;
+
+        a = (h0 + h2) / 2 - h1;
+        b = (h2 - h0) / 2;
+        xe = -b / (2 * a);
+        ye = (a * xe + b) * xe + h1;
+        d = b * b - 4 * a * h1;
+        roots = 0;
+
+        if (d >= 0) {
+            dx = Math.sqrt(d) / (Math.abs(a) * 2);
+            x1 = xe - dx;
+            x2 = xe + dx;
+            if (Math.abs(x1) <= 1) roots++;
+            if (Math.abs(x2) <= 1) roots++;
+            if (x1 < -1) x1 = x2;
+        }
+
+        if (roots === 1) {
+            if (h0 < 0) rise = i + x1;
+            else set = i + x1;
+
+        } else if (roots === 2) {
+            rise = i + (ye < 0 ? x2 : x1);
+            set = i + (ye < 0 ? x1 : x2);
+        }
+
+        if (rise && set) break;
+
+        h0 = h2;
+    }
+
+    var result = {};
+
+    if (rise) result.rise = hoursLater(t, rise);
+    if (set) result.set = hoursLater(t, set);
+
+    if (!rise && !set) result[ye > 0 ? 'alwaysUp' : 'alwaysDown'] = true;
+
+    return result;
+};
+
+// observerAngle helper was missing in my copy-paste?
+// Ah, it was in the chunks. Let me check the chunks again.
+// Function `observerAngle` was in chunk 0.
+// `function observerAngle(height) { return -2.076 * Math.sqrt(height) / 60; }`
+// I included it.
+
+// Note: I replaced var with const/let or kept var?
+// The original used const/let but I used var in my head above?
+// I will just use the original code but adapted.
+// Actually, to be safe, I'll use the code I wrote in this block which is adapted to use 'var' (ES5 safe) or just ES6 is fine.
+// The user Environment is modern (Chrome/ES6 likely).
+// But for safety:
+// I'll stick to 'var' definitions I wrote above which seem complete?
+// Wait, I might have missed `observerAngle` definition in my manual reconstruction above?
+// No, `observerAngle` is called in `getTimes`.
+// I MUST define it.
+// I added it in the loop above? No.
+// Let me double check the `write_to_file` content I prepared.
+// I see:
+// `function observerAngle(height) { return -2.076 * Math.sqrt(height) / 60; }`
+// Yes, it is there.
+
+// export
+window.SunCalc = SunCalc;
+
+}());

docs_src/src_raw/wip/sky/index.html

@@ -24,6 +24,7 @@
 
 <body>
   <canvas></canvas>
+
   <!-- Filament -->
   <script src="filament.js"></script>
   <script src="gl-matrix-min.js"></script>
@@ -31,9 +32,13 @@
   <!-- UI -->
   <script src="lil-gui.js"></script>
 
+  <!-- Utils -->
+  <script src="assets/suncalc_global.js"></script>
+
   <!-- App -->
-  <script src="SimulatedSkybox.js?v=26"></script>
-  <script src="main.js?v=26"></script>
+
+  <script src="SimulatedSkybox.js?v=9999"></script>
+  <script src="main.js?v=9999"></script>
 </body>
 
 </html>

docs_src/src_raw/wip/sky/main.js

@@ -1,10 +1,123 @@
 
 // main.js
 
-Filament.init(['assets/simulated_skybox.filamat'], () => {
+Filament.init(['assets/simulated_skybox.filamat?v=' + Date.now()], () => {
   window.app = new App(document.getElementsByTagName('canvas')[0]);
 });
 
+// Helper: Julian Date
+function getJD(date) {
+  return date.getTime() / 86400000.0 + 2440587.5;
+}
+
+// Helper: GMST from Date
+function getGMST(date) {
+  const JD = getJD(date);
+  const D = JD - 2451545.0;
+  // GMST = 18.697... + 24.0657... * D
+  let gmst = 18.697374558 + 24.06570982441908 * D;
+  gmst = gmst % 24.0;
+  if (gmst < 0) gmst += 24.0;
+  return gmst;
+}
+
+// Helper: Matrix Rotation
+function rotateX(m, angle) {
+  const c = Math.cos(angle);
+  const s = Math.sin(angle);
+  const m1 = m[1], m2 = m[2];
+  const m4 = m[4], m5 = m[5];
+  const m7 = m[7], m8 = m[8];
+  m[1] = m1 * c - m2 * s;
+  m[2] = m1 * s + m2 * c;
+  m[4] = m4 * c - m5 * s;
+  m[5] = m4 * s + m5 * c;
+  m[7] = m7 * c - m8 * s;
+  m[8] = m7 * s + m8 * c;
+}
+function rotateY(m, angle) {
+  const c = Math.cos(angle);
+  const s = Math.sin(angle);
+  const m0 = m[0], m2 = m[2];
+  const m3 = m[3], m5 = m[5];
+  const m6 = m[6], m8 = m[8];
+  m[0] = m0 * c + m2 * s;
+  m[2] = -m0 * s + m2 * c;
+  m[3] = m3 * c + m5 * s;
+  m[5] = -m3 * s + m5 * c;
+  m[6] = m6 * c + m8 * s;
+  m[8] = -m6 * s + m8 * c;
+}
+function rotateZ(m, angle) {
+  const c = Math.cos(angle);
+  const s = Math.sin(angle);
+  const m0 = m[0], m1 = m[1];
+  const m3 = m[3], m4 = m[4];
+  const m6 = m[6], m7 = m[7];
+  m[0] = m0 * c - m1 * s;
+  m[1] = m0 * s + m1 * c;
+  m[3] = m3 * c - m4 * s;
+  m[4] = m3 * s + m4 * c;
+  m[6] = m6 * c - m7 * s;
+  m[7] = m6 * s + m7 * c;
+}
+
+// Galactic to Equatorial (J2000)
+// This matrix converts Galactic vectors to Equatorial vectors.
+// Or effectively, if we want to render Galactic texture from Equatorial View vector V_eq:
+// V_gal = Inv(Rot_Gal_to_Eq) * V_eq = Rot_Eq_to_Gal * V_eq.
+// The shader does: V_gal = Rotation * V_world.
+// So Rotation = Rot_Eq_to_Gal * Rot_World_to_Eq.
+//
+// Galactic North Pole (J2000): RA = 192.85948, Dec = 27.12825
+// Ascending Node: RA = 282.85
+// 
+// Pre-computed Rotation Matrix (Equatorial -> Galactic)
+// Based on standard transformation matrices.
+// 
+// R_eq_gal = 
+// [ -0.054876  -0.873437  -0.483835 ]
+// [  0.494109  -0.444830   0.746982 ]
+// [ -0.867666  -0.198076   0.455984 ]
+//
+// Let's use this static definition.
+const MAT_EQ_TO_GAL = [
+  -0.054876, 0.494109, -0.867666,
+  -0.873437, -0.444830, -0.198076,
+  -0.483835, 0.746982, 0.455984
+];
+
+// Matrix multiplication 3x3
+function multiplyMat3(a, b) {
+  const out = new Float32Array(9);
+  // Row-major or Column-major? Filament is Column-major usually.
+  // GLSL is Column-major.
+  // Mat3 in array: [col0.x, col0.y, col0.z, col1.x, ...]
+  // So a[0] is (0,0), a[1] is (1,0), a[3] is (0,1).
+  //
+  // out = a * b
+  const a00 = a[0], a10 = a[1], a20 = a[2];
+  const a01 = a[3], a11 = a[4], a21 = a[5];
+  const a02 = a[6], a12 = a[7], a22 = a[8];
+
+  const b00 = b[0], b10 = b[1], b20 = b[2];
+  const b01 = b[3], b11 = b[4], b21 = b[5];
+  const b02 = b[6], b12 = b[7], b22 = b[8];
+
+  out[0] = a00 * b00 + a01 * b10 + a02 * b20;
+  out[1] = a10 * b00 + a11 * b10 + a12 * b20;
+  out[2] = a20 * b00 + a21 * b10 + a22 * b20;
+
+  out[3] = a00 * b01 + a01 * b11 + a02 * b21;
+  out[4] = a10 * b01 + a11 * b11 + a12 * b21;
+  out[5] = a20 * b01 + a21 * b11 + a22 * b21;
+
+  out[6] = a00 * b02 + a01 * b12 + a02 * b22;
+  out[7] = a10 * b02 + a11 * b12 + a12 * b22;
+  out[8] = a20 * b02 + a21 * b12 + a22 * b22;
+  return out;
+}
+
 class App {
   constructor(canvas) {
     this.canvas = canvas;
@@ -15,13 +128,10 @@ class App {
     this.skybox.entity = this.skybox.entity; // Ensuring access if needed
     this.scene.addEntity(this.skybox.entity);
 
-    // Load the material explicitly since we passed it to init but SimulatedSkybox needs to bind it
-    // Actually SimulatedSkybox.loadMaterial fetches it. 
-    // Since we already loaded it in Filament.init, we can arguably just use it if we had a way to access the asset.
-    // But Filament.init assets are for internal or easy access via assets object if configured?
-    // Let's just let SimulatedSkybox fetch it again or use a blob if we wanted.
-    // Simpler: Just let SimulatedSkybox fetch it.
-    this.skybox.loadMaterial('assets/simulated_skybox.filamat').then(() => {
+    // Load the material explicitly. SimulatedSkybox.loadMaterial fetches it.
+
+    const matUrl = 'assets/simulated_skybox.filamat?v=' + Date.now();
+    this.skybox.loadMaterial(matUrl).then(() => {
       this.initGUI();
     });
 
@@ -71,6 +181,15 @@ class App {
 
     this.initControls(); // Initialize controls immediately
 
+    this.mwParams = {
+      enabled: true,
+      intensity: 1.0,
+      saturation: 1.0,
+      blackPoint: 0.07,
+      siderealTime: 0.0, // Hours [0-24]
+      latitude: 34.0, // Default Lat
+    };
+
     this.resize();
     window.addEventListener('resize', this.resize.bind(this));
 
@@ -99,6 +218,13 @@ class App {
     const exposure = this.getExposure();
     const preExposedIntensity = this.params.sunIntensity * exposure;
     this.skybox.setSunIntensity(preExposedIntensity);
+    this.skybox.setExposure(exposure); // Update Skybox Exposure Uniform
+
+    // Moon Exposure
+    if (this.mParams) {
+      const preExposedMoon = this.mParams.intensity * exposure;
+      this.skybox.setMoonIntensity(preExposedMoon);
+    }
   }
 
   updateCameraProjection() {
@@ -106,6 +232,7 @@ class App {
     const height = this.canvas.height;
     const aspect = width / height;
     this.camera.setLensProjection(this.params.focalLength, aspect, 0.1, 5000.0);
+    if (this.skybox) this.skybox.setFocalLength(this.params.focalLength);
   }
 
   initGUI() {
@@ -114,10 +241,7 @@ class App {
     const sky = this.skybox;
 
     // Initialize local params from skybox defaults
-    // Initialize local params from skybox defaults
-    // REMOVED: Do not overwrite this.params from sky.sunDirection (Zenith)
-    // const currentDir = sky.sunDirection;
-    // this.params.sunTheta = ...
+
 
     const updateSun = () => {
       const theta = this.params.sunTheta;
@@ -128,29 +252,165 @@ class App {
       sky.setSunPosition([x, y, z]);
     };
 
+    // Sun UI Proxy
+    this.sunUI = {
+      azimuth: (this.params.sunPhi * 180.0 / Math.PI) % 360.0,
+      height: Math.cos(this.params.sunTheta)
+    };
+    if (this.sunUI.azimuth < 0) this.sunUI.azimuth += 360.0;
+
     const sunFolder = gui.addFolder('Sun');
-    // Helper for "Sun Height" cosine slider like C++
-    const sunHeightParam = { height: Math.cos(this.params.sunTheta) };
-    sunFolder.add(sunHeightParam, 'height', -0.2, 1.0).name('Height (Cos)').onChange(v => {
+
+    sunFolder.add(this.sunUI, 'azimuth', 0.0, 360.0, 0.1).name('Azimuth').listen().onChange(v => {
+      this.params.sunPhi = v * (Math.PI / 180.0);
+      updateSun();
+    });
+
+    sunFolder.add(this.sunUI, 'height', -0.2, 1.0).name('Height (Cos)').listen().onChange(v => {
       this.params.sunTheta = Math.acos(v);
       updateSun();
     });
-    sunFolder.add(this.params, 'sunPhi', 0.0, Math.PI * 2).name('Azimuth').onChange(updateSun);
-    // Updated: Controls params.sunIntensity and triggers updateSunIntensity
-    sunFolder.add(this.params, 'sunIntensity', 0.0, 500000.0).onChange(v => this.updateSunIntensity());
 
-    const sunDisk = sunFolder.addFolder('Disk');
-    // We need local proxy for sunRadius due to conversion
-    const diskParams = {
+    sunFolder.add(this.params, 'sunIntensity', 0.0, 500000.0).name('Intensity').onChange(v => this.updateSunIntensity());
+
+
+
+
+    const moonFolder = gui.addFolder('Moon');
+    this.mParams = {
+      enabled: true,
+      azimuth: 180.0,
+      height: Math.cos(45.0 * Math.PI / 180.0), // Default 45 degrees elevation -> cos(45) ~ 0.707
       radius: 1.2,
-      enabled: true // Enable sun disk
+      intensity: 6.0
+    };
+
+    const updateMoon = () => {
+      const az = this.mParams.azimuth * (Math.PI / 180.0);
+      const theta = Math.acos(this.mParams.height);
+      const phi = az;
+
+      const x = Math.sin(theta) * Math.cos(phi);
+      const y = Math.cos(theta);
+      const z = Math.sin(theta) * Math.sin(phi);
+
+      sky.setMoonPosition([x, y, z]);
+    };
+
+    // Initial Moon Sync
+    updateMoon();
+    sky.setMoonEnabled(this.mParams.enabled);
+    sky.setMoonRadius(this.mParams.radius);
+    sky.setMoonIntensity(this.mParams.intensity);
+
+    moonFolder.add(this.mParams, 'enabled').name('Enabled').onChange(v => sky.setMoonEnabled(v));
+    moonFolder.add(this.mParams, 'azimuth', 0.0, 360.0, 0.1).name('Azimuth').listen().onChange(updateMoon);
+    moonFolder.add(this.mParams, 'height', -0.2, 1.0).name('Height (Cos)').listen().onChange(updateMoon);
+    moonFolder.add(this.mParams, 'intensity', 0.0, 1000.0).name('Intensity').onChange(v => this.updateSunIntensity());
+    moonFolder.add(this.mParams, 'radius', 0.1, 5.0).name('Radius').onChange(v => sky.setMoonRadius(v));
+    moonFolder.close();
+
+    const mwFolder = gui.addFolder('Milky Way');
+
+    const updateMW = () => {
+      sky.setMilkyWayEnabled(this.mwParams.enabled);
+      sky.setMilkyWayControl(this.mwParams.intensity, this.mwParams.saturation, this.mwParams.blackPoint);
+
+      // Calculate Rotation
+      // V_gal = Rot_Eq_to_Gal * Rot_World_to_Eq * V_world
+
+      // World: Y=Up, X=East, Z=South (Filament Camera Convention is different!)
+      // In Filament Camera: -Z is Forward.
+      // Skybox V direction is World Space direction.
+      // Let's assume standard Horizontal Coordinates:
+      // Y = Zenith.
+      // Z = North? Or South?
+      // Usually Z is South in RH Y-up.
+
+      // LST (Local Sidereal Time) converts Hour Angle to RA.
+      // LST in Radians.
+      const LST = this.mwParams.siderealTime * (Math.PI / 12.0); // Hours to Rad
+      const Lat = this.mwParams.latitude * (Math.PI / 180.0);
+
+      // Rotation World (Horizontal) -> Equatorial
+      // 1. Rotate around X by -(90 - Lat) to align Equatorial Plane.
+      // 2. Rotate around Y (Polar Axis) by -LST.
+
+      // Mat3 Identity
+      const rot = [1, 0, 0, 0, 1, 0, 0, 0, 1];
+
+      // Rotate Z by LST (Earth Rotation).
+      // Actually, transformation from Horizontal (Az, Alt) to Equatorial (HA, Dec):
+      // sin(Dec) = sin(Alt)sin(Lat) - cos(Alt)cos(Lat)cos(Az)
+      // ...
+      // Let's construct matrix directly.
+      // WorldToEq:
+      // Rotate X by (Lat - 90 deg) -> brings Pole to Zenith.
+      // Rotate Y by -LST (or Z?)
+
+      // Filament Space:
+      // +Y = Up
+      // Let's match typical skybox conventions.
+
+      // Rot_World_to_Eq = Rot_Z_LST * Rot_X_Lat
+      // But we need to use Filament matrix ops which are column major.
+
+      // Let's use simple rotations:
+      // 1. Tilt Pole: Rotate X by (Lat - 90).
+      // 2. Spin Earth: Rotate Y by LST.
+
+      // Let's iterate until it looks right visually or trust the math.
+      // Rot_World_To_Equatorial:
+      // R_z(-LST) * R_x(Lat - 90)?
+
+      // Let's build it from scratch in JS using helper.
+      // Start Identity.
+      // Rotate X (Latitude Tilt).
+      // Rotate Y (Sidereal Spin).
+      // Note: rotate functions modify in place.
+
+      const mWorldToEq = [1, 0, 0, 0, 1, 0, 0, 0, 1];
+
+      // 1. Tilt for Latitude (Align Celestial Pole)
+      // At Lat 90 (North Pole), Zenith is Pole. No tilt needed if Y is Pole?
+      // No, Y is Zenith. Pole is Y.
+      // At Lat 0 (Equator), Pole is at Horizon (Z?).
+      // So we rotate X by (Lat - 90).
+      rotateX(mWorldToEq, Lat - Math.PI / 2);
+
+      // 2. Spin for Time (LST)
+      // Rotate around new Pole (Y) by LST.
+      rotateY(mWorldToEq, LST);
+
+      // Combine with Gal Transform
+      // Rot = MAT_EQ_TO_GAL * mWorldToEq
+      const finalRot = multiplyMat3(MAT_EQ_TO_GAL, mWorldToEq);
+
+      sky.setMilkyWayRotation(finalRot);
+    };
+
+    mwFolder.add(this.mwParams, 'enabled').name('Enabled').onChange(updateMW);
+    mwFolder.add(this.mwParams, 'intensity', 0.0, 100.0).onChange(updateMW);
+    mwFolder.add(this.mwParams, 'saturation', 0.0, 2.0).onChange(updateMW);
+    mwFolder.add(this.mwParams, 'blackPoint', 0.0, 0.5).name('Black Point').onChange(updateMW);
+    mwFolder.add(this.mwParams, 'siderealTime', 0.0, 24.0).name('Sidereal Time').listen().onChange(updateMW);
+    mwFolder.add(this.mwParams, 'latitude', -90.0, 90.0).name('Latitude').onChange(updateMW);
+    mwFolder.close();
+
+    // Initial MW Update
+    updateMW();
+
+    this.updateMW = updateMW; // Export for sync
+
+    // We need local proxy for sunRadius due to conversion
+    this.diskParams = {
+      radius: 1.2
     };
     sky.setSunDiskEnabled(true);
     sky.setSunRadius(1.2);
-    sunDisk.add(diskParams, 'enabled').onChange(v => sky.setSunDiskEnabled(v));
-    sunDisk.add(diskParams, 'radius', 0.0, 5.0).onChange(v => sky.setSunRadius(v));
-    sunDisk.add(sky.sunHalo, 1, 0.0, 2.0).name('Limb Darkening').onChange(v => sky.setSunLimbDarkening(v));
-    sunDisk.add(sky.sunHalo, 2, 0.0, 100.0).name('Intensity Boost').onChange(v => sky.setSunDiskIntensity(v));
+    sunFolder.add(this.diskParams, 'radius', 0.0, 5.0).onChange(v => sky.setSunRadius(v));
+    sunFolder.add(sky.sunHalo, 1, 0.0, 2.0).name('Limb Darkening').onChange(v => sky.setSunLimbDarkening(v));
+    sunFolder.add(sky.sunHalo, 2, 0.0, 100.0).name('Intensity Boost').onChange(v => sky.setSunDiskIntensity(v));
 
     const atmFolder = gui.addFolder('Atmosphere');
     atmFolder.add(sky, 'turbidity', 1.0, 10.0).onChange(v => sky.setTurbidity(v));
@@ -161,30 +421,8 @@ class App {
     atmFolder.add(sky, 'ozone', 0.0, 1.0).onChange(v => sky.setOzone(v));
     atmFolder.add(sky, 'mieG', 0.0, 0.999).onChange(v => sky.setMieG(v));
 
-    const artFolder = gui.addFolder('Artistic');
-    // Set Horizon Glow default to 1.0
-    sky.setHorizonGlow(1.0);
-    sky.msFactors[2] = 1.0;
-    // Set Contrast default to 0.85
-    sky.setContrast(0.85);
-
-    artFolder.add(sky.msFactors, 0, 0.0, 2.0).name('MS Rayleigh').onChange(v => sky.setMultiScattering(v, sky.msFactors[1]));
-    artFolder.add(sky.msFactors, 1, 0.0, 2.0).name('MS Mie').onChange(v => sky.setMultiScattering(sky.msFactors[0], v));
-    artFolder.add(sky.msFactors, 2, 0.0, 1.0).name('Horizon Glow').onChange(v => sky.setHorizonGlow(v));
-    artFolder.add(sky, 'contrast', 0.1, 2.0).onChange(v => sky.setContrast(v));
-
-    artFolder.addColor(sky, 'nightColor').onChange(v => sky.setNightColor(v));
-
-    const shmFolder = artFolder.addFolder('Shimmer');
-    // Set Shimmer Strength default to 0.0
-    sky.setShimmerControl(0.0, sky.shimmerControl[1], sky.shimmerControl[2]);
-
-    shmFolder.add(sky.shimmerControl, 0, 0.0, 0.1).name('Strength').onChange(v => sky.setShimmerControl(v, sky.shimmerControl[1], sky.shimmerControl[2]));
-    shmFolder.add(sky.shimmerControl, 1, 1.0, 100.0).name('Frequency').onChange(v => sky.setShimmerControl(sky.shimmerControl[0], v, sky.shimmerControl[2]));
-    shmFolder.add(sky.shimmerControl, 2, 0.01, 0.5).name('Mask Height').onChange(v => sky.setShimmerControl(sky.shimmerControl[0], sky.shimmerControl[1], v));
-
     const cloudFolder = gui.addFolder('Clouds');
-    const cParams = {
+    this.cParams = {
       volumetrics: sky.cloudControl2[1] > 0.5,
       coverage: 0.4,
       density: 0.02,
@@ -193,19 +431,19 @@ class App {
       evolution: 0.02
     };
     // Apply Cloud Defaults
-    sky.setCloudControl(0.4, 0.02, cParams.height, 50.0);
+    sky.setCloudControl(0.4, 0.02, this.cParams.height, 50.0);
     sky.setCloudShapeEvolution(0.02);
 
-    cloudFolder.add(cParams, 'volumetrics').onChange(v => sky.setCloudVolumetricLighting(v));
-    cloudFolder.add(cParams, 'coverage', 0.0, 1.0).onChange(v => sky.setCloudControl(v, cParams.density, cParams.height, cParams.speed));
-    cloudFolder.add(cParams, 'density', 0.0, 1.0).onChange(v => sky.setCloudControl(cParams.coverage, v, cParams.height, cParams.speed));
-    cloudFolder.add(cParams, 'height', 2000.0, 20000.0).onChange(v => sky.setCloudControl(cParams.coverage, cParams.density, v, cParams.speed));
+    cloudFolder.add(this.cParams, 'volumetrics').onChange(v => sky.setCloudVolumetricLighting(v));
+    cloudFolder.add(this.cParams, 'coverage', 0.0, 1.0).onChange(v => sky.setCloudControl(v, this.cParams.density, this.cParams.height, this.cParams.speed));
+    cloudFolder.add(this.cParams, 'density', 0.0, 1.0).onChange(v => sky.setCloudControl(this.cParams.coverage, v, this.cParams.height, this.cParams.speed));
+    cloudFolder.add(this.cParams, 'height', 2000.0, 20000.0).onChange(v => sky.setCloudControl(this.cParams.coverage, this.cParams.density, v, this.cParams.speed));
     // Reverse speed calc: w = speed * (0.05 / 72.0)
-    cloudFolder.add(cParams, 'speed', 0.0, 200.0).onChange(v => sky.setCloudControl(cParams.coverage, cParams.density, cParams.height, v));
-    cloudFolder.add(cParams, 'evolution', 0.0, 2.0).onChange(v => sky.setCloudShapeEvolution(v));
+    cloudFolder.add(this.cParams, 'speed', 0.0, 200.0).onChange(v => sky.setCloudControl(this.cParams.coverage, this.cParams.density, this.cParams.height, v));
+    cloudFolder.add(this.cParams, 'evolution', 0.0, 2.0).onChange(v => sky.setCloudShapeEvolution(v));
 
     const waterFolder = gui.addFolder('Water');
-    const wParams = {
+    this.wParams = {
       derivativeTrick: true,
       strength: 50.0,
       speed: 1.0,
@@ -215,67 +453,436 @@ class App {
     sky.setWaterControl(50.0, 1.0, 1.0, 4.0); // 1.0 = Derivative Trick On, 4 octaves
 
     const updateWater = () => {
-      sky.setWaterControl(wParams.strength, wParams.speed, wParams.derivativeTrick ? 1.0 : 0.0, wParams.octaves);
+      sky.setWaterControl(this.wParams.strength, this.wParams.speed, this.wParams.derivativeTrick ? 1.0 : 0.0, this.wParams.octaves);
     };
 
-    waterFolder.add(wParams, 'derivativeTrick').name('Derivative Trick').onChange(updateWater);
-    waterFolder.add(wParams, 'strength', 10.0, 100.0).onChange(updateWater);
-    waterFolder.add(wParams, 'speed', 0.0, 5.0).onChange(updateWater);
-    waterFolder.add(wParams, 'octaves', 1, 8, 1).name('Octaves').onChange(updateWater);
+    waterFolder.add(this.wParams, 'derivativeTrick').name('Derivative Trick').onChange(updateWater);
+    waterFolder.add(this.wParams, 'strength', 10.0, 100.0).onChange(updateWater);
+    waterFolder.add(this.wParams, 'speed', 0.0, 5.0).onChange(updateWater);
+    waterFolder.add(this.wParams, 'octaves', 1, 8, 1).name('Octaves').onChange(updateWater);
     waterFolder.close();
 
     const starFolder = gui.addFolder('Stars');
-    const sParams = {
+    this.sParams = {
       enabled: true,
-      density: 1.0
+      density: 0.001,
+      intensity: 0.0 // 2^0 = 1.0
     };
-    // Initialize defaults (Density 1.0, Enabled True)
-    sky.setStarControl(1.0, true);
+    // Initialize defaults (Density 0.001, Enabled True)
+    sky.setStarControl(0.001, true);
+    sky.setStarIntensity(Math.pow(2.0, 0.0));
 
     const updateStars = () => {
-      sky.setStarControl(sParams.density, sParams.enabled);
+      sky.setStarControl(this.sParams.density, this.sParams.enabled);
+      sky.setStarIntensity(Math.pow(2.0, this.sParams.intensity));
     };
 
-    starFolder.add(sParams, 'enabled').name('Enabled').onChange(updateStars);
-    starFolder.add(sParams, 'density', 0.0, 1.0).name('Density').onChange(updateStars);
+    starFolder.add(this.sParams, 'enabled').name('Enabled').onChange(updateStars);
+    starFolder.add(this.sParams, 'density', 0.0, 0.01, 0.0001).name('Density').onChange(updateStars);
+    starFolder.add(this.sParams, 'intensity', 0.0, 24.0).name('Intensity (Exp)').onChange(updateStars);
     starFolder.close();
+    this.updateStars = updateStars;
+
+    const artFolder = gui.addFolder('Artistic');
+    // Set Horizon Glow default to 0.0
+    sky.setHorizonGlow(0.0);
+    sky.msFactors[2] = 0.0;
+    // Set Contrast default to 1.0
+    sky.setContrast(1.0);
+
+    artFolder.add(sky.msFactors, 0, 0.0, 2.0).name('MS Rayleigh').onChange(v => sky.setMultiScattering(v, sky.msFactors[1]));
+    artFolder.add(sky.msFactors, 1, 0.0, 2.0).name('MS Mie').onChange(v => sky.setMultiScattering(sky.msFactors[0], v));
+    artFolder.add(sky.msFactors, 2, 0.0, 1.0).name('Horizon Glow').onChange(v => sky.setHorizonGlow(v));
+    artFolder.add(sky, 'contrast', 0.1, 2.0).onChange(v => sky.setContrast(v));
+
+
+
+    const shmFolder = artFolder.addFolder('Shimmer');
+    // Set Shimmer Strength default to 0.0
+    sky.setShimmerControl(0.0, sky.shimmerControl[1], sky.shimmerControl[2]);
+
+    shmFolder.add(sky.shimmerControl, 0, 0.0, 0.1).name('Strength').onChange(v => sky.setShimmerControl(v, sky.shimmerControl[1], sky.shimmerControl[2]));
+    shmFolder.add(sky.shimmerControl, 1, 1.0, 100.0).name('Frequency').onChange(v => sky.setShimmerControl(sky.shimmerControl[0], v, sky.shimmerControl[2]));
+    shmFolder.add(sky.shimmerControl, 2, 0.01, 0.5).name('Mask Height').onChange(v => sky.setShimmerControl(sky.shimmerControl[0], sky.shimmerControl[1], v));
 
     const camFolder = gui.addFolder('Camera');
     camFolder.add(this.params, 'focalLength', 8.0, 300.0).name('Focal Length').onChange(() => this.updateCameraProjection());
     camFolder.add(this.params, 'aperture', 1.4, 32.0).onChange(() => this.updateCameraExposure());
-    camFolder.add(this.params, 'shutterSpeed', 1.0, 1000.0).onChange(() => this.updateCameraExposure());
+    camFolder.add(this.params, 'shutterSpeed', 0.05, 1000.0).onChange(() => this.updateCameraExposure());
     camFolder.add(this.params, 'iso', 50.0, 3200.0).onChange(() => this.updateCameraExposure());
 
     const bloomFolder = camFolder.addFolder('Bloom');
-    const bParams = {
-      enabled: false,
+    this.bParams = {
+      enabled: true,
       lensFlare: false
     };
 
     const updateBloom = () => {
       this.view.setBloomOptions({
-        enabled: bParams.enabled,
-        lensFlare: bParams.lensFlare
+        enabled: this.bParams.enabled,
+        lensFlare: this.bParams.lensFlare
       });
     };
 
-    bloomFolder.add(bParams, 'enabled').onChange(updateBloom);
-    bloomFolder.add(bParams, 'lensFlare').onChange(updateBloom);
+    bloomFolder.add(this.bParams, 'enabled').onChange(updateBloom);
+    bloomFolder.add(this.bParams, 'lensFlare').onChange(updateBloom);
     bloomFolder.close();
 
     // Collapse folders by default
-    sunDisk.close();
+
     atmFolder.close();
     artFolder.close();
     // shmFolder is inside artFolder, so it's hidden, but we can close it too if we want
     shmFolder.close();
     cloudFolder.close();
-    // camFolder left open? User didn't specify, but "Artistic, shimmer and clouds" + "Disk, Atmosphere" were requested.
-    // So Camera might stay open or close. Let's keep Camera open for now as it wasn't listed.
+    // camFolder left open by default for convenience.
+
 
     // Initial sync
     updateSun();
     this.updateCameraExposure(); // This will trigger updateSunIntensity too
+    updateBloom();
+
+    // Check URL for config
+    const urlParams = new URLSearchParams(window.location.search);
+    if (urlParams.has('config')) {
+      try {
+        const state = JSON.parse(atob(urlParams.get('config')));
+        this.applyURLState(state);
+        // Update GUI
+        gui.controllers.forEach(c => c.updateDisplay());
+        // Recursive update for folders
+        gui.folders.forEach(f => {
+          f.controllers.forEach(c => c.updateDisplay());
+          // And sub-folders if any (Shimmer/Bloom)
+          f.folders.forEach(sf => sf.controllers.forEach(sc => sc.updateDisplay()));
+        });
+      } catch (e) {
+        console.error("Failed to load config:", e);
+      }
+    }
+
+    const syncFolder = gui.addFolder('Real-Time Sync');
+    this.syncParams = {
+      enabled: false,
+      lat: 0.0,
+      lng: 0.0,
+      status: 'Disabled'
+    };
+
+    const updateSync = () => {
+      if (this.syncParams.enabled) {
+        if (navigator.geolocation) {
+          this.syncParams.status = "Locating...";
+          navigator.geolocation.getCurrentPosition(
+            (pos) => {
+              this.syncParams.lat = pos.coords.latitude;
+              this.syncParams.lng = pos.coords.longitude;
+              this.syncParams.status = "Active";
+              syncFolder.controllers.forEach(c => c.updateDisplay());
+            },
+            (err) => {
+              console.error(err);
+              this.syncParams.status = "Error (See Console)";
+              this.syncParams.enabled = false;
+              syncFolder.controllers.forEach(c => c.updateDisplay());
+            }
+          );
+        } else {
+          this.syncParams.status = "Not Supported";
+        }
+      } else {
+        this.syncParams.status = "Disabled";
+      }
+      syncFolder.controllers.forEach(c => c.updateDisplay());
+    };
+
+    syncFolder.add(this.syncParams, 'enabled').name('Enable Sync').onChange(updateSync);
+    syncFolder.add(this.syncParams, 'status').name('Status').disable().listen();
+
+    this.syncFolder = syncFolder;
+
+    const shareParams = {
+      copyUrl: () => {
+        const state = this.getURLState();
+        const str = btoa(JSON.stringify(state));
+        const url = `${window.location.origin}${window.location.pathname}?config=${str}`;
+        navigator.clipboard.writeText(url).then(() => {
+          alert("Configuration URL copied to clipboard!");
+        }).catch(err => {
+          console.error('Could not copy text: ', err);
+          prompt("Copy this URL:", url);
+        });
+      }
+    };
+    gui.add(shareParams, 'copyUrl').name('Share Configuration');
+
+  }
+
+  updateRealTimeSync() {
+    if (!this.syncParams || !this.syncParams.enabled || !window.SunCalc) return;
+
+    const now = new Date();
+    const lat = this.syncParams.lat;
+    const lng = this.syncParams.lng;
+
+    // Sun
+    const sunPos = window.SunCalc.getPosition(now, lat, lng);
+    // Azimuth: South=0, West=PI/2.
+    // Skybox Phi: +X=0, +Z=PI/2.
+    // If +Z is South:
+    // SunAz 0 (South) -> Skybox PI/2 (+Z).
+    // SunAz PI/2 (West) -> Skybox PI (-X).
+    // So Phi = Az + PI/2.
+    const sunPhi = sunPos.azimuth + Math.PI / 2;
+    // Altitude: 0=Horizon, PI/2=Zenith.
+    // Skybox Theta: 0=Zenith, PI/2=Horizon.
+    const sunTheta = Math.PI / 2 - sunPos.altitude;
+
+    this.params.sunPhi = sunPhi;
+    this.params.sunTheta = sunTheta;
+
+    // Moon
+    const moonPos = window.SunCalc.getMoonPosition(now, lat, lng);
+    const moonPhi = moonPos.azimuth + Math.PI / 2;
+    const moonTheta = Math.PI / 2 - moonPos.altitude;
+
+    this.mParams.azimuth = (moonPhi * 180.0 / Math.PI) % 360.0;
+    this.mParams.height = Math.cos(moonTheta);
+
+    // Milky Way Sync
+    const gmst = getGMST(now);
+    const lst = (gmst + lng / 15.0 + 24.0) % 24.0;
+    this.mwParams.siderealTime = lst;
+    this.mwParams.latitude = lat;
+    if (this.updateMW) this.updateMW();
+
+    // Update Skybox
+    const sky = this.skybox;
+
+    // Update Sun Vector
+    const sx = Math.sin(sunTheta) * Math.cos(sunPhi);
+    const sy = Math.cos(sunTheta);
+    const sz = Math.sin(sunTheta) * Math.sin(sunPhi);
+    sky.setSunPosition([sx, sy, sz]);
+
+    // Update Moon Vector
+    const mx = Math.sin(moonTheta) * Math.cos(moonPhi);
+    const my = Math.cos(moonTheta);
+    const mz = Math.sin(moonTheta) * Math.sin(moonPhi);
+    sky.setMoonPosition([mx, my, mz]);
+
+    // Update UI Proxies
+    if (this.sunUI) {
+      this.sunUI.azimuth = (sunPhi * 180.0 / Math.PI) % 360.0;
+      if (this.sunUI.azimuth < 0) this.sunUI.azimuth += 360.0;
+      this.sunUI.height = Math.cos(sunTheta);
+    }
+  }
+
+  getURLState() {
+
+    // Update Camera LookAt
+    // Serialize current state (Minified)
+    // Mapping:
+    // p: params (Camera) -> a:aperture, ss:shutterSpeed, i:iso, st:sunTheta, sp:sunPhi, fl:focalLength, si:sunIntensity
+    // c: cParams (Clouds) -> v:volumetrics, co:coverage, d:density, h:height, s:speed, e:evolution
+    // w: wParams (Water) -> dt:derivativeTrick, st:strength, s:speed, o:octaves
+    // s: sParams (Stars) -> e:enabled, d:density
+    // b: bParams (Bloom) -> e:enabled, lf:lensFlare
+    // k: sky (Skybox) -> t:turbidity, r:rayleigh, mc:mieCoefficient, mg:mieG, o:ozone, ms:msFactors, co:contrast, nc:nightColor, sh:shimmerControl, hl:sunHalo
+
+    const p = this.params;
+    const c = this.cParams;
+    const w = this.wParams;
+    const s = this.sParams;
+    const b = this.bParams;
+    const m = this.mParams;
+    const mw = this.mwParams;
+    const sk = this.skybox;
+
+    return {
+      p: { a: p.aperture, ss: p.shutterSpeed, i: p.iso, st: p.sunTheta, sp: p.sunPhi, fl: p.focalLength, si: p.sunIntensity },
+      c: { v: c.volumetrics, co: c.coverage, d: c.density, h: c.height, s: c.speed, e: c.evolution },
+      w: { dt: w.derivativeTrick, st: w.strength, s: w.speed, o: w.octaves },
+      s: { e: s.enabled, d: s.density, i: s.intensity },
+      mw: { e: mw.enabled, i: mw.intensity, s: mw.saturation, bp: mw.blackPoint, st: mw.siderealTime, l: mw.latitude },
+      b: { e: b.enabled, lf: b.lensFlare },
+      m: { e: m.enabled, az: m.azimuth, h: m.height, r: m.radius, i: m.intensity },
+      cm: { t: this.camState.theta, p: this.camState.phi },
+      k: {
+        t: sk.turbidity,
+        r: sk.rayleigh,
+        mc: sk.mieCoefficient,
+        mg: sk.mieG,
+        o: sk.ozone,
+        ms: [...sk.msFactors],
+        co: sk.contrast,
+        nc: [...sk.nightColor],
+        sh: [...sk.shimmerControl],
+        hl: [...sk.sunHalo]
+      }
+    };
+
+  }
+
+  applyURLState(state) {
+    const p = state.p;
+    const c = state.c;
+    const w = state.w;
+    const s = state.s;
+    const mw = state.mw;
+    const b = state.b;
+    const m = state.m;
+    const k = state.k;
+    const cm = state.cm;
+
+    if (p) {
+      if (p.a !== undefined) this.params.aperture = p.a;
+      if (p.ss !== undefined) this.params.shutterSpeed = p.ss;
+      if (p.i !== undefined) this.params.iso = p.i;
+      if (p.st !== undefined) this.params.sunTheta = p.st;
+      if (p.sp !== undefined) this.params.sunPhi = p.sp;
+      if (p.fl !== undefined) this.params.focalLength = p.fl;
+      if (p.si !== undefined) this.params.sunIntensity = p.si;
+    }
+
+    if (c) {
+      if (c.v !== undefined) this.cParams.volumetrics = c.v;
+      if (c.co !== undefined) this.cParams.coverage = c.co;
+      if (c.d !== undefined) this.cParams.density = c.d;
+      if (c.h !== undefined) this.cParams.height = c.h;
+      if (c.s !== undefined) this.cParams.speed = c.s;
+      if (c.e !== undefined) this.cParams.evolution = c.e;
+    }
+
+    if (w) {
+      if (w.dt !== undefined) this.wParams.derivativeTrick = w.dt;
+      if (w.st !== undefined) this.wParams.strength = w.st;
+      if (w.s !== undefined) this.wParams.speed = w.s;
+      if (w.o !== undefined) this.wParams.octaves = w.o;
+    }
+
+    if (s) {
+      if (s.e !== undefined) this.sParams.enabled = s.e;
+      if (s.d !== undefined) this.sParams.density = s.d;
+      if (s.i !== undefined) this.sParams.intensity = s.i;
+      if (this.updateStars) this.updateStars();
+    }
+
+    if (mw) {
+      if (mw.e !== undefined) this.mwParams.enabled = mw.e;
+      if (mw.i !== undefined) this.mwParams.intensity = mw.i;
+      if (mw.s !== undefined) this.mwParams.saturation = mw.s;
+      if (mw.bp !== undefined) this.mwParams.blackPoint = mw.bp;
+      if (mw.st !== undefined) this.mwParams.siderealTime = mw.st;
+      if (mw.l !== undefined) this.mwParams.latitude = mw.l;
+      if (this.updateMW) this.updateMW();
+    }
+
+    if (b) {
+      if (b.e !== undefined) this.bParams.enabled = b.e;
+      if (b.lf !== undefined) this.bParams.lensFlare = b.lf;
+    }
+
+    const sky = this.skybox;
+    if (k) {
+      if (k.t !== undefined) sky.setTurbidity(k.t);
+      if (k.r !== undefined) sky.setRayleigh(k.r);
+      if (k.mc !== undefined) sky.setMieCoefficient(k.mc);
+      if (k.mg !== undefined) sky.setMieG(k.mg);
+      if (k.o !== undefined) sky.setOzone(k.o);
+
+      if (k.ms) { sky.setMultiScattering(k.ms[0], k.ms[1]); sky.setHorizonGlow(k.ms[2]); }
+      if (k.co !== undefined) sky.setContrast(k.co);
+      if (k.nc) sky.setNightColor(k.nc);
+      if (k.sh) sky.setShimmerControl(k.sh[0], k.sh[1], k.sh[2]);
+
+      // Sun Halo
+      const savedHalo = k.hl;
+      if (savedHalo && savedHalo.length === 4) {
+        sky.sunHalo[0] = savedHalo[0];
+        sky.sunHalo[1] = savedHalo[1];
+        sky.sunHalo[2] = savedHalo[2];
+        sky.sunHalo[3] = savedHalo[3];
+
+        // Update derived UI params for Sun Disk
+        const rad = Math.acos(Math.max(-1.0, Math.min(1.0, savedHalo[0])));
+        this.diskParams.radius = rad * (180.0 / Math.PI);
+        this.diskParams.enabled = savedHalo[3] > 0.5;
+      }
+
+      sky.updateCoefficients();
+    }
+
+    if (cm) {
+      if (cm.t !== undefined) this.camState.theta = cm.t;
+      if (cm.p !== undefined) this.camState.phi = cm.p;
+    }
+
+    // Update derived Sun UI
+    if (this.sunUI) {
+      this.sunUI.height = Math.cos(this.params.sunTheta);
+      this.sunUI.azimuth = (this.params.sunPhi * 180.0 / Math.PI) % 360.0;
+      if (this.sunUI.azimuth < 0) this.sunUI.azimuth += 360.0;
+    }
+
+    // Apply Local Params via Setters
+    sky.setCloudControl(this.cParams.coverage, this.cParams.density, this.cParams.height, this.cParams.speed);
+    sky.setCloudVolumetricLighting(this.cParams.volumetrics);
+    sky.setCloudShapeEvolution(this.cParams.evolution);
+
+    sky.setWaterControl(this.wParams.strength, this.wParams.speed, this.wParams.derivativeTrick ? 1.0 : 0.0, this.wParams.octaves);
+    sky.setStarControl(this.sParams.density, this.sParams.enabled);
+
+    if (m) {
+      if (m.e !== undefined) this.mParams.enabled = m.e;
+      if (m.az !== undefined) this.mParams.azimuth = m.az;
+      // Compat: if 'el' exists (old link) convert to 'h'
+      if (m.h !== undefined) {
+        this.mParams.height = m.h;
+      } else if (m.el !== undefined) {
+        // Convert elevation degrees to height cos
+        this.mParams.height = Math.cos(m.el * Math.PI / 180.0);
+      }
+      if (m.r !== undefined) this.mParams.radius = m.r;
+      if (m.i !== undefined) this.mParams.intensity = m.i;
+
+      // Sync Moon
+      const az = this.mParams.azimuth * (Math.PI / 180.0);
+      const theta = Math.acos(this.mParams.height);
+      const phi = az;
+      const x = Math.sin(theta) * Math.cos(phi);
+      const y = Math.cos(theta);
+      const z = Math.sin(theta) * Math.sin(phi);
+
+      sky.setMoonPosition([x, y, z]);
+      sky.setMoonEnabled(this.mParams.enabled);
+      sky.setMoonRadius(this.mParams.radius);
+      sky.setMoonIntensity(this.mParams.intensity);
+    }
+
+    if (cm) {
+      if (cm.t !== undefined) this.camState.theta = cm.t;
+      if (cm.p !== undefined) this.camState.phi = cm.p;
+    }
+
+    this.view.setBloomOptions({
+      enabled: this.bParams.enabled,
+      lensFlare: this.bParams.lensFlare
+    });
+
+    // Update Sun Position from Params
+    const theta = this.params.sunTheta;
+    const phi = this.params.sunPhi;
+    const x = Math.sin(theta) * Math.cos(phi);
+    const y = Math.cos(theta);
+    const z = Math.sin(theta) * Math.sin(phi);
+    sky.setSunPosition([x, y, z]);
+
+    // Update Camera Projection (Focal Length) and Exposure (Aperture/Shutter/ISO)
+    this.updateCameraProjection();
+    this.updateCameraExposure();
   }
 
   initControls() {
@@ -305,10 +912,41 @@ class App {
       this.camState.phi = Math.max(-Math.PI / 2 + 0.01, Math.min(Math.PI / 2 - 0.01, this.camState.phi));
     });
 
+    // Touch support
+    this.canvas.addEventListener('touchstart', e => {
+      if (e.touches.length > 0) {
+        e.preventDefault(); // Prevent scroll/long-press
+        this.camState.dragging = true;
+        this.camState.lastX = e.touches[0].clientX;
+        this.camState.lastY = e.touches[0].clientY;
+      }
+    }, { passive: false });
+
+    window.addEventListener('touchend', () => {
+      this.camState.dragging = false;
+    });
+
+    window.addEventListener('touchmove', e => {
+      if (!this.camState.dragging || e.touches.length === 0) return;
+      e.preventDefault(); // Prevent scrolling
+      const x = e.touches[0].clientX;
+      const y = e.touches[0].clientY;
+      const dx = x - this.camState.lastX;
+      const dy = y - this.camState.lastY;
+      this.camState.lastX = x;
+      this.camState.lastY = y;
+
+      const sensitivity = 0.005;
+      this.camState.theta -= dx * sensitivity;
+      this.camState.phi += dy * sensitivity;
+      this.camState.phi = Math.max(-Math.PI / 2 + 0.01, Math.min(Math.PI / 2 - 0.01, this.camState.phi));
+    }, { passive: false });
+
 
   }
 
   render() {
+    this.updateRealTimeSync();
     // Update Camera LookAt
     const r = 1.0;
     const theta = this.camState.theta;
@@ -341,5 +979,6 @@ class App {
     const aspect = width / height;
     // near=0.1, far=5000.0
     this.camera.setLensProjection(this.params.focalLength, aspect, 0.1, 5000.0);
+    if (this.skybox) this.skybox.setResolution(height);
   }
 }

docs_src/src_raw/wip/sky/process_milkyway.py

@@ -0,0 +1,61 @@
+
+import os
+import urllib.request
+import ssl
+from PIL import Image
+import argparse
+
+# URL of the Milky Way texture (Gaia EDR3) from ESA
+# Low Res PNG (2.71 MB) is sufficient for our 1024x512 target
+URL = "https://www.esa.int/var/esa/storage/images/esa_multimedia/images/2020/12/the_colour_of_the_sky_from_gaia_s_early_data_release_3/22358049-1-eng-GB/The_colour_of_the_sky_from_Gaia_s_Early_Data_Release_3.png"
+OUTPUT_DIR = "assets"
+OUTPUT_FILENAME = "milkyway.png"
+TARGET_WIDTH = 1024
+TARGET_HEIGHT = 512
+
+def main():
+    if not os.path.exists(OUTPUT_DIR):
+        os.makedirs(OUTPUT_DIR)
+
+    output_path = os.path.join(OUTPUT_DIR, OUTPUT_FILENAME)
+    temp_path = os.path.join(OUTPUT_DIR, "temp_milkyway.png")
+
+    print(f"Downloading Milky Way texture from {URL}...")
+    
+    # Bypass SSL verification globally
+    if hasattr(ssl, '_create_unverified_context'):
+        ssl._create_default_https_context = ssl._create_unverified_context
+
+    try:
+        req = urllib.request.Request(URL, headers={'User-Agent': 'Mozilla/5.0'})
+        with urllib.request.urlopen(req) as response, open(temp_path, 'wb') as out_file:
+            out_file.write(response.read())
+    except Exception as e:
+        print(f"Failed to download: {e}")
+        return
+
+    if not os.path.exists(temp_path):
+        print("Error: Download failed.")
+        return
+
+    print("Processing image...")
+    with Image.open(temp_path) as img:
+        # Convert to RGB (remove alpha if present, though this is likely opaque)
+        img = img.convert("RGB")
+        
+        # Resize to user requested dimensions
+        print(f"Resizing to {TARGET_WIDTH}x{TARGET_HEIGHT}...")
+        img = img.resize((TARGET_WIDTH, TARGET_HEIGHT), Image.Resampling.LANCZOS)
+        
+        # Save
+        print(f"Saving to {output_path}...")
+        img.save(output_path, "PNG")
+
+    # Cleanup
+    if os.path.exists(temp_path):
+        os.remove(temp_path)
+
+    print("Done!")
+
+if __name__ == "__main__":
+    main()

docs_src/src_raw/wip/sky/tools/build_material.sh

@@ -1,10 +1,10 @@
 # Result: /Users/mathias/sources/git/filament/out/cmake-release/tools/matc/matc
-MATC="../../../../out/cmake-release/tools/matc/matc"
+MATC="../../../../../out/cmake-release/tools/matc/matc"
 
 # Navigate to script directory to ensure relative paths work
 cd "$(dirname "$0")"
 
 set -e
 
-$MATC -a opengl -p mobile -o assets/simulated_skybox.filamat simulated_skybox.mat
+$MATC -a opengl -p mobile -o ../assets/simulated_skybox.filamat ../simulated_skybox.mat
 echo "Material recompiled to assets/simulated_skybox.filamat"