Factory Logistics in Mass: Architecture Plan

📦 1. Entities

Anything a player places or sees on the floor is a Mass entity. Each pipe network and each rail network is also an entity. The game works these out from what has been built.

1.1 Type assets and traits

A type asset holds no config. Its class only names the type, so that code can find the type by class. Everything a designer sets is a field on a trait. The trait turns its fields into a const shared fragment, or into the starting value of a fragment in the template, on every net mode that reads it. UMachineData breaks this rule today (section 8).

Each trait covers one behaviour, and every type with that behaviour has the same trait. So a fragment that several types have is added by one trait, never by a trait for each type. When two traits on one type add the same fragment, Mass keeps one copy and says nothing, unless mass.template.DuplicateElementsAsWarnings is turned on. A trait that reads another trait's fragments declares them with RequireFragment. When a type lacks one, Mass logs an error that names the trait and the fragment. It still makes the template.

Nothing in this design is a role. People call a machine a dock, a storage, a delivery line or an airlock. No trait, tag, field or enum says which of those a machine is, and no code asks. A machine is what its traits add and what its recipes say (4.3 and 4.4).

The two networks show the pattern. Each has its own type asset, because the topology processor spawns each by class. Both have UCarrierNetworkTrait for what every network has. Each then has one more trait for what only it does.

A parent config holds the traits that several types share. DA_MachineBase does this today for every UMachineData type. Two more parents hold the traits of a machine that holds components. DA_HoldingMachineBase has UFloorIndexTrait and UMachineBufferTrait. DA_RunningMachineBase is its child, and adds UMachineRecipeExecutionTrait. Mass builds a parent's traits before the type's own. So a trait on a parent cannot read anything the type's own traits hold. It can only add fragments that start empty. A trait that needs the type's own data is on the machine asset. Such a trait can test whether a parent's trait has already added a fragment.

Of these traits, only the ones below hold config. Every other trait adds state and tags, and has no fields.

🔢 2. Not entities

A component is never an entity. Inside a machine it is a count. Anywhere else it is an FComponentStack (kind, quantity, temperature), stored in a fragment on the entity that is carrying it. A run is a whole belt from its start to its end, as in the simulator. An entity is one section of a run.

⏱ 3. What runs each frame

3.1 The server chain

These processors run on the server every frame. The table lists them in the simulator's order. That is not the order they run in. Each processor declares the processors it has to follow, and Mass schedules them. Worker means the processor may run off the game thread. Demand order ranks competing machines by priority, then longest waiting, then oldest.

Almost every processor runs on a worker. A processor is on the game thread only where it calls something that is safe nowhere else. The chain has two such things. One is marking a proxy dirty for Iris. The rep sync processors for pipes, piles and the floor do that, and so does UFactoryProxySendProcessor. The other is reading the navigation grid, which ULogisticsBotRailPriorityProcessor and ULogisticsBotDispatchProcessor do. The grid is a component of the floor manager, so Mass cannot schedule around it. ULogisticsBotPathRefillProcessor also talks to the navigation grid and stays on the game thread. It is not part of this chain.

A processor is kept safe by what it declares, not by its thread or by its place in a list.

• A processor that reads or writes another entity's fragments declares them with AddIndirectFragmentRequirement. Every processor that follows a link does this. An indirect requirement reaches a regular fragment only, never a tag or a shared fragment. A processor sometimes needs a fact about the machine at the other end of a link. The topology processor copies that fact into a regular fragment on that machine (4.4).
• A processor that reads the occupancy grid declares UFactoryFloorSubsystem as a subsystem requirement (5.2). ULogisticsTopologyProcessor and UFloorPileProcessor read it.
• A processor declares each processor it has to follow with ExecuteAfter. The second table below lists them.
• A processor turns off query-based pruning. Mass otherwise leaves out a processor whose queries match nothing, and a dependency that passes through a processor that was left out is lost.
• A processor defers its commands through its execution context.

A dirty tag is added deferred, so the topology processor runs on the frame after the change. For that one frame the chain uses the new settings with the old shares and links.

Eight existing processors are named in section 4 and are not part of this chain.

• UTiledMachineSplitProcessor cuts and joins sections (4.6), on the game thread.
• UMachineFootprintRegistrationProcessor adds a machine's cells to the occupancy grid.
• UMachineUtilizationProcessor and UArmWorkProcessor write utilisation.
• ULogisticsBotStateProcessor moves a bot through its job.
• ULogisticsBotPathRefillProcessor gives a bot the next part of its path.
• ULogisticsBotRepSyncProcessor sends a bot's cargo.
• UMachineRepSyncProcessor sends FMachineRepStateFragment.

What each processor follows. Mass keeps two processors apart while they touch the same fragment, but it does not choose which goes first. Where the order changes the result, the later processor declares the earlier one. Where it does not, nothing is declared. Mass may then run the two in either order, or at the same time when they share nothing.

Most of these dependencies come from one rule of the simulator. Direct connections, rails, belts and bots compete for the same components and the same room, and they take them in that order.

Processors with no dependency between them are free of each other. UFloorSupplyProcessor and UMachineRecipeExecutionProcessor change different things. A machine that the floor's supply fills has no demand and runs no recipe. UPipeFlowProcessor moves fluid, and the rail, belt and bot processors move solids. UFloorPileProcessor does not touch a machine. The rep sync processors copy different entities.

