@carbonenginejs/runtime-trinity 0.6.0 → 0.7.0

package/dist/eve/child/EveChildContainer.js

@@ -3,6 +3,7 @@ import { mat4 } from '@carbonenginejs/runtime-utils/mat4';
 import { quat } from '@carbonenginejs/runtime-utils/quat';
 import { sph3 } from '@carbonenginejs/runtime-utils/sph3';
 import { vec3 } from '@carbonenginejs/runtime-utils/vec3';
+import { getBoneList } from '../../trinityCore/Tr2GrannyAnimation.js';
 import { vec4 } from '@carbonenginejs/runtime-utils/vec4';
 import { io, type, carbon, impl, schema } from '@carbonenginejs/runtime-utils/schema';
 import { EveChildTransform as _EveChildTransform, applyTransformModifiers } from './EveChildTransform.js';
@@ -11,14 +12,20 @@ import { EveChildUpdateParams as _EveChildUpdateParams } from '../EveChildUpdate
 import { EveComponentType } from '../EveComponentTypes.js';
 import { Origin } from '../../generated/eve/child/enums.js';
 import { Tr2RenderReason, TR2SHADERMODEL } from '../../generated/trinityCore/enums.js';
-import { Tr2Lod } from '../EveLODHelper.js';
-import { Tr2PerObjectData } from '../../trinityCore/Tr2PerObjectData.js';
+import { Tr2Lod } from '@carbonenginejs/runtime-utils/const/trinity';
+import { createChildPerObjectRecords, inheritParentPerObjectData, stampChildTransforms } from '../perObjectData/childPerObjectRecords.js';
 
 let _initProto, _initClass, _init_displayFilter, _init_extra_displayFilter, _init_objects, _init_extra_objects, _init_transformModifiers, _init_extra_transformModifiers, _init_curveSets, _init_extra_curveSets, _init_worldTransform, _init_extra_worldTransform, _init_mute, _init_extra_mute, _init_display, _init_extra_display, _init_name, _init_extra_name, _init_translation, _init_extra_translation, _init_rotation, _init_extra_rotation, _init_scaling, _init_extra_scaling, _init_localTransform, _init_extra_localTransform, _init_staticTransform, _init_extra_staticTransform, _init_alwaysOn, _init_extra_alwaysOn, _init_updateOnDisplay, _init_extra_updateOnDisplay, _init_attachments, _init_extra_attachments, _init_observers, _init_extra_observers, _init_fxAttributes, _init_extra_fxAttributes, _init_lights, _init_extra_lights, _init_controllers, _init_extra_controllers, _init_inheritProperties, _init_extra_inheritProperties, _init_useSRT, _init_extra_useSRT, _init_useStaticRotation, _init_extra_useStaticRotation, _init_useStaticScale, _init_extra_useStaticScale, _init_animationOwner, _init_extra_animationOwner, _init_origin, _init_extra_origin, _init_isPlacementRoot, _init_extra_isPlacementRoot;
 
 // Module scratch (read-only zero vector; container recursion forbids mutable
 // module scratch here - see GetBoundingSphere).
 const ZERO_VEC3 = vec3.create();
