@carbonenginejs/runtime 0.1.0-alpha.4 → 0.1.0-alpha.5

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

@@ -7,7 +7,9 @@ import { ShouldReflect, EveComponentType } from '../../EveComponentTypes.js';
 import { EveSpaceObjectChild as _EveSpaceObjectChild } from '../EveSpaceObjectChild.js';
 import { RawData } from '../../../core/rawData/RawData.js';
 import { Tr2RenderReason } from '../../../generated/trinityCore/enums.js';
-import { CollectInstancedOverlayAreaBlocks, EmitOverlayBatches } from '../../overlays/overlayBatches.js';
+import { CollectInstancedOverlayAreaBlocks, EmitDamageOverlayBatches, EmitOverlayBatches } from '../../overlays/overlayBatches.js';
+import { EveDamageOverlay as _EveDamageOverlay } from '../../overlays/EveDamageOverlay.js';
+import { EveGetLocatorPose } from '../../locator/EveLocatorSets.js';
 import { ITr2Renderable } from '../../../core/ITr2Renderable.js';
 import { EveChildInstancedMeshArea as _EveChildInstancedMes$3 } from './EveChildInstancedMeshArea.js';
 import { EveChildInstancedMeshInstance as _EveChildInstancedMes$1 } from './EveChildInstancedMeshInstance.js';
@@ -15,8 +17,8 @@ import { EveChildInstancedMesh as _EveChildInstancedMes$2 } from './EveChildInst
 
 let _initProto, _initClass, _init_name, _init_extra_name, _init_worldTransform, _init_extra_worldTransform, _init_hasUpdated, _init_extra_hasUpdated, _init_meshes, _init_extra_meshes;
 
-/** Carbon EveInstancedMeshManager::InstanceFlags (EveInstancedMeshManager.h:
- * 13-26, cpp:998-1048): a uint32 bitfield - bit (1 << batchType) per present
+/** Carbon EveInstancedMeshManager::InstanceFlags (EveInstancedMeshManager.h:
+ * 13-26, cpp:998-1048): a uint32 bitfield - bit (1 << batchType) per present
  * batch type, CASTS_SHADOW = 1 << 30, RENDER_IN_REFLECTION = 1 << 31. */
 const INSTANCE_FLAG_CASTS_SHADOW = 0x40000000;
 const INSTANCE_FLAG_RENDER_IN_REFLECTION = 0x80000000;
@@ -28,10 +30,28 @@ const OVERLAY_INV_WORLD_SCRATCH = mat4.create();
 const OVERLAY_INV_LOCAL_SCRATCH = mat4.create();
 const OVERLAY_CLIP_SCRATCH = vec3.create();
 
