@carbonenginejs/runtime 0.1.0-alpha.0 → 0.1.0-alpha.1

package/dist/trinity/eve/child/EveChildCloud2.js

@@ -1,15 +1,19 @@
 import { identity as _identity, applyDecs2311 as _applyDecs2311 } from '../../../_virtual/_rollupPluginBabelHelpers.js';
-import { io, type, impl } from '#schema';
+import { io, type, impl, carbon } from '#schema';
 import { EveSpaceObjectChild as _EveSpaceObjectChild } from './EveSpaceObjectChild.js';
 import { mat4 } from '#math/mat4';
 import { quat } from '#math/quat';
 import { vec3 } from '#math/vec3';
 import { RenderingMode, TriBatchType, ReflectionMode } from '#consts/graphics';
 import { EveComponentType, ShouldReflect } from '../EveComponentTypes.js';
-import { Tr2PerObjectData } from '../../core/rawData/Tr2PerObjectData.js';
-import { Tr2RenderBatch } from '../../core/batch/Tr2RenderBatch.js';
-import { TriFrustumOrtho } from '../../core/view/TriFrustumOrtho.js';
+import { Tr2PerObjectData } from '../../core/rawData/perObjectData/Tr2PerObjectData.js';
+import { Tr2RenderBatch } from '../../core/batch/TriRenderBatch/Tr2RenderBatch.js';
+import '../../core/batch/TriRenderBatch/DefaultKeyGenerator.js';
+import '../../core/batch/TriRenderBatch/EffectKeyGenerator.js';
+import '../../core/batch/TriRenderBatch/ITriRenderBatchAccumulator.js';
 import { Tr2RenderReason, Tr2VolumerticQuality } from '../../generated/trinityCore/enums.js';
+import '#consts/render-context';
+import { TriFrustumOrtho } from '../../core/view/TriFrustumOrtho.js';
 import { withITr2Renderable } from '../../core/ITr2Renderable.js';
 
 var _withITr2Renderable;
@@ -42,11 +46,11 @@ const LIGHT_SCRATCH = {
   color: vec3.create()
 };
 
