Slice Combat Depth (MC-2): enemy-variety server spine — Spitter, Swarmer, 4-type mix (DR-041)

Adds the server-authoritative mechanics for three new enemy archetypes on top of
the Grunt/Charger base, plus the weighted wave-composition that introduces them:

- Spitter: a ranged Husk variant (SpitterState) that holds a preferred range-band
  (advance/retreat/hold via EnemyAIMath.BandVelocity) and fires a telegraphed,
  dodgeable EnemyProjectile. New server EnemyProjectileMoveSystem (integrate +
  store LastStep) + EnemyProjectileDamageSystem (region-filtered swept hit-test
  rebuilt from LastStep — DR-018 anti-tunnelling; players use HitRadius, structures
  a const radius; at-most-once destroy). Concurrent-spit soft cap, soft-fail retry.
- Swarmer: marker tag + deterministic cluster spawn (1 slot = 1 pack;
  EnemyAIMath.ClusterOffset), MaxAlive counts ENTITIES so a pack defers if it
  won't fit.
- 4-type weighted mix: MixBands -> ZoneEnemyMath.WaveSlots/KindForSlot/
  PackSizeForSlot drives both the expedition director and (fork-4a) the base siege,
  with a mandatory MaxAlive cap. Legacy WaveSize/IsChargerSlot kept + parity-tested.
- Discriminator stays component-presence (no enum in Bursted systems): query-
  partition guards keep each enemy moved by exactly one EnemyAISystem pass
  (sole-Position-writer). EnemyTelegraph.IsCharger -> Kind byte for the client cue.

New authoring (Spitter/Swarmer/EnemyProjectile) + expanded director authorings with
tunable mix/cluster defaults. 13 new EditMode tests (mix composition + legacy parity,
band/cluster math, projectile move + cross-region + swept anti-tunnelling regressions);
full suite green before commit.

Dormant until the prefab/subscene wiring lands (next): the new systems guard on
TryGetSingleton/RequireForUpdate, so with no prefabs wired the new types stay inert.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Assets/_Project/Scripts/Simulation/Combat/AttackWindup.cs

@@ -29,7 +29,8 @@ namespace ProjectM.Simulation
         /// <summary>Per-variant wind-up DURATION in ticks (the client danger-ramp denominator).</summary>
         public byte WindupTicks;
 
-        /// <summary>0 = Grunt-style; 1 = Charger (committed-lunge tell).</summary>
-        public byte IsCharger;
+        /// <summary>Enemy kind for the client telegraph look: 0=Grunt, 1=Charger, 2=Spitter, 3=Swarmer (the
+        /// ZoneEnemyMath.Kind* bytes). Baked per variant by EnemyBaker (the SOLE writer); never a [GhostField].</summary>
+        public byte Kind;
     }
 }

Assets/_Project/Scripts/Simulation/Combat/EnemyAIMath.cs

@@ -126,5 +126,42 @@ namespace ProjectM.Simulation
                 if (sq < bestSq) { bestSq = sq; index = i; isStructure = true; }
             }
         }
+
+        /// <summary>
+        /// MC-2 Spitter range-band velocity (planar XZ): ADVANCE toward <paramref name="to"/> at
+        /// <paramref name="speed"/> when farther than <paramref name="preferred"/> + <paramref name="tolerance"/>,
+        /// RETREAT directly away when closer than <paramref name="preferred"/> - <paramref name="tolerance"/>, and
+        /// HOLD (zero) inside the dead-zone band. Y forced to 0. Returns zero when the points coincide. Pure /
+        /// Burst-safe / EditMode-testable; keeps the Spitter at its firing distance instead of closing to melee.
+        /// </summary>
+        public static float3 BandVelocity(float3 from, float3 to, float speed, float preferred, float tolerance)
+        {
+            float3 d = to - from;
+            d.y = 0f;
+            float distSq = math.lengthsq(d);
+            if (distSq < 1e-8f)
+                return float3.zero;
+            float dist = math.sqrt(distSq);
+            float3 dir = d / dist;
+            float tol = math.max(0f, tolerance);
+            if (dist > preferred + tol)
+                return dir * speed;          // too far -> close in
+            if (dist < preferred - tol)
+                return -dir * speed;         // too close -> back off
+            return float3.zero;              // in band -> hold and fire
+        }
+
+        /// <summary>
+        /// Deterministic tight-cluster offset for swarmer <paramref name="index"/> of a pack of
+        /// <paramref name="packSize"/> around <paramref name="center"/> at <paramref name="tightRadius"/> (reuses the
+        /// <see cref="RingPosition"/> even-angle math at a small radius). A single swarmer (packSize&lt;=1) spawns at
+        /// the centre. Stable per index so a replayed pack lands identically. Pure.
+        /// </summary>
+        public static float3 ClusterOffset(float3 center, int index, int packSize, float tightRadius)
+        {
+            if (packSize <= 1)
+                return center;
+            return RingPosition(center, index, packSize, tightRadius);
+        }
     }
 }

Assets/_Project/Scripts/Simulation/Combat/EnemyProjectile.cs

@@ -0,0 +1,53 @@
+using Unity.Entities;
+using Unity.Mathematics;
+
+namespace ProjectM.Simulation
+{
+    /// <summary>
+    /// MC-2 — a hostile Spitter projectile: a server-spawned, OWNERLESS INTERPOLATED ghost moved server-only in the
+    /// plain SimulationSystemGroup (NOT predicted — like the Husks that fire it). It replicates ONLY the stock
+    /// LocalTransform (no hand-written [GhostField]); this component is server-only state. It deliberately carries NO
+    /// Health, so it is invisible to every WithAll&lt;Health&gt; target loop (player melee/projectile hit-tests can
+    /// never see it — fork 2a: spits are pure dodge/dash checks, NOT shootable). Integrated by
+    /// EnemyProjectileMoveSystem and swept-hit-tested against players + structures by EnemyProjectileDamageSystem.
+    /// </summary>
+    public struct EnemyProjectile : IComponentData
+    {
+        /// <summary>Planar heading (world XZ -> float2 x,y), unit length, locked at spawn.</summary>
+        public float2 Direction;
+
+        /// <summary>Travel speed (world units/second).</summary>
+        public float Speed;
+
+        /// <summary>Damage applied to the first valid same-region target hit.</summary>
+        public float Damage;
+
+        /// <summary>Max travel distance before it expires (world units).</summary>
+        public float Range;
+
+        /// <summary>Accumulated travelled distance (server-only; drives range-expiry).</summary>
+        public float DistanceTravelled;
+
+        /// <summary>Distance moved on the LAST tick (= Speed * the server fixed step). The damage system rebuilds the
+        /// swept segment as cur - Direction*LastStep — NEVER a fresh SystemAPI.Time.DeltaTime (this system runs in the
+        /// PLAIN group where that dt is the wall-frame delta, not the fixed step). Prevents high-speed tunnelling.</summary>
+        public float LastStep;
+
+        /// <summary>Region byte (RegionId.Base/Expedition), copied from the firing Spitter. The damage system skips any
+        /// target whose RegionTag.Region != this — relevancy hides cross-region ghosts from CLIENTS, but the SERVER
+        /// world holds base + expedition players 1000u apart, so server damage needs its OWN region guard.</summary>
+        public byte Region;
+    }
+
+    /// <summary>
+    /// Baked subscene singleton: the Spitter projectile ghost prefab + the concurrent soft-cap. The server reads it
+    /// via GetSingleton (the prefab Entity lives HERE, never per-Spitter — mirrors AbilityDatabase / WaveEnemyPrefab).
+    /// MaxLiveProjectiles bounds the RegionRelevancySystem O(ghosts x conn)/tick loop: a Spitter at/over the cap
+    /// soft-fails its shot (no cooldown burn — the EB-2 turret soft-fail pattern).
+    /// </summary>
+    public struct SpitterProjectilePrefab : IComponentData
+    {
+        public Entity Prefab;
+        public int MaxLiveProjectiles;
+    }
+}

Assets/_Project/Scripts/Simulation/Combat/EnemyProjectile.cs.meta

@@ -0,0 +1,2 @@
+fileFormatVersion: 2
+guid: 8a31a7b0c834ae24db480005ffdb6a15

Assets/_Project/Scripts/Simulation/Combat/MixBands.cs

@@ -0,0 +1,30 @@
+using Unity.Entities;
+
+namespace ProjectM.Simulation
+{
+    /// <summary>
+    /// MC-2 — baked weighted-composition table shared by BOTH enemy directors (the expedition
+    /// ZoneEnemyDirectorSystem and the base-siege WaveSystem). Pure integer weights consumed by the deterministic
+    /// <see cref="ZoneEnemyMath"/>.{WaveSlots, KindForSlot, PackSizeForSlot} functions (no enum, no RNG -&gt;
+    /// replay/save-stable). Per kind: a base count + a per-epoch ramp; the Grunt count is the REMAINDER (slots minus
+    /// the others) so it stays a fixed floor while chargers / spitters / swarmer-slots grow as the epoch (expedition)
+    /// or wave (base siege) climbs. A "swarmer slot" expands to a PackSize cluster at spawn (PackSizeForSlot), so one
+    /// slot = one pack. The LEGACY band {GruntBase=g, ChargerBase=c, ChargerPerEpoch=1, rest 0} reproduces the old
+    /// 2-type <see cref="ZoneEnemyMath.WaveSize"/> / <see cref="ZoneEnemyMath.IsChargerSlot"/> exactly (a parity test
+    /// pins this, so the base-siege size curve is provably unchanged where it must be).
+    /// </summary>
+    public struct MixBands : IComponentData
+    {
+        public int GruntBase;
+        public int ChargerBase;
+        public int SpitterBase;
+        public int SwarmerSlotBase;
+        public int ChargerPerEpoch;
+        public int SpitterPerEpoch;
+        public int SwarmerSlotPerEpoch;
+
+        /// <summary>Exposed-but-default-0 epoch ramp for the swarmer PACK size (PackSizeForSlot adds
+        /// SwarmerPackPerEpoch*(epoch-1) to the director's base pack size). v1 keeps it 0 = fixed pack size.</summary>
+        public int SwarmerPackPerEpoch;
+    }
+}

Assets/_Project/Scripts/Simulation/Combat/MixBands.cs.meta

@@ -0,0 +1,2 @@
+fileFormatVersion: 2
+guid: 850f904d96b1c7d41959dddbdbf0b4b5

Assets/_Project/Scripts/Simulation/Combat/SpitterComponents.cs