3.2 Observers

An observer runs when Mass applies the removal, not at a fixed point in the chain. The existing server observers run on the game thread today. The new pile observer runs there too.

A section's tiles are in the occupancy grid at their own levels (5.2), so they need no new observer. On the server, UMachineFootprintRegistrationProcessor adds a section's tiles and UMachineLifecycleProcessor removes them. On a client, UClientMachineFootprintProcessor adds them and UClientMachineFootprintDeregistrar removes them. These four classes already maintain the occupancy grid in the same way.

A removal puts nothing on the ground when a whole floor is cleared. Clearing a floor destroys what the floor holds. When a section is cut or joined, the split processor has already moved the stacks on the tiles that stay to the new sections (4.6). So the observer puts down only a stack over a tile that the cut removed.

3.3 The client side

These processors run on clients and in standalone, and a listen host runs them too. They are in the mesh-instance writer group (DFMeshInstances::WriterGroup). They read only replicated state, never the server's stacks, and that includes on the host. Each new one follows the rule below for its thread.

Today's code follows one rule for these threads. A writer that only touches its own entity's fragments is not pinned to the game thread. UTiledMachineVisualizationProcessor and UMachineStatusVizProcessor are examples. A writer that loads meshes or submits effects is pinned. UMeshInstanceApplyProcessor is pinned and runs after the group.

A component has no mesh yet. Until it has one, a stack, a pile and a bot's cargo each draw one placeholder mesh for it.

🧩 4. Traits and fragments, by theme

The tables name the processors of section 3. Server means != NM_Client, everywhere means every net mode, and rendering means != NM_DedicatedServer. FKindId and FRecipeId are each a uint16. The factory database import writes a kind's id on the kind's asset, and the id never changes. The catalogue gives each recipe an id at start-up (5.2). Two kind ids are reserved. One means no kind. The other is the wildcard (4.3). The import never gives either to a component. The Trait column names the trait that adds the fragment or tag. One existing fragment has two (4.3). In these tables the machine rep sync processor is UMachineProductionRepSyncProcessor. Section 1.1 lists the traits and the types that have each.

4.1 Caps

Three fragments hold arrays that grow, and have no cap. They are the two network fragments (4.5 and 4.8) and the bot's path fragment (4.10).

The factory database is well inside these today. Its largest machine type has 7 recipes, 16 buffer rows, 12 kinds and 12 ports, of which 2 are bot ports. No recipe has more than 3 kinds on a side.

4.2 Every machine that holds components

A machine that holds components has UFloorIndexTrait, UMachineBufferTrait and UMachineRecipeAssignmentTrait (4.3). Sections and splitters have UFloorIndexTrait too.

A machine with ports also has UMachinePortsTrait. The factory database import writes its ports. The splitter is the exception. The database gives it no ports, so they are set in the engine. Each port has a type from the factory config, which is belt, pipe or bot. A kind's form is solid or fluid. A belt port carries solids and a pipe port carries fluid. A component that the database calls loose counts as a solid. A belt or pipe port is an input or an output, and it is on one edge of one cell. A splitter's four ports are neither. The topology processor decides each one from the belt that joins it (4.7). A bot port marks a cell where bots deliver and collect.

The trait builds two shared fragments from that one list. FMachinePortsSharedFragment holds the ports that belts, rails, pipes and other machines connect to. FMachineBotPortsSharedFragment holds the bot cells.

The port a kind uses. The database gives a port for some kinds. The import writes those ports into two maps on the ports trait. One map is for what a machine takes and one is for what it makes. A kind can be in both, because a machine can take a kind and also make it. For a kind in neither map, the port is worked out by the rule the database's own tool uses. The kind takes the first port that carries its form and has the right direction. It passes over a port that another kind in one of its recipes already has. UMachineRecipeAssignmentTrait works this out when the type's template is built, and keeps the answer in FMachineRecipeSetSharedFragment (4.3). It reads the ports trait on its own asset to do so, which a trait may do while a template is built. A machine with a stock gives no kind a port. Each of its ports takes anything of its form (4.4).

When a recipe is turned on or off, the machine's shares are worked out again from scratch. On a machine with no stock, the room on each side is Headroom runs of every recipe the type can run (4.11). The topology processor shares that room among the recipes that are turned on, in proportion to what one run of each takes or makes. Whole components left over go one each to the largest fractions, and to the earlier recipe on a tie. A row of a recipe that is turned off has no share. This is the simulator's rule.

4.3 Recipes and runs

Every machine in 4.2 has UMachineRecipeAssignmentTrait. It gives the machine its recipes. A recipe says what the machine takes and what it makes. The trait is today's UMachineProcessTrait, and it is on the machine asset.

A machine with UMachineRecipeExecutionTrait also runs its recipes. Every machine that makes or consumes components has it. UMachineRecipeExecutionTrait declares FMachineRecipeAssignmentFragment with RequireFragment.

What a type can run. The trait lists the processes the machine type can run, each with a speed. The factory database import writes that list. A machine can run every recipe of those processes. That is the one rule, and it is the same for every machine.

What a machine starts with. The catalogue is UFactoryCatalogueSubsystem (5.2). When the type's template is built, the trait asks the catalogue for every recipe of the type's processes. It writes them into FMachineRecipeAssignmentFragment in the template. So every machine of the type is spawned with its recipes, all turned on, in the catalogue's order. Nothing adds a recipe to a machine after that.

