t1k:unity:dots-inventory:grid
| Field | Value |
|---|---|
| Module | dots-inventory |
| Version | 3.29.3 |
| Effort | medium |
| 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
How to invoke
Section titled “How to invoke”/t1k:unity:dots-inventory:gridDOTS Inventory Grid — Grid, Crafting, Passives, Sets, Loot
Section titled “DOTS Inventory Grid — Grid, Crafting, Passives, Sets, Loot”Package:
com.the1studio.dots-inventory— namespaceDOTSInventory.*Related skills:t1k-unity-dots-core-ecs(API) ·t1k-unity-dots-combat-rpg(stats pipeline) ·t1k-unity-dots-core-ecs(ECB)
When This Skill Triggers
Section titled “When This Skill Triggers”- 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
Quick Reference
Section titled “Quick Reference”| Topic | Reference File |
|---|---|
Grid / passive / set-bonus components + InventorySystemGroup ordering — InventoryGridDimension, ItemGridShape, ItemRotation, ItemShapeMask, PassiveCondition, SetBonusDefinition, InventoryGridUtility placement API | references/grid-components-and-ordering.md |
| Placement / passives / sets / gotchas — deep dives | grid-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 |
Public Components
Section titled “Public Components”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.
| Component | Type | Purpose |
|---|---|---|
InventoryGridCell | IBufferElementData (cap 0) | Entity ItemEntity, byte IsActive (1=usable, 0=inactive expansion slot); 1D buffer represents 2D grid |
InventoryGridDimension | IComponentData | int GridWidth, GridHeight — not InventoryGridConfig (never existed) |
InventorySlot | IBufferElementData | Entity ItemEntity, int StackCount — one occupied slot |
Item | IComponentData | int ItemId, ItemType Type, ItemRarity Rarity, int StackMax — core item identity |
CraftingRecipeEntry | Blob 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 |
CraftingIngredient | IBufferElementData | int RecipeId, ItemId, byte RequiredCount — not int ItemTypeId, int Quantity |
CraftingState | IComponentData | int ActiveRecipeId, float Progress |
ItemPassiveEffect | IBufferElementData (cap 4) | StatType Stat, ModifierType ModType, float Value, PassiveCondition Condition — not int StatId, PassiveOp Op (neither type exists) |
SetBonusDefinition | IBufferElementData | int SetId, RequiredCount, StatType BonusStat, ModifierType BonusModType, float BonusValue — not ItemSetBonus (never existed) |
SetBonusEntry | Blob entry (in SetBonusBlob) | Same shape as SetBonusDefinition, Burst-readable; ItemSetBonusSystem iterates the blob directly, not by binary lookup |
EquippedItem | IBufferElementData | Entity ItemEntity, EquipSlotType SlotType — not int SlotIndex |
LootTableEntry | IBufferElementData (cap 2) | int ItemId, float DropRate (independent 0..1 roll per entry), MinCount, MaxCount, ItemType Type, ItemRarity Rarity, int StackMax — consumed by LootDropSystem |
LootTable | IBufferElementData (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 |
LootPityTracker | IBufferElementData (cap 4) | int ItemId, int ConsecutiveDrops; per-player anti-streak state |
GachaChestRequest | IBufferElementData (DOTSInventory.Loot) | GachaSource Source, uint Seed, Entity Requester — queued pull request, drained by GachaChestSystem |
GachaPullResult | IComponentData (DOTSInventory.Loot) | int ItemId, GachaRarity Rarity, uint SeedUsed — written onto the requester entity. Not a spawned item entity |
GachaPityTracker | IComponentData (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.
Public Systems
Section titled “Public Systems”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).
| System | Group | Role |
|---|---|---|
PickupSystem | InventorySystemGroup ([UpdateAfter(InventoryRespawnResetSystem)]) | Collectors pick up nearby items via a persistent SpatialHashGrid (O(N+M), not O(N·M)) |
GridPlacementSystem | InventorySystemGroup ([UpdateAfter(PickupSystem)] [UpdateBefore(EquipmentSystem)]) | Auto-places unplaced items on EquipmentDirtyTag; rect (ItemGridShape) or polyomino (ItemShapeMask) placement. Not InventoryGridPlacementSystem (never existed) |
PassiveEffectSystem | InventorySystemGroup ([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) |
EquipmentSystem | InventorySystemGroup ([UpdateAfter(PickupSystem)]) | Syncs equipment stat bonuses (EquipmentStatBonus) to StatModifier; only on EquipmentDirtyTag enabled, then disables it |
EquipmentSubStatRollSystem | InventorySystemGroup ([UpdateAfter(EquipmentSystem)]) | Rolls per-item substats from SubStatPoolBlob on first encounter with SubStatRollPending; deterministic from RunScopeSingleton.RunSeed hashed with Item.ItemId + slot |
ItemSetBonusSystem | InventorySystemGroup ([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) |
CraftingSystem | InventorySystemGroup | Ticks 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 |
LootTableSystem | InventorySystemGroup ([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 |
LootDropSystem | InventorySystemGroup, OrderLast = true | On 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 |
GachaChestSystem | SimulationSystemGroup — 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.
Common Patterns
Section titled “Common Patterns”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).
Cross-Package Interactions
Section titled “Cross-Package Interactions”| Direction | Package | Detail |
|---|---|---|
| Depends on | DOTSCore base | LocalTransform, ECB, SystemAPI |
| Depends on | DOTSCore.Stats | DerivedCombatStats that passive rollup writes into |
| Used by | DOTSCombat | Combat reads inventory passives for derived stats |
| Future split | dots-economy | CurrencyWallet moving to dots-economy in Wave 2 |
Demo Precedents
Section titled “Demo Precedents”- BackpackCrawler — polyomino grid, drag-drop, set bonuses, loot drops per room,
ItemPityRollerreference impl (CrawlerLootTable.GetRandomLootWithPity) - InventoryDemo — grid showcase with passive rollup and crafting UI
- AutoBattlerDemo — draft shop uses
GachaChestSystem/GachaRaritytiers for unit reveal (GachaEntrynever existed as a type) - ChaosForgeDemo — forge-roll loop (
ForgeRollSystem) consumesItemPityRollerfor anti-streak protection (W2.6)
Hard rules
Section titled “Hard rules”- 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(notSetBonusEvaluationSystem— never existed) clears and re-evaluates onEquipmentDirtyTag, 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
CurrencyWalletinsideDOTSInventory.*code; route through the incomingDOTSEconomy.Walletcomponent instead. Existing references are flagged[Obsolete]pending migration. PassiveEffectSystem(notPassiveEffectRollupSystem— never existed) already gates onEquipmentDirtyTag, not every frame. There is no separateInventoryDirtyTag— the real enableable flag isEquipmentDirtyTag, shared withEquipmentSystem/ItemSetBonusSystem/GridPlacementSystem. A producer that changes equipped items/passives/set membership must enableEquipmentDirtyTagitself, or the rebuild silently never fires.- Loot seeds come from
DOTSCore.Time.SimTick, NEVERElapsedTime(fixed The1Studio/unity-dots-library#118). BothLootTableSystemandLootDropSystemseed their rolls withmath.max((uint)entity.Index + simTick + salt, LootSpawnUtility.SeedMinimum), wheresimTickis read viaSystemAPI.HasSingleton<DOTSCore.Time.SimTick>() ? SystemAPI.GetSingleton<DOTSCore.Time.SimTick>().Value : 0u. SimTick is a deterministic per-frame uint counter (increments by exactly 1 perSimTickSystemupdate, 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) + saltformula it replaced. The old ElapsedTime-derived seed was framerate- AND machine-dependent: identical inputs on different hardware produced different loot rolls, and thedoubleintermediate silently folded to 0 (degenerating the RNG seed) after ~49.7 days. The SimTick salt degrades to0uin a hermetic test world that never wiresSimTickSysteminto its group, matching that singleton’s own self-heal contract.LootSpawnConfig.TimeToSeedScaleandLootSpawnUtility.TimeToSeedScaleare untouched but UNREAD — retained only so the wire/save shape doesn’t change for consumers that bake/serialize the config. Do not seed RNG fromSystemAPI.Time.ElapsedTime,WorldClock, orSystemState.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 noGachaPullSystem(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 viaDOTSProgression.Persistenceif continuity across sessions is required.ItemPityRoller≠RarityRoller—ItemPityRollerrerolls the same item id after consecutive draws (anti-streak).RarityRollerforces a min rarity tier after N sub-tier draws (gacha-style hard pity). Both live inDOTSInventory.Loot. Don’t conflate them — they answer different design problems and require different state shapes (LootPityTrackerbuffer vs. a singleint drawsSinceMinTiercounter).GachaWeightedRollneedsusing Random = Unity.Mathematics.Random;— anyDOTSInventory.Lootconsumer file that imports bothUnity.MathematicsandSystemmust add this alias; the bareRandomtoken is ambiguous (CS0104). The library source itself droppedusing System;in v4.0.0 (shims removed), but consumer files that retainusing System;for other reasons still need the alias when callingGachaWeightedRoll.Roll.- Loot rollers delegate to
DOTSCore.WeightedSampler— don’t re-implement cumulative-sum sampling.RarityRoller,WeightedRarityRoll, andGachaWeightedRollall build a tempNativeArray<float>and callWeightedSampler.Sample(in weights, ref rng). See § “Weighted-sampling SSOT” above. Adding a parallel hand-rolled sampler is an SSOT violation. UpdatePityTrackermutates the buffer in place — theref 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 sameISystem.OnUpdateslice as the roll.GachaWeightsstatic class and allGachaConstantspublic shims removed (v4.0.0).GachaWeights.COMMON_WEIGHT_PERCENT/.RARE_WEIGHT_PERCENT/.EPIC_WEIGHT_PERCENTand the publicGachaConstants.COMMON_PCT/RARE_PCT/EPIC_PCT/PITY_RARE_AFTER_N_COMMONS/FTUE_FIRST_PULL_ITEM_IDconstants no longer exist. Migrate: bake aGachaConfigsingleton in your demo’s SubScene authoring and set the weight/pity/FTUE fields there.GachaWeightedRoll.ResolveItemId(...)is also removed — useGachaItemResolverBridge.Instance.ResolveItemId(rarity, seed)instead. See references/gacha-loot-api.md.- The stat dirty flag is
DOTSCore.DirtyTag, NOT a per-packageStatsDirtyTag/InventoryDirtyTag.DOTSCore.StatsDirtyTagis now[Obsolete]and the canonical shared enableable flag isDOTSCore.DirtyTag. Inventory stat recompute is one SSOT chain: the baker bakesDirtyTagenabled, the consumer (DerivedStatsSystem) recomputes it — the disable is a separateOrderLastclear system,DirtyTagClearSystem, which disables it only after a successful recalc, NOTDerivedStatsSystemitself — and every inventory producer that changes equipped items / passives / set membership must raise the SAMEDOTSCore.DirtyTagso the recompute fires. The inventory producers areEquipmentSystem,ItemSetBonusSystem, andPassiveEffectSystem(plusGridPlacementSystem/PickupSystemon placement changes) — each callsSetComponentEnabled<DirtyTag>(entity, true)after mutating theStatModifierbuffer. A producer that forgets to raiseDirtyTagcauses a silent stat-miss — the equipped/passive/set bonus lands in the buffer butDerivedCombatStatsnever recomputes. When adding a new modifier-writing inventory system, raisingDirtyTagis part of the contract.