@@ -0,0 +1,45 @@
+using Unity.Entities;
+
+namespace ProjectM.Simulation
+{
+    /// <summary>
+    /// MC-2 — server-only Spitter "reposition" brain state. Component PRESENCE is the Spitter discriminator (no
+    /// enum / brain byte — honours the Burst cross-assembly-enum rule; EnemyAISystem is Bursted): a Husk variant
+    /// baked with SpitterState is driven by the ranged range-band branch, mutually exclusive with the Charger
+    /// branch (the AI partitions Spitter = .WithAll&lt;EnemyTag,SpitterState&gt;().WithNone&lt;LungeState&gt;() so no
+    /// enemy is ever double-moved). The Spitter holds a PREFERRED RANGE band from its target — retreating if too
+    /// close, advancing if too far — and fires a TELEGRAPHED, dodgeable projectile on its OWN fire gate. If
+    /// cornered (no retreat room) within CorneredRange it falls back to the Grunt seek+strike. NOT a [GhostField]
+    /// (only server systems read it). All ticks via TickUtil.NonZero; compared with NetworkTick only.
+    /// </summary>
+    public struct SpitterState : IComponentData
+    {
+        /// <summary>Band centre: the distance the Spitter tries to hold from its target (world units).</summary>
+        public float PreferredRange;
+
+        /// <summary>Half-width dead-zone around PreferredRange; inside [pref-tol, pref+tol] the Spitter holds.</summary>
+        public float RangeTolerance;
+
+        /// <summary>Muzzle speed baked onto the spit projectile (world units/second).</summary>
+        public float ProjectileSpeed;
+
+        /// <summary>If the target closes within this distance AND the Spitter can't retreat, it melee-falls-back.</summary>
+        public float CorneredRange;
+
+        /// <summary>Telegraph wind-up lead in ticks before the spit fires (the dodge window). Baked (v1 not
+        /// live-tunable); keep >= ~24 (> interp delay) so a player reacting to the aim-line can clear the shot.</summary>
+        public int WindupTicks;
+
+        /// <summary>Server-only fire gate: raw tick of the earliest tick it may spit again (NonZero; 0 = ready). Its
+        /// OWN gate, never EnemyAttackCooldown. Compared via NetworkTick.IsNewerThan.</summary>
+        public uint NextShotTick;
+    }
+
+    /// <summary>
+    /// MC-2 — pure marker for a Swarmer "surround" enemy: mechanically a Grunt (NO AI branch — it falls through the
+    /// Grunt seek+strike pass) with swarm-tuned baked EnemyStats (fast, low-HP, fast frequent low-chip bites). The
+    /// tag drives only (a) the director's CLUSTER spawn (PackSize swarmers in one tick) and (b) a client tint. Keeps
+    /// EnemyTag + RegionTag like every Husk, so readability / health-bars / damage / region-AI all work unchanged.
+    /// </summary>
+    public struct SwarmerTag : IComponentData { }
+}

Assets/_Project/Scripts/Simulation/Combat/SpitterComponents.cs.meta

@@ -0,0 +1,2 @@
+fileFormatVersion: 2
+guid: be9404154fd4f964099918079d2da6b8

Assets/_Project/Scripts/Simulation/Combat/WaveComponents.cs

@@ -16,6 +16,17 @@ namespace ProjectM.Simulation
         public int CountPerWave;
         public int SpawnIntervalTicks;
         public int LullTicks;
+        public int MaxAlive;              // MC-2 fork-4a: mandatory cap for the 4-type base siege (uncapped packs/spits spike relevancy).
+        // MC-2 base-siege mix bands (the director builds a ZoneEnemyMath.MixBands): BaseCount above = the Grunt base count.
+        public int ChargerBase;
+        public int SpitterBase;
+        public int SwarmerSlotBase;
+        public int ChargerPerEpoch;
+        public int SpitterPerEpoch;
+        public int SwarmerSlotPerEpoch;
+        public int SwarmerPackSize;
+        public int SwarmerPackPerEpoch;
+        public float ClusterTightRadius;
     }
 
     /// <summary>Baked pool of Husk prefab variants the director draws from round-robin (Grunt / Swarmer / Brute / ...).</summary>

Assets/_Project/Scripts/Simulation/Combat/ZoneEnemyComponents.cs

@@ -28,6 +28,16 @@ namespace ProjectM.Simulation
         public int SpawnIntervalTicks;
         public int GruntsPerWave;
         public int ChargersPerWave;
+        // MC-2 mix bands (the director builds a ZoneEnemyMath.MixBands from these): GruntsPerWave/ChargersPerWave
+        // above are the Grunt/Charger BASE counts; these add the Spitter/Swarmer bases + per-epoch ramps + the pack.
+        public int SpitterBase;
+        public int SwarmerSlotBase;
+        public int ChargerPerEpoch;
+        public int SpitterPerEpoch;
+        public int SwarmerSlotPerEpoch;
+        public int SwarmerPackSize;       // swarmers per swarmer-slot cluster (>=1)
+        public int SwarmerPackPerEpoch;   // exposed pack ramp (v1 default 0 = fixed)
+        public float ClusterTightRadius;  // tight ring radius for a swarmer pack
         public int RewardOre;
     }
 

Assets/_Project/Scripts/Simulation/Combat/ZoneEnemyMath.cs

@@ -38,5 +38,66 @@ namespace ProjectM.Simulation
             int s = ((slot % size) + size) % size;
             return s >= size - chargers;
         }
