t1k:unity:dots-combat:puzzle

Field	Value
Module	`dots-combat`
Version	`2.3.8`
Effort	`high`
Tools	—

Keywords: DOTS, game mechanics, puzzle

How to invoke

/t1k:unity:dots-combat:puzzle

DOTS Puzzle Package Reference

Package: com.the1studio.dots-puzzle | Namespace: DOTSPuzzle

Related skills: dots-ecs-core, dots-rpg, dots-inventory-grid, puzzle-game-design

When This Skill Triggers

Using DOTSPuzzle.* namespace
Creating or querying BoardConfig, BoardCell, PieceData, PieceGridPosition
Implementing match detection, cascade chains, scoring
Adding special pieces (bomb, row-clear, rainbow)
Configuring CascadeState machine transitions
Working with SwapRequest, SwapResult, FallSystem

Component Quick Reference

Board Layer

Component	Type	Fields
`BoardConfig`	IComponentData (singleton)	`int Width, Height, PieceTypeCount`
`BoardCell`	IBufferElementData (singleton)	`Entity PieceEntity, byte IsOccupied`
`CascadeState`	IComponentData (singleton)	`CascadePhase Phase, int IterationCount`
`ScoreState`	IComponentData (singleton)	`int TotalScore, int ComboMultiplier, int ChainCount`

Piece Layer

Component	Type	Fields
`PieceData`	IComponentData	`byte PieceType, PieceSpecialType SpecialType`
`PieceGridPosition`	IComponentData	`int GridX, GridY`
`PieceVisualState`	IComponentData	`float3 VisualPosition, float Scale, float Alpha`
`FallingTag`	IEnableableComponent	— piece is falling
`MatchedTag`	IEnableableComponent	— part of a match
`PieceDestroyedTag`	IEnableableComponent	— scheduled removal

Event Layer

Component	Type	Fields
`SwapRequest`	IComponentData	`int2 FromPos, int2 ToPos`
`SwapResult`	IComponentData	`bool IsValid, int MatchCount`
`ScoreEvent`	IBufferElementData (singleton)	`int Points, int2 GridPos, ScoreReason Reason`

System Ordering (PuzzleSystemGroup)

PuzzleSystemGroup (SimulationSystemGroup)
  InputSystem            [OrderFirst]
  SwapValidationSystem   [UpdateAfter(Input)]
  SwapExecutionSystem    [UpdateAfter(Validation)]
  MatchDetectionSystem   [UpdateAfter(Swap)]
  CascadeControlSystem   [UpdateAfter(Match)]
  PieceFallSystem        [UpdateAfter(Cascade)]
  BoardRefillSystem      [UpdateAfter(Fall)]
  ScoringSystem          [UpdateAfter(Cascade)]
  VisualSyncSystem       [OrderLast]

Common Patterns

// Trigger a swap
ecb.CreateEntity().AddComponent(new SwapRequest { FromPos = new int2(2,3), ToPos = new int2(3,3) });

// Read board state
var cells = SystemAPI.GetBuffer<BoardCell>(boardSingleton);
var config = SystemAPI.GetComponent<BoardConfig>(boardSingleton);
var pieceEntity = cells[gridY * config.Width + gridX].PieceEntity;

// Check cascade phase before accepting input
var cascade = SystemAPI.GetComponent<CascadeState>(boardSingleton);
if (cascade.Phase == CascadePhase.Idle) { /* safe */ }

Key Conventions

Board grid positions: int2 — never use float2 for grid logic
BoardCell flat array index: y * Width + x
MatchedTag, PieceDestroyedTag, FallingTag are IEnableableComponent — never add/remove, only SetComponentEnabled
CascadeControlSystem uses SystemBase (not ISystem) — two-pass ECB in same frame
Never write to BoardCell outside SwapExecutionSystem, PieceFallSystem, BoardRefillSystem

See cascade-scoring-guide.md for state machine, scoring formula, special pieces, and gotchas.

QueuePuzzle Module (Queue-to-Grid Puzzles)

Sub-namespace: DOTSPuzzle.QueuePuzzle — generic queue-to-grid puzzle systems (NOT game-specific).

Core Loop

Player taps queue lane → batch created → characters spawn → move to cells → fill → grid shifts → evaluate win/lose.

Components

Game State: QueuePuzzleGameState (singleton, int Phase), QueuePuzzleResult, QueuePuzzleTransitionRequest
Grid Extensions: FillableCellTag, ObstacleCellTag, CellColorRequirement, CellReserved, GridVisibilityWindow, CellJustFilled
Queue: QueueLaneTag, QueueBlock (buffer), QueueSelectionRequest
SharedList: SharedListConfig, PendingBatch (buffer)
Character: CharacterData, CharacterTargetCell, CharacterMoving, CharacterArrived
Settlement: SettlementState (counter-based)

Systems (in QueuePuzzleSystemGroup)

QueueSelectionSystem → SharedListSpawnSystem → CharacterMovementSystem → GridFillSystem → NeighborEffectSystem → SettlementTrackingSystem → GridShiftSystem → ResultEvaluationSystem → QueuePuzzlePhaseTransitionSystem (OrderLast)

Phase Constants (in PuzzleConstants)

QueuePuzzlePhaseIdle=10, Dispatching=11, Moving=12, Settling=13, Shifting=14, Evaluating=15

Key Convention

NEVER use game-specific names in library code. “QueuePuzzle” is generic. Demo-specific names (ColorFit, etc.) belong only in Assets/Demos/.

Gotchas

PuzzleVisualConfig base class is missing from the library — 5 puzzle demos each define a local PuzzleVisualConfig ScriptableObject for cell size, gap, tile sprites, and color palettes. These are nearly identical. A shared DOTSPuzzle.PuzzleVisualConfig base class with virtual overrides per puzzle type belongs in com.the1studio.dots-puzzle. Until extracted, keep demo-local configs but avoid copy-pasting — extract shared constants to PuzzleConstants. Source: review-260520-round5-extraction-skills.md §B P1

Reference Files

File	Content
cascade-scoring-guide.md	State machine, scoring formula, special pieces, gotchas

rules/library-feature-discovery-protocol.md — research the library 3× before implementing new functionality; always update this skill with what you find (or with the new code if you implement it)
rules/manual-correction-implies-skill-gap-unity.md — if you manually inject library/API knowledge into a teammate brief, that knowledge belongs in this skill, not the brief