t1k:unity:dots-core:puzzle
| Field | Value |
|---|---|
| Module | dots-core |
| Version | 3.56.1 |
| Effort | medium |
| Tools | — |
How to invoke
Section titled “How to invoke”/t1k:unity:dots-core:puzzleDOTS Puzzle Core — Board, Match, Cascade, Scoring
Section titled “DOTS Puzzle Core — Board, Match, Cascade, Scoring”Package:
com.the1studio.dots-puzzle— namespaceDOTSPuzzle.*Related skills:t1k-unity-dots-core-ecs(API) ·t1k-unity-dots-combat-puzzle(puzzle→combat bridge)
When This Skill Triggers
Section titled “When This Skill Triggers”- 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)
Public Components
Section titled “Public Components”Regenerated against source 2026-08-23 — almost nothing in the previous table matched. The board is a per-cell-ENTITY model (
BoardEntityMapis a flatNativeArray<Entity>mapping grid coordinates to cell entities), NOT aDynamicBuffer<BoardCell>on a single board entity as the previous version claimed throughout.
| Component | Type | Purpose |
|---|---|---|
BoardConfig | IComponentData (singleton) | int Width, Height, float CellSize, int ColorCount, uint RandomSeed — not GemTypeCount/Seed |
BoardEntityMap | IComponentData (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 |
BoardCell | IComponentData (per-cell entity — not a buffer) | int GridX, GridY, int CellState (PuzzleConstants.CellState*: Empty/Filled/Blocked/Spawner) |
PieceData | IComponentData (per-cell entity) | int PieceType (0 = normal), int Color — both int, no enums, for Burst compat |
MatchGroup | IBufferElementData (cap 16, on board entity) | int GroupId, MatchDirection (PuzzleConstants.MatchDirection*), PieceCount, Color — not CellIndex/Size |
MatchResult | IBufferElementData (cap 32, on board entity) | Entity PieceEntity, int GridX, GridY, GroupId — per-matched-piece list; missing entirely from the previous table |
Score | IComponentData (singleton) | int CurrentScore, HighScore — not PuzzleScore (never existed) |
ComboMultiplier | IComponentData (singleton) | float Multiplier, DecayTimer — a separate singleton from Score, not fields on one PuzzleScore |
ScoreEvent | IBufferElementData (cap 16) | int Points, Source (PuzzleConstants.ScoreSource*: Match/Chain/Special) — drained each frame by ScoreCalculationSystem |
CascadeState | IComponentData (singleton) [Obsolete] | int Phase (PuzzleConstants.Phase*: Idle/PlayerSwap/MatchCheck/Destroy/Gravity/Spawn/Settle) — migrating to DOTSCore.GameFlow.PhaseMachine.CurrentPhaseId. Not CascadeStep (never existed) |
PlayerSwapInput | IComponentData, 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 |
SwapValidation | IComponentData (singleton) | bool IsValid, int FailReason (PuzzleConstants.SwapFail*), Entity FromEntity, ToEntity — written by SwapInputSystem. Not SwapRequest (never existed) |
SwapInFlight | IComponentData, 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) |
SwapResult | enum (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 |
SwapResultEvent | IBufferElementData (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 |
CascadeStepEvent | IBufferElementData (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 |
BoardShuffledEvent | IBufferElementData (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 |
SpecialPieceType | IComponentData | int Type (PuzzleConstants.Special*: None/Bomb/LineH/LineV/Rainbow/Lightning) — not an enum, and not SpecialGem/SpecialGemType (never existed) |
SpecialPieceActivation | IComponentData (tag), IEnableableComponent | Enabled when a special piece is matched/swapped-with-another-special, to trigger its effect |
UndoEntry | IBufferElementData (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 / UndoExecutedTag | IComponentData (tags), IEnableableComponent | Request/ack signals for UndoSystem |
BoardInitRequired | IComponentData (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.GridCoordinate | IComponentData (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.
Public Systems
Section titled “Public Systems”Regenerated from
grep -rl "UpdateInGroup(typeof(PuzzleSystemGroup)"(18 real members — including 3OrderFirstsystems 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 oneCascadeSystemrow is actually driven byCascadeControlSystem(the state machine) plus the phase-specific actors below it.
| System | Group | Role |
|---|---|---|
BoardInitSystem | PuzzleSystemGroup, OrderFirst=true | One-shot: creates board grid entities from BoardConfig, each with BoardCell+PieceData+GridCoordinate; builds the BoardEntityMap singleton |
SwapInputSystem | PuzzleSystemGroup, OrderFirst=true | Validates PlayerSwapInput (adjacency, bounds, cell state) only when cascade is Idle; writes SwapValidation; raises SwapResultEvent (Rejected) on refusal; transitions to PlayerSwap phase |
PuzzleEventCleanupSystem | PuzzleSystemGroup, OrderFirst=true | One-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> |
CascadeControlSystem | PuzzleSystemGroup, OrderFirst=true | State-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) |
SwapExecuteSystem | PuzzleSystemGroup, [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 |
SwapResolutionSystem | PuzzleSystemGroup, [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 |
MatchDetectionSystem | PuzzleSystemGroup, [UpdateAfter(MatchDestroySystem)] [UpdateBefore(BoardShuffleSystem)] | Scans the board for horizontal/vertical matches during MatchCheck; populates MatchResult+MatchGroup; transitions to Destroy (found) or Settle (none) |
PatternMatchSystem | PuzzleSystemGroup, [UpdateBefore(MatchDestroySystem)] | Detects T/L/cross shapes from existing match groups during Destroy, marks pieces for special-piece creation |
SpecialPieceCreationSystem | PuzzleSystemGroup, [UpdateAfter(PatternMatchSystem)] [UpdateBefore(MatchDestroySystem)] | Configures special-piece properties (blast radius, line width) for pieces PatternMatchSystem marked, before destroy consumes them |
MatchDestroySystem | PuzzleSystemGroup | Destroys matched pieces (marks cells Empty), generates ScoreEvents, preserves special pieces (they become the special), raises CascadeStepEvent per clear step, transitions to Gravity |
SpecialPieceEffectSystem | PuzzleSystemGroup, [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) |
PieceGravitySystem | PuzzleSystemGroup | Moves pieces down to fill empty cells during Gravity; per-column parallel job (disjoint columns via BoardEntityMap), sequential bottom-to-top within a column |
PieceSpawnSystem | PuzzleSystemGroup | Spawns new pieces in empty cells during Spawn, top-row-first, colors from the board’s random seed |
BoardSettleSystem | PuzzleSystemGroup | Detects when all pieces stopped moving (placeholder for visual animation — the logical cascade uses instant transitions managed by CascadeControlSystem) |
DeadlockDetectionSystem | PuzzleSystemGroup | On cascade settling to Idle: checks whether any valid swap exists; if none, enables DirtyTag on the board entity to trigger a shuffle |
BoardShuffleSystem | PuzzleSystemGroup | On DirtyTag enabled (deadlock): Fisher-Yates shuffle on colors, preserves special pieces in place, raises BoardShuffledEvent, transitions to MatchCheck |
ScoreCalculationSystem | PuzzleSystemGroup | Processes 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) |
ComboDecaySystem | PuzzleSystemGroup | Decays ComboMultiplier.DecayTimer while cascade is idle; resets multiplier to base on expiry |
UndoSystem | PuzzleSystemGroup | On 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 |
BufferOverflowDetectionSystem | PuzzleSystemGroup | Counts non-empty BufferSlots against BufferConfig.Capacity; enables/disables BufferOverflowTag — queue-dispatch puzzle types only |
Common Patterns
Section titled “Common Patterns”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 buildsvar cell = cellLookup[cellEntity]; // BoardCell.CellStatevar piece = pieceLookup[cellEntity]; // PieceData.Color / .PieceTypeMatch 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.Seeded fill
Section titled “Seeded fill”// 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.Cross-Package Interactions
Section titled “Cross-Package Interactions”| Direction | Package | Detail |
|---|---|---|
| Depends on | DOTSCore base | GridMath.FlatIndex (row-major SSOT), ECB, SystemAPI, Random, DOTSCore.GameFlow.PhaseMachine, DOTSCore.GameFlow.CascadeState (obsolete) |
| Depends on | DOTSCore bridges | IDirtyTagBridge — DOTSCore.DirtyTag (see dots-core:dirty-tags) |
| Uses | DOTSBridges.Audio | AudioEventType.Clear (13) on every clear step, AudioEventType.Milestone (14) on combo/chain thresholds; drained by AudioDrainSystem (LateSimulation) |
| Used by | DOTSPuzzleCombat | MatchGroup.PieceCount → elemental damage pipeline (not MatchGroup.Size — never existed); reads MatchResult before MatchDestroySystem clears it (exactly-once barrier) |
| Used by | Match3RPGDemo | Board drives combat; each PieceData.Color maps to an element |
| Used by | ColorFitDemo | Queue-to-grid dispatch uses BoardCell + SwapInputSystem/SwapExecuteSystem/SwapResolutionSystem (full three-system swap pipeline, not a single SwapSystem) |
Supported Puzzle Types (7)
Section titled “Supported Puzzle Types (7)”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.
| Type | Key variation |
|---|---|
| Match-3 | MatchDetectionSystem for runs; PatternMatchSystem for L/T/cross shape detection (not MatchGroup.Size >= 4 — the real field is PieceCount) |
| Polyomino | PlayerSwapInput/SwapValidation (not a SwapRequest component) replaced by a placement system; cell↔entity mapping is BoardEntityMap, not a BoardCell.CellEntity field (never existed) |
| Block-blast | Row/column clear on match; SpecialPieceType.Type = LineH/LineV (int constants, not an enum SpecialGemType.LineBlast — never existed) |
| Slide-merge | Directional PieceGravitySystem variant; PieceData.Color doubles on collision (not a GemType field — never existed) |
| Merge | Gravity-phase pipeline runs after drop, not continuous gravity; merge on adjacency |
| Tube sort | BoardConfig encodes tube columns; match = full monochrome tube |
| Queue dispatch | BufferSlot/BufferConfig queue components; dispatch via SwapInputSystem/SwapExecuteSystem to target cells (not SwapSystem — never existed) |
Hard rules
Section titled “Hard rules”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 SINGLEWorld.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: