Skip to content

t1k:unity:dots-core:puzzle

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

DOTS Puzzle Core — Board, Match, Cascade, Scoring

Section titled “DOTS Puzzle Core — Board, Match, Cascade, Scoring”

Package: com.the1studio.dots-puzzle — namespace DOTSPuzzle.* Related skills: t1k-unity-dots-core-ecs (API) · t1k-unity-dots-combat-puzzle (puzzle→combat bridge)

  • Implementing grid-based puzzle boards (match-3, polyomino, block-blast, slide, merge)
  • Writing match detection — 3-in-a-row, L/T shapes, combo chains
  • Building cascade / gravity systems after cell removal
  • Implementing swap, rotation, fill with seeded random
  • Connecting puzzle scoring to combat (see dots-combat-puzzle)

Regenerated against source 2026-08-23 — almost nothing in the previous table matched. The board is a per-cell-ENTITY model (BoardEntityMap is a flat NativeArray<Entity> mapping grid coordinates to cell entities), NOT a DynamicBuffer<BoardCell> on a single board entity as the previous version claimed throughout.

ComponentTypePurpose
BoardConfigIComponentData (singleton)int Width, Height, float CellSize, int ColorCount, uint RandomSeed — not GemTypeCount/Seed
BoardEntityMapIComponentData (singleton, IDisposable)NativeArray<Entity> Cells (row-major, y * Width + x), Width, Height — O(1) GetCell(x, y)/SetCell(x, y, entity). Allocated/disposed by BoardInitSystem
BoardCellIComponentData (per-cell entity — not a buffer)int GridX, GridY, int CellState (PuzzleConstants.CellState*: Empty/Filled/Blocked/Spawner)
PieceDataIComponentData (per-cell entity)int PieceType (0 = normal), int Color — both int, no enums, for Burst compat
MatchGroupIBufferElementData (cap 16, on board entity)int GroupId, MatchDirection (PuzzleConstants.MatchDirection*), PieceCount, Color — not CellIndex/Size
MatchResultIBufferElementData (cap 32, on board entity)Entity PieceEntity, int GridX, GridY, GroupId — per-matched-piece list; missing entirely from the previous table
ScoreIComponentData (singleton)int CurrentScore, HighScore — not PuzzleScore (never existed)
ComboMultiplierIComponentData (singleton)float Multiplier, DecayTimer — a separate singleton from Score, not fields on one PuzzleScore
ScoreEventIBufferElementData (cap 16)int Points, Source (PuzzleConstants.ScoreSource*: Match/Chain/Special) — drained each frame by ScoreCalculationSystem
CascadeStateIComponentData (singleton) [Obsolete]int Phase (PuzzleConstants.Phase*: Idle/PlayerSwap/MatchCheck/Destroy/Gravity/Spawn/Settle) — migrating to DOTSCore.GameFlow.PhaseMachine.CurrentPhaseId. Not CascadeStep (never existed)
PlayerSwapInputIComponentData, IEnableableComponent (singleton)int FromX, FromY, ToX, ToY — no HasInput field (converted from a bool HasInput latch in v5.0.0, library #360); ENABLED means pending. Raised via DOTSCore.PendingSignalSingleton.TryRaise from the managed input bridge, consumed by SwapInputSystem which disables it. Attach DISABLED — a default-enabled zero payload fires as a phantom on frame 1
SwapValidationIComponentData (singleton)bool IsValid, int FailReason (PuzzleConstants.SwapFail*), Entity FromEntity, ToEntity — written by SwapInputSystem. Not SwapRequest (never existed)
SwapInFlightIComponentData, IEnableableComponent (on board entity)Entity FromEntity, ToEntity, int2 From, int2 To — armed ENABLED by SwapExecuteSystem when a validated swap executes, read+disabled by SwapResolutionSystem after the post-swap match check; its PRESENCE (enabled or not) gates SwapResolutionSystem via WithPresent<SwapInFlight>. Not SwapInfo/SwapState (never existed)
SwapResultenum (byte)None=0, Matched=1, NoMatch=2, Rejected=3 — carried in SwapResultEvent; appended members only, never renumber. The zero value None makes a default-initialized event read as no outcome
SwapResultEventIBufferElementData (cap PuzzleConstants.SwapResultEventCapacity = 2, on board entity)SwapResult Result, int FailReason (PuzzleConstants.SwapFail*), int2 From, int2 To — one-frame event raised by SwapInputSystem (Rejected) and SwapResolutionSystem (Matched/NoMatch); cleared by PuzzleEventCleanupSystem
CascadeStepEventIBufferElementData (cap PuzzleConstants.CascadeStepEventCapacity = 1, on board entity)int ChainDepth, int MatchGroupCount, int ClearedPieceCount — one-frame event raised by MatchDestroySystem for every clear step so progress/milestone feedback need not poll/score; cleared by PuzzleEventCleanupSystem
BoardShuffledEventIBufferElementData (cap PuzzleConstants.BoardShuffledEventCapacity = 1, on board entity)int ShuffledPieceCount — one-frame event raised by BoardShuffleSystem when it reshuffles a deadlocked board (specials excluded from the count); cleared by PuzzleEventCleanupSystem
SpecialPieceTypeIComponentDataint Type (PuzzleConstants.Special*: None/Bomb/LineH/LineV/Rainbow/Lightning) — not an enum, and not SpecialGem/SpecialGemType (never existed)
SpecialPieceActivationIComponentData (tag), IEnableableComponentEnabled when a special piece is matched/swapped-with-another-special, to trigger its effect
UndoEntryIBufferElementData (cap 16, on board entity)int CommandType, Param0..Param3 — generic per-puzzle-type payload. Not UndoState (never existed; no BoardCell-buffer snapshot exists to store)
UndoRequestTag / UndoExecutedTagIComponentData (tags), IEnableableComponentRequest/ack signals for UndoSystem
BoardInitRequiredIComponentData (tag)Attach signal for BoardInitSystem; BoardAuthoring adds it, BoardInitSystem removes it after grid creation via ecb.RemoveComponent<BoardInitRequired>(...)
BufferSlot / BufferConfig / BufferOverflowTag—Queue-dispatch puzzle types only; BufferOverflowTag (enableable) fires when slot count ≥ capacity
DOTSCore.GridCoordinateIComponentData (dots-core)Logical grid position. Replaces this package’s own PieceGridPosition, which is [Obsolete] and attached by no library system anymore

SpecialGemType as a C# enum never existed — special-piece typing is an int (SpecialPieceType.Type) against PuzzleConstants.Special*, for the same Burst-compat reason PieceData avoids enums.

Regenerated from grep -rl "UpdateInGroup(typeof(PuzzleSystemGroup)" (18 real members — including 3 OrderFirst systems the naive closing-paren grep initially missed) — the previous table named 7 systems, of which 4 (SwapSystem, SpecialGemActivationSystem, CascadeSystem, ScoringSystem) never existed under those names at all. The “cascade” concept the old table collapsed into one CascadeSystem row is actually driven by CascadeControlSystem (the state machine) plus the phase-specific actors below it.

SystemGroupRole
BoardInitSystemPuzzleSystemGroup, OrderFirst=trueOne-shot: creates board grid entities from BoardConfig, each with BoardCell+PieceData+GridCoordinate; builds the BoardEntityMap singleton
SwapInputSystemPuzzleSystemGroup, OrderFirst=trueValidates PlayerSwapInput (adjacency, bounds, cell state) only when cascade is Idle; writes SwapValidation; raises SwapResultEvent (Rejected) on refusal; transitions to PlayerSwap phase
PuzzleEventCleanupSystemPuzzleSystemGroup, OrderFirst=trueOne-frame buffer clearer for SwapResultEvent, CascadeStepEvent, BoardShuffledEvent — runs before every producer so each event lives exactly until the next group update; built on EventCleanupHelper.ClearBuffer<T>
CascadeControlSystemPuzzleSystemGroup, OrderFirst=trueState-machine controller for the cascade loop. Handles PlayerSwap→MatchCheck and resets chain count entering Settle; every OTHER phase transition is driven by the acting system itself (see act-before-set Gotcha below)
SwapExecuteSystemPuzzleSystemGroup, [UpdateAfter(CascadeControlSystem)]Executes a validated swap: exchanges PieceData between the two cells via PieceExchange, ARMS SwapInFlight (enabled) so SwapResolutionSystem can keep or revert it, transitions to MatchCheck
SwapResolutionSystemPuzzleSystemGroup, [UpdateAfter(MatchDetectionSystem)] [UpdateBefore(BoardShuffleSystem)]On the first match check after an armed swap: keeps the swap if matched (phase Destroy), or swaps it back via PieceExchange if no match (phase Settle) — the standard match-3 no-match revert; raises SwapResultEvent (Matched/NoMatch), then DISARMS SwapInFlight. Only acts while SwapInFlight is present (WithPresent), not enabled, so idle frames never enter
MatchDetectionSystemPuzzleSystemGroup, [UpdateAfter(MatchDestroySystem)] [UpdateBefore(BoardShuffleSystem)]Scans the board for horizontal/vertical matches during MatchCheck; populates MatchResult+MatchGroup; transitions to Destroy (found) or Settle (none)
PatternMatchSystemPuzzleSystemGroup, [UpdateBefore(MatchDestroySystem)]Detects T/L/cross shapes from existing match groups during Destroy, marks pieces for special-piece creation
SpecialPieceCreationSystemPuzzleSystemGroup, [UpdateAfter(PatternMatchSystem)] [UpdateBefore(MatchDestroySystem)]Configures special-piece properties (blast radius, line width) for pieces PatternMatchSystem marked, before destroy consumes them
MatchDestroySystemPuzzleSystemGroupDestroys matched pieces (marks cells Empty), generates ScoreEvents, preserves special pieces (they become the special), raises CascadeStepEvent per clear step, transitions to Gravity
SpecialPieceEffectSystemPuzzleSystemGroup, [UpdateAfter(MatchDestroySystem)]Executes special-piece effects on SpecialPieceActivation enabled: Bomb (NxN clear), LineH/V (row/column clear), Rainbow (all-of-one-color clear), Lightning (random 20% clear)
PieceGravitySystemPuzzleSystemGroupMoves pieces down to fill empty cells during Gravity; per-column parallel job (disjoint columns via BoardEntityMap), sequential bottom-to-top within a column
PieceSpawnSystemPuzzleSystemGroupSpawns new pieces in empty cells during Spawn, top-row-first, colors from the board’s random seed
BoardSettleSystemPuzzleSystemGroupDetects when all pieces stopped moving (placeholder for visual animation — the logical cascade uses instant transitions managed by CascadeControlSystem)
DeadlockDetectionSystemPuzzleSystemGroupOn cascade settling to Idle: checks whether any valid swap exists; if none, enables DirtyTag on the board entity to trigger a shuffle
BoardShuffleSystemPuzzleSystemGroupOn DirtyTag enabled (deadlock): Fisher-Yates shuffle on colors, preserves special pieces in place, raises BoardShuffledEvent, transitions to MatchCheck
ScoreCalculationSystemPuzzleSystemGroupProcesses the ScoreEvent buffer, applies ComboMultiplier, accumulates into Score.CurrentScore; clears events after processing. Guards RequireForUpdate<Score>/<ComboMultiplier>/<BoardConfig> AND HasBuffer<ScoreEvent> before reading — not ScoringSystem (never existed)
ComboDecaySystemPuzzleSystemGroupDecays ComboMultiplier.DecayTimer while cascade is idle; resets multiplier to base on expiry
UndoSystemPuzzleSystemGroupOn UndoRequestTag enabled: pops the last UndoEntry, enables UndoExecutedTag for puzzle-type-specific reversal, disables the request. Does NOT decode the entry itself — reversal is per-puzzle-type. Enforces MaxDepth by trimming oldest entries
BufferOverflowDetectionSystemPuzzleSystemGroupCounts non-empty BufferSlots against BufferConfig.Capacity; enables/disables BufferOverflowTag — queue-dispatch puzzle types only

Board layout — per-cell entities via BoardEntityMap, ROW-major, not column-major

Section titled “Board layout — per-cell entities via BoardEntityMap, ROW-major, not column-major”
// GridMath.FlatIndex (DOTSCore) is the SSOT formula, shared with dots-inventory and
// dots-puzzlemodes: y * Width + x. There is no per-board DynamicBuffer<BoardCell> to
// index at all — each cell is its own entity, looked up via the BoardEntityMap singleton.
var map = SystemAPI.GetSingleton<BoardEntityMap>();
Entity cellEntity = map.GetCell(x, y); // O(1), bounds-checked in editor builds
var cell = cellLookup[cellEntity]; // BoardCell.CellState
var piece = pieceLookup[cellEntity]; // PieceData.Color / .PieceType

Match detection — phase-gated, board-entity buffers

Section titled “Match detection — phase-gated, board-entity buffers”
// MatchDetectionSystem — only acts during PhaseMatchCheck (read via PhaseMachine,
// dots-core.GameFlow — CascadeState.Phase is the [Obsolete] predecessor):
var phase = SystemAPI.GetSingleton<PhaseMachine>();
if (phase.CurrentPhaseId != PuzzleConstants.PhaseMatchCheck) return;
// Scans horizontal + vertical runs of MinMatchLength+ (from MatchPatternConfig) across
// the board via BoardEntityMap, populating MatchResult (per-piece) and MatchGroup
// (per-group metadata) buffers on the board entity — the entity carrying BoardConfig.
// Transitions the phase to Destroy if any match found, Settle otherwise.

Cascade — a phase state machine, not one CascadeSystem

Section titled “Cascade — a phase state machine, not one CascadeSystem”
// There is no single "CascadeSystem". CascadeControlSystem is the state-machine
// controller (OrderFirst) but most transitions are driven by the ACTING system for
// that phase, per the act-before-set ordering rule (see Gotchas):
// Idle -> (player input) SwapInputSystem validates + arms PlayerSwapInput
// PlayerSwap -> SwapExecuteSystem executes the swap, ARMS SwapInFlight, → MatchCheck
// MatchCheck -> MatchDetectionSystem (→ Destroy if matched) or → Settle if not
// SwapResolutionSystem reads the match check, KEEPS or SWAPS BACK
// the swap, raises SwapResultEvent, DISARMS SwapInFlight
// Destroy -> PatternMatchSystem -> SpecialPieceCreationSystem -> MatchDestroySystem
// -> SpecialPieceEffectSystem (transitions to Gravity)
// MatchDestroySystem raises one CascadeStepEvent per clear step
// Gravity -> PieceGravitySystem (per-column parallel job, disjoint columns)
// Spawn -> PieceSpawnSystem (top-row-first, board's RandomSeed)
// Settle -> BoardSettleSystem -> DeadlockDetectionSystem (shuffle if no valid swap)
// BoardShuffleSystem raises BoardShuffledEvent
//
// All three one-frame event buffers (SwapResultEvent, CascadeStepEvent, BoardShuffledEvent)
// are cleared by PuzzleEventCleanupSystem at OrderFirst — before every producer.
// PieceSpawnSystem colors new pieces from BoardConfig.RandomSeed — the same seed
// reproduces the same fill sequence across runs (deterministic/replay-safe), matching
// the RandomSeed-mixing discipline documented in the Gotchas below for PieceSpawnSystem.
DirectionPackageDetail
Depends onDOTSCore baseGridMath.FlatIndex (row-major SSOT), ECB, SystemAPI, Random, DOTSCore.GameFlow.PhaseMachine, DOTSCore.GameFlow.CascadeState (obsolete)
Depends onDOTSCore bridgesIDirtyTagBridge — DOTSCore.DirtyTag (see dots-core:dirty-tags)
UsesDOTSBridges.AudioAudioEventType.Clear (13) on every clear step, AudioEventType.Milestone (14) on combo/chain thresholds; drained by AudioDrainSystem (LateSimulation)
Used byDOTSPuzzleCombatMatchGroup.PieceCount → elemental damage pipeline (not MatchGroup.Size — never existed); reads MatchResult before MatchDestroySystem clears it (exactly-once barrier)
Used byMatch3RPGDemoBoard drives combat; each PieceData.Color maps to an element
Used byColorFitDemoQueue-to-grid dispatch uses BoardCell + SwapInputSystem/SwapExecuteSystem/SwapResolutionSystem (full three-system swap pipeline, not a single SwapSystem)

The identifiers below are corrected to real system/component names (2026-08-23); the per-demo variation claims themselves are illustrative and were not re-verified against every demo’s source in this pass.

TypeKey variation
Match-3MatchDetectionSystem for runs; PatternMatchSystem for L/T/cross shape detection (not MatchGroup.Size >= 4 — the real field is PieceCount)
PolyominoPlayerSwapInput/SwapValidation (not a SwapRequest component) replaced by a placement system; cell↔entity mapping is BoardEntityMap, not a BoardCell.CellEntity field (never existed)
Block-blastRow/column clear on match; SpecialPieceType.Type = LineH/LineV (int constants, not an enum SpecialGemType.LineBlast — never existed)
Slide-mergeDirectional PieceGravitySystem variant; PieceData.Color doubles on collision (not a GemType field — never existed)
MergeGravity-phase pipeline runs after drop, not continuous gravity; merge on adjacency
Tube sortBoardConfig encodes tube columns; match = full monochrome tube
Queue dispatchBufferSlot/BufferConfig queue components; dispatch via SwapInputSystem/SwapExecuteSystem to target cells (not SwapSystem — never existed)

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

Normative rules kept inline:

  • Act-before-set: phase-gated cascade systems MUST be explicitly ordered, or single-Update phase tests silently break — The puzzle cascade pipeline is a phase state machine (PhaseMatchCheck → PhaseDestroy → PhaseGravity → …). Each system is gated to one phase and the EditMode tests run a SINGLE World.Update() then assert the intermediate phase. The invariant: the system that ACTS on a phase must run BEFORE the system that SETS (transitions into) that phase, so a freshly-set phase is NOT consumed in the same frame (which would skip ahead one or more phases and fail the assertion). Concretely: