M7 Automation: deterministic Harvester to Conveyor to Fabricator chains

Server-only production chains (never predicted): components + server systems + pure byte-only math (ProductionMath/ConveyorMath/MachineSlotMath), authoring + 3 machine prefabs wired into the Gameplay subscene, StructureCatalog rows, BuildPlace Direction/RuntimePlacedTag, Tuning, and 35 EditMode tests (catch-up gating, conveyor shuffle-invariance, SaveData v2 round-trip). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-06 15:05:15 -07:00
parent 31c4ab16d6
commit f3f65bccbf
49 changed files with 2599 additions and 1 deletions
@@ -0,0 +1,8 @@
+fileFormatVersion: 2
+guid: 4eba886d11c07eb4d97ca0d821a1560f
+folderAsset: yes
+DefaultImporter:
+  externalObjects: {}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 
@@ -0,0 +1,87 @@
+using Unity.Entities;
+
+namespace ProjectM.Simulation
+{
+    /// <summary>
+    /// A fixed-yield resource generator — the FRONT of the M7 auto-gather chain (Harvester -> Conveyor ->
+    /// Fabricator). Each period it deposits <see cref="Yield"/> of <see cref="ResourceId"/> into its OWN
+    /// server-only <see cref="MachineOutput"/> buffer (a conveyor pulls it onward). Server-only data (NO
+    /// [GhostField]); the client only ever sees <c>PlacedStructure.Type</c>. Reuses
+    /// <c>PlacedStructure.NextTick</c>/<c>LastProcessedTick</c> for the deterministic, within-session catch-up
+    /// cadence (see <c>HarvesterProductionSystem</c>).
+    /// </summary>
+    public struct Harvester : IComponentData
+    {
+        /// <summary>Resource id produced (a byte; see <see cref="ResourceId"/>).</summary>
+        public byte ResourceId;
+        /// <summary>Units produced per elapsed period.</summary>
+        public int Yield;
+        /// <summary>Server ticks between productions.</summary>
+        public int PeriodTicks;
+    }
+
+    /// <summary>
+    /// A recipe machine — the BACK of the M7 chain. Consumes <see cref="InAmount"/> of <see cref="InResourceId"/>
+    /// per run from its own <see cref="MachineInput"/> buffer (fed by a conveyor) and deposits <see cref="OutAmount"/>
+    /// of <see cref="OutResourceId"/> into the GLOBAL ledger. Strictly input-limited (never mints from an empty
+    /// slot). Server-only data.
+    /// </summary>
+    public struct Fabricator : IComponentData
+    {
+        public byte InResourceId;
+        public int InAmount;
+        public byte OutResourceId;
+        public int OutAmount;
+        public int PeriodTicks;
+    }
+
+    /// <summary>
+    /// A directional transport belt — the MIDDLE of the M7 chain. Each period it pulls one item off an adjacent
+    /// upstream <see cref="MachineOutput"/> (when empty) and advances a held <see cref="ConveyorItem"/> exactly one
+    /// cell toward <see cref="Direction"/>. <see cref="Direction"/> is a byte (0=+X,1=-X,2=+Z,3=-Z) — never an enum
+    /// (the cross-assembly enum-in-Burst hazard). Server-only data.
+    /// </summary>
+    public struct Conveyor : IComponentData
+    {
+        /// <summary>Belt facing: 0=+X, 1=-X, 2=+Z, 3=-Z (see <c>ConveyorMath.DirOffset</c>).</summary>
+        public byte Direction;
+        public int PeriodTicks;
+    }
+
+    /// <summary>
+    /// A machine's INPUT staging buffer (server-only, NO [GhostField] -> never replicated). A DISTINCT element type
+    /// from the global ledger's <see cref="StorageEntry"/> (so <c>GetSingleton&lt;StorageEntry&gt;</c> stays
+    /// unambiguous) and from <see cref="MachineOutput"/> (so a machine can carry both without a buffer-type clash).
+    /// </summary>
+    public struct MachineInput : IBufferElementData
+    {
+        public byte ResourceId;
+        public int Count;
+    }
+
+    /// <summary>A machine's OUTPUT staging buffer (server-only, NO [GhostField]). See <see cref="MachineInput"/>.</summary>
+    public struct MachineOutput : IBufferElementData
+    {
+        public byte ResourceId;
+        public int Count;
+    }
+
+    /// <summary>
+    /// The single in-flight item a conveyor carries. An ENABLEABLE component (enabled = the belt is occupied) so a
+    /// transport step is a bit-flip + field copy, never a structural change. Baked DISABLED (an empty belt).
+    /// Server-only.
+    /// </summary>
+    public struct ConveyorItem : IComponentData, IEnableableComponent
+    {
+        public byte ResourceId;
+        public int Count;
+    }
+
+    /// <summary>
+    /// Marks a structure PLACED by a player at runtime (BuildPlaceSystem) or restored from a save — i.e. the
+    /// persistable set, as opposed to anything baked into the subscene. SaveWriteSystem scans only these and
+    /// BaseRestoreSystem re-adds the tag, so save/restore is the single source of truth for player builds.
+    /// Server-only (not replicated).
+    /// </summary>
+    public struct RuntimePlacedTag : IComponentData { }
+}
@@ -0,0 +1,2 @@
+fileFormatVersion: 2
+guid: 6eeef378186b39d41a2db7adcc620dd9
@@ -0,0 +1,97 @@
+using Unity.Collections;
+using Unity.Mathematics;
+
+namespace ProjectM.Simulation
+{
+    /// <summary>
+    /// Pure, deterministic, ORDER-INDEPENDENT conveyor move resolver (the server <c>ConveyorTransportSystem</c>
+    /// applies the result). Determinism: sources are processed sorted by <see cref="CellKey"/> (NEVER hashmap
+    /// order); a destination belt cell accepts AT MOST ONE item and only if it was EMPTY in the pre-move snapshot
+    /// (double-buffering -> exactly one cell/tick); ties break to the lowest-CellKey source and losers STALL with no
+    /// loss; machine-input SINK cells always accept (a merge). World-free so it is exhaustively unit-tested.
+    /// </summary>
+    public static class ConveyorMath
+    {
+        /// <summary>Cardinal grid step for a belt direction byte (0=+X,1=-X,2=+Z,3=-Z).</summary>
+        public static int2 DirOffset(byte dir)
+        {
+            switch (dir)
+            {
+                case 1: return new int2(-1, 0);
+                case 2: return new int2(0, 1);
+                case 3: return new int2(0, -1);
+                default: return new int2(1, 0); // 0 = +X
+            }
+        }
+
+        /// <summary>A stable, collision-free total order over grid cells (the deterministic tie-break key).</summary>
+        public static long CellKey(int2 cell) => ((long)cell.x << 32) | (uint)cell.y;
+
+        /// <summary>
+        /// Resolve, for each belt holding an item, whether it advances one cell toward its direction this tick.
+        /// Inputs are read-only snapshots; outputs are the accepted moves (<paramref name="outMoveSrcIdx"/> ->
+        /// <paramref name="outMoveDst"/>), length <paramref name="moveCount"/>. A move is accepted when the
+        /// destination is a SINK cell (always, a merge) or an EMPTY, unclaimed belt cell. Sources are iterated in
+        /// CellKey order so the result is identical regardless of input array order. Scratch is Temp + disposed.
+        /// </summary>
+        public static void ResolveMoves(
+            NativeArray<int2> srcCells, NativeArray<byte> dirs,
+            NativeArray<int> itemRes, NativeArray<int> itemCnt,
+            NativeHashMap<int2, int> cellToIndex, NativeHashSet<int2> sinkCells,
+            NativeArray<int2> outMoveDst, NativeArray<int> outMoveSrcIdx, out int moveCount)
+        {
+            int n = srcCells.Length;
+            moveCount = 0;
+
+            // Stable iteration order = sources sorted by CellKey (insertion sort; n is small).
+            var order = new NativeArray<int>(n, Allocator.Temp);
+            for (int i = 0; i < n; i++) order[i] = i;
+            for (int i = 1; i < n; i++)
+            {
+                int cur = order[i];
+                long curKey = CellKey(srcCells[cur]);
+                int j = i - 1;
+                while (j >= 0 && CellKey(srcCells[order[j]]) > curKey)
+                {
+                    order[j + 1] = order[j];
+                    j--;
+                }
+                order[j + 1] = cur;
+            }
+
+            var claimed = new NativeHashSet<int2>(n, Allocator.Temp);
+            for (int oi = 0; oi < n; oi++)
+            {
+                int i = order[oi];
+                if (itemCnt[i] <= 0) continue; // nothing to move
+
+                int2 dst = srcCells[i] + DirOffset(dirs[i]);
+
+                bool accept = false;
+                bool isSink = sinkCells.Contains(dst);
+                if (isSink)
+                {
+                    accept = true; // sinks merge -> unlimited acceptors, never claimed
+                }
+                else if (cellToIndex.TryGetValue(dst, out int dstIdx))
+                {
+                    // dst is a belt cell: accept only if EMPTY in the snapshot AND not already claimed this tick.
+                    if (itemCnt[dstIdx] == 0 && !claimed.Contains(dst))
+                        accept = true;
+                }
+                // else: dst is neither a belt nor a sink -> dead end -> stall.
+
+                if (accept)
+                {
+                    if (!isSink) claimed.Add(dst);
+                    outMoveDst[moveCount] = dst;
+                    outMoveSrcIdx[moveCount] = i;
+                    moveCount++;
+                }
+            }
+
+            order.Dispose();
+            claimed.Dispose();
+        }
+    }
+}
@@ -0,0 +1,2 @@
+fileFormatVersion: 2
+guid: 251361cf456e888459d473b5fedf7c4a
@@ -0,0 +1,85 @@
+using Unity.Entities;
+
+namespace ProjectM.Simulation
+{
+    /// <summary>
+    /// Pure, deterministic deposit/withdraw/total helpers for a machine's server-only <see cref="MachineInput"/> /
+    /// <see cref="MachineOutput"/> staging buffers — the byte-id, non-replicated twin of <see cref="StorageMath"/>
+    /// (which serves the [GhostField] global <see cref="StorageEntry"/> ledger). No RNG/wall-clock. DynamicBuffer is
+    /// a handle, so mutations apply to the underlying entity buffer. Overloaded per buffer type because the two
+    /// element types are deliberately distinct (a machine can carry both without a singleton-buffer clash). Deposit
+    /// is a no-op for count &lt;= 0 or resource id 0; Withdraw clamps to available and drops a row at zero.
+    /// </summary>
+    public static class MachineSlotMath
+    {
+        // ---- MachineOutput ----
+        public static void Deposit(DynamicBuffer<MachineOutput> buffer, byte resourceId, int count)
+        {
+            if (count <= 0 || resourceId == 0) return;
+            for (int i = 0; i < buffer.Length; i++)
+                if (buffer[i].ResourceId == resourceId)
+                {
+                    var e = buffer[i]; e.Count += count; buffer[i] = e; return;
+                }
+            buffer.Add(new MachineOutput { ResourceId = resourceId, Count = count });
+        }
+
+        public static int Withdraw(DynamicBuffer<MachineOutput> buffer, byte resourceId, int count)
+        {
+            if (count <= 0 || resourceId == 0) return 0;
+            for (int i = 0; i < buffer.Length; i++)
+                if (buffer[i].ResourceId == resourceId)
+                {
+                    var e = buffer[i];
+                    int taken = e.Count < count ? e.Count : count;
+                    e.Count -= taken;
+                    if (e.Count <= 0) buffer.RemoveAt(i); else buffer[i] = e;
+                    return taken;
+                }
+            return 0;
+        }
+
+        public static int TotalOf(DynamicBuffer<MachineOutput> buffer, byte resourceId)
+        {
+            int total = 0;
+            for (int i = 0; i < buffer.Length; i++)
+                if (buffer[i].ResourceId == resourceId) total += buffer[i].Count;
+            return total;
+        }
+
+        // ---- MachineInput ----
+        public static void Deposit(DynamicBuffer<MachineInput> buffer, byte resourceId, int count)
+        {
+            if (count <= 0 || resourceId == 0) return;
+            for (int i = 0; i < buffer.Length; i++)
+                if (buffer[i].ResourceId == resourceId)
+                {
+                    var e = buffer[i]; e.Count += count; buffer[i] = e; return;
+                }
+            buffer.Add(new MachineInput { ResourceId = resourceId, Count = count });
+        }
+
+        public static int Withdraw(DynamicBuffer<MachineInput> buffer, byte resourceId, int count)
+        {
+            if (count <= 0 || resourceId == 0) return 0;
+            for (int i = 0; i < buffer.Length; i++)
+                if (buffer[i].ResourceId == resourceId)
+                {
+                    var e = buffer[i];
+                    int taken = e.Count < count ? e.Count : count;
+                    e.Count -= taken;
+                    if (e.Count <= 0) buffer.RemoveAt(i); else buffer[i] = e;
+                    return taken;
+                }
+            return 0;
+        }
+
+        public static int TotalOf(DynamicBuffer<MachineInput> buffer, byte resourceId)
+        {
+            int total = 0;
+            for (int i = 0; i < buffer.Length; i++)
+                if (buffer[i].ResourceId == resourceId) total += buffer[i].Count;
+            return total;
+        }
+    }
+}
@@ -0,0 +1,2 @@
+fileFormatVersion: 2
+guid: 16b6aef96031f54469f05044a2c18e66
@@ -0,0 +1,51 @@
+using Unity.Mathematics;
+using Unity.NetCode;
+
+namespace ProjectM.Simulation
+{
+    /// <summary>
+    /// Pure, deterministic catch-up + cooldown math shared by the M7 production systems (Harvester/Conveyor/
+    /// Fabricator). No RNG/wall-clock -> server-authoritative. The single GATED catch-up path: a never-processed
+    /// machine (<see cref="NeedsInit"/>) initializes first; a cooling machine yields 0; a due machine yields
+    /// floor(elapsed/period) clamped to [0, maxCatchup]; period is guarded by max(1,...). Cooldown is persisted as
+    /// REMAINING ticks (epoch-independent) so a save survives the server-tick origin reset on a fresh session.
+    /// </summary>
+    public static class ProductionMath
+    {
+        /// <summary>True for a never-processed machine (baked/just-placed) — initialize the baseline before producing.</summary>
+        public static bool NeedsInit(uint lastProcessedTick) => lastProcessedTick == 0u;
+
+        /// <summary>
+        /// Cycles to award THIS process. 0 if cooling (<paramref name="nextTick"/> newer than <paramref name="now"/>)
+        /// or nothing elapsed; otherwise floor(elapsed/period) clamped to [0, <paramref name="maxCatchup"/>].
+        /// <paramref name="nextTick"/>==0 is the inactive sentinel (never read as a future cooling tick). The lower
+        /// bound is 0 (not 1): when genuinely due the NextTick gate guarantees elapsed&gt;=period, so a sub-period
+        /// edge (e.g. a freshly restored remaining==0 machine) floors to 0 rather than minting prematurely.
+        /// <paramref name="period"/> is guarded by max(1,...) so a 0 never divides.
+        /// </summary>
+        public static int CyclesDue(NetworkTick now, uint nextTick, uint lastProcessedTick, int period, int maxCatchup)
+        {
+            int p = math.max(1, period);
+
+            if (nextTick != 0u)
+            {
+                var next = new NetworkTick(nextTick);
+                if (next.IsValid && next.IsNewerThan(now))
+                    return 0; // still cooling down
+            }
+
+            int since = now.TicksSince(new NetworkTick(TickUtil.NonZero(lastProcessedTick)));
+            if (since <= 0)
+                return 0;
+
+            return math.clamp(since / p, 0, maxCatchup);
+        }
+
+        /// <summary>Remaining cooldown ticks to PERSIST (epoch-independent): 0 if inactive or already due, else nextTick-now.</summary>
+        public static uint RemainingTicks(uint nextTick, uint nowTick) =>
+            nextTick == 0u ? 0u : (nextTick > nowTick ? nextTick - nowTick : 0u);
+
+        /// <summary>Re-anchor a persisted remaining cooldown to the current tick origin on restore (NonZero-guarded).</summary>
+        public static uint RestoreNextTick(uint nowTick, uint remaining) => TickUtil.NonZero(nowTick + remaining);
+    }
+}
@@ -0,0 +1,2 @@
+fileFormatVersion: 2
+guid: 6d461ab50604ea642b26586bffeed41e
@@ -14,5 +14,6 @@ namespace ProjectM.Simulation
        public byte StructureType;
        public int CellX;
        public int CellZ;
+        public byte Direction;
    }
 }
@@ -50,5 +50,11 @@ namespace ProjectM.Simulation

        /// <summary>Wind-up ticks before a Husk strike lands (~0.3s @ 60 ticks/sec). 0/1 = near-instant (legacy behaviour).</summary>
        public const int AttackWindupTicks = 18;
+
+        // ---- Production / automation (M7: Harvester/Conveyor/Fabricator) ----
+
+        /// <summary>Max production cycles a single machine awards in one process (bounds within-session
+        /// catch-up after any skipped ticks; restore re-seats the baseline so this never reflects wall-clock).</summary>
+        public const int MaxProductionCatchup = 600;
    }
 }