@aura3d/rendering 2.0.4 → 3.0.0

package/dist/ShaderLibrary.js

@@ -94,6 +94,7 @@ uniform float u_metallic;
 uniform float u_roughness;
 uniform vec3 u_environmentColor;
 uniform float u_environmentIntensity;
+uniform float u_materialEnvironmentIntensity;
 uniform vec3 u_environmentSkyColor;
 uniform vec3 u_environmentHorizonColor;
 uniform vec3 u_environmentGroundColor;
@@ -141,6 +142,19 @@ uniform float u_pointShadowSlopeBias;
 uniform vec2 u_pointShadowTexelSize;
 uniform float u_pointShadowPcfSampleCount;
 uniform vec4 u_pointShadowPcfSamples[32];
+uniform sampler2D u_spotShadowMapTexture;
+uniform float u_spotShadowMapEnabled;
+uniform vec3 u_spotShadowLightPosition;
+uniform vec3 u_spotShadowLightDirection;
+uniform mat4 u_spotShadowMatrix;
+uniform vec2 u_spotShadowCone;
+uniform float u_spotShadowRange;
+uniform float u_spotShadowStrength;
+uniform float u_spotShadowBias;
+uniform float u_spotShadowSlopeBias;
+uniform vec2 u_spotShadowTexelSize;
+uniform float u_spotShadowPcfSampleCount;
+uniform vec4 u_spotShadowPcfSamples[32];
 uniform float u_outputColorSpace;
 uniform vec3 u_cameraPosition;
 uniform float u_environmentFogEnabled;
@@ -150,6 +164,9 @@ uniform float u_environmentFogNear;
 uniform float u_environmentFogFar;
 uniform float u_environmentFogDensity;
 uniform float u_environmentFogHeightFalloff;
+uniform float u_volumetricIntensity;
+uniform vec3 u_volumetricLightDirection;
+uniform vec3 u_volumetricLightColor;
 uniform float u_environmentFogHeightReference;
 uniform float u_environmentFogMaxOpacity;
 in vec3 v_normal;
@@ -228,6 +245,50 @@ float a3dPointShadowFactor(vec3 worldPosition, vec3 normal, vec3 lightDirection)
   float occlusion = totalWeight > 0.0 ? shadowed / totalWeight : 0.0;
   return mix(1.0, 1.0 - occlusion, clamp(u_pointShadowStrength, 0.0, 1.0));
 }