The trait adds that fragment and its replicated copy only for a type that has FMachineBufferFragment. A parent config's trait adds the buffer fragment, and Mass builds a parent's traits first (1.1). On any other type the trait adds FMachineRecipeSetSharedFragment and nothing else.

How long a run takes. A run takes the recipe's time, divided by the process's base speed and by the speed the type gives that process. The type's speed comes from the factory database. The base speed is set on DA_FactoryConfig in the engine, and the import keeps it. A recipe with no time takes 1 second.

The wildcard. The database has one kind that is not a component. It is written *, and it stands for any kind. Three recipes use it, and each is the only recipe of its process.

A type gets these recipes as it gets any other, by listing the process. The catalogue keeps each as one recipe. There is no recipe for each kind. A type lists only these three processes, or it lists none of them. Validation reports a type that lists one of them beside any other process. Section 4.4 says what a machine with these recipes holds.

Recipes that never run. The recipe execution processor never runs a recipe that takes nothing, so nothing is made from nothing. It never runs a recipe that makes exactly what it takes, because a run would change nothing. Of the three recipes above, only r-store can run.

What a machine is assigned. FMachineRecipeAssignmentFragment holds up to 16 recipes. A recipe keeps its index in Recipes for as long as the machine exists, because other state refers to the recipe by that index. The running recipe is stored as an index, and a recipe's buffer rows start at the RowStart of its index. The player turns recipes on and off and puts them in order. The order is stored apart, in Order, so changing it moves nothing.

A recipe's rows. A recipe that does not use the wildcard has one buffer row for each kind it takes and one for each kind it makes. They are together in FMachineBufferFragment, with the kinds it takes first. A processor finds a kind's rows the same way on every machine that has no stock. It goes through the machine's assigned recipes, reads each recipe's kinds from the catalogue and counts on from RowStart. A recipe that uses the wildcard has no rows of its own (4.4).

Where an arrival goes. On a machine with no stock, a kind's room is the room left in its input rows of the recipes that are turned on, less what is coming. A component that arrives goes into the row of the first such recipe, in the machine's order, that has room. Fluid fills those rows in the same order.

4.4 Machines that hold a stock

A machine whose recipes use the wildcard holds a stock. A stock is a store of components of any kind. Every recipe on the machine that uses the wildcard acts on that one stock.

• A recipe that takes the wildcard lets the stock take components in. r-store and r-pass do.
• A recipe that makes the wildcard lets the stock give components out. r-supply and r-pass do.
• A run of r-store takes one component out of the stock and makes nothing, so the component is consumed. The run takes the oldest solid. With no solid, it takes one unit of the fluid the stock holds most of. Only a machine with UMachineRecipeExecutionTrait runs anything.

A stock takes while a recipe that takes the wildcard is turned on. It gives while a recipe that makes the wildcard is turned on. So a debug sink with r-store turned off takes nothing. The storage stops taking only when r-store and r-pass are both off. It stops giving only when r-supply and r-pass are both off.

Six machine types in the factory database have a stock today.

None of these is a role (1.1). Each difference between these machines is one of three things. It is a recipe that the type lists, a trait that the type has, or a value on a trait.

The setting that limits a stock. A player can limit a stock to a list of kinds. This section calls that list the stock's setting. FMachineKindFilterFragment holds it. It names up to 16 kinds, in the player's order. Server_SetMachineKinds sets it (section 6). A stock with no setting accepts any kind. A stock whose setting names no kinds takes nothing. The setting limits what comes in. It never stops a stock giving what it holds. A player can take a kind out of the setting while the stock holds some. Those components stay in the stock, and the stock still gives them.

Which forms a stock holds. A stock holds solids only where the type has a belt port, and fluid only where it has a pipe port. So the storage holds no fluid, and no check names the storage. The settings processor leaves out of a setting any kind whose form the stock does not hold. Validation reports a type that has a pipe port and no UMachineFluidTrait.

Where a stock is kept. A stock uses the fragments every machine in 4.2 has. On a machine with a stock, a buffer row is a kind. FMachineStockFragment::Kind says which kind each of the first 24 rows is for. Held is how many solid components of that kind the stock holds. FMachineFluidFragment::Amount is how much the stock holds of a fluid kind. FMachineLedgerFragment has three entries for the same row. InboundEnroute is how many are coming. OutboundReserved is how many are reserved for a bot. DemandSince is when demand began. The ledger's queue lists every solid component in the stock, oldest first.

Who gives a kind its row. A processor that brings a kind to a stock, or reserves room for it, gives the kind a row the first time. The topology processor gives a row to each kind the setting names. On a machine that the floor's supply fills, it also gives a row to each kind in the stock's list (see below). It also gives a row to the fluid of a pipe network on an input port (see Demand). Nothing clears a row when it empties. A processor that needs a row for a new kind takes the first free row and writes the new kind over the old one. It also clears that row's DemandSince. A row is free when five things are true.

• The row holds nothing.
• No component of its kind is coming or reserved.
• The setting does not name its kind.
• Its kind is not in the list of a stock that the floor's supply fills.
• Its kind is not the fluid of a pipe network on one of the machine's input ports.

A kind with no row, and no free row to take, has no room. When the setting names that kind, or the floor supplies it, the kind has no room and no share until the topology is next rebuilt.