-/**
- * Space-object child that hands batches of instanced meshes to the engine's
- * instanced mesh manager, owning their registration handles, instance flags and
- * world cull bounds.
+/** Stand-in for an instance sphere the async pass has not built yet: Carbon
+ * sizes instanceSpheres at AddMesh (cpp:559), JS fills it lazily. */
+const EMPTY_SPHERE = {
+  center: vec3.create(),
+  radius: 0
+};
+
+/**
+ * Returns the locator list of a part's own "damage" set, or null (Carbon
+ * EveChildInstancedMeshes.cpp:12-22, file-local).
+ */
+function FindDamageLocators(sets) {
+  for (const entry of sets) {
+    if (entry.HasName("damage")) return entry.GetLocators();
+  }
+  return null;
+}
+
+/**
+ * Space-object child that hands batches of instanced meshes to the engine's
+ * instanced mesh manager, owning their registration handles, instance flags and
+ * world cull bounds.
  */
 let _EveChildInstancedMes;
 new class extends _identity {
@@ -43,7 +63,7 @@ new class extends _identity {
       } = _applyDecs2311(this, [type.define({
         className: "EveChildInstancedMeshes",
         family: "eve/child"
-      }), carbon.inherit(ITr2Renderable)], [[[edit, edit.persist, type, type.string], 16, "name"], [[edit, edit.read, type, type.mat4], 16, "worldTransform"], [[edit, edit.read, type, type.boolean], 16, "hasUpdated"], [[edit, edit.persist, void 0, type.list("EveChildInstancedMesh")], 16, "meshes"], [[carbon, carbon.method, impl, impl.implemented], 18, "GetName"], [[carbon, carbon.method, impl, impl.implemented], 18, "SetName"], [[carbon, carbon.method, impl, impl.adapted], 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, "UpdateSyncronous"], [[carbon, carbon.method, impl, impl.adapted, void 0, impl.reason("Trinity owns the CPU per-object field copy; the raytracing mesh build (cpp:283-327) is not ported yet. Mesh bounds come from a GetMeshData duck ({minBounds, maxBounds}) and meshes without one are skipped fail-closed.")], 18, "UpdateAsyncronous"], [[carbon, carbon.method, impl, impl.implemented], 18, "GetLocalToWorldTransform"], [[carbon, carbon.method, impl, impl.implemented], 18, "Setup"], [[carbon, carbon.method, impl, impl.implemented], 18, "ChangeLOD"], [[carbon, carbon.method, impl, impl.adapted], 18, "SetOrigin"], [[carbon, carbon.method, impl, impl.implemented], 18, "IsAlwaysOn"], [[carbon, carbon.method, impl, impl.adapted, void 0, impl.reason("Handle invalidation after manager removal is explicit in JavaScript; the option write, hash refresh and registration lifecycle otherwise follow Carbon.")], 18, "SetShaderOption"], [[carbon, carbon.method, impl, impl.adapted], 18, "AddMesh"], [[carbon, carbon.method, impl, impl.adapted, void 0, impl.reason("JavaScript explicitly nulls manager handles after removal; Carbon invalidates them by reference.")], 18, "RemoveInstancesByPartTag"], [[carbon, carbon.method, impl, impl.implemented], 18, "CollectOwnedGeometry"], [[carbon, carbon.method, impl, impl.implemented], 18, "SetInstanceTransformByPartTag"], [[carbon, carbon.method, impl, impl.adapted], 18, "GetInstancesTransforms"], [[carbon, carbon.method, impl, impl.adapted], 18, "Clear"], [[carbon, carbon.method, impl, impl.implemented], 18, "GetSofSourceLocator"], [[carbon, carbon.method, impl, impl.implemented], 18, "GetMeshCount"], [[carbon, carbon.method, impl, impl.adapted], 18, "GetMeshInfo"], [[carbon, carbon.method, impl, impl.adapted], 18, "GetAreaInfo"], [[carbon, carbon.method, impl, impl.adapted], 18, "GetMeshDisplay"], [[carbon, carbon.method, impl, impl.adapted, void 0, impl.reason("Handle invalidation after removal is explicit (Carbon's DataHandle is invalidated by the manager by reference).")], 18, "SetMeshDisplay"], [[carbon, carbon.method, impl, impl.implemented], 18, "GetMeshInheritOverlayEffects"], [[carbon, carbon.method, impl, impl.implemented], 18, "SetMeshInheritOverlayEffects"], [[carbon, carbon.method, impl, impl.implemented], 18, "AddMeshOverlayEffect"], [[carbon, carbon.method, impl, impl.implemented], 18, "RemoveMeshOverlayEffect"], [[carbon, carbon.method, impl, impl.implemented], 18, "ClearMeshOverlayEffects"], [[carbon, carbon.method, impl, impl.implemented], 18, "GetMeshOverlayEffectCount"], [[carbon, carbon.method, impl, impl.adapted], 18, "SetGeometryResource"], [[carbon, carbon.method, impl, impl.adapted], 18, "GetMeshData"], [[carbon, carbon.method, impl, impl.implemented], 18, "GetRevision"], [[carbon, carbon.method, impl, impl.implemented], 18, "HasTransparentBatches"], [[carbon, carbon.method, impl, impl.adapted], 18, "GetSortValue"], [[carbon, carbon.method, impl, impl.adapted], 18, "GetPerObjectData"], [[carbon, carbon.method, impl, impl.adapted], 18, "GetBatches"], [[carbon, carbon.method, impl, impl.implemented], 18, "RegisterComponents"], [[carbon, carbon.method, impl, impl.implemented], 18, "UnRegisterComponents"], [[carbon, carbon.method, impl, impl.adapted, void 0, impl.reason("Handle invalidation after removal is explicit (Carbon's DataHandle is invalidated by the manager by reference).")], 18, "UnregisterFromMeshManager"], [[carbon, carbon.method, impl, impl.adapted, void 0, impl.reason("The manager is duck-typed and returns opaque handles (out-params become returns) - Carbon EveInstancedMeshManager is not ported (quarantined in src/trinity/dropped); Carbon's combinedVertexDeclaration gate (cpp:499, a D3D declaration handle rebuilt in RebuildCachedData cpp:435-457) reduces to geometry presence + IsGood, and the declaration argument is passed as 0 for the engine to rebuild; GetRawRoot() becomes the object itself as picking owner.")], 18, "AddMeshesToManager"], [[carbon, carbon.method, impl, impl.implemented], 18, "IsCastingShadow"], [[carbon, carbon.method, impl, impl.noop], 18, "GetShadowBatches"], [[carbon, carbon.method, impl, impl.implemented], 18, "GetShadowPerObjectData"]], 0, void 0, _EveSpaceObjectChild));
+      }), carbon.inherit(ITr2Renderable)], [[[edit, edit.persist, type, type.string], 16, "name"], [[edit, edit.read, type, type.mat4], 16, "worldTransform"], [[edit, edit.read, type, type.boolean], 16, "hasUpdated"], [[edit, edit.persist, void 0, type.list("EveChildInstancedMesh")], 16, "meshes"], [[carbon, carbon.method, impl, impl.implemented], 18, "GetName"], [[carbon, carbon.method, impl, impl.implemented], 18, "SetName"], [[carbon, carbon.method, impl, impl.adapted], 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, "UpdateSyncronous"], [[carbon, carbon.method, impl, impl.adapted, void 0, impl.reason("Trinity owns the CPU per-object field copy; the raytracing mesh build (cpp:283-327) is not ported yet. Mesh bounds come from a GetMeshData duck ({minBounds, maxBounds}) and meshes without one are skipped fail-closed.")], 18, "UpdateAsyncronous"], [[carbon, carbon.method, impl, impl.implemented], 18, "GetLocalToWorldTransform"], [[carbon, carbon.method, impl, impl.implemented], 18, "Setup"], [[carbon, carbon.method, impl, impl.implemented], 18, "ChangeLOD"], [[carbon, carbon.method, impl, impl.adapted], 18, "SetOrigin"], [[carbon, carbon.method, impl, impl.implemented], 18, "IsAlwaysOn"], [[carbon, carbon.method, impl, impl.adapted, void 0, impl.reason("Handle invalidation after manager removal is explicit in JavaScript; the option write, hash refresh and registration lifecycle otherwise follow Carbon.")], 18, "SetShaderOption"], [[carbon, carbon.method, impl, impl.adapted], 18, "AddMesh"], [[carbon, carbon.method, impl, impl.adapted, void 0, impl.reason("JavaScript explicitly nulls manager handles after removal; Carbon invalidates them by reference.")], 18, "RemoveInstancesByPartTag"], [[carbon, carbon.method, impl, impl.implemented], 18, "CollectOwnedGeometry"], [[carbon, carbon.method, impl, impl.implemented], 18, "CollectOwnedLocatorSets"], [[carbon, carbon.method, impl, impl.implemented], 18, "GetPartDamageOverlay"], [[carbon, carbon.method, impl, impl.implemented], 18, "CreatePartDamageOverlay"], [[carbon, carbon.method, impl, impl.implemented], 18, "GetPartArmorDamageShaderEffect"], [[carbon, carbon.method, impl, impl.implemented], 18, "GetPartDamageLocatorAnimatedLocal"], [[carbon, carbon.method, impl, impl.implemented], 18, "SetInstanceTransformByPartTag"], [[carbon, carbon.method, impl, impl.adapted], 18, "GetInstancesTransforms"], [[carbon, carbon.method, impl, impl.adapted], 18, "Clear"], [[carbon, carbon.method, impl, impl.implemented], 18, "GetSofSourceLocator"], [[carbon, carbon.method, impl, impl.implemented], 18, "GetMeshCount"], [[carbon, carbon.method, impl, impl.adapted], 18, "GetMeshInfo"], [[carbon, carbon.method, impl, impl.adapted], 18, "GetAreaInfo"], [[carbon, carbon.method, impl, impl.adapted], 18, "GetMeshDisplay"], [[carbon, carbon.method, impl, impl.adapted, void 0, impl.reason("Handle invalidation after removal is explicit (Carbon's DataHandle is invalidated by the manager by reference).")], 18, "SetMeshDisplay"], [[carbon, carbon.method, impl, impl.implemented], 18, "GetMeshInheritOverlayEffects"], [[carbon, carbon.method, impl, impl.implemented], 18, "SetMeshInheritOverlayEffects"], [[carbon, carbon.method, impl, impl.implemented], 18, "AddMeshOverlayEffect"], [[carbon, carbon.method, impl, impl.implemented], 18, "RemoveMeshOverlayEffect"], [[carbon, carbon.method, impl, impl.implemented], 18, "ClearMeshOverlayEffects"], [[carbon, carbon.method, impl, impl.implemented], 18, "GetMeshOverlayEffectCount"], [[carbon, carbon.method, impl, impl.adapted], 18, "SetGeometryResource"], [[carbon, carbon.method, impl, impl.adapted], 18, "GetMeshData"], [[carbon, carbon.method, impl, impl.implemented], 18, "GetRevision"], [[carbon, carbon.method, impl, impl.implemented], 18, "HasTransparentBatches"], [[carbon, carbon.method, impl, impl.adapted], 18, "GetSortValue"], [[carbon, carbon.method, impl, impl.adapted], 18, "GetPerObjectData"], [[carbon, carbon.method, impl, impl.adapted], 18, "GetBatches"], [[carbon, carbon.method, impl, impl.implemented], 18, "RegisterComponents"], [[carbon, carbon.method, impl, impl.implemented], 18, "UnRegisterComponents"], [[carbon, carbon.method, impl, impl.adapted, void 0, impl.reason("Handle invalidation after removal is explicit (Carbon's DataHandle is invalidated by the manager by reference).")], 18, "UnregisterFromMeshManager"], [[carbon, carbon.method, impl, impl.adapted, void 0, impl.reason("The manager is duck-typed and returns opaque handles (out-params become returns) - Carbon EveInstancedMeshManager is not ported (quarantined in src/trinity/dropped); Carbon's combinedVertexDeclaration gate (cpp:499, a D3D declaration handle rebuilt in RebuildCachedData cpp:435-457) reduces to geometry presence + IsGood, and the declaration argument is passed as 0 for the engine to rebuild; GetRawRoot() becomes the object itself as picking owner.")], 18, "AddMeshesToManager"], [[carbon, carbon.method, impl, impl.implemented], 18, "IsCastingShadow"], [[carbon, carbon.method, impl, impl.noop], 18, "GetShadowBatches"], [[carbon, carbon.method, impl, impl.implemented], 18, "GetShadowPerObjectData"]], 0, void 0, _EveSpaceObjectChild));
     }
     name = (_initProto(this), _init_name(this, ""));
     worldTransform = (_init_extra_name(this), _init_worldTransform(this, mat4.create()));
