Skip to content

t1k:unity:dots-core:puzzle-modes

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

DOTS Puzzle Modes — 8 Genre Modes on DOTSPuzzle Core

Section titled “DOTS Puzzle Modes — 8 Genre Modes on DOTSPuzzle Core”

Package: com.the1studio.dots-puzzlemodes — namespace root DOTSPuzzleModes.* Depends on: DOTSPuzzle (board/BoardEntityMap/PuzzleSystemGroup/PuzzleConstants), DOTSCore Evacuated from: dots-puzzle Wave 3 — [MovedFrom] aliases keep consumer builds green Related skills: t1k-unity-dots-core-puzzle (board core, match, cascade, scoring) · t1k-unity-dots-core-ecs API reference: references/api-surface.md

  • Implementing any of the 8 genre modes: Merge (Dragon City style), Slide (2048), Sort (Water Sort / Screw), Traffic (Parking Jam), TrayMatch (Triple Match 3D), Placement (Block Blast), QueuePuzzle (queue-to-grid dispatch)
  • Adding RandomSeed-driven deterministic tile spawn to a puzzle mode
  • Using LayerAccessibilityUtility for depth-layer accessibility gating (Screw Sort, TrayMatch)
  • Reading or writing a *Phase singleton to drive puzzle game-state transitions
  • Bridging puzzle-mode results to combat (see dots-puzzle-combat skill)

Every mode follows the same three-singleton structure baked from a SubScene authoring component:

Singleton patternComponentPurpose
ConfigMergeConfig, SlideConfig, SortConfig, …Grid dims, limits, RandomSeed
PhaseMergePhase, SlidePhase, SortPhase, …Int phase from PuzzleConstants.*Phase*
ResultMergeResult, SlideResult, SortPourResult, …Score / outcome tracking
ModeNamespaceKey configKey phaseBoard unit
MergeDOTSPuzzleModes.MergeMergeConfig (GridWidth/Height, MaxTier, RandomSeed)MergePhaseMergeItem per cell
SlideDOTSPuzzleModes.SlideSlideConfig (GridSize, SpawnChance4, WinValue, RandomSeed)SlidePhaseSlideTile per cell
Sort (Water)DOTSPuzzleModes.SortSortConfig (TubeCount, UnitsPerTube, ColorCount, RandomSeed)SortPhaseSortUnit buffer on tube entity
Sort (Screw)DOTSPuzzleModes.Sortsame namespace, ScrewData + ColorBox entities—ScrewData per screw, ColorBox per color
TrafficDOTSPuzzleModes.TrafficTrafficConfig (GridWidth/Height, MoveLimit)TrafficPhaseVehicle + VehiclePosition per car
TrayMatchDOTSPuzzleModes.TrayMatchTrayMatchConfig (TrayCapacity=7, MatchCount=3)TrayMatchPhaseTileData per pile tile; TraySlot buffer
PlacementDOTSPuzzleModes.PlacementPlacementConfig (GridWidth/Height, PiecesPerBatch, RandomSeed)PlacementPhasePlacementPiece buffer; LineClearResult buffer
QueuePuzzleDOTSPuzzleModes.QueuePuzzleSharedListConfig (MaxCapacity)QueuePuzzleGameStateCharacterData per unit, QueueBlock buffer per lane
// 1. Read config singleton (baked by Authoring in SubScene):
var cfg = SystemAPI.GetSingleton<SlideConfig>();
// 2. Check phase before acting:
var phase = SystemAPI.GetSingleton<SlidePhase>();
if (phase.Phase != PuzzleConstants.SlidePhaseWaitingInput) return;
// 3. Write result:
var result = SystemAPI.GetSingleton<SlideResult>();
result.TotalScore += mergeScore;
SystemAPI.SetSingleton(result);
// 4. Advance phase:
SystemAPI.SetSingleton(new SlidePhase { Phase = PuzzleConstants.SlidePhaseSpawning });
  • RandomSeed must come from SlideConfig.RandomSeed (or equivalent) — never use Random.CreateFromIndex(0) or a frame-time seed. SlideSpawnSystem mixes config.RandomSeed with a per-spawn counter via DeterministicRandom.MixSeed(seed, counter + 1u) to produce avalanche-separated seeds. Seeding from ElapsedTime or a bare 0 produces identical spawn sequences across replays and breaks deterministic testing. Same pattern applies to MergeConfig.RandomSeed, SortConfig.RandomSeed, PlacementConfig.RandomSeed.
  • [MovedFrom] aliases are shims, not source truth. All 8 namespaces carry [MovedFrom(sourceNamespace: "DOTSPuzzle.*")] so old consumer assemblies still compile, but the REAL types live in DOTSPuzzleModes.*. Write new code against DOTSPuzzleModes.* directly.
  • LayerAccessibilityUtility (namespace DOTSPuzzleModes.Common) is shared plumbing for both ScrewAccessibilitySystem (Sort) and TileAccessibilitySystem (TrayMatch). Use AccumulateMin + IsAccessibleMin for Screw (outermost layer = min index); use AccumulateMax + IsAccessibleMax for TrayMatch (topmost tile = max layer). Do NOT reimplement this per-system.
  • SortUnit.Color == 0 means empty (matches PuzzleConstants.SortColorEmpty). Index 0 is reserved — don’t assign color 0 to a real unit.
  • TileData.LayerIndex is 0 = bottom of pile. Accessibility is the HIGHEST layer (IsAccessibleMax), not the lowest. Inverting the rule shows all tiles as accessible.
  • Vehicle occupied cells are derived, not stored. For horizontal: columns HeadX to HeadX + Length - 1 at row HeadY. For vertical: rows HeadY to HeadY + Length - 1 at column HeadX. Never store a separate occupancy list.
  • All 8 modes run inside PuzzleSystemGroup (from DOTSPuzzle). Add [UpdateInGroup(typeof(PuzzleSystemGroup))] on any new mode-specific system; omitting it leaves the system running in SimulationSystemGroup and breaking phase ordering.
  • PlacementPiece is a buffer on the board entity, not per-cell. LineClearResult is also a buffer, drained each frame by LineClearSystem. Do not query for LineClearResult as a singleton.
  • QueueBlock.BlockType uses PuzzleConstants.BlockType* constants — check those constants before adding new block types; duplicating a value produces silent dispatch-routing bugs.