How much a stock holds. A stock's room is the floor rule Space (4.11), which is 12 today. A type with UMachineStockCapacityTrait has a room of its own. The storage has that trait, and its room is the database key value capacity, which is 30. The topology processor writes the room into FMachineStockFragment::Room.

How kinds share the room. There are three cases. A stock's case comes from the recipes its type lists. Turning a recipe off does not change it.

• A stock whose type can take and can give is one pool. A kind's room is the whole room, less everything the stock holds and everything that is coming. The storage is such a stock.
• A stock with a list of kinds gives each kind a share. A stock that the floor's supply fills has a list. With a setting, the list is the kinds the setting names. With no setting, it is the kinds the floor supplies that the stock can hold, in the order of FFactoryFloorSupplyFragment::Kind. A stock that can only take, and has a setting, also has a list. It is the kinds the setting names. Each kind in a list has an equal share of the room. Any remainder goes one each to the earliest kinds. When the list has more kinds than the room, the later kinds have no share. A kind's room is its own share, less what the stock holds of it and what is coming. So a kind that no machine collects from the stock cannot fill another kind's share. The topology processor writes each share into Share.
• A stock that can only take, and has no setting, has one total for solids and one for fluid. A solid's room is the whole room, less the solids the stock holds and the solids that are coming. A fluid's room is the whole room, less all the fluid the stock holds. So fluid from a pipe cannot keep solids out.

Only a stock with a list of kinds uses Share. On the other two, no processor reads it.

A stock can hold more than its room for a time. That happens when it still holds a kind that has left its list. The queue is the hard limit. When the queue is full, no solid has room.

A processor works out a kind's room again before each reservation, because kinds can share a stock's room.

What brings a kind to a stock. A stock that does not take has no room for anything in this table, whatever its setting names. Its shares are only for the floor's supply.

A component that was reserved before a setting or a recipe changed still arrives, and goes into its kind's row. A component that was reserved for a bot is still collected.

Demand. A stock that takes has demand for the kinds its setting names. With no setting it has none, because it would otherwise demand every kind on the floor. There is one more case. A stock that takes fluid and has no setting has demand for the fluid of a pipe network on one of its input ports. The topology processor keeps a row for that fluid. A stock that does not take has no demand.

The floor's supply. UFloorSupplyProcessor fills a machine that has FFloorSuppliedTag, while its stock gives. UMachineRecipeAssignmentTrait adds that tag when the type's template is built. The trait adds the tag to a type whose stock can give and can never take, because nothing else can fill such a stock. No designer sets the tag. With a setting, the floor's supply adds the named kinds only. With no setting, it adds every kind the floor supplies that the stock can hold.

Which machine may give to which. There are two rules.

• A stock that takes and gives passes a component to another such stock only when the other has the higher priority. So two storages never pass a component back and forth. The rule looks at the recipes that are turned on.
• A machine that the floor's supply fills gives nothing to a machine with FRefusesFloorSupplyTag. UFloorSupplyRefusalTrait adds that tag, and the airlock has it.

The direct connection processor, the two rail processors, the bot rail priority processor and the bot dispatch processor apply both rules. The belt transport processor and the pipe flow processor do not, as in the simulator. So a belt or a pipe still carries the floor's supply into an airlock. A processor cannot read a tag on the machine at the other end of a link (3.1). So the topology processor copies three facts into FMachineLinksFragment::TradeFlags on each machine. The first is whether its stock takes and gives now. The second is whether the floor's supply fills it. The third is whether it refuses the floor's supply.

Sweeping. A player can set a machine with UGroundSweepTrait to sweep, and the airlock has that trait. The machine sweeps only while bots serve it. Bots then bring it components that lie on the ground. They bring a kind only when no machine demands it and the machine's own setting does not name it. The bot dispatch processor gives sweep jobs lower priority than every other job. A sweep job reserves the component at its pile and nothing at the machine. The bot hand-off processor consumes a swept component as it arrives. The component does not enter the stock.

What a machine has consumed. FMachineConsumedFragment counts it, kind by kind. The recipe execution processor counts a component when its run ends. The bot hand-off processor counts a swept component when it arrives.

4.5 Fluid and pipes

Fluid is an amount held in machine buffers and moved through pipes, which hold nothing, as in the simulator; UMachineFluidTrait is on any machine type with a fluid port and UPipeTrait is on pipe sections. A pipe section also has the traits every section shares. They are UTiledMachineTrait, UFloorIndexTrait and UCarrierFlowTrait.

Which fluid a pipe network carries. The topology processor works it out from the network's ports. A port takes a fluid by name when a recipe that is turned on takes that fluid through that port (4.2). It also takes a fluid by name when the setting of its machine's stock names that fluid. A port gives a fluid when a recipe that is turned on makes that fluid through that port. The network carries the one fluid that one port gives and another port takes by name. When no port takes a fluid by name, the network carries the one fluid that is given. In either case, when more than one fluid fits, the network is mixed and nothing flows. A stock that takes and has no setting takes no fluid by name. It takes whatever the network carries. A stock that the floor's supply fills gives each fluid the floor supplies to it (4.4).

The pipe network entity. There is one for each set of connected pipes. It has UCarrierNetworkTrait, which the rail network has too, and UPipeNetworkTrait. It exists only on the server and is not replicated. The pipe flow processor loops over these entities.