+
+/**
+ * Space-object child that groups other children under one transform, owning
+ * their curve sets, controllers, observers, lights, attachments and transform
+ * modifiers, and gating them on a display-quality filter.
+ */
 let _EveChildContainer;
 new class extends _identity {
   static [class EveChildContainer extends _EveChildTransform {
@@ -29,7 +36,7 @@ new class extends _identity {
       } = _applyDecs2311(this, [type.define({
         className: "EveChildContainer",
         family: "eve/child"
-      })], [[[io, io.notify, io, io.persist, type, type.int32, void 0, schema.enum("DisplayQualityModifier")], 16, "displayFilter"], [[io, io.persist, void 0, type.list("IEveSpaceObjectChild")], 16, "objects"], [[io, io.persist, void 0, type.list("IEveChildTransformModifier")], 16, "transformModifiers"], [[io, io.persist, void 0, type.list("TriCurveSet")], 16, "curveSets"], [[io, io.read, type, type.mat4], 16, "worldTransform"], [[io, io.notify, io, io.readwrite, type, type.boolean], 16, "mute"], [[io, io.notify, io, io.persist, type, type.boolean], 16, "display"], [[io, io.persist, type, type.string], 16, "name"], [[io, io.persist, type, type.vec3], 16, "translation"], [[io, io.persist, type, type.quat], 16, "rotation"], [[io, io.persist, type, type.vec3], 16, "scaling"], [[io, io.persist, type, type.mat4], 16, "localTransform"], [[io, io.persist, type, type.boolean], 16, "staticTransform"], [[io, io.persist, type, type.boolean], 16, "alwaysOn"], [[io, io.persist, type, type.boolean], 16, "updateOnDisplay"], [[io, io.persist, void 0, type.list("IEveSpaceObjectAttachment")], 16, "attachments"], [[io, io.persist, void 0, type.list("TriObserverLocal")], 16, "observers"], [[io, io.persist, void 0, type.list("IEveFxAttribute")], 16, "fxAttributes"], [[io, io.persist, void 0, type.list("Tr2Light")], 16, "lights"], [[io, io.persist, void 0, type.list("ITr2Controller")], 16, "controllers"], [[io, io.persist, void 0, type.objectRef("EveChildInheritProperties")], 16, "inheritProperties"], [[io, io.persist, type, type.boolean], 16, "useSRT"], [[io, io.persist, type, type.boolean], 16, "useStaticRotation"], [[io, io.persist, type, type.boolean], 16, "useStaticScale"], [[io, io.persist, void 0, type.objectRef("ITr2GrannyAnimationOwner")], 16, "animationOwner"], [[io, io.persist, type, type.int32, void 0, schema.enum("Origin")], 16, "origin"], [[io, io.persist, type, type.boolean], 16, "isPlacementRoot"], [[carbon, carbon.method, impl, impl.adapted], 18, "Initialize"], [[carbon, carbon.method, impl, impl.adapted, void 0, impl.reason("Registry re-registration on display/displayFilter changes is engine-owned; the mute fan-out side effect is ported.")], 18, "OnModified"], [[carbon, carbon.method, impl, impl.implemented], 18, "Setup"], [[carbon, carbon.method, impl, impl.implemented], 18, "GetName"], [[carbon, carbon.method, impl, impl.implemented], 18, "SetName"], [[carbon, carbon.method, impl, impl.implemented], 18, "SetOrigin"], [[carbon, carbon.method, impl, impl.implemented], 18, "SetAlwaysOn"], [[carbon, carbon.method, impl, impl.implemented], 18, "IsAlwaysOn"], [[carbon, carbon.method, impl, impl.implemented], 18, "SetDisplayQualityModifier"], [[carbon, carbon.method, impl, impl.implemented], 18, "SetMute"], [[carbon, carbon.method, impl, impl.implemented], 18, "MuteChildren"], [[carbon, carbon.method, impl, impl.implemented], 18, "AddTransformModifier"], [[carbon, carbon.method, impl, impl.implemented], 18, "AddObserver"], [[carbon, carbon.method, impl, impl.adapted], 18, "AddController"], [[carbon, carbon.method, impl, impl.implemented], 18, "SetControllerVariable"], [[carbon, carbon.method, impl, impl.implemented], 18, "HandleControllerEvent"], [[carbon, carbon.method, impl, impl.implemented], 18, "StartControllers"], [[carbon, carbon.method, impl, impl.implemented], 18, "SetProceduralContainerVariable"], [[carbon, carbon.method, impl, impl.implemented], 18, "GetEffectChildByName"], [[carbon, carbon.method, impl, impl.adapted], 18, "AddToEffectChildrenList"], [[carbon, carbon.method, impl, impl.implemented], 18, "RemoveFromEffectChildrenList"], [[carbon, carbon.method, impl, impl.implemented], 18, "SetShaderOption"], [[carbon, carbon.method, impl, impl.implemented], 18, "SetAnimationOwner"], [[carbon, carbon.method, impl, impl.implemented], 18, "SetIsPlacementRoot"], [[carbon, carbon.method, impl, impl.implemented], 18, "AddAttachment"], [[carbon, carbon.method, impl, impl.implemented], 18, "ClearAttachments"], [[carbon, carbon.method, impl, impl.implemented], 18, "Empty"], [[carbon, carbon.method, impl, impl.implemented], 18, "UpdateSyncronous"], [[carbon, carbon.method, void 0, carbon.contextual(["camera"]), impl, impl.adapted, void 0, impl.reason("The GPU bone ring buffer, task-group dispatch, per-object VS/PS struct refresh, and the Granny bone-list override are engine/animation seams; the CPU update fan-out is ported.")], 18, "UpdateAsyncronous"], [[carbon, carbon.method, impl, impl.adapted, void 0, impl.reason("The animationOwner bone list for attachments awaits the animation seam (bones pass as null); the visibility fan-out is ported.")], 18, "UpdateVisibility"], [[carbon, carbon.method, impl, impl.implemented], 18, "GetRenderables"], [[carbon, carbon.method, impl, impl.implemented], 18, "GetBoundingSphere"], [[carbon, carbon.method, impl, impl.implemented], 18, "GetLocalToWorldTransform"], [[carbon, carbon.method, impl, impl.implemented], 18, "ChangeLOD"], [[carbon, carbon.method, impl, impl.implemented], 18, "GetLights"], [[carbon, carbon.method, impl, impl.implemented], 18, "GetBatches"], [[carbon, carbon.method, impl, impl.implemented], 18, "HasTransparentBatches"], [[carbon, carbon.method, impl, impl.implemented], 18, "GetSortValue"], [[carbon, carbon.method, impl, impl.adapted, void 0, impl.reason("Persistent VS/PS device buffers and the bone ring upload are engine-owned; the record carries the object reference the engine serializer consumes.")], 18, "GetPerObjectData"], [[carbon, carbon.method, impl, impl.implemented], 18, "HasRenderables"], [[carbon, carbon.method, impl, impl.adapted, void 0, impl.reason("Carbon reads the Tr2Renderer shader-model global; the browser runtime stamps EveChildContainer.shaderModel (default TR2SM_3_0_DEPTH, the DX11 depth path EVE ships).")], 18, "IsRendering"], [[carbon, carbon.method, impl, impl.implemented], 18, "IsUpdating"], [[carbon, carbon.method, impl, impl.implemented], 18, "RegisterComponents"], [[carbon, carbon.method, impl, impl.implemented], 18, "UnRegisterComponents"], [[carbon, carbon.method, impl, impl.implemented], 18, "PlayCurveSet"], [[carbon, carbon.method, impl, impl.implemented], 18, "StopCurveSet"], [[carbon, carbon.method, impl, impl.implemented], 18, "UpdateCurveSet"], [[carbon, carbon.method, impl, impl.implemented], 18, "PlayAllCurveSets"], [[carbon, carbon.method, impl, impl.implemented], 18, "StopAllCurveSets"], [[carbon, carbon.method, impl, impl.implemented], 18, "GetCurveSetDuration"], [[carbon, carbon.method, impl, impl.implemented], 18, "GetRangeDuration"], [[carbon, carbon.method, impl, impl.adapted, void 0, impl.reason("The bool + float& out-param pair collapses to value-or-null in JS.")], 18, "GetControllerValueByName"], [[carbon, carbon.method, impl, impl.implemented], 18, "GetWorldVelocity"], [[carbon, carbon.method, impl, impl.implemented], 18, "GetOwnerMaxSpeed"], [[carbon, carbon.method, impl, impl.implemented], 18, "SetInheritProperties"], [[carbon, carbon.method, impl, impl.implemented], 18, "FindSoundEmitter"]], 0, void 0, _EveChildTransform));
+      })], [[[io, io.notify, io, io.persist, type, type.int32, void 0, schema.enum("DisplayQualityModifier")], 16, "displayFilter"], [[io, io.persist, void 0, type.list("IEveSpaceObjectChild")], 16, "objects"], [[io, io.persist, void 0, type.list("IEveChildTransformModifier")], 16, "transformModifiers"], [[io, io.persist, void 0, type.list("TriCurveSet")], 16, "curveSets"], [[io, io.read, type, type.mat4], 16, "worldTransform"], [[io, io.notify, io, io.readwrite, type, type.boolean], 16, "mute"], [[io, io.notify, io, io.persist, type, type.boolean], 16, "display"], [[io, io.persist, type, type.string], 16, "name"], [[io, io.persist, type, type.vec3], 16, "translation"], [[io, io.persist, type, type.quat], 16, "rotation"], [[io, io.persist, type, type.vec3], 16, "scaling"], [[io, io.persist, type, type.mat4], 16, "localTransform"], [[io, io.persist, type, type.boolean], 16, "staticTransform"], [[io, io.persist, type, type.boolean], 16, "alwaysOn"], [[io, io.persist, type, type.boolean], 16, "updateOnDisplay"], [[io, io.persist, void 0, type.list("IEveSpaceObjectAttachment")], 16, "attachments"], [[io, io.persist, void 0, type.list("TriObserverLocal")], 16, "observers"], [[io, io.persist, void 0, type.list("IEveFxAttribute")], 16, "fxAttributes"], [[io, io.persist, void 0, type.list("Tr2Light")], 16, "lights"], [[io, io.persist, void 0, type.list("ITr2Controller")], 16, "controllers"], [[io, io.persist, void 0, type.objectRef("EveChildInheritProperties")], 16, "inheritProperties"], [[io, io.persist, type, type.boolean], 16, "useSRT"], [[io, io.persist, type, type.boolean], 16, "useStaticRotation"], [[io, io.persist, type, type.boolean], 16, "useStaticScale"], [[io, io.persist, void 0, type.objectRef("ITr2GrannyAnimationOwner")], 16, "animationOwner"], [[io, io.persist, type, type.int32, void 0, schema.enum("Origin")], 16, "origin"], [[io, io.persist, type, type.boolean], 16, "isPlacementRoot"], [[carbon, carbon.method, impl, impl.adapted], 18, "Initialize"], [[carbon, carbon.method, impl, impl.adapted, void 0, impl.reason("Registry re-registration on display/displayFilter changes is engine-owned; the mute fan-out side effect is ported.")], 18, "OnModified"], [[carbon, carbon.method, impl, impl.implemented], 18, "Setup"], [[carbon, carbon.method, impl, impl.implemented], 18, "GetName"], [[carbon, carbon.method, impl, impl.implemented], 18, "SetName"], [[carbon, carbon.method, impl, impl.implemented], 18, "SetOrigin"], [[carbon, carbon.method, impl, impl.implemented], 18, "SetAlwaysOn"], [[carbon, carbon.method, impl, impl.implemented], 18, "IsAlwaysOn"], [[carbon, carbon.method, impl, impl.implemented], 18, "SetDisplayQualityModifier"], [[carbon, carbon.method, impl, impl.implemented], 18, "SetMute"], [[carbon, carbon.method, impl, impl.implemented], 18, "MuteChildren"], [[carbon, carbon.method, impl, impl.implemented], 18, "AddTransformModifier"], [[carbon, carbon.method, impl, impl.implemented], 18, "AddObserver"], [[carbon, carbon.method, impl, impl.adapted], 18, "AddController"], [[carbon, carbon.method, impl, impl.implemented], 18, "SetControllerVariable"], [[carbon, carbon.method, impl, impl.implemented], 18, "HandleControllerEvent"], [[carbon, carbon.method, impl, impl.implemented], 18, "StartControllers"], [[carbon, carbon.method, impl, impl.implemented], 18, "SetProceduralContainerVariable"], [[carbon, carbon.method, impl, impl.implemented], 18, "GetEffectChildByName"], [[carbon, carbon.method, impl, impl.adapted], 18, "AddToEffectChildrenList"], [[carbon, carbon.method, impl, impl.implemented], 18, "RemoveFromEffectChildrenList"], [[carbon, carbon.method, impl, impl.implemented], 18, "SetShaderOption"], [[carbon, carbon.method, impl, impl.implemented], 18, "SetAnimationOwner"], [[carbon, carbon.method, impl, impl.implemented], 18, "SetIsPlacementRoot"], [[carbon, carbon.method, impl, impl.implemented], 18, "AddAttachment"], [[carbon, carbon.method, impl, impl.implemented], 18, "ClearAttachments"], [[carbon, carbon.method, impl, impl.implemented], 18, "Empty"], [[carbon, carbon.method, impl, impl.implemented], 18, "UpdateSyncronous"], [[carbon, carbon.method, void 0, carbon.contextual(["camera"]), impl, impl.adapted, void 0, impl.reason("The GPU bone ring buffer, task-group dispatch, per-object VS/PS struct refresh, and the Granny bone-list override are engine/animation seams; the CPU update fan-out is ported.")], 18, "UpdateAsyncronous"], [[carbon, carbon.method, impl, impl.implemented], 18, "UpdateVisibility"], [[carbon, carbon.method, impl, impl.implemented], 18, "GetRenderables"], [[carbon, carbon.method, impl, impl.implemented], 18, "GetBoundingSphere"], [[carbon, carbon.method, impl, impl.implemented], 18, "GetLocalToWorldTransform"], [[carbon, carbon.method, impl, impl.implemented], 18, "ChangeLOD"], [[carbon, carbon.method, impl, impl.implemented], 18, "GetLights"], [[carbon, carbon.method, impl, impl.implemented], 18, "GetBatches"], [[carbon, carbon.method, impl, impl.implemented], 18, "HasTransparentBatches"], [[carbon, carbon.method, impl, impl.implemented], 18, "GetSortValue"], [[carbon, carbon.method, impl, impl.adapted, void 0, impl.reason("GPU ring-buffer offsets have no CPU derivation and keep their defaults; every CPU-known field is filled.")], 18, "GetPerObjectData"], [[carbon, carbon.method, impl, impl.implemented], 18, "HasRenderables"], [[carbon, carbon.method, impl, impl.adapted, void 0, impl.reason("Carbon reads the Tr2Renderer shader-model global; the browser runtime stamps EveChildContainer.shaderModel (default TR2SM_3_0_DEPTH, the DX11 depth path EVE ships).")], 18, "IsRendering"], [[carbon, carbon.method, impl, impl.implemented], 18, "IsUpdating"], [[carbon, carbon.method, impl, impl.implemented], 18, "RegisterComponents"], [[carbon, carbon.method, impl, impl.implemented], 18, "UnRegisterComponents"], [[carbon, carbon.method, impl, impl.implemented], 18, "PlayCurveSet"], [[carbon, carbon.method, impl, impl.implemented], 18, "StopCurveSet"], [[carbon, carbon.method, impl, impl.implemented], 18, "UpdateCurveSet"], [[carbon, carbon.method, impl, impl.implemented], 18, "PlayAllCurveSets"], [[carbon, carbon.method, impl, impl.implemented], 18, "StopAllCurveSets"], [[carbon, carbon.method, impl, impl.implemented], 18, "GetCurveSetDuration"], [[carbon, carbon.method, impl, impl.implemented], 18, "GetRangeDuration"], [[carbon, carbon.method, impl, impl.adapted, void 0, impl.reason("The bool + float& out-param pair collapses to value-or-null in JS.")], 18, "GetControllerValueByName"], [[carbon, carbon.method, impl, impl.implemented], 18, "GetWorldVelocity"], [[carbon, carbon.method, impl, impl.implemented], 18, "GetOwnerMaxSpeed"], [[carbon, carbon.method, impl, impl.implemented], 18, "SetInheritProperties"], [[carbon, carbon.method, impl, impl.implemented], 18, "FindSoundEmitter"]], 0, void 0, _EveChildTransform));
     }
     displayFilter = (_initProto(this), _init_displayFilter(this, 5));
     objects = (_init_extra_displayFilter(this), _init_objects(this, []));
