Skip to content

t1k:unity:dots-inventory:grid

FieldValue
Moduledots-inventory
Version3.29.3
Effortmedium
Tools—

Keywords: adjacency, AdjacencyMathUtility, auto-battler board, BlobConfig, blobconfig migration, BlobConfigRegistry, config blob, crafting, CraftingRecipeBlob, diminishing returns, gacha, grid, GridAdjacencyEvaluator, inventory, inventory blob, loot, LootTableBlob, match-3 combo, passive, PlacementShapeBlob, polyomino, set bonus, SetBonusBlob, synergy, tower defense adjacency

/t1k:unity:dots-inventory:grid

DOTS Inventory Grid — Grid, Crafting, Passives, Sets, Loot

Section titled “DOTS Inventory Grid — Grid, Crafting, Passives, Sets, Loot”

Package: com.the1studio.dots-inventory — namespace DOTSInventory.* Related skills: t1k-unity-dots-core-ecs (API) · t1k-unity-dots-combat-rpg (stats pipeline) · t1k-unity-dots-core-ecs (ECB)

  • Implementing polyomino / 2D inventory grid (slot cells, occupancy, placement, rotation, auto-fit)
  • Crafting recipes with ingredient matching and craft progress tracking
  • Passive item effects that aggregate into derived stat buffers
  • Set bonuses triggered when N matching items are equipped
  • Loot table drops and gacha pulls with rarity tiers
  • Computing synergy / adjacency bonuses with diminishing returns (inventory, board, tower, puzzle)
  • Auto-battler unit placement bonuses based on neighboring allies
  • Tower defense adjacency fire-rate boosts between adjacent towers of the same type
TopicReference File
Grid / passive / set-bonus components + InventorySystemGroup ordering — InventoryGridDimension, ItemGridShape, ItemRotation, ItemShapeMask, PassiveCondition, SetBonusDefinition, InventoryGridUtility placement APIreferences/grid-components-and-ordering.md
Placement / passives / sets / gotchas — deep divesgrid-placement-guide.md (references/grid-placement-guide.md) · passive-effects-guide.md (references/passive-effects-guide.md) · set-bonuses-guide.md (references/set-bonuses-guide.md) · demo-shapes-guide.md (references/demo-shapes-guide.md) · library-api.md (references/library-api.md) · hard-rules.md (references/hard-rules.md) · hard-rules-ui-drag.md (references/hard-rules-ui-drag.md)
GridAdjacencyEvaluator — diminishing-returns synergy formula (generic, Burst-safe)references/grid-adjacency-evaluator-guide.md
BlobConfig migration — migrate inventory config tables (CraftingRecipe, PlacementShape, SetBonus, LootTable) to baked BlobAsset; SO-based vs inline-entries shapes; gotchas../t1k-unity-dots-core-ecs/references/blobconfig-migration.md

Regenerated against source 2026-08-23 — see § Public Systems below for how the previous table diverged (4 of 6 systems fabricated). The component table had the same defect: several types either never existed, or exist with different fields than documented.

ComponentTypePurpose
InventoryGridCellIBufferElementData (cap 0)Entity ItemEntity, byte IsActive (1=usable, 0=inactive expansion slot); 1D buffer represents 2D grid
InventoryGridDimensionIComponentDataint GridWidth, GridHeight — not InventoryGridConfig (never existed)
InventorySlotIBufferElementDataEntity ItemEntity, int StackCount — one occupied slot
ItemIComponentDataint ItemId, ItemType Type, ItemRarity Rarity, int StackMax — core item identity
CraftingRecipeEntryBlob entry (IBlobConfigEntry, in CraftingRecipeBlob)int DefId (== RecipeId), OutputItemId, byte OutputCount, float CraftDuration. Not a per-entity CraftingRecipe buffer — CraftingSystem reads recipes from the blob singleton only; no such buffer exists
CraftingIngredientIBufferElementDataint RecipeId, ItemId, byte RequiredCount — not int ItemTypeId, int Quantity
CraftingStateIComponentDataint ActiveRecipeId, float Progress
ItemPassiveEffectIBufferElementData (cap 4)StatType Stat, ModifierType ModType, float Value, PassiveCondition Condition — not int StatId, PassiveOp Op (neither type exists)
SetBonusDefinitionIBufferElementDataint SetId, RequiredCount, StatType BonusStat, ModifierType BonusModType, float BonusValue — not ItemSetBonus (never existed)
SetBonusEntryBlob entry (in SetBonusBlob)Same shape as SetBonusDefinition, Burst-readable; ItemSetBonusSystem iterates the blob directly, not by binary lookup
EquippedItemIBufferElementDataEntity ItemEntity, EquipSlotType SlotType — not int SlotIndex
LootTableEntryIBufferElementData (cap 2)int ItemId, float DropRate (independent 0..1 roll per entry), MinCount, MaxCount, ItemType Type, ItemRarity Rarity, int StackMax — consumed by LootDropSystem
LootTableIBufferElementData (cap 4)int ItemId, float Weight (relative, for weighted selection), byte MinCount/MaxCount, float DropChance (per-entry eligibility gate), ItemRarity Rarity, ItemType Type, byte StackMax — consumed by LootTableSystem. Two independent loot-buffer conventions, not one — see Gotchas
LootPityTrackerIBufferElementData (cap 4)int ItemId, int ConsecutiveDrops; per-player anti-streak state
GachaChestRequestIBufferElementData (DOTSInventory.Loot)GachaSource Source, uint Seed, Entity Requester — queued pull request, drained by GachaChestSystem
GachaPullResultIComponentData (DOTSInventory.Loot)int ItemId, GachaRarity Rarity, uint SeedUsed — written onto the requester entity. Not a spawned item entity
GachaPityTrackerIComponentData (singleton, DOTSInventory.Loot)int ConsecutiveCommons, bool FtueFirstPullUsed, int TotalPulls