4.6 Belts and rails

Belts and rails are the same thing with three differences. Both carry stacks along a run, and both store and replicate them the same way. A belt section and a rail section each have UCarrierStacksTrait and the traits every section shares (4.5). Each also has UCarrierItemsVisualTrait, as the splitter does. Section 4.8 covers the three things only a rail does.

Stacks are kept apart by the stack radius, which is a floor rule (4.11). It is 30 cm today, which is half the size the factory database gives a component. Two stacks on a run are never closer than twice the radius. A stack's place is stored as a distance along its section, in centimetres. Nothing is stored or limited per tile.

A run can span several sections. A stack is stored on the section it is over, and moves to the next section's fragment when it crosses the boundary.

These structs are used inside the fragments above. They are not fragments. Splitters, piles and bots use FComponentStack too, and so does a recipe.

A merge is not a machine and not an entity. A merge is where one belt run ends against the side of another. The run being joined carries straight on, and the joining run adds a stack only where there is a gap. Where several runs join at one tile, the one built first goes first (FCarrierBuildOrderFragment). A merge has no state of its own.

A run is not an entity either. It is just its sections, which FCarrierLinksFragment links in order. The belt transport processor gathers each run's sections every frame and handles the oldest run first.

A cut or a join keeps what a section holds. UTiledMachineSplitProcessor destroys the section and spawns new ones, as it does today. It first moves the stacks, the flow and the build serials of the tiles that stay to the new sections. A cut takes a tile away. A stack over that tile stays on the old section, and UMachineLifecycleProcessor puts it down as a pile (3.2). Nothing else is put on the ground. A tiled machine with no carrier fragments, such as cradle track, is split as it is today.

4.7 Splitters

A splitter is a machine like any other. It is a UMachineData type on DA_MachineBase and is placed like a machine. It has UMachinePortsTrait for its four sides and UBeltSplitterTrait for its behaviour. It shares UFloorIndexTrait and UCarrierItemsVisualTrait with belt and rail sections. It is not a tiled machine and not part of a run. Belt runs start and end at its sides, and a machine port facing a side connects to it directly. The topology processor works out which sides are inputs and which are outputs from what is connected to them. A splitter does not have UMachineBufferTrait, and it has no bot port. It has no demand of its own, so nothing is delivered to it on demand and no bot visits it. It holds the stacks that fit across it, kept apart by the stack radius.

This struct is used inside FBeltSplitterFragment. It is not a fragment.

4.8 What only rails do

A rail section has URailTrait on top of the traits in 4.6. A rail does three things a belt does not.

• Each stack has a destination. A rail only loads a stack that a machine it reaches has demanded. Room is reserved for the stack at that machine.
• A rail can branch anywhere. At a branch, a stack takes the way to its destination. A belt only branches at a splitter.
• Rails take turns where they join. A belt lets a joining stack in only where there is a gap.

A rail also has its own speed, which is a floor rule.

This struct is used inside FRailStacksFragment. It is not a fragment.

The rail network entity. There is one for each set of connected rails. It has UCarrierNetworkTrait and URailNetworkTrait. It exists only on the server and is not replicated. The two rail processors loop over these entities. A rail network's age and group are in FCarrierNetworkFragment (4.5), which UCarrierNetworkTrait adds.

4.9 Piles

A pile has UFloorPileTrait. Every pile starts unplaced. The trait also adds the surface membership fragments on the server. A replicated type needs them unless it has FHorizonAlwaysRelevantTag. A type with neither replicates to no one.

4.10 Bots

Bots keep ULogisticsBotTrait. It gains one field, which is the time a pick-up takes. The factory config gives a pick-up time too, and which one a bot uses is undecided (section 8). The job fragment replaces FLogisticsBotOrderFragment. A bot has FLogisticsBotOrderedTag while it has a job. The processors that write the job fragment add and remove the tag, deferred.

4.11 The floor

There is one floor entity per surface. It has UFactoryFloorRulesTrait and UFactoryFloorTrait. AFactoryFloorManager spawns it for its surface and keeps its handle. A processor finds it with a second query. Observers, commands and RPC code ask the floor manager.

UFactoryFloorRulesTrait builds the floor's rules. One set applies to the whole floor. The rules come from DA_FactoryConfig, which the factory database import writes, so the trait has no fields. The trait turns them into a const shared fragment on every net mode, so nothing replicates them.

UFactoryFloorTrait also adds FHorizonAlwaysRelevantTag on every net mode, and the surface membership fragments on the server. The floor entity has no position, so nothing else would keep it relevant to a client.

4.12 Existing types that change

🗺 5. Topology and subsystems

5.1 Topology

How the floor is connected is worked out from what has been built and which recipes are enabled. This exists only on the server. There is no single topology object. Each derived fact is stored on the entity it describes, and ULogisticsTopologyProcessor is the only thing that writes any of it, except the last row.

Indexes. A link refers to a machine, section or splitter by its floor index. The topology processor gives each new entity an index. There is no table of indexes. If no live entity has a given index, nothing is found for it that frame. When the floor is dirty, the processor first finds every rail stack and bot job that refers to an index with no entity behind it, and re-addresses or drops them. Only then does it reuse that index.