@@ -69,7 +76,18 @@ new class extends _identity {
     #worldVelocity = vec3.create();
     #ownerMaxSpeed = 0;
     #activationStrength = 1;
+
+    /** m_vsData / m_psData - this container's PERSISTENT per-object pair. */
+    #perObjectData = createChildPerObjectRecords();
+
+    /** Carbon's local `lastWorldTransform`, kept across frames here. */
+    #lastWorldTransform = mat4.create();
     #hasUpdated = false;
+
+    /**
+     * Links every authored controller that is not already linked to this
+     * container, so controller variables and events reach them.
+     */
     Initialize() {
       for (const controller of this.controllers) {
         if (!controller?.IsLinked?.()) {
@@ -89,27 +107,60 @@ new class extends _identity {
       }
       return true;
     }
+
+    /**
+     * Applies the authored scale/rotation/translation through the shared child
+     * transform setup and returns the rebuilt local transform; lowestLodVisible is
+     * accepted for signature parity only.
+     */
     Setup(scale = null, rotation = null, translation = null, lowestLodVisible = null) {
       return super.Setup(scale, rotation, translation, lowestLodVisible);
     }
+
+    /**
+     * Returns the authored container name, which GetEffectChildByName matches
+     * against on the parent side.
+     */
     GetName() {
       return this.name;
     }
+
+    /** Sets the authored container name, coercing nullish to the empty string. */
     SetName(name) {
       this.name = String(name ?? "");
     }
+
+    /**
+     * Records whether this container's placement was authored in space or by SOF
+     * (the Origin enum).
+     */
     SetOrigin(origin) {
       this.origin = Number(origin) | 0;
     }
+
+    /** Stores the always-on flag that IsAlwaysOn reports to the owner. */
     SetAlwaysOn(alwaysOn) {
       this.alwaysOn = !!alwaysOn;
     }
+
+    /** Reports the authored always-on flag. */
     IsAlwaysOn() {
       return this.alwaysOn;
     }
+
+    /**
+     * Sets the display-quality filter that IsRendering tests the current shader
+     * model against, which in turn gates every update and render path on this
+     * container.
+     */
     SetDisplayQualityModifier(filter) {
       this.displayFilter = Number(filter) | 0;
     }
+
+    /**
+     * Sets the mute flag and, only when it changes, pushes it down to the
+     * contained children and local observers.
+     */
     SetMute(mute) {
       const next = !!mute;
       if (next !== this.mute) {
@@ -117,6 +168,11 @@ new class extends _identity {
         this.MuteChildren();
       }
     }
+
+    /**
+     * Pushes this container's current mute flag onto every contained child and
+     * local observer - it mutates their state, not the container's.
+     */
     MuteChildren() {
       for (const child of this.objects) {
         child?.SetMute?.(this.mute);
@@ -125,12 +181,27 @@ new class extends _identity {
         observer?.SetMute?.(this.mute);
       }
     }
+
+    /**
+     * Appends a transform modifier; modifiers fold over the container's world
+     * transform in insertion order on each async update.
+     */
     AddTransformModifier(modifier) {
       this.transformModifiers.push(modifier);
     }
+
+    /**
+     * Appends a local audio observer, which is re-placed from the container's
+     * world transform on every sync update.
+     */
     AddObserver(observer) {
       this.observers.push(observer);
     }
+
+    /**
+     * Appends a controller, links it to this container, and replays every
+     * controller variable set so far onto it so it starts in sync.
+     */
     AddController(controller) {
       this.controllers.push(controller);
       controller?.Link?.(this);
@@ -138,6 +209,12 @@ new class extends _identity {
         controller?.SetVariable?.(name, value);
       }
     }
+
+    /**
+     * Records a named float variable, pushes it to every controller on this
+     * container, and recurses into the contained children; the recorded value is
+     * also replayed onto controllers and children added later.
+     */
     SetControllerVariable(name, value) {
       const key = String(name ?? "");
       const next = Number(value);
@@ -149,6 +226,11 @@ new class extends _identity {
         child?.SetControllerVariable?.(key, next);
       }
     }
+
+    /**
+     * Fires a named controller event on every controller here and recurses into
+     * the contained children.
+     */
     HandleControllerEvent(name) {
       const eventName = String(name ?? "");
       for (const controller of this.controllers) {
@@ -158,6 +240,8 @@ new class extends _identity {
         child?.HandleControllerEvent?.(eventName);
       }
     }
+
+    /** Starts every controller here and recurses into the contained children. */
     StartControllers() {
       for (const controller of this.controllers) {
         controller?.Start?.();
@@ -166,11 +250,21 @@ new class extends _identity {
         child?.StartControllers?.();
       }
     }
+
+    /**
+     * Forwards a procedural container variable to the contained children; a plain
+     * container holds none of its own.
+     */
     SetProceduralContainerVariable(name, value) {
       for (const child of this.objects) {
         child?.SetProceduralContainerVariable?.(name, value);
       }
     }
+
+    /**
+     * Returns the first direct child whose GetName()/name matches, or null; the
+     * search does not recurse into nested containers.
+     */
     GetEffectChildByName(name) {
       const target = String(name ?? "");
       for (const child of this.objects) {
@@ -180,6 +274,11 @@ new class extends _identity {
       }
       return null;
     }
+
+    /**
+     * Appends a child and replays every controller variable set so far onto it,
+     * then returns that same child.
+     */
     AddToEffectChildrenList(child) {
       this.objects.push(child);
       for (const [name, value] of this.#controllerVariables) {
@@ -187,6 +286,8 @@ new class extends _identity {
       }
       return child;
     }
+
+    /** Removes a child by identity and reports whether it was present. */
     RemoveFromEffectChildrenList(child) {
       const index = this.objects.indexOf(child);
       if (index !== -1) {
@@ -195,6 +296,11 @@ new class extends _identity {
       }
       return false;
     }
+
+    /**
+     * Forwards a shader option to every contained child and attachment; the
+     * container compiles nothing itself.
+     */
     SetShaderOption(name, value) {
       for (const child of this.objects) {
         child?.SetShaderOption?.(name, value);
@@ -203,18 +309,44 @@ new class extends _identity {
         attachment?.SetShaderOption?.(name, value);
       }
     }
+
+    /**
+     * Stores the Granny animation owner supplied by SOF placement; the bone-list
+     * override that would consume it awaits the JS animation seam.
+     */
     SetAnimationOwner(animationOwner) {
       this.animationOwner = animationOwner ?? null;
     }
+
+    /**
+     * Flags this container as a SOF placement root - authored placement state,
+     * persisted for interchange parity, with no consumer inside the container
+     * itself.
+     */
     SetIsPlacementRoot(isPlacementRoot) {
       this.isPlacementRoot = !!isPlacementRoot;
     }
+
+    /**
+     * Appends an attachment; attachments are the only thing a container renders
+     * itself (HasRenderables) and the only thing GetBatches submits.
+     */
     AddAttachment(attachment) {
       this.attachments.push(attachment);
     }
+
+    /**
+     * Drops every attachment, which also stops the container from contributing any
+     * renderable of its own.
+     */
     ClearAttachments() {
       this.attachments.length = 0;
     }
+
+    /**
+     * Reports whether the container owns nothing at all - no children, lights,
+     * attachments, controllers, curve sets, transform modifiers or observers.
+     */
     Empty() {
       return this.objects.length === 0 && this.lights.length === 0 && this.attachments.length === 0 && this.controllers.length === 0 && this.curveSets.length === 0 && this.transformModifiers.length === 0 && this.observers.length === 0;
     }
@@ -262,9 +394,17 @@ new class extends _identity {
         return this.worldTransform;
       }
       const parentTransform = params?.localToWorldTransform;
+
+      // Carbon captures the OUTGOING transform before rebuilding.
+      mat4.copy(this.#lastWorldTransform, this.worldTransform);
       if (parentTransform && parentTransform.length === 16) {
         this.UpdateTransform(parentTransform);
       }
+
+      // Carbon cpp:576-589: inherit the hull's per-object values, rebase the clip
+      // data by this child's translation, then stamp our own transforms.
+      inheritParentPerObjectData(this.#perObjectData, params?.spaceObjectParent, this.translation);
+      stampChildTransforms(this.#perObjectData, this.worldTransform, this.#lastWorldTransform);
       const frequency = params?.controllerUpdateFrequency ?? 0.5;
       for (const controller of this.controllers) {
         controller?.Update?.(frequency);
@@ -272,9 +412,10 @@ new class extends _identity {
 
       // Carbon's DoUpdateAsyncronous overrides boneCount/bones from this
       // container's own animation controller here (Tr2GrannyAnimationUtils::
-      // GetBoneList, cpp:556-559) before folding modifiers. Deferred until the
-      // Granny bone-list API and the bone-consuming EveChildModifierAttachToBone
-      // are ported; no currently-ported modifier reads bones.
+      // GetBoneList, cpp:556-559) before folding modifiers. AttachToBone already
+      // consumes an explicitly threaded params palette; overriding that palette
+      // from the animation controller remains deferred until the Granny
+      // bone-list API is ported.
       const boneCount = params?.boneCount ?? 0;
       const bones = params?.bones ?? null;
       applyTransformModifiers(this, updateContext, boneCount, bones);
@@ -351,8 +492,14 @@ new class extends _identity {
         child?.UpdateVisibility?.(updateContext, parentTransform, parentLod);
       }
       if (this.HasRenderables()) {
+        // cpp:398-409 - the container has no updater of its own; the palette
+        // comes from whichever object owns the animation.
+        const {
+          bones,
+          boneCount
+        } = getBoneList(this.animationOwner?.GetAnimationController?.());
         for (const attachment of this.attachments) {
-          attachment?.UpdateVisibility?.(updateContext, this.worldTransform, null, 0);
+          attachment?.UpdateVisibility?.(updateContext, this.worldTransform, bones, boneCount);
         }
       }
       return true;
@@ -459,15 +606,21 @@ new class extends _identity {
       return 0;
     }
 
-    /** Carbon EveChildContainer::GetPerObjectData (cpp:1180-1203) uploads the
-     * animationOwner bone palette into the GPU ring buffer and allocates
-     * Tr2PerObjectDataWithPersistentBuffers; both are GPU seams, so the GPU-free
-     * record carries the live object reference for the engine serializer
-     * (mirrors EveSpaceObject2.GetPerObjectData). */
-    GetPerObjectData(accumulator = null) {
-      const data = typeof accumulator?.Allocate === "function" ? accumulator.Allocate(Tr2PerObjectData) : new Tr2PerObjectData();
-      data.object = this;
-      return data;
+    /**
+     * Carbon EveChildContainer::GetPerObjectData (cpp:1180-1203): uploads the
+     * animation owner's bone palette, then hands back a handle over this
+     * container's two PERSISTENT buffers. The ring offsets are GPU addresses with
+     * no CPU derivation and keep their defaults; the bone COUNT is CPU-known.
+     */
+    GetPerObjectData(_accumulator = null) {
+      const updater = this.animationOwner?.animationUpdater ?? this.animationUpdater;
+      if (updater?.IsInitialized?.()) {
+        this.#perObjectData.vs.SetIndex("boneOffsets", 2, [updater.GetMeshBoneCount?.() ?? 0]);
+      }
+      return {
+        vs: this.#perObjectData.vs,
+        ps: this.#perObjectData.ps
+      };
     }
 
     /** Carbon EveChildContainer::HasRenderables (cpp:1129-1132): the container
@@ -717,6 +870,12 @@ new class extends _identity {
     // EveSpaceObject2's child fan-out - container recursion makes a module
     // scratch record unsafe.
 
+    /**
+     * Copies the caller's update params into a fresh child-facing record (Carbon
+     * passes EveChildUpdateParams by value, cpp:505/592); allocated per call
+     * because container recursion makes a shared module scratch record unsafe.
+     */
+
     // Carbon reads Tr2Renderer::GetShaderModel() (a renderer global); the
     // browser runtime stamps it here. TR2SM_3_0_DEPTH is the DX11 depth path
     // EVE ships, so every quality-gated container renders by default.