+
+        // ---- MC-2: 4-type weighted composition (Grunt/Charger/Spitter/Swarmer), shared by both directors ----
+        // Kind bytes (NO C# enum — directors index a per-Kind prefab buffer by these; EnemyAISystem is Bursted).
+        public const byte KindGrunt = 0;
+        public const byte KindCharger = 1;
+        public const byte KindSpitter = 2;
+        public const byte KindSwarmer = 3;
+
+        /// <summary>
+        /// Total SLOTS in this epoch/wave under <paramref name="bands"/>: GruntBase + the per-kind ramped counts
+        /// (charger/spitter/swarmer-slot = base + perEpoch*(epoch-1)). Lower-bounded at 1 so there is always a fight.
+        /// A swarmer SLOT expands to a pack at spawn (<see cref="PackSizeForSlot"/>), so this counts packs, not
+        /// individual swarmers. For the LEGACY band it equals <see cref="WaveSize"/> (parity-tested). Pure integer.
+        /// </summary>
+        public static int WaveSlots(int epoch, in MixBands bands)
+        {
+            int e = math.max(1, epoch);
+            int grunts = math.max(0, bands.GruntBase);
+            int chargers = math.max(0, bands.ChargerBase + bands.ChargerPerEpoch * (e - 1));
+            int spitters = math.max(0, bands.SpitterBase + bands.SpitterPerEpoch * (e - 1));
+            int swarmers = math.max(0, bands.SwarmerSlotBase + bands.SwarmerSlotPerEpoch * (e - 1));
+            return math.max(1, grunts + chargers + spitters + swarmers);
+        }
+
+        /// <summary>
+        /// Deterministic Kind byte for spawn <paramref name="slot"/> of this epoch/wave. Slots are partitioned in a
+        /// FIXED order — Grunts, then Spitters, then Chargers, then Swarmer-slots last — so the wave skews threat-heavy
+        /// as the ramped counts climb (Grunts are the remainder = a fixed floor). Any leftover slot (when the kinds
+        /// under-fill the max(1,..) floor) defaults to Grunt. Stable per (epoch, slot). For the LEGACY band this
+        /// returns KindCharger on exactly the slots the old <see cref="IsChargerSlot"/> did (parity-tested). Pure.
+        /// </summary>
+        public static byte KindForSlot(int epoch, int slot, in MixBands bands)
+        {
+            int e = math.max(1, epoch);
+            int size = WaveSlots(epoch, bands);
+            int chargers = math.max(0, bands.ChargerBase + bands.ChargerPerEpoch * (e - 1));
+            int spitters = math.max(0, bands.SpitterBase + bands.SpitterPerEpoch * (e - 1));
+            int swarmers = math.max(0, bands.SwarmerSlotBase + bands.SwarmerSlotPerEpoch * (e - 1));
+            int grunts = math.max(0, size - chargers - spitters - swarmers); // remainder = fixed grunt floor
+
+            int s = ((slot % size) + size) % size;
+            if (s < grunts) return KindGrunt;
+            s -= grunts;
+            if (s < spitters) return KindSpitter;
+            s -= spitters;
+            if (s < chargers) return KindCharger;
+            s -= chargers;
+            if (s < swarmers) return KindSwarmer;
+            return KindGrunt; // defensive: unreachable while counts sum to size
+        }
+
+        /// <summary>
+        /// Swarmer cluster size for a swarmer slot: <paramref name="basePackSize"/> plus the (default-0)
+        /// <see cref="MixBands.SwarmerPackPerEpoch"/> ramp. Lower-bounded at 1. v1 bakes the ramp 0 -> a fixed pack;
+        /// the field is exposed for later tuning.
+        /// </summary>
+        public static int PackSizeForSlot(int epoch, int slot, in MixBands bands, int basePackSize)
+        {
+            int e = math.max(1, epoch);
+            return math.max(1, basePackSize + math.max(0, bands.SwarmerPackPerEpoch) * (e - 1));
+        }
     }
 }