Oldest means the lowest build serial. Every machine has a build serial, and so does every tile of a section. AFactoryFloorManager::RequestMachinePlacement stamps them from a counter the floor manager keeps for its surface. A route's tiles are stamped in path order. AMachinePlacementActor and Debug_SpawnMachine spawn a machine without the placement request. They take a serial from the same counter. Nothing has a build serial today. The serial decides the order among machines of equal priority that have waited equally long. It also decides which joining run goes first and which network is the older.

A network is only created or destroyed when something is built or removed. A network is identified by its oldest piece. When two networks are joined, the one with the older piece is kept and the other is destroyed. When a network is cut in two, the half with the oldest piece keeps the entity and the other half gets a new one. A new network is spawned deferred, so it starts working on the frame after it is built. A network holds no components and no fluid, so nothing has to be moved when one is created or destroyed.

Reservations are recounted. When a machine, section or bot is removed, nothing has to release its reservations one by one. The floor is tagged dirty, and the topology processor recounts every reservation from the rail stacks and bot jobs that still exist. The reservations are InboundEnroute and OutboundReserved on machines, and OutboundReserved on piles.

5.2 What is a subsystem, and why

A subsystem is only used where the data has no entity to live on, or where something has to look the data up without going through an entity. This plan adds one subsystem and keeps one for a single job. It deletes four (section 7). The table shows the largest of them.

This table shows what ULogisticsSimulationSubsystem held, and where each thing goes.

UFactoryFloorSubsystem also spawns machines, saves and restores them, and keeps each machine's footprint cells in a map keyed by entity. None of that is an index, and this plan does not move it. The spawn gains two things. They are the build serial and each tile's exits. A save gains each machine's settings. They are its recipes, its kinds, its priority, whether bots serve it and whether it sweeps. A save also gains splitter sides, run direction and build serials, and the floor's serial counter and supply rates. A save does not hold what a machine contains, as today.

📡 6. Replication and commands

Everything in the chain exists only on the server. A client gets copies of what it needs in replicated fragments, and a listen host draws from those same fragments.

What is on a belt or rail is sent as a sampled state, not as a stream of events. A few times a second, while it is changing, each section sends the kind of each stack, where it is, and the server time of the sample. The client slides each stack between samples at its render time.

A machine's run is sent as the server time it started and its length. The client works out progress from those. Nothing on a client follows a handle to another entity.

A section is complete in itself on a client. A belt, rail or pipe is cut into sections so that a client needs only the sections relevant to it, never the whole run. So everything a client draws or shows for a section comes from that section's own replicated state. A fact that belongs to the whole run or network is copied onto each of its sections by the rep sync. Examples are the fluid a pipe carries and whether a belt's front is stuck. Networks, and anything else that groups sections, stay on the server.

There is one proxy for each set of replicated fragments. Horizon picks a type's proxy by the exact set of replicated fragments the type has, and it asserts at the first spawn when no proxy matches. So a replicated fragment and its proxy are always added together. A machine proxy derives from UMachineEntityProxy, and a section proxy derives from UTiledMachineEntityProxy. The existing rep sync processors for machines and for tiles look for those two classes. The proxies that exist today keep their sets of fragments. Three are for machines. They are a tiled machine with no carrier fragments, an arm and a retrieval machine. The other three are for a cradle, the factory monitor and the build ghost. UMachineEntityProxy and UTiledMachineEntityProxy are regenerated, because FMachineRepStateFragment loses five fields and each tile gains a level (4.12).

A retrieval machine that also holds components needs one more proxy. The benchmark floor goes from about 7,800 proxies to perhaps 13,000.

Iris allows 65,536 replicated objects by default. That is a setting on the net driver (MaxReplicatedObjectCount), not a hard limit, so it can be raised. It counts everything the server replicates, on every surface, whether or not a client can see it.

Player changes are Server_ RPCs on UPlayerBuildingHandler. Each one is validated and then raised as a request fragment, which the settings processor and the topology processor consume. Pasting one machine's settings onto another uses the same calls. These are the RPCs.

• Server_SetMachineRecipes
• Server_SetMachineKinds
• Server_SetMachineLogistics
• Server_SetSplitterPriority
• Server_FlipRun

Server_SetMachineRecipes sets which of a machine's recipes are on, and their order. Server_SetMachineKinds sets the kinds a machine's stock is limited to, or removes the limit (4.4). Server_SetMachineLogistics sets a machine's priority, whether bots serve it and whether it sweeps.

🗑 7. What is deleted

AFactoryFloorTestHarnessActor, the benchmark's factory scenario (UDFFactoryBenchScenario) and the order progress window are built on these types, so they go with them.

What takes the place of a parts bin is not designed (section 8).

❓ 8. Open