-/** Carbon OrthoNormalBasisZ (math Matrix_inline.h:531-546): identity; row Z =
- * Normalize(z); X seeded (0,1,0) when |Z.x| > 0.99 else (1,0,0); Y =
- * Normalize(Cross(X, Z)); X = Cross(Y, Z). Carbon's basis rows land at gl flat
- * [0..2]/[4..6]/[8..10] on the shared byte layout - single-matrix build, no
- * composition, no operand swap. A zero-length z NaNs exactly as Carbon's
+/** Carbon OrthoNormalBasisZ (math Matrix_inline.h:531-546): identity; row Z =
+ * Normalize(z); X seeded (0,1,0) when |Z.x| > 0.99 else (1,0,0); Y =
+ * Normalize(Cross(X, Z)); X = Cross(Y, Z). Carbon's basis rows land at gl flat
+ * [0..2]/[4..6]/[8..10] on the shared byte layout - single-matrix build, no
+ * composition, no operand swap. A zero-length z NaNs exactly as Carbon's
  * Normalize does. */
 function OrthoNormalBasisZ(out, z) {
   mat4.identity(out);
@@ -77,9 +81,9 @@ function OrthoNormalBasisZ(out, z) {
   return out;
 }
 
-/** Carbon OrthoOffCenterMatrix (math Matrix_inline.h:749-765): D3D-style
- * z-in-[0,1] off-center orthographic projection. Deliberately NOT gl-matrix's
- * mat4.ortho (GL z-in-[-1,1], different off-center terms). Carbon m[i][j]
+/** Carbon OrthoOffCenterMatrix (math Matrix_inline.h:749-765): D3D-style
+ * z-in-[0,1] off-center orthographic projection. Deliberately NOT gl-matrix's
+ * mat4.ortho (GL z-in-[-1,1], different off-center terms). Carbon m[i][j]
  * lands at gl flat [i*4+j] on the shared byte layout. */
 function OrthoOffCenterMatrix(out, l, r, b, t, zn, zf) {
   mat4.identity(out);
@@ -92,8 +96,8 @@ function OrthoOffCenterMatrix(out, l, r, b, t, zn, zf) {
   return out;
 }
 
-/** Carbon TransformNormal(v, M) - row-vector basis-only transform (no
- * translation): out_j = sum_i v_i * M[i][j], rows at gl flat [0..2]/[4..6]/
+/** Carbon TransformNormal(v, M) - row-vector basis-only transform (no
+ * translation): out_j = sum_i v_i * M[i][j], rows at gl flat [0..2]/[4..6]/
  * [8..10]. vec3.transformMat4 would add the translation - do not use it. */
 function TransformNormal(out, v, m) {
   const x = v[0];
@@ -116,7 +120,7 @@ new class extends _identity {
       } = _applyDecs2311(this, [type.define({
         className: "EveChildCloud2",
         family: "eve/child"
-      })], [[[io, io.notify, io, io.persist, type, type.int32, void 0, type.enum("ReflectionMode")], 16, "reflectionMode"], [[io, io.persist, type, type.int32, void 0, type.enum("Tr2VolumerticQuality")], 16, "minVisibleQuality"], [[io, io.persist, type, type.float32], 16, "sortingModifier"], [[io, io.persist, void 0, type.model("Tr2TextureAnimation")], 16, "animation"], [[io, io.notify, io, io.readwrite, void 0, type.objectRef("Tr2DepthStencil")], 16, "shadowMapDS"], [[io, io.read, void 0, type.objectRef("Tr2TextureReference")], 16, "lightmap"], [[io, io.read, type, type.float32], 16, "lightmapSizeScale"], [[io, io.persist, void 0, type.list("Tr2Light")], 16, "lights"], [[io, io.persist, type, type.float32], 16, "minScreenSize"], [[io, io.persist, type, type.quat], 16, "rotation"], [[io, io.persist, type, type.vec3], 16, "translation"], [[io, io.persist, type, type.vec3], 16, "scaling"], [[io, io.notify, io, io.persist, void 0, type.model("Tr2Effect")], 16, "reflectionEffect"], [[io, io.notify, io, io.persist, void 0, type.model("Tr2Effect")], 16, "effect"], [[io, io.persist, type, type.uint32], 16, "noiseTextureSize"], [[io, io.read, type, type.vec3], 16, "mapOffset0"], [[io, io.read, type, type.vec3], 16, "mapOffset1"], [[io, io.read, type, type.vec3], 16, "mapOffset2"], [[io, io.persist, type, type.boolean], 16, "castShadows"], [[io, io.persist, type, type.boolean], 16, "receiveShadows"], [[io, io.persist, type, type.string], 16, "name"], [[io, io.persist, type, type.vec3], 16, "detailTiling1"], [[io, io.persist, type, type.vec3], 16, "detailTiling2"], [[io, io.persist, type, type.vec3], 16, "textureTiling"], [[io, io.notify, io, io.persist, type, type.boolean], 16, "display"], [[impl, impl.implemented], 18, "RegisterComponents"], [[impl, impl.adapted, void 0, impl.reason("DensityMap texture discovery and empty-lightmap creation (cpp:634-674) are engine-owned resource work - lightmapWidth stays 0 until the engine stamps it, which fail-closes UpdateVolumetricLightmap; the hash invalidation, animation gate and renderedLastFrame contract are ported.")], 18, "UpdateSyncronous"], [[impl, impl.implemented], 18, "UpdateAsyncronous"], [[impl, impl.implemented], 18, "GetBoundingSphere"], [[impl, impl.implemented], 18, "GetLocalToWorldTransform"], [[impl, impl.implemented], 18, "IsVisible"], [[impl, impl.implemented], 18, "HasValidTransform"], [[impl, impl.implemented], 18, "IsLightmapDirty"], [[impl, impl.implemented], 18, "MarkLightmapDirty"], [[impl, impl.implemented], 18, "GetLights"], [[impl, impl.implemented], 18, "GetSortValue"], [[impl, impl.adapted, void 0, impl.reason("The procedural unit-cube vertex/index buffers and declaration (OnPrepareResources cpp:453-532) are engine-realized, so the buffer-validity gate (cpp:267-270) and shader-state gate (cpp:271-274) reduce to the effect presence check; the batch records the effect, per-object data and draw arguments for the engine to bind the cube.")], 18, "GetVolumetricBatches"], [[impl, impl.adapted, void 0, impl.reason("The 3D lightmap texture lifecycle, per-object upload and LightMap variable swaps (cpp:327-352, 363-372) are engine-owned; the GenerateLightmap dispatch is delegated to a renderContext.RunComputeShader duck and fail-closes to false when absent.")], 18, "UpdateVolumetricLightmap"], [[impl, impl.adapted, void 0, impl.reason("Carbon dereferences m_effect with no null guard (cpp:417); the JS option writes are optional-chained. Everything else is verbatim, including the missing degree conversion in the sun-motion threshold.")], 18, "SetSceneInformation"], [[impl, impl.adapted, void 0, impl.reason("The 'Shadow' technique gate applies only when a shader-state interface is realized - in GPU-free collection the engine drops the batch at realization otherwise; NULL_DECLARATION maps to declaration 0.")], 18, "GetVolumetricShadowBatches"], [[impl, impl.implemented], 18, "GetVolumetricShadowInfo"], [[impl, impl.implemented], 18, "SetupShadowFrustum"], [[impl, impl.adapted, void 0, impl.reason("Depth-stencil creation and the viewport/render-target pushes (cpp:801-823) are engine-owned, delegated to a renderContext duck; the gate and return contract are ported.")], 18, "PrepareCloudShadowMap"], [[impl, impl.adapted, void 0, impl.reason("The variable store is engine-owned (depthShadowMapHandle is an injected duck); Carbon's unguarded m_shadowMapDS dereference is optional-chained.")], 18, "SetCloudShadowMapHandle"], [[impl, impl.adapted, void 0, impl.reason("Unit-cube buffers/declaration are engine-realized (as GetVolumetricBatches); the perObjectData parameter is unused because Carbon allocates the cloud's own with screenSize 10000 (cpp:878).")], 18, "GetBatches"], [[impl, impl.implemented], 18, "HasTransparentBatches"], [[impl, impl.adapted, void 0, impl.reason("EveChildCloudPerObjectData's device constant buffers are engine-owned; the record carries the object reference, the collection-time screenSize and the CPU field block.")], 18, "GetPerObjectData"], [[impl, impl.adapted, void 0, impl.reason("Tr2Renderer's view/projection globals relocate onto the optional renderContext duck (identity/zero fallbacks when absent - the engine repopulates at realization); rand() maps to Math.random with a zero-size guard Carbon's UB-free ctor default (32) never needed; the Tr2Light Perlin flicker inside GetLight awaits the frame-clock seam.")], 18, "PopulatePerObjectData"]], 0, void 0, _withITr2Renderable));
+      })], [[[io, io.notify, io, io.persist, type, type.int32, void 0, type.enum("ReflectionMode")], 16, "reflectionMode"], [[io, io.persist, type, type.int32, void 0, type.enum("Tr2VolumerticQuality")], 16, "minVisibleQuality"], [[io, io.persist, type, type.float32], 16, "sortingModifier"], [[io, io.persist, void 0, type.model("Tr2TextureAnimation")], 16, "animation"], [[io, io.notify, io, io.readwrite, void 0, type.objectRef("Tr2DepthStencil")], 16, "shadowMapDS"], [[io, io.read, void 0, type.objectRef("Tr2TextureReference")], 16, "lightmap"], [[io, io.read, type, type.float32], 16, "lightmapSizeScale"], [[io, io.persist, void 0, type.list("Tr2Light")], 16, "lights"], [[io, io.persist, type, type.float32], 16, "minScreenSize"], [[io, io.persist, type, type.quat], 16, "rotation"], [[io, io.persist, type, type.vec3], 16, "translation"], [[io, io.persist, type, type.vec3], 16, "scaling"], [[io, io.notify, io, io.persist, void 0, type.model("Tr2Effect")], 16, "reflectionEffect"], [[io, io.notify, io, io.persist, void 0, type.model("Tr2Effect")], 16, "effect"], [[io, io.persist, type, type.uint32], 16, "noiseTextureSize"], [[io, io.read, type, type.vec3], 16, "mapOffset0"], [[io, io.read, type, type.vec3], 16, "mapOffset1"], [[io, io.read, type, type.vec3], 16, "mapOffset2"], [[io, io.persist, type, type.boolean], 16, "castShadows"], [[io, io.persist, type, type.boolean], 16, "receiveShadows"], [[io, io.persist, type, type.string], 16, "name"], [[io, io.persist, type, type.vec3], 16, "detailTiling1"], [[io, io.persist, type, type.vec3], 16, "detailTiling2"], [[io, io.persist, type, type.vec3], 16, "textureTiling"], [[io, io.notify, io, io.persist, type, type.boolean], 16, "display"], [[impl, impl.implemented], 18, "RegisterComponents"], [[impl, impl.adapted, void 0, impl.reason("DensityMap texture discovery and empty-lightmap creation (cpp:634-674) are engine-owned resource work - lightmapWidth stays 0 until the engine stamps it, which fail-closes UpdateVolumetricLightmap; the hash invalidation, animation gate and renderedLastFrame contract are ported.")], 18, "UpdateSyncronous"], [[impl, impl.implemented], 18, "UpdateAsyncronous"], [[impl, impl.implemented], 18, "GetBoundingSphere"], [[impl, impl.implemented], 18, "GetLocalToWorldTransform"], [[impl, impl.implemented], 18, "IsVisible"], [[impl, impl.implemented], 18, "HasValidTransform"], [[impl, impl.implemented], 18, "IsLightmapDirty"], [[impl, impl.implemented], 18, "MarkLightmapDirty"], [[impl, impl.implemented], 18, "GetLights"], [[impl, impl.implemented], 18, "GetSortValue"], [[impl, impl.adapted, void 0, impl.reason("The procedural unit-cube vertex/index buffers and declaration (OnPrepareResources cpp:453-532) are engine-realized, so the buffer-validity gate (cpp:267-270) and shader-state gate (cpp:271-274) reduce to the effect presence check; the batch records the effect, per-object data and draw arguments for the engine to bind the cube.")], 18, "GetVolumetricBatches"], [[impl, impl.adapted, void 0, impl.reason("The 3D lightmap texture lifecycle, per-object upload and LightMap variable swaps (cpp:327-352, 363-372) are engine-owned; the GenerateLightmap dispatch is delegated to a renderContext.RunComputeShader duck and fail-closes to false when absent.")], 18, "UpdateVolumetricLightmap"], [[impl, impl.adapted, void 0, impl.reason("Carbon dereferences m_effect with no null guard (cpp:417); the JS option writes are optional-chained. Everything else is verbatim, including the missing degree conversion in the sun-motion threshold.")], 18, "SetSceneInformation"], [[impl, impl.adapted, void 0, impl.reason("The 'Shadow' technique gate applies only when a shader-state interface is realized - in GPU-free collection the engine drops the batch at realization otherwise; NULL_DECLARATION maps to declaration 0.")], 18, "GetVolumetricShadowBatches"], [[impl, impl.implemented], 18, "GetVolumetricShadowInfo"], [[impl, impl.implemented], 18, "SetupShadowFrustum"], [[carbon, carbon.method, impl, impl.notImplemented, void 0, impl.reason("Needs Tr2DepthStencil, which is a generated shell: Create throws and GetTexture/IsValid/GetWidth/GetHeight are absent. The receiveShadows gate and the false return are ported.")], 18, "PrepareCloudShadowMap"], [[impl, impl.adapted, void 0, impl.reason("The variable store is engine-owned (depthShadowMapHandle is an injected duck); Carbon's unguarded m_shadowMapDS dereference is optional-chained.")], 18, "SetCloudShadowMapHandle"], [[impl, impl.adapted, void 0, impl.reason("Unit-cube buffers/declaration are engine-realized (as GetVolumetricBatches); the perObjectData parameter is unused because Carbon allocates the cloud's own with screenSize 10000 (cpp:878).")], 18, "GetBatches"], [[impl, impl.implemented], 18, "HasTransparentBatches"], [[impl, impl.adapted, void 0, impl.reason("EveChildCloudPerObjectData's device constant buffers are engine-owned; the record carries the object reference, the collection-time screenSize and the CPU field block.")], 18, "GetPerObjectData"], [[impl, impl.adapted, void 0, impl.reason("Tr2Renderer's view/projection globals relocate onto the optional renderContext duck (identity/zero fallbacks when absent - the engine repopulates at realization); rand() maps to Math.random with a zero-size guard Carbon's UB-free ctor default (32) never needed; the Tr2Light Perlin flicker inside GetLight awaits the frame-clock seam.")], 18, "PopulatePerObjectData"]], 0, void 0, _withITr2Renderable));
     }
     /** m_reflectionMode (EntityComponents::ReflectionMode - enum ReflectionMode) [READWRITE, PERSIST, NOTIFY, ENUM] */
     reflectionMode = (_initProto(this), _init_reflectionMode(this, 0));
