Factory: Mass Architecture

🗺 Overview

The current FactoryFloor/ module is actor-based: AMachineBase subclasses each run their own tick/state-machine, coordinated by AFactoryFloorManager and a suite of subsystem managers. At target scale this doesn't hold up.

The new module (FactoryFloor2/) moves everything into Mass. Machines and Operations are entities; actors become a thin visual/input layer. Parts stay as handles behind a central registry. The scheduler runs as an ordered chain of server-side processors.

What stays the same

LogisticsBots are already on Mass (Source/Dropforge/Mass/Logistics/ + Mass/Navigation/) and replicate via the HorizonReplication plugin. The new module reuses those exact patterns. Logistics-bot code itself is not rewritten.

📁 Module Layout

The new module lives entirely under Source/Dropforge/FactoryFloor2/.

Source/Dropforge/FactoryFloor2/
  Actors/
    MachineActor.h/.cpp                 // thin AActor: mesh, click, footprint, FMassEntityHandle back-ref
    MachineActorRepresentation.h/.cpp   // arm-pose interpolation; ISM/anim driven by fragment reads
  Mass/
    Fragments/
      MachineFragments.h                // identity, slots, progress, modifiers, actor ref, rep state
      OperationFragments.h              // operation data, DAG links, progress, MWKR cache
      PartHandleFragment.h              // FPartHandle (uint32) + small inline arrays
    Tags/
      MachineTags.h                     // FActiveMachineTag, FMachineWorkingTag, FHorizonRepDirtyTag
      OperationTags.h                   // one tag per Operation state (Queued, InProgress, ...)
    Traits/
      MachineServerTrait.h/.cpp
      MachineClientTrait.h/.cpp
      OperationServerTrait.h/.cpp       // ops are server-only; not replicated
    Processors/Server/
      OperationReadinessProcessor       // WaitingForParts → Queued when inputs land
      MWKRRecomputeProcessor            // memoised DAG walk; runs only on op-graph changes
      MachineDispatchProcessor          // the JIT-pull scheduler loop
      MachineWorkProgressProcessor      // parallel: accumulate progress on InProgress slots
      OperationCompletionProcessor      // InProgress → SenderAwaitingExport; register output handles
      LogisticsHandoffProcessor         // SenderAwaitingExport ↔ ReceiverAwaitingDelivery; floor-part retry
      MachineLifecycleProcessor         // on machine entity removal: reset ops, drop parts to floor
    Processors/Client/
      MachineRepresentationProcessor    // drive ISM/animation from replicated fragment state
    Registry/
      PartRegistry.h/.cpp               // UPartRegistrySubsystem (see Part Safety section)
    Spawner/
      MachineSpawner.h/.cpp             // replaces FactoryFloorManager placement entity path
  Management/
    FactoryFloorSubsystem.h/.cpp        // grid/placement only — no work dispatch
    BotOrderSubsystem.h/.cpp            // ingest player Bot Orders, build Operation DAGs
  Replication/
    MachineEntityProxy.h/.cpp           // extends UHorizonEntityProxy
  DataTypes/
    OperationData.h                     // FOperationState enum, FRecipeStep, FProcessSpeed
    MachineData.h                       // ported UMachineData (verbs, slots, layout, ISM)

⚙️ Machine Entity

One Mass entity per machine. All fragments are server-side unless noted. The actor is a thin back-reference — no game logic lives there.

Fragments

Tags

FActiveMachineTag — machine is powered and eligible for dispatch.
FMachineWorkingTag — presence-only; drives the work-progress query.
FHorizonRepDirtyTag — existing pattern; marks the proxy for replication.

🔗 Operation Entity

One Mass entity per operation step. Server-only — operations do not replicate; clients infer work state from machine fragments.

Fragments

State Tags

Exactly one tag per operation at all times — mutually exclusive. Tag transitions are the primary mechanism processors use to filter their work.

🔐 Part Safety

Parts are handles, not entities. UPartRegistrySubsystem (a UWorldSubsystem) is the sole source of truth for every part in the factory. This gives the performance of handles — no Mass-entity overhead at 10k+ parts — with stronger lifetime guarantees than the current implicit-ownership TArray soup.

Record structure

struct FPartRecord {
  EPartType         Type;
  EPartOwner        OwnerKind;          // Slot | Bin | BotCargo | Floor
  uint64            OwnerKey;           // packed: (entity handle | bin id | bot entity); unused when Floor
  uint32            Generation;         // increments on every owner change