• The cost of a frame is an estimate until a benchmark measures it. The benchmark should measure each stage on a floor that is filling and on one that is full. It should compare a full topology rebuild with a rebuild of one island. It should report the largest group's share of each stage. It should time dispatch matching without path finding. It should also time finding the entities a processor's links refer to. The results decide whether any carrier stage is worth spreading across threads.
• Nobody has measured what running the chain on a worker gains. A dedicated-server build runs every processor on the main thread, so it gains nothing there. The editor makes the game thread wait until the phase is done, so the gain only shows in a packaged build. Processors still run on workers in the editor, so a race between two processors can show there. A race between a worker processor and code outside Mass only shows in a packaged build. Most of the processors write FMachineBufferFragment or FMachineLedgerFragment, so Mass still runs most of them one at a time. Declaring dependencies removes ordering that nothing needs. It does not by itself make the chain parallel.
• The dependency table in 3.1 has not been tested. It was worked out by reading the simulator. A missing dependency does not crash. It gives a result that differs from the simulator's, and only on some runs, because the order Mass picks can differ from one frame to the next.
• A game-thread processor sits between two worker processors. ULogisticsBotRailPriorityProcessor reads the navigation grid's region labels, so it has to run on the game thread. It also has to run between URailAdvanceProcessor and URailLoadProcessor. Those two wait for the game thread at that point. ULogisticsBotDispatchProcessor reads the same labels and is on the game thread for the same reason. Both could move to a worker if the labels were stored on entities. That would be a new system, and it is not part of this plan.
• Four processors do the same job for different types. They are the pipe, pile and floor rep sync processors and UFactoryProxySendProcessor. Today each rep-sync processor fills the replicated fragment, copies it into the proxy and marks the proxy, all on the game thread. One processor in Horizon could send every type, if each generated proxy could copy from its entity through one virtual function. That is a change to the rep-proxy recipe.
• A carrier sample reaches its proxy a frame late. UCarrierRepSyncProcessor cannot add a tag within the frame, so UFactoryProxySendProcessor sends the sample on the next one. Each sample carries its own server time. A flag in a fragment would remove the delay.
• Code outside Mass reads the occupancy grid on the game thread. In a packaged build it can run while a worker processor runs. That is safe only while everything that writes the occupancy grid stays on the game thread. Footprint registration writes it today.
• UFloorPileProcessor can run on a worker only while piles are not stored in the occupancy grid. It finds the piles on a tile with a query. If piles are added to the occupancy grid, something on the game thread has to add them.
• UMachineData still holds config. A machine type's name, description, icon and category are fields on the type asset. So are its placement flags and its screenshot settings. By the rule in section 1.1 they belong on traits. This plan does not move them. The DFMoveFieldsToTrait commandlet exists for moves of this kind.
• One set of rules applies to the whole floor. The rules come from the factory database's config asset. That is the simulator's model too. A rule could instead be set on the trait of the type it applies to, such as belt speed on UBeltTrait. Two types whose values must agree would then each hold a copy. A belt and a splitter are an example.
• Network entities are untried. A processor creates and destroys them. A player does not place them. A new one starts a frame late. A destroyed one has to do nothing until it is gone. Every link to one is rewritten in the same pass. A network's routes or junctions are stored in a fragment that holds arrays, and a rail network that joins a whole floor makes that fragment large.
• The order of rail networks that share a machine. The simulator has no rail networks. It works through every rail tile on the floor in one order. Processing networks one at a time, oldest first, can load a contested destination from a different source than the simulator would. Pipes do not have this problem, because the simulator already processes pipe networks one at a time in that order.
• Belt runs are not entities, so state that belongs to a run is stored on a section. Whether a run's front is stuck is stored on the section holding the run's end (FCarrierStacksFragment::bHeld). A run entity would be the consistent place for it.
• Rails are stored like belts, and the simulator's are not. Both keep stacks apart by the stack radius. When it runs on the database's config, the simulator's belt also keeps stacks one component's size apart, which is twice the radius, so a belt agrees with it. The simulator's rail holds one stack per tile. So a rail cannot be checked against the simulator exactly.
• A rail stack's destination is stored beside the stack, not in it. FRailStacksFragment::To has to stay in the same order as the stacks in FCarrierStacksFragment. Keeping two lists in step is a risk. The other choice is a destination field on every stack, which belts would ignore.
• Recounting reservations is this plan's idea, not the simulator's. The simulator releases each reservation when its stack or job goes. A recount gives the same result. It costs a pass over the rail sections and bots on every frame the floor is dirty.
• Bot ids. Bots get an id from UFactoryObjectIDRegistry today. With no bot registry, we need to find what still uses that id. The server can refer to a bot by its entity, and a client by its NetID.
• The rest of UFactoryFloorSubsystem. Its spawn, save and restore functions and its per-entity footprint map are not an index. This plan does not move them. Section 5.2 says what the spawn and a save gain.
• Islands on real floors. How much players connect their floors into one network decides how much there is to gain from processing parts of the floor in parallel.
• Push model. The proxies are written for the push model, but the game target does not set bWithPushModel and nothing sets Net.IsPushModelEnabled. If that is right, Iris compares every property of every relevant proxy on every update, and the server cost of the new arrays goes up. This was read from the configuration. It has not been observed running. While push model is off, a mark does nothing, and the processors that send to a proxy only copy plain values into it. They stay on the game thread so that turning push model on changes nothing in the chain.
• More than one factory surface. This plan has one floor per surface. The navigation grid is set up for surface 0 only today, and the logistics subsystem holds one path provider. The first build supports surface 0 only. New spawners and commands take a surface id from the start.
• Unplaced piles and replication. It is undecided whether a pile is held back from replication until it has a tile. Holding it back would stop a client seeing a pile that is about to merge into another.
• UPipeFlowProcessor writes to pipe sections as well as machines. It writes FPipeFlowRepStateFragment, and it does so from a worker thread.
• The cost of a stack sample. Each stack on a belt or rail is at its own distance. So a section's sample is a kind and a distance for each stack, where it used to be a kind for each tile. This has not been measured.
• Storing the gaps between stacks instead of their positions. Factorio does this for its belts (Friday Facts 176, https://www.factorio.com/blog/post/fff-176). While a belt moves freely the gaps do not change, so very little would need to be sent to clients. This could replace the belt sample. The details have not been worked out.
• What happens to a stack's state inside a machine. A buffer row is a count, so a stack's temperature has nowhere to go when the stack is delivered. Either the temperature is dropped and set again on what the machine makes, or each row keeps an average. What sets the state of a stack that a machine gives out is undecided too.
• Stacks of more than one. While every stack holds one component, a stack is loaded and delivered whole. A larger stack needs a rule for a machine that has room for only part of it. It also needs a rule for two stacks joining. Two piles of the same kind join today. Their quantities add up, and their state has to be combined somehow.
• State that changes in transit. If a stack cools as it travels, its temperature can be stored as a value at a time. Anything can then work out the current temperature, and nothing has to be updated every frame.
• What a client is sent about a stack. The samples carry a kind for each stack. Quantity and temperature are only added if they are drawn.
• The simulator moves bare kinds. With stacks of one, this plan can still be checked against the simulator on kind and position. The simulator cannot check a stack's state.
• Fluid amounts will not match the simulator exactly. This plan compares fluid amounts with a tolerance. The simulator rounds them to a millionth. So fluid amounts can only be checked against the simulator to within that tolerance, and a run can start up to a thousandth of a unit short of what its recipe needs.
• A splitter is different from the simulator's. In the simulator it is a belt tile. Here it is a machine. It still holds the stacks that fit across it and sends them out the same way, so it can still be checked against the simulator.
• A stock is this design's reading of the database's three wildcard recipes. The simulator has no wildcard. It makes a recipe for each kind a machine is set to. It also knows four machine types by name. Section 4.4 gets the same behaviour from the recipes and a few small traits.
• Where a stock behaves differently from the simulator.
  • A stock with no setting accepts every kind. The simulator's machine accepts none until a kind is set.
  • A debug sink consumes the oldest component it holds. The simulator's line consumes in the order of its kinds.
  • A debug sink takes 1 second for each component, because r-store has no time in the database. The simulator takes 0.25 seconds.
  • A storage has rows for at most 24 kinds at once, and its three recipes can be turned on and off.
  • A debug sink with no setting on a pipe network takes the network's fluid. It is served before a machine that makes things, because it starts at priority 18, as a line does in the simulator.
• What the simulator shows that this design does not keep. The simulator's airlock lists the last ten things it received. Its floor shows one count of everything that was delivered. Here each machine counts what it has consumed, and nothing adds those counts up.
• Storing a machine's recipes by index is this plan's idea, not the simulator's. The simulator keeps what a machine holds in a map keyed by recipe, which has no fixed size. Here a machine has 16 indexes, so a machine type can have no more recipes than that.
• Each machine stores where its recipes' rows start. RowStart is the same for every machine of a type, so 16 bytes that are fixed per type are copied on to each machine. The other choice is a row table on the type.
• Finding a kind's rows reads the catalogue. A processor goes through up to 16 recipes and reads each one's kinds from the catalogue, often on a worker thread. This has not been measured.
• A machine that only consumes gains the modifier and utilisation fragments. UMachineRecipeExecutionTrait adds both, and the two debug sinks and the airlock have that trait. Whether the monitor should list such a machine is undecided.
• The factory database gives more than this design uses. A machine can have a fuel, and only the smelter has one. A machine can have key values of its own, such as the storage's capacity and a belt's speed. The import does not write either yet. Until it does, this design has no fuel, and the floor's rules use the defaults of the key values.
• Bot speed and pick-up time have two sources. The factory config gives a bot speed of 4 tiles a second, which is 400 cm a second, and a pick-up time. ULogisticsBotTrait has a speed of its own, which is 375 cm a second. Which one a bot uses is undecided.
• What feeds the floor's supply in the game. In the first build a test floor sets the rates. A supply machine takes a supply interval from USupplyMachineTrait, and a retrieval machine works one out from its yield. Both keep it on FSupplyRateFragment, which this design deletes. How either feeds the floor's supply is not designed. What replaces a parts bin is not designed either. How a part type maps to a kind is not designed either.
• How an authority draws moving stacks. A listen host and a standalone game have no render delay, so they never have a sample either side of the render time. One answer is for UCarrierRepSyncProcessor to write the replicated fragment every frame there, and to limit only what is sent.
• Where a pipe tile's drawn values go. UPipeVisualizationProcessor needs three values on a tile. A mesh instance has two custom floats, and a tiled machine already uses both.
• How an underpass and its ramps get a mesh. A tile's shape is chosen from its directions alone today.
• A bot's job when its path fails. What the job does then is undecided.
• How an observer tells a cleared floor from a removed machine. Both arrive as the same tag being removed. Clearing a floor has to put nothing on the ground (3.2).
• The floor entity is always relevant and also bound to a surface. Horizon's code allows both together. No existing type does it.
• Nothing in the project declares a subsystem requirement or an indirect requirement today. No processor spawns an entity from a worker thread either. The engine allows that through the processor's own command buffer, with the template fetched on the game thread first. In a build with slow checks on, the engine checks that an indirect access was declared. No other build checks it.