@@ -231,8 +235,8 @@ new class extends _identity {
     /** m_effectHash - effect identity tracked by UpdateSyncronous (cpp:625-633). */
     effectHash = 0;
 
-    /** Unscaled lightmap dimensions - Carbon discovers them from the effect's
-     * DensityMap resource (cpp:634-665, engine-owned in JS; 0 fail-closes
+    /** Unscaled lightmap dimensions - Carbon discovers them from the effect's
+     * DensityMap resource (cpp:634-665, engine-owned in JS; 0 fail-closes
      * UpdateVolumetricLightmap). */
     lightmapWidth = 0;
 
@@ -251,35 +255,35 @@ new class extends _identity {
     /** m_localSunDirection (SetSceneInformation cpp:407). */
     localSunDirection = vec3.create();
 
-    /** m_depthSlices - SceneInformation::depthSliceCount = 4
+    /** m_depthSlices - SceneInformation::depthSliceCount = 4
      * (ITr2VolumetricRenderable.h:26). */
     depthSlices = new Float32Array(4);
 
-    /** m_targetWidth - Carbon leaves it uninitialized until SetSceneInformation;
-     * JS zeroes (targetInvSize then divides by zero to Infinity, matching
+    /** m_targetWidth - Carbon leaves it uninitialized until SetSceneInformation;
+     * JS zeroes (targetInvSize then divides by zero to Infinity, matching
      * Carbon's float semantics on garbage-free zero). */
     targetWidth = 0;
 
     /** m_targetHeight - see targetWidth. */
     targetHeight = 0;
 
-    /** m_lightViewProj - Carbon: uninitialized memory until SetupShadowFrustum;
+    /** m_lightViewProj - Carbon: uninitialized memory until SetupShadowFrustum;
      * JS: identity. */
     lightViewProj = mat4.create();
 
     /** m_shadowMapSize (cpp:101). */
     shadowMapSize = 512;
 
-    /** The global "DepthShadowMap" variable handle Carbon registers in the ctor
-     * (cpp:115) - the variable store is engine-owned in JS, so the handle is an
+    /** The global "DepthShadowMap" variable handle Carbon registers in the ctor
+     * (cpp:115) - the variable store is engine-owned in JS, so the handle is an
      * engine-injected duck. */
     depthShadowMapHandle = null;
 
-    /** Carbon EveChildCloud2::RegisterComponents (EveChildCloud2.cpp:148-163):
-     * LightOwner when lights are authored; VolumetricRenderable UNCONDITIONAL;
-     * ReflectionRenderable only when ShouldReflect && display &&
-     * reflectionEffect. Note: no whole-block display gate in Carbon. No
-     * UnRegisterComponents override (base no-op; EveEntity::UnRegister already
+    /** Carbon EveChildCloud2::RegisterComponents (EveChildCloud2.cpp:148-163):
+     * LightOwner when lights are authored; VolumetricRenderable UNCONDITIONAL;
+     * ReflectionRenderable only when ShouldReflect && display &&
+     * reflectionEffect. Note: no whole-block display gate in Carbon. No
+     * UnRegisterComponents override (base no-op; EveEntity::UnRegister already
      * removes the components, EveEntity.cpp:90). */
     RegisterComponents() {
       const registry = this.GetComponentRegistry();
@@ -294,13 +298,13 @@ new class extends _identity {
       }
     }
 
-    /** Carbon EveChildCloud2::UpdateSyncronous (cpp:621-685): an effect-hash
-     * change invalidates the lightmap and zeroes its dimensions (cpp:625-633);
-     * the DensityMap-driven dimension discovery and the empty-lightmap fallback
-     * (cpp:634-674) are GPU/resource work; the texture animation advances gated
-     * on UpdateOnlyWhenRendered/renderedLastFrame (cpp:677-683) and
-     * renderedLastFrame is cleared every pass (cpp:684) - the flag is only
-     * re-stamped by the volumetric batch path (GetVolumetricBatches cpp:283),
+    /** Carbon EveChildCloud2::UpdateSyncronous (cpp:621-685): an effect-hash
+     * change invalidates the lightmap and zeroes its dimensions (cpp:625-633);
+     * the DensityMap-driven dimension discovery and the empty-lightmap fallback
+     * (cpp:634-674) are GPU/resource work; the texture animation advances gated
+     * on UpdateOnlyWhenRendered/renderedLastFrame (cpp:677-683) and
+     * renderedLastFrame is cleared every pass (cpp:684) - the flag is only
+     * re-stamped by the volumetric batch path (GetVolumetricBatches cpp:283),
      * deliberately NOT by the reflection path. */
     UpdateSyncronous(updateContext, _params) {
       if (this.effect) {
@@ -315,20 +319,20 @@ new class extends _identity {
       }
       if (this.animation) {
         if (!this.animation.UpdateOnlyWhenRendered?.() || this.renderedLastFrame) {
-          this.animation.AdvanceTime?.(updateContext?.GetDeltaT?.() ?? 0);
+          this.animation.AdvanceTime?.(updateContext?.GetDeltaT() ?? 0);
         }
       }
       this.renderedLastFrame = false;
     }
 
-    /** Carbon EveChildCloud2::UpdateAsyncronous (cpp:687-708): local SRT
-     * transform (cpp:689); world = localTransform * parent - Carbon row-vector,
-     * local applies first, so the gl-matrix operands swap (cpp:693); bounding
-     * sphere = CcpMath::Sphere(unit cube, world) which transforms ONLY the min
-     * and max corners (math Sphere.cpp:10-17 - the cheap two-corner form, not an
-     * 8-corner bound; preserved); map-offset scroll from the origin-shift-
-     * corrected world movement rotated into local space (cpp:697-704 - QUIRK
-     * kept verbatim: the .z offset scrolls by mapTiling.y, cpp:703); adjusted
+    /** Carbon EveChildCloud2::UpdateAsyncronous (cpp:687-708): local SRT
+     * transform (cpp:689); world = localTransform * parent - Carbon row-vector,
+     * local applies first, so the gl-matrix operands swap (cpp:693); bounding
+     * sphere = CcpMath::Sphere(unit cube, world) which transforms ONLY the min
+     * and max corners (math Sphere.cpp:10-17 - the cheap two-corner form, not an
+     * 8-corner bound; preserved); map-offset scroll from the origin-shift-
+     * corrected world movement rotated into local space (cpp:697-704 - QUIRK
+     * kept verbatim: the .z offset scrolls by mapTiling.y, cpp:703); adjusted
      * min screen size (cpp:706); hasUpdated stamp (cpp:707). */
     UpdateAsyncronous(updateContext, params = {}) {
       // Carbon TransformationMatrix(m_scaling, m_rotation, m_translation)
@@ -355,7 +359,7 @@ new class extends _identity {
 
       // shift = -originShift + (new - previous world translation), then rotated
       // into local space with TransformNormal(shift, Inverse(world)) (cpp:697-698).
-      const originShift = updateContext?.GetOriginShift?.();
+      const originShift = updateContext?.GetOriginShift();
       SHIFT_SCRATCH[0] = (originShift ? -originShift[0] : 0) + w[12] - prevX;
       SHIFT_SCRATCH[1] = (originShift ? -originShift[1] : 0) + w[13] - prevY;
       SHIFT_SCRATCH[2] = (originShift ? -originShift[2] : 0) + w[14] - prevZ;
@@ -373,12 +377,12 @@ new class extends _identity {
         // Carbon bug preserved verbatim: .z scrolls by mapTiling.y (cpp:703).
         offset[2] = (offset[2] + SHIFT_SCRATCH[2] * tiling[1]) % 1;
       }
-      this.adjustedMinScreenSize = this.minScreenSize * (updateContext?.GetLodFactor?.() ?? 1);
+      this.adjustedMinScreenSize = this.minScreenSize * (updateContext?.GetLodFactor() ?? 1);
       this.hasUpdated = true;
     }
 
-    /** Carbon EveChildCloud2::GetBoundingSphere (cpp:226-230): the packed
-     * (center, radius) cloud sphere, unconditionally true. IEveSpaceObjectChild
+    /** Carbon EveChildCloud2::GetBoundingSphere (cpp:226-230): the packed
+     * (center, radius) cloud sphere, unconditionally true. IEveSpaceObjectChild
      * override - parent bounds unions consume it optional-chained. */
     GetBoundingSphere(out = new Float32Array(4), _query = 0) {
       out[0] = this.boundingSphere.center[0];
@@ -388,7 +392,7 @@ new class extends _identity {
       return true;
     }
 
-    /** Carbon EveChildCloud2::GetLocalToWorldTransform (cpp:232-235); the
+    /** Carbon EveChildCloud2::GetLocalToWorldTransform (cpp:232-235); the
      * optional out follows the EveChildContainer copy-out shape. */
     GetLocalToWorldTransform(out = null) {
       if (out) {
@@ -397,14 +401,14 @@ new class extends _identity {
       return this.worldTransform;
     }
 
-    /** Carbon EveChildCloud2::IsVisible (cpp:837-852): display + one-arg
-     * IsSphereVisible (the back-plane-ignored TriFrustum quirk applies), then
-     * the Sphere-duck GetPixelSizeAccross (Est path) against minScreenSize *
-     * the LIVE lodFactor (not the adjusted stamp). Carbon's override of the
-     * defaulted ITr2Renderable::IsVisible (h:47-50 returns true) - without it
+    /** Carbon EveChildCloud2::IsVisible (cpp:837-852): display + one-arg
+     * IsSphereVisible (the back-plane-ignored TriFrustum quirk applies), then
+     * the Sphere-duck GetPixelSizeAccross (Est path) against minScreenSize *
+     * the LIVE lodFactor (not the adjusted stamp). Carbon's override of the
+     * defaulted ITr2Renderable::IsVisible (h:47-50 returns true) - without it
      * the reflection gather would treat the cloud as always visible. */
     IsVisible(updateContext) {
-      const frustum = updateContext?.GetFrustum?.();
+      const frustum = updateContext?.GetFrustum();
       if (!frustum) {
         return false;
       }
@@ -413,13 +417,13 @@ new class extends _identity {
         return false;
       }
       const screenSize = frustum.GetPixelSizeAccross(sphere);
-      if (screenSize < this.minScreenSize * (updateContext?.GetLodFactor?.() ?? 1)) {
+      if (screenSize < this.minScreenSize * (updateContext?.GetLodFactor() ?? 1)) {
         return false;
       }
       return true;
     }
 
-    /** Carbon EveChildCloud2::HasValidTransform (cpp:309-317): determinant is
+    /** Carbon EveChildCloud2::HasValidTransform (cpp:309-317): determinant is
      * nonzero and finite. */
     HasValidTransform() {
       const det = mat4.determinant(this.worldTransform);
@@ -431,20 +435,20 @@ new class extends _identity {
       return this.lightmapDirty;
     }
 
-    /** Carbon EveChildCloud2::MarkLightmapDirty (cpp:753-757): also zeroes the
-     * dirty offset (contrast SetSceneInformation's scale-change path, which
+    /** Carbon EveChildCloud2::MarkLightmapDirty (cpp:753-757): also zeroes the
+     * dirty offset (contrast SetSceneInformation's scale-change path, which
      * sets the flag WITHOUT resetting the offset - cpp:398-402). */
     MarkLightmapDirty(dirty) {
       this.lightmapDirty = !!dirty;
       this.lightmapDirtyOffset = 0;
     }
 
-    /** Carbon EveChildCloud2::GetLights (cpp:732-746): display gate only (no
-     * hasUpdated gate, unlike EveChildContainer), average world-basis-row-length
-     * scaling (Carbon LengthEst; exact hypot is the accepted divergence - single
-     * matrix reads, no composition), each light submitted with the world
-     * transform through the duck-typed manager. Inside Tr2Light::AddLight
-     * Carbon composes boneTransform * transform (Tr2Light.cpp:132) - that swap
+    /** Carbon EveChildCloud2::GetLights (cpp:732-746): display gate only (no
+     * hasUpdated gate, unlike EveChildContainer), average world-basis-row-length
+     * scaling (Carbon LengthEst; exact hypot is the accepted divergence - single
+     * matrix reads, no composition), each light submitted with the world
+     * transform through the duck-typed manager. Inside Tr2Light::AddLight
+     * Carbon composes boneTransform * transform (Tr2Light.cpp:132) - that swap
      * belongs to the Tr2Light port, not here. */
     GetLights(lightManager) {
       if (!this.display) {
@@ -457,12 +461,12 @@ new class extends _identity {
       }
     }
 
-    /** Carbon's two GetSortValue overloads, dispatched on argument presence:
-     * the ITr2VolumetricRenderable frustum form (cpp:237-242) - view distance
-     * minus |authored local scaling| * sortingModifier, consumed by the
-     * volumetric renderer's DESCENDING stable sort (farthest first,
-     * Tr2VolumetricsRenderer.cpp:276-287) - and the ITr2Renderable zero-arg
-     * form (cpp:914-917) - float32 max (finite, NOT Infinity), so the
+    /** Carbon's two GetSortValue overloads, dispatched on argument presence:
+     * the ITr2VolumetricRenderable frustum form (cpp:237-242) - view distance
+     * minus |authored local scaling| * sortingModifier, consumed by the
+     * volumetric renderer's DESCENDING stable sort (farthest first,
+     * Tr2VolumetricsRenderer.cpp:276-287) - and the ITr2Renderable zero-arg
+     * form (cpp:914-917) - float32 max (finite, NOT Infinity), so the
      * transparent reflection pass sorts the cloud to draw first. */
     GetSortValue(frustum = null) {
       if (!frustum) {
@@ -476,13 +480,13 @@ new class extends _identity {
       return Math.hypot(dx, dy, dz) - vec3.length(this.scaling) * this.sortingModifier;
     }
 
-    /** Carbon EveChildCloud2::GetVolumetricBatches (cpp:244-284), exact gate
-     * order: quality (cpp:246), display+hasUpdated+frustum sphere (cpp:250),
-     * Sphere-duck pixel size vs the adjusted min screen size (cpp:256-260),
-     * HasValidTransform (cpp:262), unit-cube buffers + effect shader
-     * (cpp:267-274), then ONE transparent volumetric batch with the real
-     * screenSize per-object data and Carbon's 36-index draw (cpp:276-281).
-     * Stamps renderedLastFrame (cpp:283) - the texture-animation keep-alive.
+    /** Carbon EveChildCloud2::GetVolumetricBatches (cpp:244-284), exact gate
+     * order: quality (cpp:246), display+hasUpdated+frustum sphere (cpp:250),
+     * Sphere-duck pixel size vs the adjusted min screen size (cpp:256-260),
+     * HasValidTransform (cpp:262), unit-cube buffers + effect shader
+     * (cpp:267-274), then ONE transparent volumetric batch with the real
+     * screenSize per-object data and Carbon's 36-index draw (cpp:276-281).
+     * Stamps renderedLastFrame (cpp:283) - the texture-animation keep-alive.
      * Returns whether a batch was committed (JS addition; Carbon returns void). */
     GetVolumetricBatches(frustum, batches) {
       if (this.currentQuality < this.minVisibleQuality) {
@@ -515,15 +519,15 @@ new class extends _identity {
       return committed;
     }
 
-    /** Carbon EveChildCloud2::UpdateVolumetricLightmap (cpp:319-382): the
-     * scene-facing contract is the gates and the bool return - true means "this
-     * cloud consumed the frame's single scene-wide lightmap budget"
-     * (Tr2VolumetricsRenderer::ProcessComponentsUntil stops at the FIRST true,
-     * cpp:219-221). Slice budget: VOXELS_PER_UPDATE = 6400000 * scale^3;
-     * slices = max(VOXELS / (scaledHeight * scaledDepth), 1) (cpp:354-355).
-     * QUIRK verbatim: the dispatch group Y/Z counts use the UNSCALED dims while
-     * the slice count uses the scaled ones (cpp:359-361). Success advances
-     * lightmapDirtyOffset by slices; reaching scaledWidth completes the map
+    /** Carbon EveChildCloud2::UpdateVolumetricLightmap (cpp:319-382): the
+     * scene-facing contract is the gates and the bool return - true means "this
+     * cloud consumed the frame's single scene-wide lightmap budget"
+     * (Tr2VolumetricsRenderer::ProcessComponentsUntil stops at the FIRST true,
+     * cpp:219-221). Slice budget: VOXELS_PER_UPDATE = 6400000 * scale^3;
+     * slices = max(VOXELS / (scaledHeight * scaledDepth), 1) (cpp:354-355).
+     * QUIRK verbatim: the dispatch group Y/Z counts use the UNSCALED dims while
+     * the slice count uses the scaled ones (cpp:359-361). Success advances
+     * lightmapDirtyOffset by slices; reaching scaledWidth completes the map
      * (dirty false, offset 0); failure resets the offset and returns false. */
     UpdateVolumetricLightmap(renderContext) {
       if (this.currentQuality < this.minVisibleQuality || !this.hasUpdated) {
@@ -549,15 +553,15 @@ new class extends _identity {
       return false;
     }
 
-    /** Carbon EveChildCloud2::SetSceneInformation (cpp:384-424): quality maps to
-     * lightmapSizeScale (Low 0.1 / Medium 0.15 / default 0.25, cpp:386-397); a
-     * scale change sets lightmapDirty WITHOUT resetting the dirty offset
-     * (cpp:398-402 - asymmetric vs MarkLightmapDirty, preserved); copies the 4
-     * depth slices; localSunDirection = Normalize(TransformNormal(sunDir,
-     * Inverse(world))) (cpp:407 - single-matrix inverse + basis transform, no
-     * composition); re-dirties the lightmap when the sun moved past
-     * cos(5/180) - QUIRK verbatim: Carbon omits the degree conversion, so the
-     * threshold is ~1.59 degrees, not 5 (cpp:408); stamps target dims; flips
+    /** Carbon EveChildCloud2::SetSceneInformation (cpp:384-424): quality maps to
+     * lightmapSizeScale (Low 0.1 / Medium 0.15 / default 0.25, cpp:386-397); a
+     * scale change sets lightmapDirty WITHOUT resetting the dirty offset
+     * (cpp:398-402 - asymmetric vs MarkLightmapDirty, preserved); copies the 4
+     * depth slices; localSunDirection = Normalize(TransformNormal(sunDir,
+     * Inverse(world))) (cpp:407 - single-matrix inverse + basis transform, no
+     * composition); re-dirties the lightmap when the sun moved past
+     * cos(5/180) - QUIRK verbatim: Carbon omits the degree conversion, so the
+     * threshold is ~1.59 degrees, not 5 (cpp:408); stamps target dims; flips
      * the two cloud-shadow effect options (cpp:417-423). */
     SetSceneInformation(sceneInformation) {
       let lightmapSizeScale;
@@ -596,11 +600,11 @@ new class extends _identity {
       this.effect?.SetOption?.("CLOUD_SHADOW_ALGORITHM", receive && sceneInformation.raytracedShadows ? "CLOUD_SHADOWS_RAYTRACED" : "CLOUD_SHADOWS_CASCADED");
     }
 
-    /** Carbon EveChildCloud2::GetVolumetricShadowBatches (cpp:759-785): gated on
-     * display + effect + castShadows, then the "Shadow" technique presence
-     * (cpp:766-776); emits ONE alpha, declaration-less (NULL_DECLARATION,
-     * cpp:782), non-indexed single-triangle batch with screenSize-1 per-object
-     * data (cpp:778-784). Does NOT stamp renderedLastFrame. Returns whether the
+    /** Carbon EveChildCloud2::GetVolumetricShadowBatches (cpp:759-785): gated on
+     * display + effect + castShadows, then the "Shadow" technique presence
+     * (cpp:766-776); emits ONE alpha, declaration-less (NULL_DECLARATION,
+     * cpp:782), non-indexed single-triangle batch with screenSize-1 per-object
+     * data (cpp:778-784). Does NOT stamp renderedLastFrame. Returns whether the
      * batch was committed (JS addition). */
     GetVolumetricShadowBatches(batches) {
       if (!this.display || !this.effect || !this.castShadows) {
@@ -625,25 +629,25 @@ new class extends _identity {
       return batches?.Commit?.(batch) === true;
     }
 
-    /** Carbon EveChildCloud2::GetVolumetricShadowInfo (cpp:787-790): pure
-     * delegation to SetupShadowFrustum. The scene calls this to build the
-     * shadow-camera package before rendering casters into the cloud shadow map
+    /** Carbon EveChildCloud2::GetVolumetricShadowInfo (cpp:787-790): pure
+     * delegation to SetupShadowFrustum. The scene calls this to build the
+     * shadow-camera package before rendering casters into the cloud shadow map
      * (EveSpaceScene.cpp:2355-2371). */
     GetVolumetricShadowInfo(shadowInfo, sunDir) {
       return this.SetupShadowFrustum(shadowInfo, sunDir);
     }
 
-    /** Carbon EveChildCloud2::SetupShadowFrustum (cpp:886-907):
-     * lightView = Inverse(OrthoNormalBasisZ(-sunDir)) (cpp:889 - single-matrix
-     * build + invert); the unit-cube AABB transformed by worldTransform *
-     * lightView - COMPOSITION, world applies first, so the gl-matrix operands
-     * swap (cpp:893; all 8 corners, math AxisAlignedBox.cpp:9-33); max.z
-     * extended by the 2,500,000 sun-ray magic constant (cpp:895); lightViewProj
-     * = lightView * OrthoOffCenterMatrix(...) - COMPOSITION, lightView first,
-     * operands swap (cpp:897), with Carbon's deliberately mirrored argument
-     * order (max.x, min.x, max.y, min.y, -max.z, -min.z) and D3D z-in-[0,1]
-     * formula both preserved; DeriveFrustum(lightView, aabb.min, aabb.max)
-     * (cpp:900-901); outputs aabbMax / lightViewProj copy / shadowFrustum /
+    /** Carbon EveChildCloud2::SetupShadowFrustum (cpp:886-907):
+     * lightView = Inverse(OrthoNormalBasisZ(-sunDir)) (cpp:889 - single-matrix
+     * build + invert); the unit-cube AABB transformed by worldTransform *
+     * lightView - COMPOSITION, world applies first, so the gl-matrix operands
+     * swap (cpp:893; all 8 corners, math AxisAlignedBox.cpp:9-33); max.z
+     * extended by the 2,500,000 sun-ray magic constant (cpp:895); lightViewProj
+     * = lightView * OrthoOffCenterMatrix(...) - COMPOSITION, lightView first,
+     * operands swap (cpp:897), with Carbon's deliberately mirrored argument
+     * order (max.x, min.x, max.y, min.y, -max.z, -min.z) and D3D z-in-[0,1]
+     * formula both preserved; DeriveFrustum(lightView, aabb.min, aabb.max)
+     * (cpp:900-901); outputs aabbMax / lightViewProj copy / shadowFrustum /
      * shadowMapSize (cpp:903-906). */
     SetupShadowFrustum(shadowInfo, sunDir) {
       vec3.set(SUN_SCRATCH, -sunDir[0], -sunDir[1], -sunDir[2]);
@@ -687,23 +691,46 @@ new class extends _identity {
       return shadowInfo;
     }
 
-    /** Carbon EveChildCloud2::PrepareCloudShadowMap (cpp:792-826): the CPU
-     * contract is the receiveShadows gate (cpp:796-799) and the bool return -
-     * the scene calls SetCloudShadowMapHandle ONLY after a true return
-     * (EveSpaceScene.cpp:2365-2368), which is what makes Carbon's unguarded
-     * m_shadowMapDS dereference there safe. */
-    PrepareCloudShadowMap(renderContext) {
+    /**
+     * Makes this cloud's depth-stencil the render target for its shadow pass.
+     *
+     * THE GATE IS PORTED AND THE WORK IS NOT, which is why this returns false in
+     * one case and throws in the other. Carbon's contract
+     * (`EveChildCloud2.cpp:774-808`) is that `receiveShadows` decides whether
+     * there is a shadow map at all, and the scene calls `SetCloudShadowMapHandle`
+     * ONLY after a true return (`EveSpaceScene.cpp:2365-2368`) - which is what
+     * makes Carbon's unguarded `m_shadowMapDS` dereference there safe.
+     *
+     * A cloud that does not receive shadows is therefore fully correct here.
+     *
+     * WHAT IS MISSING. Carbon creates the depth-stencil, pushes it as the target,
+     * clears depth and sets the viewport. Every push, the clear and
+     * `SetReadOnlyDepth` exist here; `Tr2DepthStencil` does not. Ours is a
+     * generated shell whose `Create` throws and which declares none of
+     * `GetTexture`, `IsValid`, `GetWidth` or `GetHeight` - the four Carbon uses
+     * (`Tr2DepthStencil.h:29,40,48,54-55`).
+     *
+     * THIS USED TO RETURN TRUE HAVING DONE NOTHING. The body was
+     * `renderContext?.PrepareCloudShadowMap?.(this)` against a method no render
+     * context defines - optional-chained, so it no-opped, and the scene then
+     * published a shadow-map handle for a shadow map that was never rendered.
+     * Failing here is the point: the gap is in `Tr2DepthStencil`, and it should
+     * be visible from the one place that needs it.
+     *
+     * @returns {boolean} False when this cloud receives no shadows; otherwise
+     *   never returns.
+     */
+    PrepareCloudShadowMap() {
       if (!this.receiveShadows) {
         return false;
       }
-      renderContext?.PrepareCloudShadowMap?.(this);
-      return true;
+      throw new Error("EveChildCloud2.PrepareCloudShadowMap: needs Tr2DepthStencil.Create and its " + "GetTexture/IsValid/GetWidth/GetHeight accessors, which are unported.");
     }
 
-    /** Carbon EveChildCloud2::SetCloudShadowMapHandle (cpp:829-835): publish the
-     * shadow depth-stencil into the global "DepthShadowMap" variable handle
-     * (registered in the Carbon ctor, cpp:115). QUIRK: Carbon dereferences
-     * m_shadowMapDS with no null guard - safe only via the
+    /** Carbon EveChildCloud2::SetCloudShadowMapHandle (cpp:829-835): publish the
+     * shadow depth-stencil into the global "DepthShadowMap" variable handle
+     * (registered in the Carbon ctor, cpp:115). QUIRK: Carbon dereferences
+     * m_shadowMapDS with no null guard - safe only via the
      * PrepareCloudShadowMap-first call order (see above). */
     SetCloudShadowMapHandle() {
       if (this.shadowMapDS?.IsValid?.()) {
@@ -711,13 +738,13 @@ new class extends _identity {
       }
     }
 
-    /** Carbon EveChildCloud2::GetBatches (cpp:854-884): quality gate, then ONLY
-     * the (REFLECTION, TRANSPARENT) type/reason pair produces anything
-     * (cpp:860) - every other combination is a silent no-op; HasValidTransform
-     * + unit-cube buffers + reflectionEffect gates (cpp:862-874); one alpha
-     * batch with the hardcoded 10000 screen size forcing max lodFactor
-     * (cpp:878). QUIRK: unlike GetVolumetricBatches this does NOT stamp
-     * renderedLastFrame - reflection-only rendering does not keep texture
+    /** Carbon EveChildCloud2::GetBatches (cpp:854-884): quality gate, then ONLY
+     * the (REFLECTION, TRANSPARENT) type/reason pair produces anything
+     * (cpp:860) - every other combination is a silent no-op; HasValidTransform
+     * + unit-cube buffers + reflectionEffect gates (cpp:862-874); one alpha
+     * batch with the hardcoded 10000 screen size forcing max lodFactor
+     * (cpp:878). QUIRK: unlike GetVolumetricBatches this does NOT stamp
+     * renderedLastFrame - reflection-only rendering does not keep texture
      * animations alive. Returns whether a batch was committed (JS addition). */
     GetBatches(batches, batchType, _perObjectData, reason = Tr2RenderReason.TR2RENDERREASON_NORMAL) {
       if (this.currentQuality < this.minVisibleQuality) {
@@ -740,18 +767,18 @@ new class extends _identity {
       return batches?.Commit?.(batch) === true;
     }
 
-    /** Carbon EveChildCloud2::HasTransparentBatches (cpp:909-912):
-     * unconditionally true - the reflection gather always routes the cloud
+    /** Carbon EveChildCloud2::HasTransparentBatches (cpp:909-912):
+     * unconditionally true - the reflection gather always routes the cloud
      * through the transparent leg that feeds GetBatches' type/reason filter. */
     HasTransparentBatches() {
       return true;
     }
 
-    /** Carbon's two GetPerObjectData overloads (public, screenSize 1:
-     * cpp:919-927; private, caller screenSize: cpp:534-542): allocate from the
-     * accumulator and populate. The GPU-free record carries the live object
-     * reference plus the CPU-populated field block (cloudData); view-dependent
-     * members are refreshed by the engine calling PopulatePerObjectData again
+    /** Carbon's two GetPerObjectData overloads (public, screenSize 1:
+     * cpp:919-927; private, caller screenSize: cpp:534-542): allocate from the
+     * accumulator and populate. The GPU-free record carries the live object
+     * reference plus the CPU-populated field block (cloudData); view-dependent
+     * members are refreshed by the engine calling PopulatePerObjectData again
      * with its render context at realization (screenSize is stamped for that). */
     GetPerObjectData(accumulator = null, screenSize = 1) {
       const data = typeof accumulator?.Allocate === "function" ? accumulator.Allocate(Tr2PerObjectData) : new Tr2PerObjectData();
@@ -764,16 +791,16 @@ new class extends _identity {
       return data;
     }
 
-    /** Carbon EveChildCloud2::PopulatePerObjectData (cpp:544-619) against the
-     * PerObjectData block (EveChildCloud2.h:125-145). Compositions (Carbon
-     * row-vector -> gl-matrix operands swap):
-     *   - cpp:548/567 worldTransform * viewTransform (world first) ->
-     *     mat4.multiply(WV, view, world); the cpp:567 transpose is folded into
-     *     explicit element reads: viewDirection = TransformNormal((0,0,-1),
-     *     worldViewT) = (-WV[2], -WV[6], -WV[10]); depthSliceN =
-     *     -WV[14] - slice * WV[15].
-     * Single-matrix sites (NO swap): the cpp:546/547/551 HLSL packing
-     * transposes, cpp:550 TransformCoord with the inverted world, cpp:578
+    /** Carbon EveChildCloud2::PopulatePerObjectData (cpp:544-619) against the
+     * PerObjectData block (EveChildCloud2.h:125-145). Compositions (Carbon
+     * row-vector -> gl-matrix operands swap):
+     *   - cpp:548/567 worldTransform * viewTransform (world first) ->
+     *     mat4.multiply(WV, view, world); the cpp:567 transpose is folded into
+     *     explicit element reads: viewDirection = TransformNormal((0,0,-1),
+     *     worldViewT) = (-WV[2], -WV[6], -WV[10]); depthSliceN =
+     *     -WV[14] - slice * WV[15].
+     * Single-matrix sites (NO swap): the cpp:546/547/551 HLSL packing
+     * transposes, cpp:550 TransformCoord with the inverted world, cpp:578
      * Decompose (mat4.getScaling). */
     PopulatePerObjectData(data, screenSize = 1, renderContext = null) {
       const w = this.worldTransform;