GachaEntry never existed as a type. Loot uses ItemRarity (Common/Uncommon/Rare/Epic/…); gacha uses a separate, narrower GachaRarity (Common/Rare/Epic) — do not conflate them.

Regenerated from grep -rl "UpdateInGroup(typeof(InventorySystemGroup))" — the previous version of this table fabricated 4 of its 6 rows (InventoryGridPlacementSystem, PassiveEffectRollupSystem, SetBonusEvaluationSystem, GachaPullSystem) and omitted 4 real group members entirely (PickupSystem, EquipmentSystem, EquipmentSubStatRollSystem, LootTableSystem).

SystemGroupRole
PickupSystemInventorySystemGroup ([UpdateAfter(InventoryRespawnResetSystem)])Collectors pick up nearby items via a persistent SpatialHashGrid (O(N+M), not O(N·M))
GridPlacementSystemInventorySystemGroup ([UpdateAfter(PickupSystem)] [UpdateBefore(EquipmentSystem)])Auto-places unplaced items on EquipmentDirtyTag; rect (ItemGridShape) or polyomino (ItemShapeMask) placement. Not InventoryGridPlacementSystem (never existed)
PassiveEffectSystemInventorySystemGroup ([UpdateAfter(PickupSystem)] [UpdateBefore(EquipmentSystem)])Clear-and-rebuild: removes all ItemPassive modifiers, re-adds from current inventory. Fires on EquipmentDirtyTag (same trigger as EquipmentSystem). Not PassiveEffectRollupSystem (never existed)
EquipmentSystemInventorySystemGroup ([UpdateAfter(PickupSystem)])Syncs equipment stat bonuses (EquipmentStatBonus) to StatModifier; only on EquipmentDirtyTag enabled, then disables it
EquipmentSubStatRollSystemInventorySystemGroup ([UpdateAfter(EquipmentSystem)])Rolls per-item substats from SubStatPoolBlob on first encounter with SubStatRollPending; deterministic from RunScopeSingleton.RunSeed hashed with Item.ItemId + slot
ItemSetBonusSystemInventorySystemGroup ([UpdateAfter(PickupSystem)] [UpdateBefore(EquipmentSystem)])Clear-and-rebuild set-bonus modifiers: counts items per set, applies every threshold met in the SetBonusBlob singleton. Fires on EquipmentDirtyTag. Not SetBonusEvaluationSystem (never existed)
CraftingSystemInventorySystemGroupTicks CraftingState.Progress; on completion adds the output item to InventorySlot and resets state. Reads recipes from the CraftingRecipeBlob singleton — no per-entity CraftingRecipe buffer exists
LootTableSystemInventorySystemGroup ([UpdateBefore(LootDropSystem)])On DeadTag: rolls each LootTable entry’s DropChance (× optional RarityMultiplier) to build an eligible pool, then weighted-cumulative-selects ONE entry by Weight; spawns via LootSpawnUtility. Missing from the previous table entirely
LootDropSystemInventorySystemGroup, OrderLast = trueOn DeadTag: drains LootTableEntry — a SEPARATE, independent-per-entry-probability roll (DropRate), not weighted selection. Every entry that beats its own roll drops. Appends to the optional LootDropEvent singleton for Mono-side reaction
GachaChestSystemSimulationSystemGroup — NOT InventorySystemGroup (DOTSInventory.Loot)Drains GachaChestRequest, rolls via GachaWeightedRoll (reading GachaConfig, falling back to GachaConfig.Default), resolves the item id via GachaItemResolverBridge, writes GachaPullResult onto the requester. Does not spawn an entity via ECB — the previous table’s GachaPullSystem (wrong name, wrong group, wrong behavior) never existed