@@ -54,9 +74,9 @@ new class extends _identity {
     /** Carbon m_perObjectDataHandle (h:143) - manager registration handle. */
     #perObjectDataHandle = null;
 
-    /**
-     * Carbon m_perObjectData (EveSpacePerObjectData): the PERSISTENT per-instance
-     * record the mesh manager uploads into its structured buffer.
+    /**
+     * Carbon m_perObjectData (EveSpacePerObjectData): the PERSISTENT per-instance
+     * record the mesh manager uploads into its structured buffer.
      */
     #perObjectData = RawData.create("EveSpacePerObjectData");
 
@@ -70,16 +90,20 @@ new class extends _identity {
     #lastCameraFrustum = null;
     #lastInvLodFactor = 1;
 
+    /** Carbon m_partDamageOverlays (h:215): one damage overlay per part tag,
+     * created on first damage through CreatePartDamageOverlay. */
+    _partDamageOverlays = new Map();
+
     /** EVE_SPACEOBJECT_CUSTOWMASK_MAX (EveSpaceObject2.h:49). */
 
-    /** Carbon m_allRegistered (h:147) - the AddMeshesToManager retry latch:
-     * set optimistically each pass, cleared by ANY not-ready mesh/area so the
+    /** Carbon m_allRegistered (h:147) - the AddMeshesToManager retry latch:
+     * set optimistically each pass, cleared by ANY not-ready mesh/area so the
      * per-frame CollectMeshes retries until geometry streams in. */
     #allRegistered = false;
 
-    /**
-     * The authored name, persisted with the child and used to identify it in the
-     * parent graph.
+    /**
+     * The authored name, persisted with the child and used to identify it in the
+     * parent graph.
      */
     GetName() {
       return this.name;
@@ -90,43 +114,43 @@ new class extends _identity {
       this.name = String(name ?? "");
     }
 
-    /**
-     * Carbon EveChildInstancedMeshes::UpdateVisibility (cpp:183-186) only caches
-     * the frame's camera frustum for later use; the JS port has no consumer for
-     * that cache, so the frame hook does nothing.
+    /**
+     * Carbon EveChildInstancedMeshes::UpdateVisibility (cpp:183-186) only caches
+     * the frame's camera frustum for later use; the JS port has no consumer for
+     * that cache, so the frame hook does nothing.
      */
     UpdateVisibility(updateContext) {
       this.#lastCameraFrustum = updateContext.GetFrustum();
       this.#lastInvLodFactor = updateContext.GetInvLodFactor();
     }
 
-    /**
-     * Carbon EveChildInstancedMeshes::GetRenderables (cpp:188-190) collects
-     * nothing: the instanced mesh manager emits the draws, so the accumulator
-     * comes back unchanged.
+    /**
+     * Carbon EveChildInstancedMeshes::GetRenderables (cpp:200-207): the base
+     * hull draws through the instanced mesh manager, so this child is a
+     * renderable only for overlay draws - inherited, own, or part damage.
      */
     GetRenderables(renderables = []) {
-      if (this.hasUpdated && (this.#parentOverlayEffects?.length && this.#AnyMeshInheritsOverlayEffects() || this.#HasAnyOwnOverlayEffects())) {
+      if (this.hasUpdated && (this.#parentOverlayEffects?.length && this.#AnyMeshInheritsOverlayEffects() || this.#HasAnyOwnOverlayEffects() || this._partDamageOverlays.size !== 0)) {
         renderables.push(this);
       }
       return renderables;
     }
 
-    /**
-     * Carbon EveChildInstancedMeshes::GetBoundingSphere (cpp:192-195) always
-     * returns false - the child publishes no bounds of its own, because each mesh
-     * registers its own sphere group with the manager.
+    /**
+     * Carbon EveChildInstancedMeshes::GetBoundingSphere (cpp:192-195) always
+     * returns false - the child publishes no bounds of its own, because each mesh
+     * registers its own sphere group with the manager.
      */
     GetBoundingSphere() {
       return false;
     }
 
-    /**
-     * Carbon EveChildInstancedMeshes::UpdateAsyncronous (cpp:204-238): the
-     * per-instance record is this child's own transforms plus the hull values it
-     * inherits, flattened into ONE struct - EveSpacePerObjectData carries both
-     * the VS and PS halves because the manager uploads it as a single instance.
-     * @param {Object} parent - the space-object parent, when there is one
+    /**
+     * Carbon EveChildInstancedMeshes::UpdateAsyncronous (cpp:204-238): the
+     * per-instance record is this child's own transforms plus the hull values it
+     * inherits, flattened into ONE struct - EveSpacePerObjectData carries both
+     * the VS and PS halves because the manager uploads it as a single instance.
+     * @param {Object} parent - the space-object parent, when there is one
      */
     #UpdatePerObjectData(parent) {
       const record = this.#perObjectData;
@@ -184,10 +208,10 @@ new class extends _identity {
       };
     }
 
-    /**
-     * Stamps the child's world transform from the parent's localToWorldTransform
-     * (Carbon cpp:197-200); every per-instance cull sphere the async pass builds
-     * is derived from it.
+    /**
+     * Stamps the child's world transform from the parent's localToWorldTransform
+     * (Carbon cpp:197-200); every per-instance cull sphere the async pass builds
+     * is derived from it.
      */
     UpdateSyncronous(updateContext, params) {
       if (params?.localToWorldTransform?.length === 16) {
@@ -197,22 +221,25 @@ new class extends _identity {
       for (const mesh of this.meshes) {
         for (const overlay of mesh.ownOverlayEffects) overlay.Update(time, time);
       }
+
+      // Carbon cpp:228-231: every part's damage overlay publishes its block.
+      for (const overlay of this._partDamageOverlays.values()) overlay.UpdateSyncronous(updateContext);
     }
 
-    /** Carbon EveChildInstancedMeshes::UpdateAsyncronous (cpp:202-328), the CPU
-     * half: per-mesh RENDER_IN_REFLECTION refresh (cpp:251), the mesh-local
-     * bounds sphere radius = |center| + radius (cpp:254-255), per-instance
-     * world cull spheres - position from the instance translation (Carbon reads
-     * the packed rows' w = _41.._43, i.e. the transform translation) moved
-     * through the child world transform, radius scaled by the instance's max
-     * basis length times the child worldScale (cpp:259-269; NOTE Carbon's two
-     * scale extractions deliberately differ - worldScale uses the world
-     * transform's basis ROWS while the instance scale uses the packed rows'
-     * xyz = the transpose's rows; equal under rotation + uniform scale,
-     * ported exactly) - the world bounding sphere over all instance spheres
-     * (cpp:257-270), a live SetSphereGroupBounds refresh on registered handles
+    /** Carbon EveChildInstancedMeshes::UpdateAsyncronous (cpp:234-413), the CPU
+     * half: per-mesh RENDER_IN_REFLECTION refresh (cpp:251), the mesh-local
+     * bounds sphere radius = |center| + radius (cpp:254-255), per-instance
+     * world cull spheres - position from the instance translation (Carbon reads
+     * the packed rows' w = _41.._43, i.e. the transform translation) moved
+     * through the child world transform, radius scaled by the instance's max
+     * basis length times the child worldScale (cpp:259-269; NOTE Carbon's two
+     * scale extractions deliberately differ - worldScale uses the world
+     * transform's basis ROWS while the instance scale uses the packed rows'
+     * xyz = the transpose's rows; equal under rotation + uniform scale,
+     * ported exactly) - the world bounding sphere over all instance spheres
+     * (cpp:257-270), a live SetSphereGroupBounds refresh on registered handles
      * (cpp:272-278), and the hasUpdated stamp (cpp:281). */
-    UpdateAsyncronous(_updateContext, params) {
+    UpdateAsyncronous(updateContext, params) {
       const previousWorldTransform = mat4.create();
       mat4.transpose(previousWorldTransform, this.#perObjectData.GetTransposed("worldTransform"));
       const parentRecords = this.#UpdatePerObjectData(params?.spaceObjectParent ?? null);
@@ -288,16 +315,49 @@ new class extends _identity {
       }
       const parent = params?.spaceObjectParent ?? null;
       this.#parentOverlayEffects = Array.isArray(parent?.overlayEffects) && parent.overlayEffects.length ? parent.overlayEffects : null;
-      if (this.#parentOverlayEffects && this.#AnyMeshInheritsOverlayEffects() || this.#HasAnyOwnOverlayEffects()) {
-        this.#UpdateOverlayInstanceData(parentRecords.vs, parentRecords.ps, previousWorldTransform);
+
+      // Carbon cpp:333-359: each part's overlay is aged against its own
+      // instance - local mesh sphere, world instance sphere, and the part's own
+      // bind-pose damage locators. A part whose mesh is not loaded gets Carbon's
+      // default owner info, which resolves no locators.
+      for (const [partTag, overlay] of this._partDamageOverlays) {
+        const info = {
+          boundingSphere: [0, 0, 0, -1],
+          estimatedPixelDiameter: 0,
+          isInFrustum: false
+        };
+        const found = this._FindMeshByPartTag(partTag);
+        const geometry = found?.mesh.GetGeometryResource();
+        if (found && geometry && geometry.IsGood() !== false) {
+          const meshData = geometry.GetMeshData(found.mesh.meshIndex);
+          if (meshData?.minBounds && meshData?.maxBounds) {
+            const minBounds = meshData.minBounds;
+            const maxBounds = meshData.maxBounds;
+            info.boundingSphere = [(minBounds[0] + maxBounds[0]) * 0.5, (minBounds[1] + maxBounds[1]) * 0.5, (minBounds[2] + maxBounds[2]) * 0.5, Math.hypot(maxBounds[0] - minBounds[0], maxBounds[1] - minBounds[1], maxBounds[2] - minBounds[2]) * 0.5];
+          }
+          const worldSphere = found.mesh.instanceSpheres[found.instanceIndex] ?? EMPTY_SPHERE;
+          const frustum = updateContext.GetFrustum();
+          info.estimatedPixelDiameter = Math.max(frustum.GetPixelSizeAccrossEst(worldSphere.center, worldSphere.radius) * updateContext.GetInvLodFactor(), 0);
+          info.isInFrustum = frustum.IsSphereVisible(worldSphere.center, worldSphere.radius);
+          const damageLocators = FindDamageLocators(found.mesh.ownedLocatorSets);
+          info.getDamageLocatorPositionOS = (index, out) => {
+            if (!damageLocators || index < 0 || index >= damageLocators.length) return false;
+            vec3.copy(out, damageLocators[index].position);
+            return true;
+          };
+        }
+        overlay.UpdateAsyncronous(updateContext, info, 0, false);
+      }
+      if (this.#parentOverlayEffects && this.#AnyMeshInheritsOverlayEffects() || this.#HasAnyOwnOverlayEffects() || this._partDamageOverlays.size !== 0) {
+        this.#UpdateOverlayInstanceData(updateContext, parentRecords.vs, parentRecords.ps, previousWorldTransform);
       }
       this.hasUpdated = true;
     }
 
     /** Builds one persistent VS/PS record pair per authored instance. */
-    #UpdateOverlayInstanceData(parentVs, parentPs, previousWorldTransform) {
+    #UpdateOverlayInstanceData(updateContext, parentVs, parentPs, previousWorldTransform) {
       for (const mesh of this.meshes) {
-        if (!mesh.instances.length || !mesh.display || !this.#MeshHasActiveOverlayEffects(mesh)) continue;
+        if (!mesh.instances.length || !mesh.display || !this._MeshNeedsOverlayPods(mesh)) continue;
         if (!mesh.overlayPods || mesh.overlayPods.length !== mesh.instances.length) {
           mesh.overlayPods = Array.from({
             length: mesh.instances.length
@@ -337,6 +397,15 @@ new class extends _identity {
             pod.ps.Set("clipSphereFactor", [0]);
             pod.ps.Set("clipSphereFactor2", [0]);
           }
+
+          // Carbon cpp:1238-1242: a damaged part flickers and reads its own
+          // rows of the damage data texture.
+          const damageOverlay = this._FindPartDamageOverlay(mesh.partTags[index]);
+          if (damageOverlay) {
+            const shipData = pod.ps.Get("shipData");
+            pod.ps.Set("shipData", [shipData[0], shipData[1] * damageOverlay.GetActivationStrength(updateContext), shipData[2], shipData[3]]);
+            pod.ps.Set("impactDataOffset", [damageOverlay.GetDataTextureOffset()]);
+          }
         }
       }
     }
@@ -356,10 +425,43 @@ new class extends _identity {
       return mesh.ownOverlayEffects.length !== 0 || this.#parentOverlayEffects !== null && mesh.inheritOverlayEffects;
     }
 
-    /**
-     * Returns the child's world transform as stamped by the last sync update.
-     * @param {Float32Array} [out] - caller-owned; when given, receives a copy and is returned instead of the live matrix
-     * @returns {Float32Array} out when supplied, otherwise the live internal matrix
+    /**
+     * Finds the mesh holding an instance of a part, and that instance's index
+     * (Carbon FindMeshByPartTag, cpp:1115-1132; the size_t* out-param becomes
+     * the returned record).
+     * @returns {{mesh: EveChildInstancedMesh, instanceIndex: Number}|null}
+     */
+    _FindMeshByPartTag(partTag) {
+      for (const mesh of this.meshes) {
+        const instanceIndex = mesh.partTags.indexOf(partTag);
+        if (instanceIndex !== -1) return {
+          mesh,
+          instanceIndex
+        };
+      }
+      return null;
+    }
+
+    /** Returns a part's damage overlay, or null (Carbon FindPartDamageOverlay, cpp:1134-1142). */
+    _FindPartDamageOverlay(partTag) {
+      return this._partDamageOverlays.get(partTag) ?? null;
+    }
+
+    /** Reports whether any instance of a mesh belongs to a damaged part (Carbon cpp:1144-1158). */
+    _MeshHasDamageOverlays(mesh) {
+      if (this._partDamageOverlays.size === 0) return false;
+      return mesh.partTags.some(tag => this._partDamageOverlays.has(tag));
+    }
+
+    /** Reports whether a mesh needs per-instance overlay pods (Carbon cpp:1160-1163). */
+    _MeshNeedsOverlayPods(mesh) {
+      return this.#MeshHasActiveOverlayEffects(mesh) || this._MeshHasDamageOverlays(mesh);
+    }
+
+    /**
+     * Returns the child's world transform as stamped by the last sync update.
+     * @param {Float32Array} [out] - caller-owned; when given, receives a copy and is returned instead of the live matrix
+     * @returns {Float32Array} out when supplied, otherwise the live internal matrix
      */
     GetLocalToWorldTransform(out = null) {
       if (out) {
@@ -368,37 +470,37 @@ new class extends _identity {
       return this.worldTransform;
     }
 
-    /**
-     * Carbon EveChildInstancedMeshes::Setup (cpp:335-337) is an intentional no-op:
-     * placement comes from the authored per-instance transforms, not from an SRT
-     * setup.
+    /**
+     * Carbon EveChildInstancedMeshes::Setup (cpp:335-337) is an intentional no-op:
+     * placement comes from the authored per-instance transforms, not from an SRT
+     * setup.
      */
     Setup() {}
 
-    /**
-     * Carbon EveChildInstancedMeshes::ChangeLOD (cpp:339-341) is an intentional
-     * no-op; the child keeps no LOD state.
+    /**
+     * Carbon EveChildInstancedMeshes::ChangeLOD (cpp:339-341) is an intentional
+     * no-op; the child keeps no LOD state.
      */
     ChangeLOD() {}
 
-    /**
-     * Accepts and discards the placement origin; this child has no Carbon origin
-     * field and stores none.
+    /**
+     * Accepts and discards the placement origin; this child has no Carbon origin
+     * field and stores none.
      */
     SetOrigin() {}
 
-    /**
-     * Returns false, so owners treat this child as subject to normal activation
-     * gating.
+    /**
+     * Returns false, so owners treat this child as subject to normal activation
+     * gating.
      */
     IsAlwaysOn() {
       return false;
     }
 
-    /** Carbon EveChildInstancedMeshes::SetShaderOption (cpp:343-359): flips the
-     * option and refreshes the effect hash on every area, then removes any
-     * registered mesh-group handle and clears the latch - so the groups
-     * re-register with the NEW effectHash on the next AddMeshesToManager pass.
+    /** Carbon EveChildInstancedMeshes::SetShaderOption (cpp:343-359): flips the
+     * option and refreshes the effect hash on every area, then removes any
+     * registered mesh-group handle and clears the latch - so the groups
+     * re-register with the NEW effectHash on the next AddMeshesToManager pass.
      * Sphere/per-object handles deliberately stay registered. */
     SetShaderOption(name, value) {
       for (const mesh of this.meshes) {
@@ -415,14 +517,16 @@ new class extends _identity {
       this.#revision++;
     }
 
-    /**
-     * Appends one instanced mesh: normalizes the area ducks, copies the instance transforms, stamps CASTS_SHADOW plus one flag bit per area batch type (Carbon cpp:418-425), and clears the registration latch so the next AddMeshesToManager pass picks it up.
-     * @param {Iterable} areas - area ducks ({effect, batchType, areaIndex, areaCount})
-     * @param {Iterable<Float32Array>} instanceTransforms - 16-value matrices; copied, not retained
-     * @param {Number} partTag - modular owner shared by every appended instance
-     * @returns {Boolean} false when no areas or no instances were supplied (nothing is added)
+    /**
+     * Appends one instanced mesh: normalizes the area ducks, copies the instance transforms, stamps CASTS_SHADOW plus one flag bit per area batch type (Carbon cpp:574-581), and clears the registration latch so the next AddMeshesToManager pass picks it up.
+     * @param {Iterable} areas - area ducks ({effect, batchType, areaIndex, areaCount})
+     * @param {Iterable<Float32Array>} instanceTransforms - 16-value matrices; copied, not retained
+     * @param {Number} partTag - modular owner shared by every appended instance
+     * @param {Iterable} ownedLocatorSets - the part's hull-local EveLocatorSets, merged by the owner per instance
+     * @param {Object|null} armorDamageShader - the part's armour damage Tr2Effect
+     * @returns {Boolean} false when no areas or no instances were supplied (nothing is added)
      */
-    AddMesh(geometryPath, castsShadow, reflectionMode, meshIndex, areas, instanceTransforms, sofHullName = "", sofLocatorSetName = "", partTag = 0) {
+    AddMesh(geometryPath, castsShadow, reflectionMode, meshIndex, areas, instanceTransforms, sofHullName = "", sofLocatorSetName = "", partTag = 0, ownedLocatorSets = [], armorDamageShader = null) {
       const sourceAreas = Array.from(areas ?? []);
       const sourceTransforms = Array.from(instanceTransforms ?? []);
       if (!sourceAreas.length || !sourceTransforms.length) {
@@ -448,9 +552,15 @@ new class extends _identity {
       mesh.partTags = instances.map(() => Number(partTag) >>> 0);
       mesh.sofHullName = String(sofHullName ?? "");
       mesh.sofLocatorSetName = String(sofLocatorSetName ?? "");
-      // Carbon (cpp:418-425): the CASTS_SHADOW flag and one bit per area batch
+      mesh.ownedLocatorSets = Array.from(ownedLocatorSets ?? []);
+      mesh.armorDamageShader = armorDamageShader ?? null;
+      // Carbon cpp:586-589: the owner merges this part's sets per instance.
+      if (mesh.ownedLocatorSets.length && this.GetOwner()) {
+        this.GetOwner().InvalidateMergedLocators("structure");
+      }
+      // Carbon (cpp:574-581): the CASTS_SHADOW flag and one bit per area batch
       // type are stamped at add time; RENDER_IN_REFLECTION is refreshed each
-      // async pass. cpp:428 clears the registration latch.
+      // async pass. cpp:590 clears the registration latch.
       if (mesh.castsShadow) {
         mesh.flags = (mesh.flags | INSTANCE_FLAG_CASTS_SHADOW) >>> 0;
       }
@@ -463,13 +573,14 @@ new class extends _identity {
       return true;
     }
 
-    /**
-     * Removes every instance owned by a modular part, dropping empty meshes and
-     * invalidating manager registrations.
+    /**
+     * Removes every instance owned by a modular part, dropping empty meshes and
+     * invalidating manager registrations.
      */
     RemoveInstancesByPartTag(partTag) {
       const tag = Number(partTag) >>> 0;
       let changed = false;
+      let removedOwnedLocators = false;
       for (let meshIndex = this.meshes.length - 1; meshIndex >= 0; meshIndex--) {
         const mesh = this.meshes[meshIndex];
         const keptInstances = [];
@@ -484,6 +595,7 @@ new class extends _identity {
           keptTags.push(instanceTag);
         }
         if (keptInstances.length === mesh.instances.length) continue;
+        removedOwnedLocators ||= mesh.ownedLocatorSets.length !== 0;
         if (mesh.sphereHandle !== null) {
           this.#meshManager.RemoveBoundingSphereGroup(mesh.sphereHandle);
           mesh.sphereHandle = null;
@@ -509,16 +621,22 @@ new class extends _identity {
         this.#allRegistered = false;
         this.#revision++;
       }
+      // Carbon cpp:659-663: the part's damage overlay goes with it, and the
+      // owner re-merges without the part's locators.
+      this._partDamageOverlays.delete(tag);
+      if (removedOwnedLocators && this.GetOwner()) {
+        this.GetOwner().InvalidateMergedLocators("structure");
+      }
       return changed;
     }
 
-    /**
-     * Contributes every instance of every mesh to the owner's merged raycast set
-     * (Carbon EveChildInstancedMeshes.cpp:1279-1324): the type-matching areas
-     * are appended ONCE per mesh and shared by all of that mesh's instance
-     * records via areaStart/areaCount; meshes with no matching areas contribute
-     * nothing. Carbon row-vector instanceTransform * parentTransform maps to
-     * gl-matrix multiply(out, parentTransform, instanceTransform).
+    /**
+     * Contributes every instance of every mesh to the owner's merged raycast set
+     * (Carbon EveChildInstancedMeshes.cpp:1279-1324): the type-matching areas
+     * are appended ONCE per mesh and shared by all of that mesh's instance
+     * records via areaStart/areaCount; meshes with no matching areas contribute
+     * nothing. Carbon row-vector instanceTransform * parentTransform maps to
+     * gl-matrix multiply(out, parentTransform, instanceTransform).
      */
     CollectOwnedGeometry(type, parentTransform, out, areaPool) {
       for (const mesh of this.meshes) {
@@ -549,30 +667,91 @@ new class extends _identity {
       }
     }
 
-    /**
-     * Overwrites the transform of every instance owned by a modular part with an
-     * ABSOLUTE new transform (Carbon EveChildInstancedMeshes.cpp:591-605,
-     * PLAT-11963). Carbon writes only the instance transform: no dirty flag, no
-     * handle teardown - the per-frame async pass refreshes the cull spheres from
-     * the live transforms, and the per-part filter lives HERE, not at the call
-     * site (the shared child carries many parts' instances).
+    /**
+     * Contributes each part's owned locator sets once per instance, tagged with
+     * that instance's part (Carbon EveChildInstancedMeshes.cpp:1473-1495).
+     * Carbon row-vector instanceTransform * parentTransform maps to gl-matrix
+     * multiply(out, parentTransform, instanceTransform).
+     */
+    CollectOwnedLocatorSets(parentTransform, out) {
+      for (const mesh of this.meshes) {
+        for (const sets of mesh.ownedLocatorSets) {
+          if (!sets || !sets.GetLocators().length) continue;
+          for (let index = 0; index < mesh.instances.length; index++) {
+            const childToObject = mat4.create();
+            mat4.multiply(childToObject, parentTransform, mesh.instances[index].transform);
+            out.push({
+              childToObject,
+              owner: this,
+              partTag: mesh.partTags[index],
+              sets
+            });
+          }
+        }
+      }
+    }
+
+    /** Returns a part's damage overlay, or null while it has none (Carbon cpp:1497-1500). */
+    GetPartDamageOverlay(partTag) {
+      return this._FindPartDamageOverlay(partTag);
+    }
+
+    /** Creates a part's damage overlay when it does not yet exist (Carbon cpp:1502-1509). */
+    CreatePartDamageOverlay(partTag) {
+      if (!this._partDamageOverlays.has(partTag)) {
+        this._partDamageOverlays.set(partTag, new _EveDamageOverlay());
+      }
+    }
+
+    /** Returns the armour damage shader of the mesh carrying a part (Carbon cpp:1511-1518). */
+    GetPartArmorDamageShaderEffect(partTag) {
+      return this._FindMeshByPartTag(partTag)?.mesh.armorDamageShader ?? null;
+    }
+
+    /**
+     * Writes the part-local pose of one of a part's damage locators. Shared
+     * instances carry no skeleton, so the pose is the authored one (Carbon
+     * cpp:1520-1534 passes a null animation updater).
+     */
+    GetPartDamageLocatorAnimatedLocal(partTag, index, position, direction) {
+      const found = this._FindMeshByPartTag(partTag);
+      if (!found) return false;
+      const locators = FindDamageLocators(found.mesh.ownedLocatorSets);
+      if (!locators || index < 0 || index >= locators.length) return false;
+      EveGetLocatorPose(position, direction, null, locators[index]);
+      return true;
+    }
+
+    /**
+     * Overwrites the transform of every instance owned by a modular part with an
+     * ABSOLUTE new transform (Carbon EveChildInstancedMeshes.cpp:665-685,
+     * PLAT-11963). No handle teardown - the per-frame async pass refreshes the
+     * cull spheres from the live transforms - but a part that owns locators
+     * invalidates the owner's merged set. The per-part filter lives HERE, not at
+     * the call site (the shared child carries many parts' instances).
      */
     SetInstanceTransformByPartTag(partTag, translation, rotation, scale) {
       const tag = Number(partTag) >>> 0;
       const transform = mat4.fromRotationTranslationScale(mat4.create(), rotation, translation, scale);
+      let movedOwnedLocators = false;
       for (const mesh of this.meshes) {
         for (let index = 0; index < mesh.instances.length; index++) {
           if (Number(mesh.partTags[index] ?? 0) >>> 0 === tag) {
             mat4.copy(mesh.instances[index].transform, transform);
+            movedOwnedLocators ||= mesh.ownedLocatorSets.length !== 0;
           }
         }
       }
+      // Carbon cpp:681-684: moved part-owned locators are re-merged.
+      if (movedOwnedLocators && this.GetOwner()) {
+        this.GetOwner().InvalidateMergedLocators("partMoved");
+      }
     }
 
-    /**
-     * Returns one [translation, rotation, scale] decomposition per instance of a
-     * mesh (Carbon EveChildInstancedMeshes.cpp:781-806, script-exposed tooling);
-     * throws RangeError where Carbon raises IndexError.
+    /**
+     * Returns one [translation, rotation, scale] decomposition per instance of a
+     * mesh (Carbon EveChildInstancedMeshes.cpp:781-806, script-exposed tooling);
+     * throws RangeError where Carbon raises IndexError.
      */
     GetInstancesTransforms(meshId) {
       const index = Number(meshId) >>> 0;
@@ -595,10 +774,10 @@ new class extends _identity {
       });
     }
 
-    /**
-     * Drops every mesh and clears the hasUpdated stamp so nothing re-registers
-     * until another update pass runs; registration handles are NOT released here,
-     * so call UnregisterFromMeshManager first when a manager still holds them.
+    /**
+     * Drops every mesh and clears the hasUpdated stamp so nothing re-registers
+     * until another update pass runs; registration handles are NOT released here,
+     * so call UnregisterFromMeshManager first when a manager still holds them.
      */
     Clear() {
       this.meshes.length = 0;
@@ -606,10 +785,10 @@ new class extends _identity {
       this.#revision++;
     }
 
-    /**
-     * Decodes a picking area id back to the SOF locator it came from.
-     * @param {Number} areaId - mesh ordinal in the high 16 bits, locator index in the low 16 (the pairing AddMeshesToManager registers)
-     * @returns {Array|null} [sofHullName, sofLocatorSetName, locatorIndex], or null when the mesh is unknown or carries no SOF hull name
+    /**
+     * Decodes a picking area id back to the SOF locator it came from.
+     * @param {Number} areaId - mesh ordinal in the high 16 bits, locator index in the low 16 (the pairing AddMeshesToManager registers)
+     * @returns {Array|null} [sofHullName, sofLocatorSetName, locatorIndex], or null when the mesh is unknown or carries no SOF hull name
      */
     GetSofSourceLocator(areaId) {
       const value = Number(areaId) >>> 0;
@@ -625,21 +804,21 @@ new class extends _identity {
       return this.meshes.length;
     }
 
-    /**
-     * Reports one mesh's authoring state as a positional tuple (Carbon's multiple out-params).
-     * @param {Number} meshId - mesh index; RangeError when out of range
-     * @returns {Array} [geometryPath, geometryResource, meshIndex, castsShadow, reflectionMode, areaCount, instanceCount]
+    /**
+     * Reports one mesh's authoring state as a positional tuple (Carbon's multiple out-params).
+     * @param {Number} meshId - mesh index; RangeError when out of range
+     * @returns {Array} [geometryPath, geometryResource, meshIndex, castsShadow, reflectionMode, areaCount, instanceCount]
      */
     GetMeshInfo(meshId) {
       const mesh = _EveChildInstancedMes.#GetMesh(this.meshes, meshId);
       return [mesh.geometryPath, mesh.GetGeometryResource(), mesh.meshIndex, mesh.castsShadow, mesh.reflectionMode, mesh.areas.length, mesh.instances.length];
     }
 
-    /**
-     * Reports one area of one mesh as a positional tuple (Carbon's multiple out-params).
-     * @param {Number} meshId - mesh index; RangeError when out of range
-     * @param {Number} areaId - area index within that mesh; RangeError when out of range
-     * @returns {Array} [effect, batchType, areaIndex, areaCount] - the effect is the live reference
+    /**
+     * Reports one area of one mesh as a positional tuple (Carbon's multiple out-params).
+     * @param {Number} meshId - mesh index; RangeError when out of range
+     * @param {Number} areaId - area index within that mesh; RangeError when out of range
+     * @returns {Array} [effect, batchType, areaIndex, areaCount] - the effect is the live reference
      */
     GetAreaInfo(meshId, areaId) {
       const mesh = _EveChildInstancedMes.#GetMesh(this.meshes, meshId);
@@ -651,17 +830,17 @@ new class extends _identity {
       return [area.effect, area.batchType, area.areaIndex, area.areaCount];
     }
 
-    /**
-     * Whether the given mesh is currently displayed; throws RangeError for an
-     * unknown mesh index.
+    /**
+     * Whether the given mesh is currently displayed; throws RangeError for an
+     * unknown mesh index.
      */
     GetMeshDisplay(meshId) {
       return _EveChildInstancedMes.#GetMesh(this.meshes, meshId).display;
     }
 
-    /** Carbon EveChildInstancedMeshes::SetMeshDisplay (cpp:663-691): a toggle
-     * clears the latch; turning a mesh OFF eagerly removes its sphere and
-     * mesh-group handles - which is why AddMeshesToManager's display-off skip
+    /** Carbon EveChildInstancedMeshes::SetMeshDisplay (cpp:663-691): a toggle
+     * clears the latch; turning a mesh OFF eagerly removes its sphere and
+     * mesh-group handles - which is why AddMeshesToManager's display-off skip
      * does NOT clear the latch (the handles are already gone). */
     SetMeshDisplay(meshId, display) {
       const mesh = _EveChildInstancedMes.#GetMesh(this.meshes, meshId);
@@ -727,9 +906,9 @@ new class extends _identity {
       return _EveChildInstancedMes.#GetMesh(this.meshes, meshId).ownOverlayEffects.length;
     }
 
-    /**
-     * Assigns one mesh's geometry resource, bumping the revision only when it
-     * actually changes; registration waits for the next AddMeshesToManager pass.
+    /**
+     * Assigns one mesh's geometry resource, bumping the revision only when it
+     * actually changes; registration waits for the next AddMeshesToManager pass.
      */
     SetGeometryResource(meshId, geometry) {
       const mesh = _EveChildInstancedMes.#GetMesh(this.meshes, meshId);
@@ -739,20 +918,20 @@ new class extends _identity {
       }
     }
 
-    /**
-     * Returns a detached snapshot of one mesh - instance transforms cloned, areas
-     * shallow-copied, geometry resource shared by reference - so callers can read
-     * it without touching live registration state.
+    /**
+     * Returns a detached snapshot of one mesh - instance transforms cloned, areas
+     * shallow-copied, geometry resource shared by reference - so callers can read
+     * it without touching live registration state.
      */
     GetMeshData(meshId) {
       const mesh = _EveChildInstancedMes.#GetMesh(this.meshes, meshId);
       return _EveChildInstancedMes.#CloneMesh(mesh);
     }
 
-    /**
-     * Monotonic counter bumped by every structural change (AddMesh, Clear,
-     * SetMeshDisplay, SetGeometryResource, SetShaderOption), for consumers caching
-     * derived data.
+    /**
+     * Monotonic counter bumped by every structural change (AddMesh, Clear,
+     * SetMeshDisplay, SetGeometryResource, SetShaderOption), for consumers caching
+     * derived data.
      */
     GetRevision() {
       return this.#revision;
@@ -779,11 +958,11 @@ new class extends _identity {
 
     /** Exposes stable per-instance CPU record pairs for this frame's overlay batches. */
     GetPerObjectData(_accumulator = null) {
-      if ((!this.#parentOverlayEffects || !this.#AnyMeshInheritsOverlayEffects()) && !this.#HasAnyOwnOverlayEffects()) return null;
+      if ((!this.#parentOverlayEffects || !this.#AnyMeshInheritsOverlayEffects()) && !this.#HasAnyOwnOverlayEffects() && this._partDamageOverlays.size === 0) return null;
       let first = null;
       for (const mesh of this.meshes) {
         if (!mesh.overlayPods) continue;
-        if (!mesh.display || !this.#MeshHasActiveOverlayEffects(mesh)) {
+        if (!mesh.display || !this._MeshNeedsOverlayPods(mesh)) {
           for (const pod of mesh.overlayPods) pod.framePod = null;
           continue;
         }
@@ -804,7 +983,8 @@ new class extends _identity {
       let committed = false;
       for (const mesh of this.meshes) {
         const inherited = this.#parentOverlayEffects && mesh.inheritOverlayEffects ? this.#parentOverlayEffects : null;
-        if (!inherited?.length && !mesh.ownOverlayEffects.length || !mesh.display || !mesh.overlayPods) continue;
+        const hasDamageOverlays = this._MeshHasDamageOverlays(mesh);
+        if (!inherited?.length && !mesh.ownOverlayEffects.length && !hasDamageOverlays || !mesh.display || !mesh.overlayPods) continue;
         if (reason === Tr2RenderReason.TR2RENDERREASON_REFLECTION && !ShouldReflect(mesh.reflectionMode)) continue;
         const geometry = mesh.GetGeometryResource();
         if (!geometry || geometry.IsGood() === false) continue;
@@ -820,6 +1000,15 @@ new class extends _identity {
           if (this.#lastCameraFrustum && this.#lastCameraFrustum.IsSphereVisible(sphere.center, sphere.radius) === false) continue;
           const screenSize = this.#lastCameraFrustum ? this.#lastCameraFrustum.GetPixelSizeAccrossEst(sphere.center, sphere.radius) * this.#lastInvLodFactor : Infinity;
           const lod = geometry.GetMeshLod(mesh.meshIndex, screenSize);
+
+          // Carbon cpp:1404-1413: the part's damage pass comes first, under
+          // its own and the inherited overlays.
+          if (hasDamageOverlays) {
+            const damageShader = this._FindPartDamageOverlay(mesh.partTags[index])?.GetArmorDamageShader(batchType);
+            if (damageShader) {
+              committed = EmitDamageOverlayBatches(batches, pod.framePod, damageShader, mesh.overlayAreaBlocks, geometry, mesh.meshIndex, lod) || committed;
+            }
+          }
           if (mesh.ownOverlayEffects.length) {
             committed = EmitOverlayBatches(batches, pod.framePod, batchType, mesh.ownOverlayEffects, mesh.overlayAreaBlocks, geometry, mesh.meshIndex, lod) || committed;
           }
@@ -831,8 +1020,8 @@ new class extends _identity {
       return committed;
     }
 
-    /** Carbon EveChildInstancedMeshes::RegisterComponents (cpp:36-43):
-     * unconditional InstancedMeshProvider + ShadowCaster leaf
+    /** Carbon EveChildInstancedMeshes::RegisterComponents (cpp:36-43):
+     * unconditional InstancedMeshProvider + ShadowCaster leaf
      * self-registration. */
     RegisterComponents() {
       const registry = this.GetComponentRegistry();
@@ -842,15 +1031,15 @@ new class extends _identity {
       }
     }
 
-    /** Carbon EveChildInstancedMeshes::UnRegisterComponents (cpp:45-48) only
-     * calls UnregisterFromMeshManager; own components were already removed by
+    /** Carbon EveChildInstancedMeshes::UnRegisterComponents (cpp:45-48) only
+     * calls UnregisterFromMeshManager; own components were already removed by
      * EveEntity::UnRegister (EveEntity.cpp:90). */
     UnRegisterComponents() {
       this.UnregisterFromMeshManager();
     }
 
-    /** Carbon EveChildInstancedMeshes::UnregisterFromMeshManager (cpp:50-71):
-     * every registered mesh-group / sphere-group / per-object handle is removed
+    /** Carbon EveChildInstancedMeshes::UnregisterFromMeshManager (cpp:50-71):
+     * every registered mesh-group / sphere-group / per-object handle is removed
      * through the manager that issued the opaque handles, then the latch clears. */
     UnregisterFromMeshManager() {
       for (const mesh of this.meshes) {
@@ -877,19 +1066,19 @@ new class extends _identity {
       this.#allRegistered = false;
     }
 
-    /** Carbon EveChildInstancedMeshes::AddMeshesToManager (cpp:472-553), the
-     * InstancedMeshProvider entry the engine's CollectMeshes drives
-     * (EveInstancedMeshManager.cpp:45-56; scene EveSpaceScene.cpp:1516).
-     * Contract quirks preserved: nothing registers before the first update
-     * pass (cpp:474); switching managers tears EVERYTHING down BEFORE the
-     * latch early-out (cpp:478-481); the latch is set optimistically and
-     * cleared by ANY not-ready mesh/area so the per-frame caller retries until
-     * geometry streams in - EXCEPT display-off meshes, which skip WITHOUT
-     * clearing it (their handles were already removed by SetMeshDisplay);
-     * handles are add-once (partial re-registration after SetShaderOption /
-     * display toggles); an area-level effect failure clears the latch while
-     * the mesh's sphere group STAYS registered (Carbon's asymmetry);
-     * pickingOwnerIndex is the mesh ordinal (pairs with GetSofSourceLocator's
+    /** Carbon EveChildInstancedMeshes::AddMeshesToManager (cpp:472-553), the
+     * InstancedMeshProvider entry the engine's CollectMeshes drives
+     * (EveInstancedMeshManager.cpp:45-56; scene EveSpaceScene.cpp:1516).
+     * Contract quirks preserved: nothing registers before the first update
+     * pass (cpp:474); switching managers tears EVERYTHING down BEFORE the
+     * latch early-out (cpp:478-481); the latch is set optimistically and
+     * cleared by ANY not-ready mesh/area so the per-frame caller retries until
+     * geometry streams in - EXCEPT display-off meshes, which skip WITHOUT
+     * clearing it (their handles were already removed by SetMeshDisplay);
+     * handles are add-once (partial re-registration after SetShaderOption /
+     * display toggles); an area-level effect failure clears the latch while
+     * the mesh's sphere group STAYS registered (Carbon's asymmetry);
+     * pickingOwnerIndex is the mesh ordinal (pairs with GetSofSourceLocator's
      * meshIndex<<16 decode). */
     AddMeshesToManager(manager) {
       if (!this.hasUpdated) {
@@ -943,41 +1132,41 @@ new class extends _identity {
       }
     }
 
-    /** Carbon EveChildInstancedMeshes::IsCastingShadow (cpp:73-76) always
-     * returns false (instanced shadows cull per instance group); presence
+    /** Carbon EveChildInstancedMeshes::IsCastingShadow (cpp:73-76) always
+     * returns false (instanced shadows cull per instance group); presence
      * satisfies the "ShadowCaster" duck contract. */
     IsCastingShadow(..._args) {
       return false;
     }
 
-    /** Carbon EveChildInstancedMeshes::GetShadowBatches (cpp:78-80) is an
+    /** Carbon EveChildInstancedMeshes::GetShadowBatches (cpp:78-80) is an
      * intentional no-op (the instanced mesh manager emits the batches). */
     GetShadowBatches(..._args) {}
 
-    /** Carbon EveChildInstancedMeshes::GetShadowPerObjectData (cpp:82-85)
+    /** Carbon EveChildInstancedMeshes::GetShadowPerObjectData (cpp:82-85)
      * returns null (per-object data flows through the mesh manager). */
     GetShadowPerObjectData(..._args) {
       return null;
     }
 
-    /**
-     * Resolves a mesh index against the list, throwing RangeError rather than
-     * returning undefined so every public accessor fails loudly.
+    /**
+     * Resolves a mesh index against the list, throwing RangeError rather than
+     * returning undefined so every public accessor fails loudly.
      */
 
-    /**
-     * Builds an area record from a plain duck, defaulting areaCount to 1 and
-     * caching the effect hash the manager registers the mesh group under.
+    /**
+     * Builds an area record from a plain duck, defaulting areaCount to 1 and
+     * caching the effect hash the manager registers the mesh group under.
      */
 
-    /**
-     * Deep-copies a mesh into a plain object for GetMeshData: instance transforms
-     * cloned, areas spread-copied, the geometry resource shared by reference.
+    /**
+     * Deep-copies a mesh into a plain object for GetMeshData: instance transforms
+     * cloned, areas spread-copied, the geometry resource shared by reference.
      */
 
-    /**
-     * Reads an owned effect's stable registration hash; null areas retain the
-     * Carbon zero hash until their effect arrives.
+    /**
+     * Reads an owned effect's stable registration hash; null areas retain the
+     * Carbon zero hash until their effect arrives.
      */
   }];
   #inverseScratch = mat4.create();