@myned-ai/gsplat-flame-avatar-renderer 1.0.5 → 1.0.6

package/src/loaders/PlyLoader.js

@@ -1,10 +1,11 @@
 /**
- * PlyLoader
- * 
+ * PlyLoader - Loads and parses PLY format Gaussian Splat files
+ *
  * Derived from @mkkellogg/gaussian-splats-3d (MIT License)
  * https://github.com/mkkellogg/GaussianSplats3D
- * 
+ *
  * Simplified for FLAME avatar - only supports INRIAV1 PLY format.
+ * Provides both progressive streaming and file-based loading.
  */
 
 import { Vector3 } from 'three';
@@ -16,18 +17,35 @@ import { PlyParserUtils } from './PlyParserUtils.js';
 import { INRIAV1PlyParser } from './INRIAV1PlyParser.js';
 import { Constants, InternalLoadType, LoaderStatus } from '../enums/EngineConstants.js';
 import { fetchWithProgress, delayedExecute, nativePromiseWithExtractedComponents } from '../utils/Util.js';
+import { getLogger } from '../utils/Logger.js';
+import { ValidationError, NetworkError, ParseError, AssetLoadError } from '../errors/index.js';
+import { validateUrl, validateCallback, validateArrayBuffer } from '../utils/ValidationUtils.js';
+
+const logger = getLogger('PlyLoader');
 
 /**
- * Helper function to store chunks into a single buffer
+ * Store data chunks into a single ArrayBuffer
+ *
+ * Combines multiple downloaded chunks into a contiguous buffer for parsing.
+ * Reallocates buffer if needed to fit all chunks.
+ *
+ * @private
+ * @param {Array<{data: Uint8Array, sizeBytes: number}>} chunks - Array of data chunks
+ * @param {ArrayBuffer} [buffer] - Existing buffer to reuse (will reallocate if too small)
+ * @returns {ArrayBuffer} Buffer containing all chunk data
  */
 function storeChunksInBuffer(chunks, buffer) {
     let inBytes = 0;
-    for (let chunk of chunks) inBytes += chunk.sizeBytes;
+    for (let chunk of chunks) {
+        inBytes += chunk.sizeBytes;
+    }
 
+    // Reallocate if buffer doesn't exist or is too small
     if (!buffer || buffer.byteLength < inBytes) {
         buffer = new ArrayBuffer(inBytes);
     }
 
+    // Copy all chunks into buffer sequentially
     let offset = 0;
     for (let chunk of chunks) {
         new Uint8Array(buffer, offset, chunk.sizeBytes).set(chunk.data);
@@ -38,25 +56,103 @@ function storeChunksInBuffer(chunks, buffer) {
 }
 
 /**
- * Helper function to finalize splat data
+ * Finalize splat data into a SplatBuffer
+ *
+ * Converts UncompressedSplatArray into final optimized SplatBuffer format.
+ * Applies compression and optimization if requested.
+ *
+ * @private
+ * @param {UncompressedSplatArray} splatData - Parsed splat data
+ * @param {boolean} optimizeSplatData - Whether to optimize/compress the data
+ * @param {number} minimumAlpha - Minimum alpha threshold for splat culling
+ * @param {number} compressionLevel - Compression level (0-2)
+ * @param {number} sectionSize - Section size for partitioning
+ * @param {Vector3} sceneCenter - Center point of the scene
+ * @param {number} blockSize - Block size for spatial partitioning
+ * @param {number} bucketSize - Bucket size for sorting
+ * @returns {SplatBuffer} Finalized splat buffer ready for rendering
+ * @throws {ParseError} If splat data is invalid or finalization fails
  */
-function finalize$1(splatData, optimizeSplatData, minimumAlpha, compressionLevel, sectionSize, sceneCenter, blockSize, bucketSize) {
-    if (optimizeSplatData) {
-        const splatBufferGenerator = SplatBufferGenerator.getStandardGenerator(minimumAlpha, compressionLevel,
-                                                                               sectionSize, sceneCenter,
-                                                                               blockSize, bucketSize);
-        return splatBufferGenerator.generateFromUncompressedSplatArray(splatData);
-    } else {
-        return SplatBuffer.generateFromUncompressedSplatArrays([splatData], minimumAlpha, 0, new Vector3());
+function finalizeSplatData(splatData, optimizeSplatData, minimumAlpha, compressionLevel, sectionSize, sceneCenter, blockSize, bucketSize) {
+    try {
+        if (optimizeSplatData) {
+            const splatBufferGenerator = SplatBufferGenerator.getStandardGenerator(
+                minimumAlpha,
+                compressionLevel,
+                sectionSize,
+                sceneCenter,
+                blockSize,
+                bucketSize
+            );
+            return splatBufferGenerator.generateFromUncompressedSplatArray(splatData);
+        } else {
+            return SplatBuffer.generateFromUncompressedSplatArrays([splatData], minimumAlpha, 0, new Vector3());
+        }
+    } catch (error) {
+        throw new ParseError(
+            `Failed to finalize splat data: ${error.message}`,
+            'splatData',
+            error
+        );
     }
 }
 
+/**
+ * PlyLoader - Loads and parses PLY format Gaussian Splat files
+ *
+ * Supports both progressive streaming and complete file loading.
+ * Optimized for INRIAV1 PLY format used in FLAME avatars.
+ */
 export class PlyLoader {
 
+    /**
+     * Load PLY file from URL with progressive streaming support
+     *
+     * Downloads and parses PLY data progressively, enabling render during load.
+     * Supports both direct-to-buffer and array-based loading modes.
+     *
+     * @static
+     * @param {string} fileName - URL to the PLY file
+     * @param {Function} [onProgress] - Progress callback (percent, percentLabel, status)
+     * @param {boolean} [loadDirectoToSplatBuffer=false] - Load directly to SplatBuffer (faster but less flexible)
+     * @param {Function} [onProgressiveLoadSectionProgress] - Callback for progressive section updates
+     * @param {number} [minimumAlpha=1] - Minimum alpha threshold for splat culling
+     * @param {number} [compressionLevel=0] - Compression level (0=none, 1=medium, 2=high)
+     * @param {boolean} [optimizeSplatData=true] - Whether to optimize/compress splat data
+     * @param {number} [outSphericalHarmonicsDegree=0] - Spherical harmonics degree (0-3)
+     * @param {Object} [headers] - HTTP headers for fetch request
+     * @param {number} [sectionSize] - Section size for partitioning
+     * @param {Vector3} [sceneCenter] - Center point of the scene
+     * @param {number} [blockSize] - Block size for spatial partitioning
+     * @param {number} [bucketSize] - Bucket size for sorting
+     * @returns {Promise<SplatBuffer>} Loaded and parsed splat buffer
+     * @throws {ValidationError} If parameters are invalid
+     * @throws {NetworkError} If file download fails
+     * @throws {ParseError} If PLY parsing fails
+     * @throws {AssetLoadError} If asset loading fails
+     */
     static loadFromURL(fileName, onProgress, loadDirectoToSplatBuffer, onProgressiveLoadSectionProgress,
                        minimumAlpha, compressionLevel, optimizeSplatData = true, outSphericalHarmonicsDegree = 0,
                        headers, sectionSize, sceneCenter, blockSize, bucketSize) {
 
+        // Validate required parameters
+        try {
+            validateUrl(fileName);
+        } catch (error) {
+            logger.error('Invalid URL provided to loadFromURL', { fileName, error });
+            throw error;
+        }
+
+        // Validate optional callbacks
+        if (onProgress) {
+            validateCallback(onProgress, 'onProgress', false);
+        }
+        if (onProgressiveLoadSectionProgress) {
+            validateCallback(onProgressiveLoadSectionProgress, 'onProgressiveLoadSectionProgress', false);
+        }
+
+        logger.info('Loading PLY from URL', { fileName, optimizeSplatData, outSphericalHarmonicsDegree });
+
         let internalLoadType = loadDirectoToSplatBuffer ? InternalLoadType.DirectToSplatBuffer : InternalLoadType.DirectToSplatArray;
         if (optimizeSplatData) internalLoadType = InternalLoadType.DirectToSplatArray;
 
@@ -108,12 +204,28 @@ export class PlyLoader {
                 if (!headerLoaded) {
                     headerText += textDecoder.decode(chunkData);
                     if (PlyParserUtils.checkTextForEndHeader(headerText)) {
-                        // FLAME avatars use INRIAV1 format
-                        header = inriaV1PlyParser.decodeHeaderText(headerText);
-                        maxSplatCount = header.splatCount;
-                        readyToLoadSplatData = true;
-                        
-                        outSphericalHarmonicsDegree = Math.min(outSphericalHarmonicsDegree, header.sphericalHarmonicsDegree);
+                        // FLAME avatars use INRIAV1 format - parse header
+                        try {
+                            header = inriaV1PlyParser.decodeHeaderText(headerText);
+                            maxSplatCount = header.splatCount;
+                            readyToLoadSplatData = true;
+
+                            logger.debug('PLY header decoded', {
+                                splatCount: maxSplatCount,
+                                sphericalHarmonicsDegree: header.sphericalHarmonicsDegree
+                            });
+
+                            outSphericalHarmonicsDegree = Math.min(outSphericalHarmonicsDegree, header.sphericalHarmonicsDegree);
+                        } catch (error) {
+                            const parseError = new ParseError(
+                                `Failed to decode PLY header: ${error.message}`,
+                                'headerText',
+                                error
+                            );
+                            logger.error('Header parsing failed', parseError);
+                            loadPromise.reject(parseError);
+                            return;
+                        }
 
                         const shDescriptor = SplatBuffer.CompressionLevels[0].SphericalHarmonicsDegrees[outSphericalHarmonicsDegree];
                         const splatBufferSizeBytes = splatDataOffsetBytes + shDescriptor.BytesPerSplat * maxSplatCount;
@@ -159,14 +271,30 @@ export class PlyLoader {
                             const shDescriptor = SplatBuffer.CompressionLevels[0].SphericalHarmonicsDegrees[outSphericalHarmonicsDegree];
                             const outOffset = splatCount * shDescriptor.BytesPerSplat + splatDataOffsetBytes;
 
-                            if (internalLoadType === InternalLoadType.DirectToSplatBuffer) {
-                                inriaV1PlyParser.parseToUncompressedSplatBufferSection(header, 0, addedSplatCount - 1, dataToParse,
-                                                                                    0, directLoadBufferOut, outOffset,
-                                                                                    outSphericalHarmonicsDegree);
-                            } else {
-                                inriaV1PlyParser.parseToUncompressedSplatArraySection(header, 0, addedSplatCount - 1, dataToParse,
-                                                                                    0, standardLoadUncompressedSplatArray,
-                                                                                    outSphericalHarmonicsDegree);
+                            // Parse splat data with error handling
+                            try {
+                                if (internalLoadType === InternalLoadType.DirectToSplatBuffer) {
+                                    inriaV1PlyParser.parseToUncompressedSplatBufferSection(
+                                        header, 0, addedSplatCount - 1, dataToParse,
+                                        0, directLoadBufferOut, outOffset,
+                                        outSphericalHarmonicsDegree
+                                    );
+                                } else {
+                                    inriaV1PlyParser.parseToUncompressedSplatArraySection(
+                                        header, 0, addedSplatCount - 1, dataToParse,
+                                        0, standardLoadUncompressedSplatArray,
+                                        outSphericalHarmonicsDegree
+                                    );
+                                }
+                            } catch (error) {
+                                const parseError = new ParseError(
+                                    `Failed to parse splat data section: ${error.message}`,
+                                    'splatData',
+                                    error
+                                );
+                                logger.error('Splat data parsing failed', { splatCount, addedSplatCount, error });
+                                loadPromise.reject(parseError);
+                                return;
                             }
 
                             splatCount = newSplatCount;
@@ -222,40 +350,170 @@ export class PlyLoader {
                 }
             }
 
-            if (onProgress) onProgress(percent, percentLabel, LoaderStatus.Downloading);
+            // Progress callback with error isolation
+            if (onProgress) {
+                try {
+                    onProgress(percent, percentLabel, LoaderStatus.Downloading);
+                } catch (error) {
+                    logger.warn('Error in onProgress callback', error);
+                }
+            }
         };
 
-        if (onProgress) onProgress(0, '0%', LoaderStatus.Downloading);
-        return fetchWithProgress(fileName, localOnProgress, false, headers).then(() => {
-            if (onProgress) onProgress(0, '0%', LoaderStatus.Processing);
-            return loadPromise.promise.then((splatData) => {
-                if (onProgress) onProgress(100, '100%', LoaderStatus.Done);
+        // Initial progress callback
+        if (onProgress) {
+            try {
+                onProgress(0, '0%', LoaderStatus.Downloading);
+            } catch (error) {
+                logger.warn('Error in onProgress callback', error);
+            }
+        }
+
+        // Fetch and process the PLY file
+        return fetchWithProgress(fileName, localOnProgress, false, headers)
+            .then(() => {
+                if (onProgress) {
+                    try {
+                        onProgress(0, '0%', LoaderStatus.Processing);
+                    } catch (error) {
+                        logger.warn('Error in onProgress callback', error);
+                    }
+                }
+                return loadPromise.promise;
+            })
+            .then((splatData) => {
+                if (onProgress) {
+                    try {
+                        onProgress(100, '100%', LoaderStatus.Done);
+                    } catch (error) {
+                        logger.warn('Error in onProgress callback', error);
+                    }
+                }
+
+                logger.debug('PLY data loaded successfully', {
+                    internalLoadType,
+                    splatCount: splatData?.splatCount || 'unknown'
+                });
+
+                // Process based on load type
                 if (internalLoadType === InternalLoadType.DownloadBeforeProcessing) {
                     const chunkDatas = chunks.map((chunk) => chunk.data);
-                    return new Blob(chunkDatas).arrayBuffer().then((plyFileData) => {
-                        return PlyLoader.loadFromFileData(plyFileData, minimumAlpha, compressionLevel, optimizeSplatData,
-                                                          outSphericalHarmonicsDegree, sectionSize, sceneCenter, blockSize, bucketSize);
-                    });
+                    return new Blob(chunkDatas).arrayBuffer()
+                        .then((plyFileData) => {
+                            return PlyLoader.loadFromFileData(
+                                plyFileData, minimumAlpha, compressionLevel, optimizeSplatData,
+                                outSphericalHarmonicsDegree, sectionSize, sceneCenter, blockSize, bucketSize
+                            );
+                        })
+                        .catch((error) => {
+                            throw new AssetLoadError(
+                                `Failed to process downloaded PLY data: ${error.message}`,
+                                fileName,
+                                error
+                            );
+                        });
                 } else if (internalLoadType === InternalLoadType.DirectToSplatBuffer) {
                     return splatData;
                 } else {
                     return delayedExecute(() => {
-                        return finalize$1(splatData, optimizeSplatData, minimumAlpha, compressionLevel,
-                                        sectionSize, sceneCenter, blockSize, bucketSize);
+                        return finalizeSplatData(
+                            splatData, optimizeSplatData, minimumAlpha, compressionLevel,
+                            sectionSize, sceneCenter, blockSize, bucketSize
+                        );
                     });
                 }
+            })
+            .catch((error) => {
+                // Re-throw custom errors as-is
+                if (error instanceof ValidationError ||
+                    error instanceof NetworkError ||
+                    error instanceof ParseError ||
+                    error instanceof AssetLoadError) {
+                    logger.error('PLY loading failed', { fileName, errorCode: error.code });
+                    throw error;
+                }
+
+                // Wrap unexpected errors
+                logger.error('Unexpected error loading PLY', { fileName, error });
+                throw new AssetLoadError(
+                    `Unexpected error loading PLY file: ${error.message}`,
+                    fileName,
+                    error
+                );
             });
-        });
     }
 
+    /**
+     * Load PLY file from raw ArrayBuffer data
+     *
+     * Parses PLY data that has already been downloaded. Useful for loading
+     * from local files or when data is provided directly.
+     *
+     * @static
+     * @param {ArrayBuffer} plyFileData - Raw PLY file data as ArrayBuffer
+     * @param {number} [minimumAlpha=1] - Minimum alpha threshold for splat culling
+     * @param {number} [compressionLevel=0] - Compression level (0=none, 1=medium, 2=high)
+     * @param {boolean} [optimizeSplatData=true] - Whether to optimize/compress splat data
+     * @param {number} [outSphericalHarmonicsDegree=0] - Spherical harmonics degree (0-3)
+     * @param {number} [sectionSize] - Section size for partitioning
+     * @param {Vector3} [sceneCenter] - Center point of the scene
+     * @param {number} [blockSize] - Block size for spatial partitioning
+     * @param {number} [bucketSize] - Bucket size for sorting
+     * @returns {Promise<SplatBuffer>} Parsed and finalized splat buffer
+     * @throws {ValidationError} If plyFileData is invalid
+     * @throws {ParseError} If parsing fails
+     */
     static loadFromFileData(plyFileData, minimumAlpha, compressionLevel, optimizeSplatData, outSphericalHarmonicsDegree = 0,
                             sectionSize, sceneCenter, blockSize, bucketSize) {
+        // Validate input
+        try {
+            validateArrayBuffer(plyFileData, 'plyFileData');
+        } catch (error) {
+            logger.error('Invalid PLY file data', error);
+            return Promise.reject(error);
+        }
+
+        logger.info('Loading PLY from file data', {
+            sizeBytes: plyFileData.byteLength,
+            optimizeSplatData,
+            outSphericalHarmonicsDegree
+        });
+
         return delayedExecute(() => {
-            return PlyParser.parseToUncompressedSplatArray(plyFileData, outSphericalHarmonicsDegree);
+            try {
+                return PlyParser.parseToUncompressedSplatArray(plyFileData, outSphericalHarmonicsDegree);
+            } catch (error) {
+                throw new ParseError(
+                    `Failed to parse PLY file data: ${error.message}`,
+                    'plyFileData',
+                    error
+                );
+            }
         })
         .then((splatArray) => {
-            return finalize$1(splatArray, optimizeSplatData, minimumAlpha, compressionLevel,
-                            sectionSize, sceneCenter, blockSize, bucketSize);
+            logger.debug('PLY parsed successfully', {
+                splatCount: splatArray?.splatCount || 'unknown'
+            });
+
+            return finalizeSplatData(
+                splatArray, optimizeSplatData, minimumAlpha, compressionLevel,
+                sectionSize, sceneCenter, blockSize, bucketSize
+            );
+        })
+        .catch((error) => {
+            // Re-throw custom errors as-is
+            if (error instanceof ValidationError || error instanceof ParseError) {
+                logger.error('PLY file data loading failed', { errorCode: error.code });
+                throw error;
+            }
+
+            // Wrap unexpected errors
+            logger.error('Unexpected error loading PLY from file data', error);
+            throw new ParseError(
+                `Unexpected error parsing PLY data: ${error.message}`,
+                'plyFileData',
+                error
+            );
         });
     }
 }

package/src/materials/SplatMaterial.js

@@ -16,14 +16,9 @@ import { Constants } from '../enums/EngineConstants.js';
 
 export class SplatMaterial {
 
-    static buildVertexShaderBase(dynamicMode = false, enableOptionalEffects = false, maxSphericalHarmonicsDegree = 0, customVars = '', useFlame = true) {
-        let vertexShaderSource = ``;
-        if (useFlame == true) {
-            vertexShaderSource += `#define USE_FLAME`;
-        } else {
-            vertexShaderSource += `#define USE_SKINNING`;
-        }
-        vertexShaderSource += `
+    static buildVertexShaderBase(dynamicMode = false, enableOptionalEffects = false, maxSphericalHarmonicsDegree = 0, customVars = '') {
+        let vertexShaderSource = `#define USE_SKINNING
+
         precision highp float;
         #include <common>
 
@@ -755,6 +750,14 @@ export class SplatMaterial {
             'headBoneIndex': {
                 'type': 'f',
                 'value': -1.0
+            },
+            'eyeBlinkLeft': {
+                'type': 'f',
+                'value': 0.0
+            },
+            'eyeBlinkRight': {
+                'type': 'f',
+                'value': 0.0
             }
         };
         for (let i = 0; i < Constants.MaxScenes; i++) {
@@ -815,7 +818,7 @@ class SplatMaterial3D {
      * @return {THREE.ShaderMaterial}
      */
     static build(dynamicMode = false, enableOptionalEffects = false, antialiased = false, maxScreenSpaceSplatSize = 2048,
-                 splatScale = 1.0, pointCloudModeEnabled = false, maxSphericalHarmonicsDegree = 0, kernel2DSize = 0.3, useFlame = true) {
+                 splatScale = 1.0, pointCloudModeEnabled = false, maxSphericalHarmonicsDegree = 0, kernel2DSize = 0.3) {
 
         const customVertexVars = `
             uniform vec2 covariancesTextureSize;
@@ -834,7 +837,7 @@ class SplatMaterial3D {
         `;
 
         let vertexShaderSource = SplatMaterial.buildVertexShaderBase(dynamicMode, enableOptionalEffects,
-                                                                     maxSphericalHarmonicsDegree, customVertexVars, useFlame);
+                                                                     maxSphericalHarmonicsDegree, customVertexVars);
         vertexShaderSource += SplatMaterial3D.buildVertexShaderProjection(antialiased, enableOptionalEffects,
                                                                           maxScreenSpaceSplatSize, kernel2DSize);
         const fragmentShaderSource = SplatMaterial3D.buildFragmentShader();

package/src/materials/SplatMaterial3D.js

@@ -28,7 +28,7 @@ export class SplatMaterial3D {
      * @return {THREE.ShaderMaterial}
      */
     static build(dynamicMode = false, enableOptionalEffects = false, antialiased = false, maxScreenSpaceSplatSize = 2048,
-                 splatScale = 1.0, pointCloudModeEnabled = false, maxSphericalHarmonicsDegree = 0, kernel2DSize = 0.3, useFlame = true) {
+                 splatScale = 1.0, pointCloudModeEnabled = false, maxSphericalHarmonicsDegree = 0, kernel2DSize = 0.3, irisOcclusionConfig = null) {
 
         const customVertexVars = `
             uniform vec2 covariancesTextureSize;
@@ -46,11 +46,12 @@ export class SplatMaterial3D {
             }
         `;
 
+        // Add a varying for iris splats
         let vertexShaderSource = SplatMaterial.buildVertexShaderBase(dynamicMode, enableOptionalEffects,
-                                                                     maxSphericalHarmonicsDegree, customVertexVars, useFlame);
+                                         maxSphericalHarmonicsDegree, customVertexVars);
         vertexShaderSource += SplatMaterial3D.buildVertexShaderProjection(antialiased, enableOptionalEffects,
-                                                                          maxScreenSpaceSplatSize, kernel2DSize);
-        const fragmentShaderSource = SplatMaterial3D.buildFragmentShader();
+                                          maxScreenSpaceSplatSize, kernel2DSize);
+        const fragmentShaderSource = SplatMaterial3D.buildFragmentShader(irisOcclusionConfig);
 
         const uniforms = SplatMaterial.getUniforms(dynamicMode, enableOptionalEffects,
                                                    maxSphericalHarmonicsDegree, splatScale, pointCloudModeEnabled);
@@ -229,48 +230,92 @@ export class SplatMaterial3D {
         return vertexShaderSource;
     }
 
-    static buildFragmentShader() {
+    static buildFragmentShader(irisOcclusionConfig = null) {
         let fragmentShaderSource = `
             precision highp float;
             #include <common>
- 
-            uniform vec3 debugColor;
+
+            uniform float eyeBlinkLeft;
+            uniform float eyeBlinkRight;
 
             varying vec4 vColor;
             varying vec2 vUv;
             varying vec2 vPosition;
             varying vec2 vSplatIndex;
-
         `;
 
         fragmentShaderSource += `
             void main () {
-                // Compute the positional squared distance from the center of the splat to the current fragment.
                 float A = dot(vPosition, vPosition);
-                // Since the positional data in vPosition has been scaled by sqrt(8), the squared result will be
-                // scaled by a factor of 8. If the squared result is larger than 8, it means it is outside the ellipse
-                // defined by the rectangle formed by vPosition. It also means it's farther
-                // away than sqrt(8) standard deviations from the mean.
-
-                // if(vSplatIndex.x > 20000.0) discard;
-                // if (A > 8.0) discard;
-                vec3 color = vColor.rgb;
-
-                // Since the rendered splat is scaled by sqrt(8), the inverse covariance matrix that is part of
-                // the gaussian formula becomes the identity matrix. We're then left with (X - mean) * (X - mean),
-                // and since 'mean' is zero, we have X * X, which is the same as A:
-                float opacity = exp( -0.5*A) * vColor.a;
-                if(opacity < 1.0 / 255.0)
+                float opacity = exp(-0.5 * A) * vColor.a;
+                if (opacity < 1.0 / 255.0)
                     discard;
+                `;
+
+        // Generate iris occlusion code only if config exists
+        if (irisOcclusionConfig && (irisOcclusionConfig.right_iris || irisOcclusionConfig.left_iris)) {
+            fragmentShaderSource += `
+                float idx = vSplatIndex.x;
+                `;
+
+            // Generate right iris checks
+            if (irisOcclusionConfig.right_iris && irisOcclusionConfig.right_iris.length > 0) {
+                const rightConditions = irisOcclusionConfig.right_iris
+                    .map(([start, end]) => `(idx >= ${start}.0 && idx <= ${end}.0)`)
+                    .join(' ||\n                                   ');
+
+                fragmentShaderSource += `
+                // Check if this splat is part of right iris
+                bool isRightIris = ${rightConditions};
+                `;
+            } else {
+                fragmentShaderSource += `
+                bool isRightIris = false;
+                `;
+            }
+
+            // Generate left iris checks
+            if (irisOcclusionConfig.left_iris && irisOcclusionConfig.left_iris.length > 0) {
+                const leftConditions = irisOcclusionConfig.left_iris
+                    .map(([start, end]) => `(idx >= ${start}.0 && idx <= ${end}.0)`)
+                    .join(' ||\n                                  ');
+
+                fragmentShaderSource += `
+                // Check if this splat is part of left iris
+                bool isLeftIris = ${leftConditions};
+                `;
+            } else {
+                fragmentShaderSource += `
+                bool isLeftIris = false;
+                `;
+            }
+
+            fragmentShaderSource += `
+                float finalOpacity = opacity;
 
-                // uint a = uint(255);
-                // vec3 c = vec3(vSplatIndex.x / 256.0 / 256.0, float(uint(vSplatIndex.x / 256.0 )% a) / 256.0, float(uint(vSplatIndex.x)% a) / 256.0);
-                // gl_FragColor = vec4(c, 1.0);
-                gl_FragColor = vec4(color, opacity);
+                // Smooth fade: iris fades out as eye closes (blink increases)
+                // smoothstep(0.1, 0.5, blink) = 0 when blink<0.1, 1 when blink>0.5
+                if (isRightIris) {
+                    float fadeFactor = 1.0 - smoothstep(0.1, 0.5, eyeBlinkRight);
+                    finalOpacity = opacity * fadeFactor;
+                } else if (isLeftIris) {
+                    float fadeFactor = 1.0 - smoothstep(0.1, 0.5, eyeBlinkLeft);
+                    finalOpacity = opacity * fadeFactor;
+                }
 
+                if (finalOpacity < 1.0 / 255.0)
+                    discard;
 
+                gl_FragColor = vec4(vColor.rgb, finalOpacity);
             }
         `;
+        } else {
+            // No iris occlusion - simple rendering
+            fragmentShaderSource += `
+                gl_FragColor = vec4(vColor.rgb, opacity);
+            }
+        `;
+        }
 
         return fragmentShaderSource;
     }