+float a3dSpotShadowFactor(vec3 worldPosition, vec3 normal, vec3 lightDirection) {
+  if (u_spotShadowMapEnabled < 0.5) return 1.0;
+  vec3 toFragment = worldPosition - u_spotShadowLightPosition;
+  float distanceToLight = max(length(toFragment), 0.0001);
+  if (distanceToLight > u_spotShadowRange) return 1.0;
+  vec3 coneAxis = u_spotShadowLightDirection / max(length(u_spotShadowLightDirection), 0.0001);
+  if (dot(toFragment / distanceToLight, coneAxis) < cos(u_spotShadowCone.x)) return 1.0;
+  vec4 lightPosition = u_spotShadowMatrix * vec4(worldPosition, 1.0);
+  vec3 projected = lightPosition.xyz / max(lightPosition.w, 0.0001);
+  vec2 uv = projected.xy * 0.5 + 0.5;
+  if (uv.x < 0.0 || uv.x > 1.0 || uv.y < 0.0 || uv.y > 1.0) return 1.0;
+  vec3 receiverNormal = normalize(normal);
+  vec3 receiverLightDirection = lightDirection / max(length(lightDirection), 0.0001);
+  float normalDotLight = clamp(abs(dot(receiverNormal, receiverLightDirection)), 0.0, 1.0);
+  // Shared bias-table policy: the same per-sample, tangent-scaled slope bias as the
+  // directional and point-cube paths. A centre-only bias under-compensates outer PCF
+  // taps on sloped receivers, so each tap scales by its own texel distance.
+  float slopeTangent = min(sqrt(max(1.0 - normalDotLight * normalDotLight, 0.0)) / max(normalDotLight, 0.05), 8.0);
+  float slopeTexelBias = slopeTangent * u_spotShadowSlopeBias * max(u_spotShadowTexelSize.x, u_spotShadowTexelSize.y);
+  float projectedDepth = projected.z * 0.5 + 0.5;
+  float shadowed = 0.0;
+  float totalWeight = 0.0;
+  int sampleCount = clamp(int(u_spotShadowPcfSampleCount), 1, 32);
+  for (int i = 0; i < 32; ++i) {
+    if (i >= sampleCount) break;
+    vec4 sampleData = u_spotShadowPcfSamples[i];
+    float weight = max(sampleData.z, 0.0);
+    vec2 offset = sampleData.xy * u_spotShadowTexelSize;
+    float storedDepth = texture(u_spotShadowMapTexture, uv + offset).r;
+    float sampleTexelDistance = max(1.0, length(sampleData.xy));
+    float receiverDepth = projectedDepth - u_spotShadowBias - slopeTexelBias * sampleTexelDistance;
+    shadowed += (receiverDepth > storedDepth ? 1.0 : 0.0) * weight;
+    totalWeight += weight;
+  }
+  float occlusion = totalWeight > 0.0 ? shadowed / totalWeight : 0.0;
+  return mix(1.0, 1.0 - occlusion, clamp(u_spotShadowStrength, 0.0, 1.0));
+}
+float a3dResolveSpotShadowOverride(float baseFactor, float kind, float shadowFlag, vec3 worldPosition, vec3 normal, vec3 lightDirection) {
+  // Spot-kind lights (kind == 2) sample the perspective spot map only when it is
+  // bound. Every gate term is 0 when no spot map is present, so mix() returns
+  // baseFactor exactly and scenes without spot lights render unchanged.
+  float spotGate = step(1.5, kind) * (1.0 - step(2.5, kind)) * step(0.5, u_spotShadowMapEnabled) * step(0.5, shadowFlag);
+  return mix(baseFactor, a3dSpotShadowFactor(worldPosition, normal, lightDirection), spotGate);
+}
 vec2 a3dEnvironmentEquirectUv(vec3 direction, float rotation) {
   vec3 d = normalize(direction);
   float u = atan(d.z, d.x) / 6.28318530718 + 0.5 + rotation;
@@ -282,7 +343,7 @@ vec3 a3dPbrEnvironmentDiffuseInput(vec3 normal) {
   float sampledEnvironmentWeight = step(0.0001, u_environmentMapTextureEnabled * u_environmentMapTextureIntensity);
   float diffuseEnvironmentLod = max(u_environmentMapTextureMipCount - 1.0, 0.0);
   vec3 sampledDiffuse = a3dPbrDecodeEnvironmentSample(a3dPbrEnvironmentSampleRaw(normal, diffuseEnvironmentLod));
-  return mix(environmentDiffuse, ambientEnvironment + sampledDiffuse * u_environmentMapTextureIntensity, sampledEnvironmentWeight);
+  return mix(environmentDiffuse, ambientEnvironment + sampledDiffuse * u_environmentMapTextureIntensity * u_materialEnvironmentIntensity, sampledEnvironmentWeight);
 }
 vec3 a3dPbrEnvironmentSpecularInput(vec3 normal, vec3 viewDirection, float roughness) {
   float proceduralEnvironmentWeight = step(0.0001, u_environmentMapIntensity);
@@ -304,7 +365,7 @@ vec3 a3dPbrEnvironmentSpecularInput(vec3 normal, vec3 viewDirection, float rough
   vec3 sampledSpecular = a3dPbrBoundHdrSpecularRadiance(a3dPbrDecodeEnvironmentSample(a3dPbrEnvironmentSampleRaw(reflectionDirection, environmentLod)));
   float nDotV = clamp(dot(normal, viewDirection), 0.0, 1.0);
   sampledSpecular = a3dPbrClampSampledSpecularEdgeEnergy(sampledSpecular, nDotV, clampedRoughness);
-  sampledSpecular *= u_environmentMapTextureSpecularIntensity * sampledEnvironmentWeight * mix(0.84, 0.58, clampedRoughness);
+  sampledSpecular *= u_environmentMapTextureSpecularIntensity * u_materialEnvironmentIntensity * sampledEnvironmentWeight * mix(0.84, 0.58, clampedRoughness);
   return proceduralSpecular + sampledSpecular;
 }
 vec2 a3dPbrEnvironmentBrdfInput(vec3 normal, vec3 viewDirection, float roughness) {
@@ -312,10 +373,16 @@ vec2 a3dPbrEnvironmentBrdfInput(vec3 normal, vec3 viewDirection, float roughness
   vec2 lut = texture(u_environmentBrdfLutTexture, vec2(nDotV, clamp(roughness, 0.0, 1.0))).rg;
   return mix(vec2(1.0, 0.0), lut, step(0.0001, u_environmentBrdfLutEnabled));
 }
+vec3 a3dLinearToSrgb(vec3 linear) {
+  vec3 clamped = max(linear, vec3(0.0));
+  vec3 low = clamped * 12.92;
+  vec3 high = 1.055 * pow(clamped, vec3(1.0 / 2.4)) - 0.055;
+  return mix(low, high, step(vec3(0.0031308), clamped));
+}
 vec3 a3dPbrEncodeOutput(vec3 linearColor) {
   vec3 color = max(linearColor, vec3(0.0));
   vec3 filmic = clamp((color * (2.51 * color + 0.03)) / (color * (2.43 * color + 0.59) + 0.14), vec3(0.0), vec3(1.0));
-  vec3 srgb = pow(filmic, vec3(1.0 / 2.2));
+  vec3 srgb = a3dLinearToSrgb(filmic);
   return mix(color, srgb, step(0.5, u_outputColorSpace));
 }
 void main() {
@@ -376,7 +443,7 @@ void main() {
       float inner = cos(spotShadowLayer.x * max(1.0 - spotShadowLayer.y, 0.001));
       attenuation *= smoothstep(outer, inner, cone);
     }
-    float shadowFactor = mix(1.0, kind > 0.5 && kind < 1.5 ? a3dPointShadowFactor(v_worldPosition, normal, lightDirection) : a3dForwardShadowFactor(v_worldPosition, normal, lightDirection), step(0.5, spotShadowLayer.z));
+    float shadowFactor = a3dResolveSpotShadowOverride(mix(1.0, kind > 0.5 && kind < 1.5 ? a3dPointShadowFactor(v_worldPosition, normal, lightDirection) : a3dForwardShadowFactor(v_worldPosition, normal, lightDirection), step(0.5, spotShadowLayer.z)), kind, spotShadowLayer.z, v_worldPosition, normal, lightDirection);
     shaded += a3dPbrDirectLight(normal, viewDirection, lightDirection, colorIntensity.rgb, colorIntensity.a * attenuation * shadowFactor, base, u_metallic, u_roughness, 1.0, vec3(1.0));
   }
   float alpha = u_baseColor.a * v_instanceColor.a;
@@ -395,10 +462,18 @@ precision highp float;
 layout(location = 0) in vec3 a_position;
 layout(location = 2) in vec2 a_uv;
 layout(location = 4) in vec4 a_color;
+layout(location = 8) in vec4 a_instanceMatrix0;
+layout(location = 9) in vec4 a_instanceMatrix1;
+layout(location = 10) in vec4 a_instanceMatrix2;
+layout(location = 11) in vec4 a_instanceMatrix3;
+layout(location = 12) in vec4 a_instanceColor;
 uniform mat4 u_modelViewProjection;
 uniform vec2 u_baseColorTextureOffset;
 uniform vec2 u_baseColorTextureScale;
 uniform float u_baseColorTextureRotation;
+uniform mat4 u_instanceMatrices[64];
+uniform float u_instanceCount;
+uniform float u_instanceAttributeMode;
 out vec2 v_uv;
 out vec4 v_vertexColor;
 void main() {
@@ -406,8 +481,19 @@ void main() {
   float c = cos(u_baseColorTextureRotation);
   float s = sin(u_baseColorTextureRotation);
   v_uv = vec2(scaledUv.x * c - scaledUv.y * s, scaledUv.x * s + scaledUv.y * c) + u_baseColorTextureOffset;
-  v_vertexColor = a_color;
-  gl_Position = u_modelViewProjection * vec4(a_position, 1.0);
+  // P2 instanced-GLB path (muse3jsparity-PRD): the u_instanceCount branch is
+  // taken only for items carrying instanceTransforms; every other draw keeps
+  // the legacy math bit-exact.
+  if (u_instanceCount > 0.5) {
+    int instanceIndex = clamp(gl_InstanceID, 0, max(int(u_instanceCount) - 1, 0));
+    mat4 attributeMatrix = mat4(a_instanceMatrix0, a_instanceMatrix1, a_instanceMatrix2, a_instanceMatrix3);
+    mat4 instanceMatrix = u_instanceAttributeMode > 0.5 ? attributeMatrix : u_instanceMatrices[instanceIndex];
+    v_vertexColor = a_color * a_instanceColor;
+    gl_Position = u_modelViewProjection * instanceMatrix * vec4(a_position, 1.0);
+  } else {
+    v_vertexColor = a_color;
+    gl_Position = u_modelViewProjection * vec4(a_position, 1.0);
+  }
 }
 `,
         fragment: `#version 300 es
@@ -508,6 +594,7 @@ uniform float u_baseColorTextureEnabled;
 uniform sampler2D u_normalTexture;
 uniform float u_normalTextureEnabled;
 uniform float u_normalScale;
+uniform float u_wrinkleStrength;
 uniform sampler2D u_metallicRoughnessTexture;
 uniform float u_metallicRoughnessTextureEnabled;
 uniform sampler2D u_occlusionTexture;
@@ -520,6 +607,7 @@ uniform float u_metallic;
 uniform float u_roughness;
 uniform vec3 u_environmentColor;
 uniform float u_environmentIntensity;
+uniform float u_materialEnvironmentIntensity;
 uniform vec3 u_environmentSkyColor;
 uniform vec3 u_environmentHorizonColor;
 uniform vec3 u_environmentGroundColor;
@@ -593,6 +681,19 @@ uniform float u_pointShadowSlopeBias;
 uniform vec2 u_pointShadowTexelSize;
 uniform float u_pointShadowPcfSampleCount;
 uniform vec4 u_pointShadowPcfSamples[32];
+uniform sampler2D u_spotShadowMapTexture;
+uniform float u_spotShadowMapEnabled;
+uniform vec3 u_spotShadowLightPosition;
+uniform vec3 u_spotShadowLightDirection;
+uniform mat4 u_spotShadowMatrix;
+uniform vec2 u_spotShadowCone;
+uniform float u_spotShadowRange;
+uniform float u_spotShadowStrength;
+uniform float u_spotShadowBias;
+uniform float u_spotShadowSlopeBias;
+uniform vec2 u_spotShadowTexelSize;
+uniform float u_spotShadowPcfSampleCount;
+uniform vec4 u_spotShadowPcfSamples[32];
 uniform float u_outputColorSpace;
 uniform vec3 u_cameraPosition;
 uniform float u_environmentFogEnabled;
@@ -602,6 +703,9 @@ uniform float u_environmentFogNear;
 uniform float u_environmentFogFar;
 uniform float u_environmentFogDensity;
 uniform float u_environmentFogHeightFalloff;
+uniform float u_volumetricIntensity;
+uniform vec3 u_volumetricLightDirection;
+uniform vec3 u_volumetricLightColor;
 uniform float u_environmentFogHeightReference;
 uniform float u_environmentFogMaxOpacity;
 in vec3 v_normal;
@@ -649,6 +753,17 @@ vec4 a3dPbrEnvironmentSampleRaw(vec3 direction, float lod) {
   vec4 cubeSample = textureLod(u_environmentCubeMapTexture, a3dEnvironmentCubeDirection(direction, u_environmentMapTextureRotation), lod);
   return mix(equirectSample, cubeSample, step(0.5, u_environmentCubeMapTextureEnabled));
 }
+/**
+ * Procedural wrinkle detail (E1 face-rig demo): high-frequency normal perturbation driven
+ * by u_wrinkleStrength, which the engine resolves per frame from live morph weights
+ * (resolveWrinkleMapStrength). Stable in world space (no time input); strength 0 uploads
+ * 0 and the guarded call site below leaves the normal bit-identical.
+ */
+vec3 a3dWrinkleDetail(vec3 p) {
+  float f = sin(p.x * 230.0) * sin(p.y * 197.0 + 1.7) * sin(p.z * 211.0 + 0.6);
+  float g = sin(p.x * 97.0 + 0.4) * sin(p.y * 113.0 + 2.1) * sin(p.z * 103.0 + 1.2);
+  return vec3(f, g, f * g) * 0.35;
+}
 vec3 a3dSkinnedPbrNormal(vec3 baseNormal, vec4 tangentFrame, vec2 uv) {
   vec3 sampled = texture(u_normalTexture, uv).xyz * 2.0 - 1.0;
   vec3 n = normalize(baseNormal);
@@ -744,15 +859,68 @@ float a3dPointShadowFactor(vec3 worldPosition, vec3 normal, vec3 lightDirection)
   float occlusion = totalWeight > 0.0 ? shadowed / totalWeight : 0.0;
   return mix(1.0, 1.0 - occlusion, clamp(u_pointShadowStrength, 0.0, 1.0));
 }
+float a3dSpotShadowFactor(vec3 worldPosition, vec3 normal, vec3 lightDirection) {
+  if (u_spotShadowMapEnabled < 0.5) return 1.0;
+  vec3 toFragment = worldPosition - u_spotShadowLightPosition;
+  float distanceToLight = max(length(toFragment), 0.0001);
+  if (distanceToLight > u_spotShadowRange) return 1.0;
+  vec3 coneAxis = u_spotShadowLightDirection / max(length(u_spotShadowLightDirection), 0.0001);
+  if (dot(toFragment / distanceToLight, coneAxis) < cos(u_spotShadowCone.x)) return 1.0;
+  vec4 lightPosition = u_spotShadowMatrix * vec4(worldPosition, 1.0);
+  vec3 projected = lightPosition.xyz / max(lightPosition.w, 0.0001);
+  vec2 uv = projected.xy * 0.5 + 0.5;
+  if (uv.x < 0.0 || uv.x > 1.0 || uv.y < 0.0 || uv.y > 1.0) return 1.0;
+  vec3 receiverNormal = normalize(normal);
+  vec3 receiverLightDirection = lightDirection / max(length(lightDirection), 0.0001);
+  float normalDotLight = clamp(abs(dot(receiverNormal, receiverLightDirection)), 0.0, 1.0);
+  // Shared bias-table policy: the same per-sample, tangent-scaled slope bias as the
+  // directional and point-cube paths. A centre-only bias under-compensates outer PCF
+  // taps on sloped receivers, so each tap scales by its own texel distance.
+  float slopeTangent = min(sqrt(max(1.0 - normalDotLight * normalDotLight, 0.0)) / max(normalDotLight, 0.05), 8.0);
+  float slopeTexelBias = slopeTangent * u_spotShadowSlopeBias * max(u_spotShadowTexelSize.x, u_spotShadowTexelSize.y);
+  float projectedDepth = projected.z * 0.5 + 0.5;
+  float shadowed = 0.0;
+  float totalWeight = 0.0;
+  int sampleCount = clamp(int(u_spotShadowPcfSampleCount), 1, 32);
+  for (int i = 0; i < 32; ++i) {
+    if (i >= sampleCount) break;
+    vec4 sampleData = u_spotShadowPcfSamples[i];
+    float weight = max(sampleData.z, 0.0);
+    vec2 offset = sampleData.xy * u_spotShadowTexelSize;
+    float storedDepth = texture(u_spotShadowMapTexture, uv + offset).r;
+    float sampleTexelDistance = max(1.0, length(sampleData.xy));
+    float receiverDepth = projectedDepth - u_spotShadowBias - slopeTexelBias * sampleTexelDistance;
+    shadowed += (receiverDepth > storedDepth ? 1.0 : 0.0) * weight;
+    totalWeight += weight;
+  }
+  float occlusion = totalWeight > 0.0 ? shadowed / totalWeight : 0.0;
+  return mix(1.0, 1.0 - occlusion, clamp(u_spotShadowStrength, 0.0, 1.0));
+}
+float a3dResolveSpotShadowOverride(float baseFactor, float kind, float shadowFlag, vec3 worldPosition, vec3 normal, vec3 lightDirection) {
+  // Spot-kind lights (kind == 2) sample the perspective spot map only when it is
+  // bound. Every gate term is 0 when no spot map is present, so mix() returns
+  // baseFactor exactly and scenes without spot lights render unchanged.
+  float spotGate = step(1.5, kind) * (1.0 - step(2.5, kind)) * step(0.5, u_spotShadowMapEnabled) * step(0.5, shadowFlag);
+  return mix(baseFactor, a3dSpotShadowFactor(worldPosition, normal, lightDirection), spotGate);
+}
+vec3 a3dLinearToSrgb(vec3 linear) {
+  vec3 clamped = max(linear, vec3(0.0));
+  vec3 low = clamped * 12.92;
+  vec3 high = 1.055 * pow(clamped, vec3(1.0 / 2.4)) - 0.055;
+  return mix(low, high, step(vec3(0.0031308), clamped));
+}
 vec3 a3dPbrEncodeOutput(vec3 linearColor) {
   vec3 color = max(linearColor, vec3(0.0));
   vec3 filmic = clamp((color * (2.51 * color + 0.03)) / (color * (2.43 * color + 0.59) + 0.14), vec3(0.0), vec3(1.0));
-  vec3 srgb = pow(filmic, vec3(1.0 / 2.2));
+  vec3 srgb = a3dLinearToSrgb(filmic);
   return mix(color, srgb, step(0.5, u_outputColorSpace));
 }
 void main() {
   vec3 normal = normalize(v_normal);
   normal = mix(normal, a3dSkinnedPbrNormal(v_normal, v_tangent, v_uv), step(0.5, u_normalTextureEnabled));
+  if (u_wrinkleStrength > 0.0) {
+    normal = normalize(normal + u_wrinkleStrength * a3dWrinkleDetail(v_worldPosition));
+  }
   if (!gl_FrontFacing) normal = -normal;
   vec3 viewDirection = normalize(u_cameraPosition - v_worldPosition);
   vec4 sampledBaseColor = texture(u_baseColorTexture, v_uv);
@@ -822,11 +990,11 @@ void main() {
   float nDotV = clamp(dot(normal, viewDirection), 0.0, 1.0);
   vec2 brdfLut = texture(u_environmentBrdfLutTexture, vec2(nDotV, clampedRoughness)).rg;
   sampledSpecular = a3dPbrClampSampledSpecularEdgeEnergy(sampledSpecular, nDotV, clampedRoughness);
-  sampledSpecular *= u_environmentMapTextureSpecularIntensity * sampledEnvironmentWeight * mix(1.1, 0.65, roughness);
+  sampledSpecular *= u_environmentMapTextureSpecularIntensity * u_materialEnvironmentIntensity * sampledEnvironmentWeight * mix(1.1, 0.65, roughness);
   vec3 shaded = a3dPbrEnvironmentLightSplitSum(
     normal,
     viewDirection,
-    mix(environmentDiffuse, ambientEnvironment + sampledDiffuse * u_environmentMapTextureIntensity, sampledEnvironmentWeight),
+    mix(environmentDiffuse, ambientEnvironment + sampledDiffuse * u_environmentMapTextureIntensity * u_materialEnvironmentIntensity, sampledEnvironmentWeight),
     proceduralSpecular + sampledSpecular,
     mix(vec2(1.0, 0.0), brdfLut, step(0.0001, u_environmentBrdfLutEnabled)),
     materialBase,
@@ -881,7 +1049,7 @@ void main() {
       viewDirection,
       lightDirection,
       colorIntensity.rgb,
-      colorIntensity.a * attenuation * mix(1.0, kind > 0.5 && kind < 1.5 ? a3dPointShadowFactor(v_worldPosition, normal, lightDirection) : a3dForwardShadowFactor(v_worldPosition, normal, lightDirection), step(0.5, spotShadowLayer.z)),
+      colorIntensity.a * attenuation * a3dResolveSpotShadowOverride(mix(1.0, kind > 0.5 && kind < 1.5 ? a3dPointShadowFactor(v_worldPosition, normal, lightDirection) : a3dForwardShadowFactor(v_worldPosition, normal, lightDirection), step(0.5, spotShadowLayer.z)), kind, spotShadowLayer.z, v_worldPosition, normal, lightDirection),
       materialBase,
       metallic,
       roughness,
@@ -987,6 +1155,7 @@ uniform float u_baseColorTextureEnabled;
 uniform sampler2D u_normalTexture;
 uniform float u_normalTextureEnabled;
 uniform float u_normalScale;
+uniform float u_wrinkleStrength;
 uniform sampler2D u_metallicRoughnessTexture;
 uniform float u_metallicRoughnessTextureEnabled;
 uniform sampler2D u_occlusionTexture;
@@ -999,6 +1168,7 @@ uniform float u_metallic;
 uniform float u_roughness;
 uniform vec3 u_environmentColor;
 uniform float u_environmentIntensity;
+uniform float u_materialEnvironmentIntensity;
 uniform vec3 u_environmentSkyColor;
 uniform vec3 u_environmentHorizonColor;
 uniform vec3 u_environmentGroundColor;
@@ -1072,6 +1242,19 @@ uniform float u_pointShadowSlopeBias;
 uniform vec2 u_pointShadowTexelSize;
 uniform float u_pointShadowPcfSampleCount;
 uniform vec4 u_pointShadowPcfSamples[32];
+uniform sampler2D u_spotShadowMapTexture;
+uniform float u_spotShadowMapEnabled;
+uniform vec3 u_spotShadowLightPosition;
+uniform vec3 u_spotShadowLightDirection;
+uniform mat4 u_spotShadowMatrix;
+uniform vec2 u_spotShadowCone;
+uniform float u_spotShadowRange;
+uniform float u_spotShadowStrength;
+uniform float u_spotShadowBias;
+uniform float u_spotShadowSlopeBias;
+uniform vec2 u_spotShadowTexelSize;
+uniform float u_spotShadowPcfSampleCount;
+uniform vec4 u_spotShadowPcfSamples[32];
 uniform float u_outputColorSpace;
 uniform vec3 u_cameraPosition;
 uniform float u_environmentFogEnabled;
@@ -1081,6 +1264,9 @@ uniform float u_environmentFogNear;
 uniform float u_environmentFogFar;
 uniform float u_environmentFogDensity;
 uniform float u_environmentFogHeightFalloff;
+uniform float u_volumetricIntensity;
+uniform vec3 u_volumetricLightDirection;
+uniform vec3 u_volumetricLightColor;
 uniform float u_environmentFogHeightReference;
 uniform float u_environmentFogMaxOpacity;
 in vec3 v_normal;
@@ -1128,6 +1314,17 @@ vec4 a3dPbrEnvironmentSampleRaw(vec3 direction, float lod) {
   vec4 cubeSample = textureLod(u_environmentCubeMapTexture, a3dEnvironmentCubeDirection(direction, u_environmentMapTextureRotation), lod);
   return mix(equirectSample, cubeSample, step(0.5, u_environmentCubeMapTextureEnabled));
 }
+/**
+ * Procedural wrinkle detail (E1 face-rig demo): high-frequency normal perturbation driven
+ * by u_wrinkleStrength, which the engine resolves per frame from live morph weights
+ * (resolveWrinkleMapStrength). Stable in world space (no time input); strength 0 uploads
+ * 0 and the guarded call site below leaves the normal bit-identical.
+ */
+vec3 a3dWrinkleDetail(vec3 p) {
+  float f = sin(p.x * 230.0) * sin(p.y * 197.0 + 1.7) * sin(p.z * 211.0 + 0.6);
+  float g = sin(p.x * 97.0 + 0.4) * sin(p.y * 113.0 + 2.1) * sin(p.z * 103.0 + 1.2);
+  return vec3(f, g, f * g) * 0.35;
+}
 vec3 a3dSkinnedPbrNormal(vec3 baseNormal, vec4 tangentFrame, vec2 uv) {
   vec3 sampled = texture(u_normalTexture, uv).xyz * 2.0 - 1.0;
   vec3 n = normalize(baseNormal);
@@ -1223,15 +1420,68 @@ float a3dPointShadowFactor(vec3 worldPosition, vec3 normal, vec3 lightDirection)
   float occlusion = totalWeight > 0.0 ? shadowed / totalWeight : 0.0;
   return mix(1.0, 1.0 - occlusion, clamp(u_pointShadowStrength, 0.0, 1.0));
 }
+float a3dSpotShadowFactor(vec3 worldPosition, vec3 normal, vec3 lightDirection) {
+  if (u_spotShadowMapEnabled < 0.5) return 1.0;
+  vec3 toFragment = worldPosition - u_spotShadowLightPosition;
+  float distanceToLight = max(length(toFragment), 0.0001);
+  if (distanceToLight > u_spotShadowRange) return 1.0;
+  vec3 coneAxis = u_spotShadowLightDirection / max(length(u_spotShadowLightDirection), 0.0001);
+  if (dot(toFragment / distanceToLight, coneAxis) < cos(u_spotShadowCone.x)) return 1.0;
+  vec4 lightPosition = u_spotShadowMatrix * vec4(worldPosition, 1.0);
+  vec3 projected = lightPosition.xyz / max(lightPosition.w, 0.0001);
+  vec2 uv = projected.xy * 0.5 + 0.5;
+  if (uv.x < 0.0 || uv.x > 1.0 || uv.y < 0.0 || uv.y > 1.0) return 1.0;
+  vec3 receiverNormal = normalize(normal);
+  vec3 receiverLightDirection = lightDirection / max(length(lightDirection), 0.0001);
+  float normalDotLight = clamp(abs(dot(receiverNormal, receiverLightDirection)), 0.0, 1.0);
+  // Shared bias-table policy: the same per-sample, tangent-scaled slope bias as the
+  // directional and point-cube paths. A centre-only bias under-compensates outer PCF
+  // taps on sloped receivers, so each tap scales by its own texel distance.
+  float slopeTangent = min(sqrt(max(1.0 - normalDotLight * normalDotLight, 0.0)) / max(normalDotLight, 0.05), 8.0);
+  float slopeTexelBias = slopeTangent * u_spotShadowSlopeBias * max(u_spotShadowTexelSize.x, u_spotShadowTexelSize.y);
+  float projectedDepth = projected.z * 0.5 + 0.5;
+  float shadowed = 0.0;
+  float totalWeight = 0.0;
+  int sampleCount = clamp(int(u_spotShadowPcfSampleCount), 1, 32);
+  for (int i = 0; i < 32; ++i) {
+    if (i >= sampleCount) break;
+    vec4 sampleData = u_spotShadowPcfSamples[i];
+    float weight = max(sampleData.z, 0.0);
+    vec2 offset = sampleData.xy * u_spotShadowTexelSize;
+    float storedDepth = texture(u_spotShadowMapTexture, uv + offset).r;
+    float sampleTexelDistance = max(1.0, length(sampleData.xy));
+    float receiverDepth = projectedDepth - u_spotShadowBias - slopeTexelBias * sampleTexelDistance;
+    shadowed += (receiverDepth > storedDepth ? 1.0 : 0.0) * weight;
+    totalWeight += weight;
+  }
+  float occlusion = totalWeight > 0.0 ? shadowed / totalWeight : 0.0;
+  return mix(1.0, 1.0 - occlusion, clamp(u_spotShadowStrength, 0.0, 1.0));
+}
+float a3dResolveSpotShadowOverride(float baseFactor, float kind, float shadowFlag, vec3 worldPosition, vec3 normal, vec3 lightDirection) {
+  // Spot-kind lights (kind == 2) sample the perspective spot map only when it is
+  // bound. Every gate term is 0 when no spot map is present, so mix() returns
+  // baseFactor exactly and scenes without spot lights render unchanged.
+  float spotGate = step(1.5, kind) * (1.0 - step(2.5, kind)) * step(0.5, u_spotShadowMapEnabled) * step(0.5, shadowFlag);
+  return mix(baseFactor, a3dSpotShadowFactor(worldPosition, normal, lightDirection), spotGate);
+}
+vec3 a3dLinearToSrgb(vec3 linear) {
+  vec3 clamped = max(linear, vec3(0.0));
+  vec3 low = clamped * 12.92;
+  vec3 high = 1.055 * pow(clamped, vec3(1.0 / 2.4)) - 0.055;
+  return mix(low, high, step(vec3(0.0031308), clamped));
+}
 vec3 a3dPbrEncodeOutput(vec3 linearColor) {
   vec3 color = max(linearColor, vec3(0.0));
   vec3 filmic = clamp((color * (2.51 * color + 0.03)) / (color * (2.43 * color + 0.59) + 0.14), vec3(0.0), vec3(1.0));
-  vec3 srgb = pow(filmic, vec3(1.0 / 2.2));
+  vec3 srgb = a3dLinearToSrgb(filmic);
   return mix(color, srgb, step(0.5, u_outputColorSpace));
 }
 void main() {
   vec3 normal = normalize(v_normal);
   normal = mix(normal, a3dSkinnedPbrNormal(v_normal, v_tangent, v_uv), step(0.5, u_normalTextureEnabled));
+  if (u_wrinkleStrength > 0.0) {
+    normal = normalize(normal + u_wrinkleStrength * a3dWrinkleDetail(v_worldPosition));
+  }
   if (!gl_FrontFacing) normal = -normal;
   vec3 viewDirection = normalize(u_cameraPosition - v_worldPosition);
   vec4 sampledBaseColor = texture(u_baseColorTexture, v_uv);
@@ -1301,11 +1551,11 @@ void main() {
   float nDotV = clamp(dot(normal, viewDirection), 0.0, 1.0);
   vec2 brdfLut = texture(u_environmentBrdfLutTexture, vec2(nDotV, clampedRoughness)).rg;
   sampledSpecular = a3dPbrClampSampledSpecularEdgeEnergy(sampledSpecular, nDotV, clampedRoughness);
-  sampledSpecular *= u_environmentMapTextureSpecularIntensity * sampledEnvironmentWeight * mix(1.1, 0.65, roughness);
+  sampledSpecular *= u_environmentMapTextureSpecularIntensity * u_materialEnvironmentIntensity * sampledEnvironmentWeight * mix(1.1, 0.65, roughness);
   vec3 shaded = a3dPbrEnvironmentLightSplitSum(
     normal,
     viewDirection,
-    mix(environmentDiffuse, ambientEnvironment + sampledDiffuse * u_environmentMapTextureIntensity, sampledEnvironmentWeight),
+    mix(environmentDiffuse, ambientEnvironment + sampledDiffuse * u_environmentMapTextureIntensity * u_materialEnvironmentIntensity, sampledEnvironmentWeight),
     proceduralSpecular + sampledSpecular,
     mix(vec2(1.0, 0.0), brdfLut, step(0.0001, u_environmentBrdfLutEnabled)),
     materialBase,
@@ -1360,7 +1610,7 @@ void main() {
       viewDirection,
       lightDirection,
       colorIntensity.rgb,
-      colorIntensity.a * attenuation * mix(1.0, kind > 0.5 && kind < 1.5 ? a3dPointShadowFactor(v_worldPosition, normal, lightDirection) : a3dForwardShadowFactor(v_worldPosition, normal, lightDirection), step(0.5, spotShadowLayer.z)),
+      colorIntensity.a * attenuation * a3dResolveSpotShadowOverride(mix(1.0, kind > 0.5 && kind < 1.5 ? a3dPointShadowFactor(v_worldPosition, normal, lightDirection) : a3dForwardShadowFactor(v_worldPosition, normal, lightDirection), step(0.5, spotShadowLayer.z)), kind, spotShadowLayer.z, v_worldPosition, normal, lightDirection),
       materialBase,
       metallic,
       roughness,
@@ -1443,21 +1693,45 @@ layout(location = 2) in vec2 a_uv;
 layout(location = 3) in vec4 a_tangent;
 layout(location = 4) in vec4 a_color;
 layout(location = 7) in vec2 a_uv1;
+layout(location = 8) in vec4 a_instanceMatrix0;
+layout(location = 9) in vec4 a_instanceMatrix1;
+layout(location = 10) in vec4 a_instanceMatrix2;
+layout(location = 11) in vec4 a_instanceMatrix3;
+layout(location = 12) in vec4 a_instanceColor;
 uniform mat4 u_modelViewProjection;
 uniform mat4 u_modelMatrix;
 uniform mat4 u_normalMatrix;
+uniform mat4 u_instanceMatrices[64];
+uniform float u_instanceCount;
+uniform float u_instanceAttributeMode;
 out vec3 v_normal;
 out vec4 v_tangent;
 out vec3 v_worldPosition;
 out vec2 v_uv;
 out vec4 v_vertexColor;
 void main() {
-  v_normal = mat3(u_normalMatrix) * a_normal;
-  v_tangent = vec4(mat3(u_normalMatrix) * a_tangent.xyz, a_tangent.w);
-  v_worldPosition = (u_modelMatrix * vec4(a_position, 1.0)).xyz;
-  v_uv = a_uv;
-  v_vertexColor = a_color;
-  gl_Position = u_modelViewProjection * vec4(a_position, 1.0);
+  // P2 instanced-GLB path (muse3jsparity-PRD): the u_instanceCount branch is
+  // taken only for items carrying instanceTransforms; every other draw keeps
+  // the legacy math bit-exact. Mirrors the instanced-PBR vertex convention.
+  if (u_instanceCount > 0.5) {
+    int instanceIndex = clamp(gl_InstanceID, 0, max(int(u_instanceCount) - 1, 0));
+    mat4 attributeMatrix = mat4(a_instanceMatrix0, a_instanceMatrix1, a_instanceMatrix2, a_instanceMatrix3);
+    mat4 instanceMatrix = u_instanceAttributeMode > 0.5 ? attributeMatrix : u_instanceMatrices[instanceIndex];
+    vec4 worldPosition = u_modelMatrix * instanceMatrix * vec4(a_position, 1.0);
+    v_normal = mat3(u_normalMatrix) * transpose(inverse(mat3(instanceMatrix))) * a_normal;
+    v_tangent = vec4(mat3(u_normalMatrix) * (mat3(instanceMatrix) * a_tangent.xyz), a_tangent.w);
+    v_worldPosition = worldPosition.xyz;
+    v_uv = a_uv;
+    v_vertexColor = a_color * a_instanceColor;
+    gl_Position = u_modelViewProjection * instanceMatrix * vec4(a_position, 1.0);
+  } else {
+    v_normal = mat3(u_normalMatrix) * a_normal;
+    v_tangent = vec4(mat3(u_normalMatrix) * a_tangent.xyz, a_tangent.w);
+    v_worldPosition = (u_modelMatrix * vec4(a_position, 1.0)).xyz;
+    v_uv = a_uv;
+    v_vertexColor = a_color;
+    gl_Position = u_modelViewProjection * vec4(a_position, 1.0);
+  }
 }
 `,
         fragment: `#version 300 es
@@ -1471,6 +1745,7 @@ uniform float u_metallic;
 uniform float u_roughness;
 uniform vec3 u_environmentColor;
 uniform float u_environmentIntensity;
+uniform float u_materialEnvironmentIntensity;
 uniform vec3 u_environmentSkyColor;
 uniform vec3 u_environmentHorizonColor;
 uniform vec3 u_environmentGroundColor;
@@ -1539,6 +1814,19 @@ uniform float u_pointShadowSlopeBias;
 uniform vec2 u_pointShadowTexelSize;
 uniform float u_pointShadowPcfSampleCount;
 uniform vec4 u_pointShadowPcfSamples[32];
+uniform sampler2D u_spotShadowMapTexture;
+uniform float u_spotShadowMapEnabled;
+uniform vec3 u_spotShadowLightPosition;
+uniform vec3 u_spotShadowLightDirection;
+uniform mat4 u_spotShadowMatrix;
+uniform vec2 u_spotShadowCone;
+uniform float u_spotShadowRange;
+uniform float u_spotShadowStrength;
+uniform float u_spotShadowBias;
+uniform float u_spotShadowSlopeBias;
+uniform vec2 u_spotShadowTexelSize;
+uniform float u_spotShadowPcfSampleCount;
+uniform vec4 u_spotShadowPcfSamples[32];
 uniform float u_outputColorSpace;
 uniform vec3 u_cameraPosition;
 uniform float u_environmentFogEnabled;
@@ -1548,6 +1836,9 @@ uniform float u_environmentFogNear;
 uniform float u_environmentFogFar;
 uniform float u_environmentFogDensity;
 uniform float u_environmentFogHeightFalloff;
+uniform float u_volumetricIntensity;
+uniform vec3 u_volumetricLightDirection;
+uniform vec3 u_volumetricLightColor;
 uniform float u_environmentFogHeightReference;
 uniform float u_environmentFogMaxOpacity;
 in vec3 v_normal;
@@ -1635,6 +1926,50 @@ float a3dPointShadowFactor(vec3 worldPosition, vec3 normal, vec3 lightDirection)
   float occlusion = totalWeight > 0.0 ? shadowed / totalWeight : 0.0;
   return mix(1.0, 1.0 - occlusion, clamp(u_pointShadowStrength, 0.0, 1.0));
 }
+float a3dSpotShadowFactor(vec3 worldPosition, vec3 normal, vec3 lightDirection) {
+  if (u_spotShadowMapEnabled < 0.5) return 1.0;
+  vec3 toFragment = worldPosition - u_spotShadowLightPosition;
+  float distanceToLight = max(length(toFragment), 0.0001);
+  if (distanceToLight > u_spotShadowRange) return 1.0;
+  vec3 coneAxis = u_spotShadowLightDirection / max(length(u_spotShadowLightDirection), 0.0001);
+  if (dot(toFragment / distanceToLight, coneAxis) < cos(u_spotShadowCone.x)) return 1.0;
+  vec4 lightPosition = u_spotShadowMatrix * vec4(worldPosition, 1.0);
+  vec3 projected = lightPosition.xyz / max(lightPosition.w, 0.0001);
+  vec2 uv = projected.xy * 0.5 + 0.5;
+  if (uv.x < 0.0 || uv.x > 1.0 || uv.y < 0.0 || uv.y > 1.0) return 1.0;
+  vec3 receiverNormal = normalize(normal);
+  vec3 receiverLightDirection = lightDirection / max(length(lightDirection), 0.0001);
+  float normalDotLight = clamp(abs(dot(receiverNormal, receiverLightDirection)), 0.0, 1.0);
+  // Shared bias-table policy: the same per-sample, tangent-scaled slope bias as the
+  // directional and point-cube paths. A centre-only bias under-compensates outer PCF
+  // taps on sloped receivers, so each tap scales by its own texel distance.
+  float slopeTangent = min(sqrt(max(1.0 - normalDotLight * normalDotLight, 0.0)) / max(normalDotLight, 0.05), 8.0);
+  float slopeTexelBias = slopeTangent * u_spotShadowSlopeBias * max(u_spotShadowTexelSize.x, u_spotShadowTexelSize.y);
+  float projectedDepth = projected.z * 0.5 + 0.5;
+  float shadowed = 0.0;
+  float totalWeight = 0.0;
+  int sampleCount = clamp(int(u_spotShadowPcfSampleCount), 1, 32);
+  for (int i = 0; i < 32; ++i) {
+    if (i >= sampleCount) break;
+    vec4 sampleData = u_spotShadowPcfSamples[i];
+    float weight = max(sampleData.z, 0.0);
+    vec2 offset = sampleData.xy * u_spotShadowTexelSize;
+    float storedDepth = texture(u_spotShadowMapTexture, uv + offset).r;
+    float sampleTexelDistance = max(1.0, length(sampleData.xy));
+    float receiverDepth = projectedDepth - u_spotShadowBias - slopeTexelBias * sampleTexelDistance;
+    shadowed += (receiverDepth > storedDepth ? 1.0 : 0.0) * weight;
+    totalWeight += weight;
+  }
+  float occlusion = totalWeight > 0.0 ? shadowed / totalWeight : 0.0;
+  return mix(1.0, 1.0 - occlusion, clamp(u_spotShadowStrength, 0.0, 1.0));
+}
+float a3dResolveSpotShadowOverride(float baseFactor, float kind, float shadowFlag, vec3 worldPosition, vec3 normal, vec3 lightDirection) {
+  // Spot-kind lights (kind == 2) sample the perspective spot map only when it is
+  // bound. Every gate term is 0 when no spot map is present, so mix() returns
+  // baseFactor exactly and scenes without spot lights render unchanged.
+  float spotGate = step(1.5, kind) * (1.0 - step(2.5, kind)) * step(0.5, u_spotShadowMapEnabled) * step(0.5, shadowFlag);
+  return mix(baseFactor, a3dSpotShadowFactor(worldPosition, normal, lightDirection), spotGate);
+}
 vec2 a3dEnvironmentEquirectUv(vec3 direction, float rotation) {
   vec3 d = normalize(direction);
   float u = atan(d.z, d.x) / 6.28318530718 + 0.5 + rotation;
@@ -1689,7 +2024,7 @@ vec3 a3dPbrEnvironmentDiffuseInput(vec3 normal) {
   float sampledEnvironmentWeight = step(0.0001, u_environmentMapTextureEnabled * u_environmentMapTextureIntensity);
   float diffuseEnvironmentLod = max(u_environmentMapTextureMipCount - 1.0, 0.0);
   vec3 sampledDiffuse = a3dPbrDecodeEnvironmentSample(a3dPbrEnvironmentSampleRaw(normal, diffuseEnvironmentLod));
-  return mix(environmentDiffuse, ambientEnvironment + sampledDiffuse * u_environmentMapTextureIntensity, sampledEnvironmentWeight);
+  return mix(environmentDiffuse, ambientEnvironment + sampledDiffuse * u_environmentMapTextureIntensity * u_materialEnvironmentIntensity, sampledEnvironmentWeight);
 }
 vec3 a3dPbrEnvironmentSpecularInput(vec3 normal, vec3 viewDirection, float roughness) {
   float proceduralEnvironmentWeight = step(0.0001, u_environmentMapIntensity);
@@ -1704,7 +2039,7 @@ vec3 a3dPbrEnvironmentSpecularInput(vec3 normal, vec3 viewDirection, float rough
   vec3 sampledSpecular = a3dPbrBoundHdrSpecularRadiance(a3dPbrDecodeEnvironmentSample(a3dPbrEnvironmentSampleRaw(reflectionDirection, environmentLod)));
   float nDotV = clamp(dot(normal, viewDirection), 0.0, 1.0);
   sampledSpecular = a3dPbrClampSampledSpecularEdgeEnergy(sampledSpecular, nDotV, clampedRoughness);
-  sampledSpecular *= u_environmentMapTextureSpecularIntensity * sampledEnvironmentWeight * mix(0.84, 0.58, clampedRoughness);
+  sampledSpecular *= u_environmentMapTextureSpecularIntensity * u_materialEnvironmentIntensity * sampledEnvironmentWeight * mix(0.84, 0.58, clampedRoughness);
   return proceduralSpecular + sampledSpecular;
 }
 vec2 a3dPbrEnvironmentBrdfInput(vec3 normal, vec3 viewDirection, float roughness) {
@@ -1712,10 +2047,16 @@ vec2 a3dPbrEnvironmentBrdfInput(vec3 normal, vec3 viewDirection, float roughness
   vec2 lut = texture(u_environmentBrdfLutTexture, vec2(nDotV, clamp(roughness, 0.0, 1.0))).rg;
   return mix(vec2(1.0, 0.0), lut, step(0.0001, u_environmentBrdfLutEnabled));
 }
+vec3 a3dLinearToSrgb(vec3 linear) {
+  vec3 clamped = max(linear, vec3(0.0));
+  vec3 low = clamped * 12.92;
+  vec3 high = 1.055 * pow(clamped, vec3(1.0 / 2.4)) - 0.055;
+  return mix(low, high, step(vec3(0.0031308), clamped));
+}
 vec3 a3dPbrEncodeOutput(vec3 linearColor) {
   vec3 color = max(linearColor, vec3(0.0));
   vec3 filmic = clamp((color * (2.51 * color + 0.03)) / (color * (2.43 * color + 0.59) + 0.14), vec3(0.0), vec3(1.0));
-  vec3 srgb = pow(filmic, vec3(1.0 / 2.2));
+  vec3 srgb = a3dLinearToSrgb(filmic);
   return mix(color, srgb, step(0.5, u_outputColorSpace));
 }
 void main() {
@@ -1776,7 +2117,7 @@ void main() {
       float inner = cos(spotShadowLayer.x * max(1.0 - spotShadowLayer.y, 0.001));
       attenuation *= smoothstep(outer, inner, cone);
     }
-    float shadowFactor = mix(1.0, kind > 0.5 && kind < 1.5 ? a3dPointShadowFactor(v_worldPosition, mappedNormal, lightDirection) : a3dForwardShadowFactor(v_worldPosition, mappedNormal, lightDirection), step(0.5, spotShadowLayer.z));
+    float shadowFactor = a3dResolveSpotShadowOverride(mix(1.0, kind > 0.5 && kind < 1.5 ? a3dPointShadowFactor(v_worldPosition, mappedNormal, lightDirection) : a3dForwardShadowFactor(v_worldPosition, mappedNormal, lightDirection), step(0.5, spotShadowLayer.z)), kind, spotShadowLayer.z, v_worldPosition, mappedNormal, lightDirection);
     shaded += a3dPbrDirectLight(mappedNormal, viewDirection, lightDirection, colorIntensity.rgb, colorIntensity.a * attenuation * shadowFactor, materialBase, u_metallic, u_roughness, u_specularFactor, u_specularColorFactor);
   }
   float alpha = u_baseColor.a * v_vertexColor.a;
@@ -1794,9 +2135,9 @@ void main() {
             { name: DEFAULT_TEXTURED_PBR_TRANSMISSION_VOLUME_TEXTURES_VARIANT, defines: { A3D_PBR_TRANSMISSION_VOLUME_TEXTURES: true, A3D_PBR_DISABLE_TRANSMISSION_BACKDROP: true, A3D_PBR_DISABLE_CLUSTERED_LIGHTING: true } },
             { name: DEFAULT_TEXTURED_PBR_SPECULAR_SHEEN_ANISOTROPY_TEXTURES_VARIANT, defines: { A3D_PBR_SPECULAR_TEXTURES: true, A3D_PBR_SPECULAR_SHEEN_ANISOTROPY_TEXTURES: true, A3D_PBR_DISABLE_TRANSMISSION_BACKDROP: true, A3D_PBR_DISABLE_CLUSTERED_LIGHTING: true } },
             { name: DEFAULT_TEXTURED_PBR_IRIDESCENCE_TEXTURES_VARIANT, defines: { A3D_PBR_IRIDESCENCE_TEXTURES: true, A3D_PBR_DISABLE_TRANSMISSION_BACKDROP: true, A3D_PBR_DISABLE_CLUSTERED_LIGHTING: true } },
-            { name: DEFAULT_TEXTURED_PBR_CLEARCOAT_TRANSMISSION_VOLUME_TEXTURES_VARIANT, defines: { A3D_PBR_CLEARCOAT_TEXTURES: true, A3D_PBR_TRANSMISSION_VOLUME_TEXTURES: true, A3D_PBR_DISABLE_TRANSMISSION_BACKDROP: true, A3D_PBR_DISABLE_CLUSTERED_LIGHTING: true } },
+            { name: DEFAULT_TEXTURED_PBR_CLEARCOAT_TRANSMISSION_VOLUME_TEXTURES_VARIANT, defines: { A3D_PBR_CLEARCOAT_TEXTURES: true, A3D_PBR_TRANSMISSION_VOLUME_TEXTURES: true, A3D_PBR_DISABLE_TRANSMISSION_BACKDROP: true, A3D_PBR_DISABLE_CLUSTERED_LIGHTING: true, A3D_PBR_NO_SPOT_SHADOW: true } },
             { name: DEFAULT_TEXTURED_PBR_CLEARCOAT_SPECULAR_TEXTURES_VARIANT, defines: { A3D_PBR_CLEARCOAT_TEXTURES: true, A3D_PBR_SPECULAR_TEXTURES: true, A3D_PBR_DISABLE_TRANSMISSION_BACKDROP: true, A3D_PBR_DISABLE_CLUSTERED_LIGHTING: true } },
-            { name: DEFAULT_TEXTURED_PBR_SPECULAR_SHEEN_ANISOTROPY_IRIDESCENCE_TEXTURES_VARIANT, defines: { A3D_PBR_SPECULAR_TEXTURES: true, A3D_PBR_SPECULAR_SHEEN_ANISOTROPY_TEXTURES: true, A3D_PBR_IRIDESCENCE_TEXTURES: true, A3D_PBR_DISABLE_TRANSMISSION_BACKDROP: true, A3D_PBR_DISABLE_CLUSTERED_LIGHTING: true } }
+            { name: DEFAULT_TEXTURED_PBR_SPECULAR_SHEEN_ANISOTROPY_IRIDESCENCE_TEXTURES_VARIANT, defines: { A3D_PBR_SPECULAR_TEXTURES: true, A3D_PBR_SPECULAR_SHEEN_ANISOTROPY_TEXTURES: true, A3D_PBR_IRIDESCENCE_TEXTURES: true, A3D_PBR_DISABLE_TRANSMISSION_BACKDROP: true, A3D_PBR_DISABLE_CLUSTERED_LIGHTING: true, A3D_PBR_NO_SPOT_SHADOW: true } },
         ],
         vertex: `#version 300 es
 // ${DEFAULT_TEXTURED_PBR_SHADER_MARKER}
@@ -1807,9 +2148,17 @@ layout(location = 2) in vec2 a_uv;
 layout(location = 3) in vec4 a_tangent;
 layout(location = 4) in vec4 a_color;
 layout(location = 7) in vec2 a_uv1;
+layout(location = 8) in vec4 a_instanceMatrix0;
+layout(location = 9) in vec4 a_instanceMatrix1;
+layout(location = 10) in vec4 a_instanceMatrix2;
+layout(location = 11) in vec4 a_instanceMatrix3;
+layout(location = 12) in vec4 a_instanceColor;
 uniform mat4 u_modelViewProjection;
 uniform mat4 u_modelMatrix;
 uniform mat4 u_normalMatrix;
+uniform mat4 u_instanceMatrices[64];
+uniform float u_instanceCount;
+uniform float u_instanceAttributeMode;
 out vec3 v_normal;
 out vec4 v_tangent;
 out vec3 v_worldPosition;
@@ -1819,11 +2168,27 @@ out vec4 v_vertexColor;
 void main() {
   v_uv = a_uv;
   v_uv1 = a_uv1;
-  v_normal = mat3(u_normalMatrix) * a_normal;
-  v_tangent = vec4(mat3(u_normalMatrix) * a_tangent.xyz, a_tangent.w);
-  v_worldPosition = (u_modelMatrix * vec4(a_position, 1.0)).xyz;
-  v_vertexColor = a_color;
-  gl_Position = u_modelViewProjection * vec4(a_position, 1.0);
+  // P2 instanced-GLB path (muse3jsparity-PRD): the u_instanceCount branch is
+  // taken only for items carrying instanceTransforms (applyInstanceBinding
+  // stamps a count >= 1); every other draw keeps the legacy math bit-exact.
+  // Mirrors the instanced-PBR vertex convention (MVP carries the base model).
+  if (u_instanceCount > 0.5) {
+    int instanceIndex = clamp(gl_InstanceID, 0, max(int(u_instanceCount) - 1, 0));
+    mat4 attributeMatrix = mat4(a_instanceMatrix0, a_instanceMatrix1, a_instanceMatrix2, a_instanceMatrix3);
+    mat4 instanceMatrix = u_instanceAttributeMode > 0.5 ? attributeMatrix : u_instanceMatrices[instanceIndex];
+    vec4 worldPosition = u_modelMatrix * instanceMatrix * vec4(a_position, 1.0);
+    v_normal = mat3(u_normalMatrix) * transpose(inverse(mat3(instanceMatrix))) * a_normal;
+    v_tangent = vec4(mat3(u_normalMatrix) * (mat3(instanceMatrix) * a_tangent.xyz), a_tangent.w);
+    v_worldPosition = worldPosition.xyz;
+    v_vertexColor = a_color * a_instanceColor;
+    gl_Position = u_modelViewProjection * instanceMatrix * vec4(a_position, 1.0);
+  } else {
+    v_normal = mat3(u_normalMatrix) * a_normal;
+    v_tangent = vec4(mat3(u_normalMatrix) * a_tangent.xyz, a_tangent.w);
+    v_worldPosition = (u_modelMatrix * vec4(a_position, 1.0)).xyz;
+    v_vertexColor = a_color;
+    gl_Position = u_modelViewProjection * vec4(a_position, 1.0);
+  }
 }
 `,
         fragment: `#version 300 es
@@ -1837,6 +2202,7 @@ uniform float u_metallic;
 uniform float u_roughness;
 uniform vec3 u_environmentColor;
 uniform float u_environmentIntensity;
+uniform float u_materialEnvironmentIntensity;
 uniform vec3 u_environmentSkyColor;
 uniform vec3 u_environmentHorizonColor;
 uniform vec3 u_environmentGroundColor;
@@ -1921,6 +2287,26 @@ uniform float u_pointShadowSlopeBias;
 uniform vec2 u_pointShadowTexelSize;
 uniform float u_pointShadowPcfSampleCount;
 uniform vec4 u_pointShadowPcfSamples[32];
+// B1 spot path (muse3jsparity-PRD): the two A3D_PBR_NO_SPOT_SHADOW variants
+// (clearcoat-transmission-volume, specular-sheen-anisotropy-iridescence) sit at
+// the 16-sampler WebGL2 minimum without it, so they sample spot lights through
+// the legacy directional factor while every other lit program takes the spot
+// override. ForwardPass binds spot uniforms only when reflection declares them.
+#ifndef A3D_PBR_NO_SPOT_SHADOW
+uniform sampler2D u_spotShadowMapTexture;
+uniform float u_spotShadowMapEnabled;
+uniform vec3 u_spotShadowLightPosition;
+uniform vec3 u_spotShadowLightDirection;
+uniform mat4 u_spotShadowMatrix;
+uniform vec2 u_spotShadowCone;
+uniform float u_spotShadowRange;
+uniform float u_spotShadowStrength;
+uniform float u_spotShadowBias;
+uniform float u_spotShadowSlopeBias;
+uniform vec2 u_spotShadowTexelSize;
+uniform float u_spotShadowPcfSampleCount;
+uniform vec4 u_spotShadowPcfSamples[32];
+#endif
 uniform sampler2D u_baseColorTexture;
 uniform float u_baseColorTextureEnabled;
 uniform vec2 u_baseColorTextureOffset;
@@ -2076,6 +2462,9 @@ uniform float u_environmentFogNear;
 uniform float u_environmentFogFar;
 uniform float u_environmentFogDensity;
 uniform float u_environmentFogHeightFalloff;
+uniform float u_volumetricIntensity;
+uniform vec3 u_volumetricLightDirection;
+uniform vec3 u_volumetricLightColor;
 uniform float u_environmentFogHeightReference;
 uniform float u_environmentFogMaxOpacity;
 in vec3 v_normal;
@@ -2110,10 +2499,16 @@ vec2 a3dTexturedPbrWrapUv(vec2 uv, vec2 wrapMode) {
     a3dTexturedPbrWrapCoordinate(uv.y, wrapMode.y)
   );
 }
+vec3 a3dTexturedPbrEncodeLinearToSrgb(vec3 linear) {
+  vec3 clamped = max(linear, vec3(0.0));
+  vec3 low = clamped * 12.92;
+  vec3 high = 1.055 * pow(clamped, vec3(1.0 / 2.4)) - 0.055;
+  return mix(low, high, step(vec3(0.0031308), clamped));
+}
 vec3 a3dTexturedPbrEncodeOutput(vec3 linearColor) {
   vec3 color = max(linearColor, vec3(0.0));
   vec3 filmic = clamp((color * (2.51 * color + 0.03)) / (color * (2.43 * color + 0.59) + 0.14), vec3(0.0), vec3(1.0));
-  vec3 srgb = pow(filmic, vec3(1.0 / 2.2));
+  vec3 srgb = a3dTexturedPbrEncodeLinearToSrgb(filmic);
   return mix(color, srgb, step(0.5, u_outputColorSpace));
 }
 vec3 a3dTexturedPbrDecodeSrgb(vec3 encodedColor) {
@@ -2220,6 +2615,52 @@ float a3dTexturedPbrPointShadowFactor(vec3 worldPosition, vec3 normal, vec3 ligh
   float occlusion = totalWeight > 0.0 ? shadowed / totalWeight : 0.0;
   return mix(1.0, 1.0 - occlusion, clamp(u_pointShadowStrength, 0.0, 1.0));
 }
+#ifndef A3D_PBR_NO_SPOT_SHADOW
+float a3dTexturedPbrSpotShadowFactor(vec3 worldPosition, vec3 normal, vec3 lightDirection) {
+  if (u_spotShadowMapEnabled < 0.5) return 1.0;
+  vec3 toFragment = worldPosition - u_spotShadowLightPosition;
+  float distanceToLight = max(length(toFragment), 0.0001);
+  if (distanceToLight > u_spotShadowRange) return 1.0;
+  vec3 coneAxis = u_spotShadowLightDirection / max(length(u_spotShadowLightDirection), 0.0001);
+  if (dot(toFragment / distanceToLight, coneAxis) < cos(u_spotShadowCone.x)) return 1.0;
+  vec4 lightPosition = u_spotShadowMatrix * vec4(worldPosition, 1.0);
+  vec3 projected = lightPosition.xyz / max(lightPosition.w, 0.0001);
+  vec2 uv = projected.xy * 0.5 + 0.5;
+  if (uv.x < 0.0 || uv.x > 1.0 || uv.y < 0.0 || uv.y > 1.0) return 1.0;
+  vec3 receiverNormal = normalize(normal);
+  vec3 receiverLightDirection = lightDirection / max(length(lightDirection), 0.0001);
+  float normalDotLight = clamp(abs(dot(receiverNormal, receiverLightDirection)), 0.0, 1.0);
+  // Shared bias-table policy: the same per-sample, tangent-scaled slope bias as the
+  // directional and point-cube paths. A centre-only bias under-compensates outer PCF
+  // taps on sloped receivers, so each tap scales by its own texel distance.
+  float slopeTangent = min(sqrt(max(1.0 - normalDotLight * normalDotLight, 0.0)) / max(normalDotLight, 0.05), 8.0);
+  float slopeTexelBias = slopeTangent * u_spotShadowSlopeBias * max(u_spotShadowTexelSize.x, u_spotShadowTexelSize.y);
+  float projectedDepth = projected.z * 0.5 + 0.5;
+  float shadowed = 0.0;
+  float totalWeight = 0.0;
+  int sampleCount = clamp(int(u_spotShadowPcfSampleCount), 1, 32);
+  for (int i = 0; i < 32; ++i) {
+    if (i >= sampleCount) break;
+    vec4 sampleData = u_spotShadowPcfSamples[i];
+    float weight = max(sampleData.z, 0.0);
+    vec2 offset = sampleData.xy * u_spotShadowTexelSize;
+    float storedDepth = texture(u_spotShadowMapTexture, uv + offset).r;
+    float sampleTexelDistance = max(1.0, length(sampleData.xy));
+    float receiverDepth = projectedDepth - u_spotShadowBias - slopeTexelBias * sampleTexelDistance;
+    shadowed += (receiverDepth > storedDepth ? 1.0 : 0.0) * weight;
+    totalWeight += weight;
+  }
+  float occlusion = totalWeight > 0.0 ? shadowed / totalWeight : 0.0;
+  return mix(1.0, 1.0 - occlusion, clamp(u_spotShadowStrength, 0.0, 1.0));
+}
+float a3dTexturedPbrResolveSpotShadowOverride(float baseFactor, float kind, float shadowFlag, vec3 worldPosition, vec3 normal, vec3 lightDirection) {
+  // Spot-kind lights (kind == 2) sample the perspective spot map only when it is
+  // bound. Every gate term is 0 when no spot map is present, so mix() returns
+  // baseFactor exactly and scenes without spot lights render unchanged.
+  float spotGate = step(1.5, kind) * (1.0 - step(2.5, kind)) * step(0.5, u_spotShadowMapEnabled) * step(0.5, shadowFlag);
+  return mix(baseFactor, a3dTexturedPbrSpotShadowFactor(worldPosition, normal, lightDirection), spotGate);
+}
+#endif
 vec2 a3dTexturedPbrEnvironmentUv(vec3 direction, float rotation) {
   vec3 d = normalize(direction);
   float u = atan(d.z, d.x) / 6.28318530718 + 0.5 + rotation;
@@ -2268,7 +2709,7 @@ vec3 a3dTexturedPbrEnvironmentDiffuseInput(vec3 normal) {
   float sampledEnvironmentWeight = step(0.0001, u_environmentMapTextureEnabled * u_environmentMapTextureIntensity);
   float diffuseEnvironmentLod = max(u_environmentMapTextureMipCount - 1.0, 0.0);
   vec3 sampledDiffuse = a3dTexturedPbrDecodeEnvironmentSample(a3dTexturedPbrEnvironmentSampleRaw(normal, diffuseEnvironmentLod));
-  return mix(environmentDiffuse, ambientEnvironment + sampledDiffuse * u_environmentMapTextureIntensity, sampledEnvironmentWeight);
+  return mix(environmentDiffuse, ambientEnvironment + sampledDiffuse * u_environmentMapTextureIntensity * u_materialEnvironmentIntensity, sampledEnvironmentWeight);
 }
 vec3 a3dTexturedPbrEnvironmentSpecularInput(vec3 normal, vec3 viewDirection, float roughness) {
   float materialEnvironmentSpecularScale = clamp(u_materialEnvironmentSpecularScale, 0.0, 1.0);
@@ -2297,7 +2738,7 @@ vec3 a3dTexturedPbrEnvironmentSpecularInput(vec3 normal, vec3 viewDirection, flo
   float environmentLod = clampedRoughness * max(u_environmentMapTextureMipCount - 1.0, 0.0);
   vec3 sampledSpecular = a3dTexturedPbrBoundHdrSpecularRadiance(a3dTexturedPbrDecodeEnvironmentSample(a3dTexturedPbrEnvironmentSampleRaw(reflectionDirection, environmentLod)));
   sampledSpecular = a3dTexturedPbrClampSampledSpecularEdgeEnergy(sampledSpecular, nDotV, clampedRoughness);
-  sampledSpecular *= u_environmentMapTextureSpecularIntensity * sampledEnvironmentWeight * mix(1.1, 0.65, clampedRoughness);
+  sampledSpecular *= u_environmentMapTextureSpecularIntensity * u_materialEnvironmentIntensity * sampledEnvironmentWeight * mix(1.1, 0.65, clampedRoughness);
   float proceduralSpecularScale = materialFiniteSpecularScale;
   float sampledSpecularScale = materialEnvironmentSpecularScale;
   return proceduralSpecular * proceduralSpecularScale + sampledSpecular * sampledSpecularScale;
@@ -2720,6 +3161,9 @@ void main() {
       attenuation *= smoothstep(outer, inner, cone);
     }
     float shadowFactor = mix(1.0, kind > 0.5 && kind < 1.5 ? a3dTexturedPbrPointShadowFactor(v_worldPosition, mappedNormal, lightDirection) : a3dTexturedPbrShadowFactor(v_worldPosition, mappedNormal, lightDirection), step(0.5, spotShadowLayer.z));
+#ifndef A3D_PBR_NO_SPOT_SHADOW
+    shadowFactor = a3dTexturedPbrResolveSpotShadowOverride(shadowFactor, kind, spotShadowLayer.z, v_worldPosition, mappedNormal, lightDirection);
+#endif
     float directLightIntensity = colorIntensity.a
       * attenuation
       * shadowFactor