Skip to content

t1k:unity:dots-combat:puzzle-bridge

FieldValue
Moduledots-combat
Version3.33.3
Effortmedium
Tools—
/t1k:unity:dots-combat:puzzle-bridge

Package: com.the1studio.dots-puzzle-combat — namespace DOTSPuzzleCombat Depends on: com.the1studio.dots-puzzle (DOTSPuzzle.*) · com.the1studio.dots-combat (DOTSCombat/DOTSCore) Related skills: t1k-unity-dots-combat-puzzle (DOTSPuzzle API) · t1k-unity-dots-combat-rpg (Health, DamageType)

  • Wiring puzzle match results into enemy damage (match-3 RPG, Match3RPGDemo)
  • Configuring PuzzleCombatBridge singleton or GemDamageMapping buffer
  • Implementing enemy turn phases (Telegraph → Act → WaitForPlayer) above a puzzle board
  • Applying ComboMultiplier to aggregate match damage
  • Diagnosing double-apply or missed damage across MatchDestroySystem
FileContents
api-reference.md (references/api-reference.md)Full component/system table, singleton setup snippet, test world pattern

Renamed 2026-08-23 — PuzzleEnemy→PuzzleOpponent, EnemyTurnState→OpponentTurnState, EnemyTurnPhase→OpponentTurnPhase, EnemyTurnSystem→OpponentTurnSystem. This is a genuine source rename, not a fabrication: the three data types carry [MovedFrom(true, sourceClassName: "Enemy...")] API-updater aliases in source (e.g. [MovedFrom(true, sourceClassName: "PuzzleEnemy")] on PuzzleOpponent), and the old Enemy* identifiers are kept below only as the documented previous name — they no longer compile on their own. All field names and behavior were otherwise already accurate.

ComponentTypeKey Fields
PuzzleCombatBridgeIComponentData (singleton)DamagePerGem: float, ComboMultiplier: float
GemDamageMappingIBufferElementData (cap 4)GemColor: int, DamageType: DamageType, DamageMultiplier: float
PuzzleOpponent (renamed from PuzzleEnemy)IComponentDataHealth, MaxHealth, AttackDamage, TurnTimer, TurnInterval
OpponentTurnState (renamed from EnemyTurnState)IComponentDataPhase: OpponentTurnPhase, Timer: float, TelegraphDuration, ActDuration
public enum OpponentTurnPhase : byte { Telegraph, Act, WaitForPlayer } // renamed from EnemyTurnPhase
SystemGroupOrdering
PuzzleDamageSystemPuzzleSystemGroup[UpdateBefore(MatchDestroySystem)]
OpponentTurnSystem (renamed from EnemyTurnSystem)DOTSCore.CombatSystemGroup[UpdateAfter(PuzzleDamageSystem)]
// One entity holds both the bridge config and the color-damage buffer.
var bridgeEntity = ecb.CreateEntity();
ecb.AddComponent(bridgeEntity, new PuzzleCombatBridge
{
DamagePerGem = 10f,
ComboMultiplier = 0.5f, // +50% bonus per cascade chain level
});
var mappings = ecb.AddBuffer<GemDamageMapping>(bridgeEntity);
mappings.Add(new GemDamageMapping { GemColor = 0, DamageType = DamageType.Physical, DamageMultiplier = 1.0f });
mappings.Add(new GemDamageMapping { GemColor = 1, DamageType = DamageType.Magical, DamageMultiplier = 1.5f });
var opponentEntity = ecb.CreateEntity();
ecb.AddComponent(opponentEntity, new PuzzleOpponent // renamed from PuzzleEnemy
{
Health = 500f, MaxHealth = 500f,
AttackDamage = 25f, TurnTimer = 3f, TurnInterval = 3f,
});
ecb.AddComponent(opponentEntity, new OpponentTurnState // renamed from EnemyTurnState
{
Phase = OpponentTurnPhase.Telegraph, // renamed from EnemyTurnPhase
TelegraphDuration = 1f, ActDuration = 0.2f,
});
totalDamage = SUM_per_group(DamagePerGem * gemCount * colorMultiplier)
* (1 + (ComboMultiplier.Multiplier - 1) * bridge.ComboMultiplier)

Color -1 (piece Entity.Null or missing PieceData) skips all mapping entries — effective multiplier 1.0.

  • Exactly-once consumption barrier — PuzzleDamageSystem is in PuzzleSystemGroup with [UpdateBefore(MatchDestroySystem)]. Do NOT move it to CombatSystemGroup. The former cross-group design had no ordering guarantee between the two system groups, causing double-apply or missed damage depending on world-creation order. The in-group barrier is load-bearing; removing it re-introduces the race.
  • MatchDestroySystem requires BoardConfig, CascadeState, MatchGroup, AND ScoreEvent buffers — in tests (or custom bootstrap worlds) that host MatchDestroySystem alongside PuzzleDamageSystem, the board entity MUST carry all four. Missing ScoreEvent causes MatchDestroySystem to throw on frame 1, get disabled by Unity’s exception handler, and never clear MatchResult. PuzzleDamageSystem then re-reads the stale buffer on the next frame — this is the classic double-apply symptom. See DamageAppliedExactlyOncePerMatchCycle test for the full setup template.
  • Entity.Null in MatchResult is legal — PuzzleDamageSystem guards _pieceLookup.HasComponent(result.PieceEntity) and assigns color -1 on miss. This skips all GemDamageMapping entries, yielding a raw DamagePerGem * count for that group. Not a bug; handle it in mappings if needed.
  • GemDamageMapping buffer MUST exist on the bridge entity even if empty — TryGetSingletonBuffer<GemDamageMapping> returns false if no entity has the buffer. System early-exits (no damage applied). Always AddBuffer<GemDamageMapping> alongside PuzzleCombatBridge.
  • OpponentTurnSystem.WaitForPlayer phase never auto-transitions (system renamed from EnemyTurnSystem) — the system has no built-in mechanic to move from WaitForPlayer back to Telegraph. Demo systems must set OpponentTurnState.Phase = OpponentTurnPhase.Telegraph and reset Timer when the player completes their move (e.g., on CascadeState.Phase == Idle).
  • PuzzleOpponent.Health (renamed from PuzzleEnemy.Health) is NOT wired to DOTSCombat.Health — they are separate components. Opponent death (Health <= 0) is detected by consumer systems; OpponentTurnSystem skips entities with Health <= 0 but does not fire any death event. Consumer must poll or add a death-tag system.
  • OpponentTurnSystem’s Act-phase damage targets the entity carrying PuzzlePlayerTag, not a “DOTSCombat.Health singleton.” It queries SystemAPI.Query<RefRW<Health>>().WithAll<PuzzlePlayerTag>() — gated by the tag, not a singleton lookup — specifically so non-player Health entities (future opponent HP bars, UI) are never accidentally damaged by opponent Act resolution.
  • NativeHashMap<int, GroupAgg> uses Allocator.Temp — allocated each OnUpdate and disposed before return. If the system is hot-patched to keep the map across frames, switch to Persistent and dispose in OnDestroy.