LootTableSystem and LootDropSystem are two independent loot pipelines, not one — an entity carrying both a LootTable buffer and a LootTableEntry buffer gets processed by both, with different RNG streams (0xBEEF vs 0xC0FFEE salts) and different selection semantics (weighted single-pick vs. independent-per-entry). Pick one buffer type per entity archetype; mixing both without understanding this produces double drops, not a richer loot table.

Code patterns for: 1D-as-2D grid indexing (row-major), passive-effect aggregation across equipped items, set-bonus all-or-nothing evaluation, weighted loot drop (reservoir), per-item anti-streak pity (DOTSInventory.Loot.ItemPityRoller, paired with the baked LootPityTracker buffer), and rarity-pity (RarityRoller). All three loot rollers (RarityRoller/WeightedRarityRoll/ GachaWeightedRoll) delegate to the shared DOTSCore.WeightedSampler.Sample primitive — do NOT re-implement cumulative-sum sampling for a new roller. Gacha config + item resolution belong to the consumer (v4.0.0): register an IGachaItemResolver via GachaItemResolverBridge.

Full code for each pattern: references/common-patterns.md. Gacha API detail: gacha-loot-api.md (references/gacha-loot-api.md).

DirectionPackageDetail
Depends onDOTSCore baseLocalTransform, ECB, SystemAPI
Depends onDOTSCore.StatsDerivedCombatStats that passive rollup writes into
Used byDOTSCombatCombat reads inventory passives for derived stats
Future splitdots-economyCurrencyWallet moving to dots-economy in Wave 2
  • BackpackCrawler — polyomino grid, drag-drop, set bonuses, loot drops per room, ItemPityRoller reference impl (CrawlerLootTable.GetRandomLootWithPity)
  • InventoryDemo — grid showcase with passive rollup and crafting UI
  • AutoBattlerDemo — draft shop uses GachaChestSystem/GachaRarity tiers for unit reveal (GachaEntry never existed as a type)
  • ChaosForgeDemo — forge-roll loop (ForgeRollSystem) consumes ItemPityRoller for anti-streak protection (W2.6)
  • Grid cells are a 1D buffer representing 2D layout — never use a 2D NativeArray per entity; the flat buffer with row-major indexing (Y * Width + X) is chunk-friendly and Burst-safe. Accessing out-of-bounds silently returns the wrong cell — always bounds-check before ElementAt.
  • Multi-cell items occupy consecutive cells in row-major order — placement must reserve a contiguous run of cells for wide items; overlap detection is the consumer’s responsibility.
  • Set bonuses are all-or-nothing — partial set membership never grants partial bonus. ItemSetBonusSystem (not SetBonusEvaluationSystem — never existed) clears and re-evaluates on EquipmentDirtyTag, not every frame; do NOT cache the bonus outside the system (drift risk).
  • CurrencyWallet moves to dots-economy post-Wave 2 — do NOT add new references to CurrencyWallet inside DOTSInventory.* code; route through the incoming DOTSEconomy.Wallet component instead. Existing references are flagged [Obsolete] pending migration.
  • PassiveEffectSystem (not PassiveEffectRollupSystem — never existed) already gates on EquipmentDirtyTag, not every frame. There is no separate InventoryDirtyTag — the real enableable flag is EquipmentDirtyTag, shared with EquipmentSystem/ItemSetBonusSystem/GridPlacementSystem. A producer that changes equipped items/passives/set membership must enable EquipmentDirtyTag itself, or the rebuild silently never fires.
  • Loot seeds come from DOTSCore.Time.SimTick, NEVER ElapsedTime (fixed The1Studio/unity-dots-library#118). Both LootTableSystem and LootDropSystem seed their rolls with math.max((uint)entity.Index + simTick + salt, LootSpawnUtility.SeedMinimum), where simTick is read via SystemAPI.HasSingleton<DOTSCore.Time.SimTick>() ? SystemAPI.GetSingleton<DOTSCore.Time.SimTick>().Value : 0u. SimTick is a deterministic per-frame uint counter (increments by exactly 1 per SimTickSystem update, wraps harmlessly at ~2^32) — no time-to-uint scale conversion, and therefore no overflow-guarding cast dance, unlike the former (uint)entity.Index + (uint)(elapsedTime * config.TimeToSeedScale) + salt formula it replaced. The old ElapsedTime-derived seed was framerate- AND machine-dependent: identical inputs on different hardware produced different loot rolls, and the double intermediate silently folded to 0 (degenerating the RNG seed) after ~49.7 days. The SimTick salt degrades to 0u in a hermetic test world that never wires SimTickSystem into its group, matching that singleton’s own self-heal contract. LootSpawnConfig.TimeToSeedScale and LootSpawnUtility.TimeToSeedScale are untouched but UNREAD — retained only so the wire/save shape doesn’t change for consumers that bake/serialize the config. Do not seed RNG from SystemAPI.Time.ElapsedTime, WorldClock, or SystemState.GlobalSystemVersion (the last encodes structural-change history and diverges across save-reload) in this package; SimTick is the contract.
  • GachaChestSystem’s pity counter (GachaPityTracker) is a SINGLETON, not a per-entity component — there is no GachaPullSystem (never existed). Destroying/recreating the requester entity does NOT reset pity; the singleton persists across all requesters in the world. Persist it in save data via DOTSProgression.Persistence if continuity across sessions is required.
  • ItemPityRoller ≠ RarityRoller — ItemPityRoller rerolls the same item id after consecutive draws (anti-streak). RarityRoller forces a min rarity tier after N sub-tier draws (gacha-style hard pity). Both live in DOTSInventory.Loot. Don’t conflate them — they answer different design problems and require different state shapes (LootPityTracker buffer vs. a single int drawsSinceMinTier counter).
  • GachaWeightedRoll needs using Random = Unity.Mathematics.Random; — any DOTSInventory.Loot consumer file that imports both Unity.Mathematics and System must add this alias; the bare Random token is ambiguous (CS0104). The library source itself dropped using System; in v4.0.0 (shims removed), but consumer files that retain using System; for other reasons still need the alias when calling GachaWeightedRoll.Roll.
  • Loot rollers delegate to DOTSCore.WeightedSampler — don’t re-implement cumulative-sum sampling. RarityRoller, WeightedRarityRoll, and GachaWeightedRoll all build a temp NativeArray<float> and call WeightedSampler.Sample(in weights, ref rng). See § “Weighted-sampling SSOT” above. Adding a parallel hand-rolled sampler is an SSOT violation.
  • UpdatePityTracker mutates the buffer in place — the ref DynamicBuffer<LootPityTracker> argument captures the buffer reference. Do NOT call it inside a job that has structural changes scheduled between OnUpdate ticks; structural changes invalidate buffer references. Always run it on the main thread inside the same ISystem.OnUpdate slice as the roll.
  • GachaWeights static class and all GachaConstants public shims removed (v4.0.0). GachaWeights.COMMON_WEIGHT_PERCENT / .RARE_WEIGHT_PERCENT / .EPIC_WEIGHT_PERCENT and the public GachaConstants.COMMON_PCT / RARE_PCT / EPIC_PCT / PITY_RARE_AFTER_N_COMMONS / FTUE_FIRST_PULL_ITEM_ID constants no longer exist. Migrate: bake a GachaConfig singleton in your demo’s SubScene authoring and set the weight/pity/FTUE fields there. GachaWeightedRoll.ResolveItemId(...) is also removed — use GachaItemResolverBridge.Instance.ResolveItemId(rarity, seed) instead. See references/gacha-loot-api.md.
  • The stat dirty flag is DOTSCore.DirtyTag, NOT a per-package StatsDirtyTag/InventoryDirtyTag. DOTSCore.StatsDirtyTag is now [Obsolete] and the canonical shared enableable flag is DOTSCore.DirtyTag. Inventory stat recompute is one SSOT chain: the baker bakes DirtyTag enabled, the consumer (DerivedStatsSystem) recomputes it — the disable is a separate OrderLast clear system, DirtyTagClearSystem, which disables it only after a successful recalc, NOT DerivedStatsSystem itself — and every inventory producer that changes equipped items / passives / set membership must raise the SAME DOTSCore.DirtyTag so the recompute fires. The inventory producers are EquipmentSystem, ItemSetBonusSystem, and PassiveEffectSystem (plus GridPlacementSystem/PickupSystem on placement changes) — each calls SetComponentEnabled<DirtyTag>(entity, true) after mutating the StatModifier buffer. A producer that forgets to raise DirtyTag causes a silent stat-miss — the equipped/passive/set bonus lands in the buffer but DerivedCombatStats never recomputes. When adding a new modifier-writing inventory system, raising DirtyTag is part of the contract.