  // valid only when OwnerKind == Floor:
  FVector           FloorPosition;
  FMassEntityHandle PendingDestination; // receiving op handle; null = orphaned → needs re-dispatch
};
TSparseArray<FPartRecord> Records;

FPartHandle = {uint32 Index, uint32 Generation}. Every read goes through Resolve(FPartHandle) → FPartRecord*. A mismatched generation is a stale handle — hard assert in Dev, log-and-drop in Shipping.

Safety invariants

1. 1Every live FPartHandle resolves to exactly one record.
2. 2Every record's OwnerKey is reachable from that owner (round-trip check).
3. 3PartRegistryAuditProcessor runs every N ticks in Dev/Test builds: walks all machine slots, bins, and bot cargo fragments; rebuilds the owner→part map; asserts it matches the registry. Orphans are logged loudly.
4. 4Ownership transfers go through a single TransferOwnership(Handle, NewOwner) call that bumps generation — no field-poking.

Floor recovery API

📐 Scheduler Processor Chain

The scheduler is an ordered chain of server-side processors. Order is fixed. All run single-threaded except MachineWorkProgressProcessor.

♻️ Destruction & Recovery

Machine destroyed

MachineLifecycleProcessor implements a pre-removal hook and runs synchronously before the entity is removed:

1. 1Read world position from FMachineActorFragment::Actor->GetActorLocation() before teardown — the actor may already be marked pending-kill.
2. 2For each occupied slot: call PartRegistry.DropToFloor(handle, worldPos) for any slot-owned parts. Reset InProgress/Queued ops to WaitingForMachine (clear assignment, reset Progress, mark MWKR dirty). Leave SenderAwaitingExport ops as-is — the part is now on the floor; LogisticsHandoffProcessor re-dispatches pickup on the next tick.
3. 3Set FHorizonRepDirtyTag for a final replication push before entity removal so clients see slots clear.

Bot destroyed mid-transit

ULogisticsSimulationSubsystem fires OnBotDestroyed(FMassEntityHandle, FVector LastPosition). LogisticsHandoffProcessor subscribes and for each part the bot was carrying:

1. 1Call PartRegistry.DropToFloor(handle, lastPosition).
2. 2Leave the receiving op in FOpReceiverAwaitingDeliveryTag — it is still waiting for the same part, just needs a new carrier.
3. 3On the next tick, GetOrphanedFloorParts() surfaces the handle; LogisticsHandoffProcessor re-emits a pickup bot order (floor position → original destination slot) and calls AssignFloorPartToBotOrder.
4. 4Cancel the old in-flight order record.

No op tag change is needed — FOpReceiverAwaitingDeliveryTag already means "waiting for this part to arrive"; the new bot order satisfies it identically.

🎨 Actor Representation Layer

AMachineActor is a thin AActor created once per machine. It owns: scene root, mesh, ISM handles, click collision, and a FMassEntityHandle MyEntity back-ref set during spawn.

📡 Replication

Reuses the existing Plugins/Horizon/ patterns from the logistics bot implementation.

🚀 Cutover Plan

Eight steps from skeleton to full cutover. Both modules compile in parallel throughout. No incremental migration — the old module is deleted in a single PR at step 8.

1. 1Stand up FactoryFloor2/ module skeleton — traits and empty processors. Builds alongside FactoryFloor/.
2. 2Implement UPartRegistrySubsystem + audit processor with unit-like dev tests.
3. 3Implement Operation entity + full scheduler chain. Validate with a synthetic harness (no actors) — determinism gate and audit processor at every tick.
4. 4Implement Machine entity + AMachineActor + representation processor. Port one machine type end-to-end — recommend Fabricator (cleanest single-slot work loop).
5. 5Port remaining machine types (RobotArm variants, ItemBin, ItemSpawner, Monorail). Flag: Monorail conveyors may need a dedicated movement processor — treat as a sub-design when reached.
6. 6Bridge ULogisticsSimulationSubsystem callbacks to the new LogisticsHandoffProcessor.
7. 7Migrate placement/grid responsibilities from AFactoryFloorManager into UFactoryFloorSubsystem. Drop the work-dispatch managers entirely.
8. 8Replace all spawn sites producing old AMachineBase with UMachineSpawner. Delete FactoryFloor/ in the same PR.

📎 Critical Reference Files

These existing files are read-only references — pattern sources, not files to modify during FactoryFloor2 development.

✅ Verification