Skip to content

t1k:unity:dots-core:logistics

FieldValue
Moduledots-core
Version3.56.1
Effortmedium
Tools—
/t1k:unity:dots-core:logistics

DOTS Logistics — Carry Items & Worker Hauling

Section titled “DOTS Logistics — Carry Items & Worker Hauling”

Package: com.the1studio.dots-core — namespace DOTSCore.Logistics Assembly: DOTSCore.Logistics (its own asmdef, not part of DOTSCore.Runtime) Group: LogisticsSystemGroup — declared in Runtime/Core/Systems/SystemGroups.cs, sources live in Runtime/Logistics/

The loop this package models: something produces a loose item into the world → a worker claims it → the worker carries it to a destination → throughput is measured. Production spawns a world entity, not a currency delta; currency is credited later at the sale step (DOTSEconomy.Sale), downstream of delivery.

  • Spawning loose goods into the world for workers to collect (farm yields, factory output, drops)
  • Building a claim/carry/deliver worker loop where two workers must never take the same item
  • Capping how many loose items may exist, and choosing what happens at the cap
  • Measuring items-per-second, mean haul time, or peak loose count
  • Debugging “workers never pick anything up” or “deliveries are being lost”

Eight systems, all in LogisticsSystemGroup:

OrderSystemRole
OrderFirstCarryGridBuildSystemBuilds a SpatialHashGrid over every CarryItemTag entity; publishes CarryGridRegistry
—LooseItemCapSystemRefreshes LooseItemCap.CurrentLooseCount; enforces the opt-in DespawnOldest policy
after LooseItemCapSystemCarryItemSpawnSystemDrains the CarrySpawnRequest buffer into real entities, respecting the cap
after CarryGridBuildSystemHaulClaimSystemSingle-threaded claim walk + delivery-target selection
before WorkerHaulSystemHaulBufferEnsureSystemGuarantees HeldItem on every worker and PendingDelivery on every destination. Exists as its own system for a Burst-correctness reason — see Gotchas
after HaulClaimSystemWorkerHaulSystemParallel movement pass, then a serial arrival/mutation pass
—WorkerHaulReleaseSystemHands a finished/never-started hauler back to the WorkQueue pool (resets AgentAssignment.Kind off Carry)
OrderLastHaulThroughputSystemDrains DeliveryEvent into HaulThroughputMetrics

LogisticsTestBase.UpdateLogisticsFrame is the canonical frame order this was written against: claim/haul → cap → spawn-drain → throughput.

The typed delivery channel — HeldItem → PendingDelivery → StoredItem

Section titled “The typed delivery channel — HeldItem → PendingDelivery → StoredItem”

WorkerHaul.HeldCount is a flat, untyped total (by original design, when the only sink was the equally untyped HaulDestination.Stored). Once delivered stock has to become a typed deposit, item identity must survive from pickup to drop-off. Two buffers carry it, and the channel is purely additive — HaulDestination.Stored bookkeeping is untouched and still works exactly as before.

TypeWhereCapMeaning
HeldItemon the worker[InternalBufferCapacity(4)]{ int ItemDefId; int Count; } — typed stacks currently carried
PendingDeliveryon the destination[InternalBufferCapacity(4)]{ int ItemDefId; int Count; } — dropped off, awaiting typed-storage application

Flow across the package boundary:

WorkerHaulSystem (DOTSCore.Logistics)
pickup → AddOrMergeHeldItem(worker's HeldItem, carryItem.ItemIndex, 1)
delivery → for each held stack the destination ACCEPTS:
AddOrMergePendingDelivery(destination's PendingDelivery, ...) ; held.RemoveAt(h)
rejected stacks stay held for the next trip
(+ the untyped destination.Stored += deliveredCount, clamped to Capacity)
(+ HeldCount -= deliveredCount — NOT zeroed; see § Item-type-aware routing)
HaulDeliveryApplySystem (DOTSEconomy.Storage, EconomySystemGroup)
drains PendingDelivery → StorageUtility.TryDeposit → StoredItem, gated on StorageCapacity

Why the hop exists at all: DOTSCore.Logistics cannot reference DOTSEconomy.Storage.StoredItem — the asmdef dependency runs the other way (DOTSEconomy.Runtime → DOTSCore.Logistics, never the reverse). So Logistics writes a plain data record and the downstream package, which alone can see both sides, drains it. Same shape as the CarrySpawnRequest producer bridge. Do not “fix” the apparent HeldItem/StoredItem duplication by inverting the package dependency.

Item-type-aware routing — HaulAcceptPolicy + HaulAcceptFilter

Section titled “Item-type-aware routing — HaulAcceptPolicy + HaulAcceptFilter”

A HaulDestination was originally an untyped bulk sink, and the search was purely nearest with spare capacity. That made a per-building hopper impossible: every worker dumped whatever it carried into whichever sink was closest, silently misrouting stock, so consumers were stuck attaching HaulDestination to exactly one global storage entity. The filter makes a sink able to say what it wants.

TypeShapeMeaning
HaulAcceptPolicyenum : byte — AcceptAny = 0, AcceptListedOnly = 1Field HaulDestination.AcceptPolicy
HaulAcceptFilterIBufferElementData, [InternalBufferCapacity(4)], { int ItemDefId; }On the destination — one row per accepted item id
HaulAcceptUtility.Accepts(policy, destination, itemDefId, filterLookup)static boolPer-item test, asked again at delivery
HaulAcceptUtility.AcceptsAnyHeld(policy, destination, held, filterLookup)static boolRouting test — “wants at least one type this worker holds”
HaulDestinationSearch.TryFindNearestAccepting(...)internal static boolAccept-aware search, alongside the untyped TryFindNearestWithSpareCapacity

AcceptAny is deliberately the zero value. Every HaulDestination attach site authored before the filter existed keeps its exact previous behaviour with no edit — a barn/silo/market wants everything, which is the honest default for a sink whose whole shape is one untyped Stored total. Do not sweep existing attach sites “to be explicit”; the default is correct.

The one genuinely breaking edge is positional construction — HaulDestination gained a field, so new HaulDestination(cap, stored)-style positional initialisation shifts. Named-initialiser construction (what the Quick Setup below and every in-repo call site use) is unaffected.

AcceptListedOnly + an empty or absent buffer accepts NOTHING

Section titled “AcceptListedOnly + an empty or absent buffer accepts NOTHING”

This is deliberate, not a degenerate case to guard against. A production building the player has not yet assigned a recipe to should not attract deliveries it has no use for — it is skipped by every destination search until its filter is populated. Mirror the buffer from the consuming recipe’s input list and re-sync it whenever that recipe changes.

The corollary when debugging: a filtered building that never receives anything is far more likely to have an unpopulated filter than a broken search. Read the HaulAcceptFilter buffer before suspecting TryFindNearestAccepting.

The filter compares the same untyped int already carried by CarryItem.ItemIndex, HeldItem.ItemDefId and PendingDelivery.ItemDefId. dots-core has no notion of what an item is; whatever content layer mints those ids owns their meaning. The filter only ever tests equality.

Routing is “accepts ANY held type”, delivery is per-item

Section titled “Routing is “accepts ANY held type”, delivery is per-item”

A worker can hold a mixed load (HeldItem merges by id, up to buffer capacity). Routing on any rather than all keeps a worker from deadlocking with a load no single sink wants in full. The delivery path then re-asks the per-item question and transfers only the accepted subset, leaving the remainder held for the next trip. Both paths call the same HaulAcceptUtility predicate precisely so routing and delivery can never disagree.

Consequently WorkerHaulSystem decrements HeldCount by what actually moved rather than zeroing it. Going Idle with a non-zero remainder is a correct state — HaulClaimSystem re-routes it next pass.

Filtered sinks win ties against bulk storage, deliberately (distance-only ranking), and the accept list is a buffer, not a field, because a recipe can require more than one distinct input. Full rationale for both: references/quick-setup-and-constants.md § “Rationale”.

HaulClaimSystem falls back to the untyped search — deliberately

Section titled “HaulClaimSystem falls back to the untyped search — deliberately”

When a worker has no HeldItem buffer at all, HaulClaimSystem calls TryFindNearestWithSpareCapacity instead. This is intentional, not an oversight or dead code: a worker constructed outside the normal claim flow (so HaulBufferEnsureSystem never saw it) still gets pre-filter behaviour rather than silently never finding a destination. The untyped search is also still the correct call for a worker with an empty hold — it has no item type to match on. Do not “simplify” the fallback away.

Public predicate, internal search — the asymmetry is deliberate

Section titled “Public predicate, internal search — the asymmetry is deliberate”
SymbolReachWhy
HaulAcceptUtility + Accepts / AcceptsAnyHeldpublicA genuinely reusable API
HaulDestinationSearch + both overloadsinternalAn implementation helper

The predicate is public because consumers legitimately need it. Anyone writing their own routing pass, or their own delivery-apply pass, has to be able to ask “does this sink accept this item?” — and can supply their own BufferLookup<HaulAcceptFilter> to do so. Asking it through the same shared predicate the library uses is what stops a consumer’s routing from disagreeing with the library’s delivery.

The search is internal because it has no consumer-facing contract. It is a helper shared by exactly two library systems (HaulClaimSystem and WorkerHaulSystem), free to change shape as they do. TryFindNearestAccepting is therefore exactly as reachable as the TryFindNearestWithSpareCapacity it sits beside — deliberately no more public than its neighbour, not an accidental under-exposure. Out-of-assembly consumers drive routing by attaching HaulDestination + HaulAcceptFilter and letting the systems search.

Neither half of the split is an oversight; do not “fix” either direction.

⛔ StorageSlot / StorageCapacityConfig / StorageHeadroomUtility are RETIRED

Section titled “⛔ StorageSlot / StorageCapacityConfig / StorageHeadroomUtility are RETIRED”

All three carry [System.Obsolete]. They were declared here under a cross-wave contract when no per-item storage shape existed yet; the reconciliation has since happened and DOTSEconomy.Storage.StoredItem + StorageCapacity is the storage SSOT. Every production writer has been redirected — these three have no remaining production callers, only their own tests, and are kept for one release cycle per the library-quality mandate rather than deleted outright.

RetiredUse instead
StorageSlot (buffer, cap 8)DOTSEconomy.Storage.StoredItem
StorageCapacityConfig.DefaultCapacityDOTSEconomy.Storage.StorageCapacity
StorageHeadroomUtility.Headroom / .ReserveDOTSEconomy.Storage.StorageUtility.TryDeposit / .Reserve

New code must not add callers. The granted + cappedLoss == requested contract (“nothing vanishes unreported”) carried over to the replacement — that idiom is not what was retired, only this implementation of it.

Request a spawn (append CarrySpawnRequest to the singleton buffer), give a worker WorkerHaul (Capacity, MoveSpeed, Phase = Idle), attach HaulDestination (bulk sink — AcceptPolicy defaults to AcceptAny, the zero value, so omitting it preserves pre-filter behaviour) or a filtered HaulDestination + HaulAcceptFilter buffer mirroring the consuming recipe’s inputs (an empty/absent filter under AcceptListedOnly accepts NOTHING — deliberate), cap loose items via LooseItemCap, and read HaulThroughputMetrics for DeliveredPerSecond/MeanHaulSeconds/etc. Full code for each: references/quick-setup-and-constants.md § “Quick Setup”.

LogisticsConstants.{CarryCellSize=5f, CarryGridCapacity=1024, DefaultMaxRings=8}, LooseItemCapConstants.DefaultMaxLooseItems=512, HaulThroughputConstants.DefaultWindowSeconds=5f. Full table: references/quick-setup-and-constants.md § “Constants”.

DirectionPackageDetail
Depends onDOTSCoreSpatialHashGrid, LocalTransform, DeadTag, LogisticsSystemGroup
Produced byDOTSFarmingHarvestSpawnBridgeSystem drains each tile’s PendingHarvestSpawn into the shared CarrySpawnRequest buffer
Produced byDOTSEconomy.ProductionProductionTickSystem appends CarrySpawnRequest on cycle completion
FeedsDOTSEconomy.StorageHaulDeliveryApplySystem drains this package’s PendingDelivery into StoredItem. The dependency runs Economy → Logistics; Logistics never references Economy
FeedsDOTSEconomy.SaleDelivered stock is what later gets sold; only the sale step credits the wallet
Integrates withDOTSCore.Workers / DOTSAI.WorkQueueWorkerHaulReleaseSystem resets AgentAssignment.Kind off Carry. Reference is to DOTSCore.Workers only — not to dots-ai

Full detail: references/hard-rules.md. Read it before acting on this topic.