t1k:unity:dots-combat:puzzle-bridge
| Field | Value |
|---|---|
| Module | dots-combat |
| Version | 3.33.3 |
| Effort | medium |
| Tools | — |
How to invoke
Section titled “How to invoke”/t1k:unity:dots-combat:puzzle-bridgeDOTS Puzzle-Combat Bridge
Section titled “DOTS Puzzle-Combat Bridge”Package:
com.the1studio.dots-puzzle-combat— namespaceDOTSPuzzleCombatDepends 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)
When This Skill Triggers
Section titled “When This Skill Triggers”- Wiring puzzle match results into enemy damage (match-3 RPG, Match3RPGDemo)
- Configuring
PuzzleCombatBridgesingleton orGemDamageMappingbuffer - Implementing enemy turn phases (Telegraph → Act → WaitForPlayer) above a puzzle board
- Applying
ComboMultiplierto aggregate match damage - Diagnosing double-apply or missed damage across
MatchDestroySystem
Reference Files
Section titled “Reference Files”| File | Contents |
|---|---|
api-reference.md (references/api-reference.md) | Full component/system table, singleton setup snippet, test world pattern |
Public Components
Section titled “Public Components”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")]onPuzzleOpponent), and the oldEnemy*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.
| Component | Type | Key Fields |
|---|---|---|
PuzzleCombatBridge | IComponentData (singleton) | DamagePerGem: float, ComboMultiplier: float |
GemDamageMapping | IBufferElementData (cap 4) | GemColor: int, DamageType: DamageType, DamageMultiplier: float |
PuzzleOpponent (renamed from PuzzleEnemy) | IComponentData | Health, MaxHealth, AttackDamage, TurnTimer, TurnInterval |
OpponentTurnState (renamed from EnemyTurnState) | IComponentData | Phase: OpponentTurnPhase, Timer: float, TelegraphDuration, ActDuration |
public enum OpponentTurnPhase : byte { Telegraph, Act, WaitForPlayer } // renamed from EnemyTurnPhasePublic Systems
Section titled “Public Systems”| System | Group | Ordering |
|---|---|---|
PuzzleDamageSystem | PuzzleSystemGroup | [UpdateBefore(MatchDestroySystem)] |
OpponentTurnSystem (renamed from EnemyTurnSystem) | DOTSCore.CombatSystemGroup | [UpdateAfter(PuzzleDamageSystem)] |
Common Patterns
Section titled “Common Patterns”Setup — singleton + color mapping
Section titled “Setup — singleton + color mapping”// 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 });Create a puzzle enemy
Section titled “Create a puzzle enemy”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,});Damage formula
Section titled “Damage formula”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.
Hard rules
Section titled “Hard rules”- Exactly-once consumption barrier —
PuzzleDamageSystemis inPuzzleSystemGroupwith[UpdateBefore(MatchDestroySystem)]. Do NOT move it toCombatSystemGroup. 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, ANDScoreEventbuffers — in tests (or custom bootstrap worlds) that hostMatchDestroySystemalongsidePuzzleDamageSystem, the board entity MUST carry all four. MissingScoreEventcausesMatchDestroySystemto throw on frame 1, get disabled by Unity’s exception handler, and never clearMatchResult.PuzzleDamageSystemthen re-reads the stale buffer on the next frame — this is the classic double-apply symptom. SeeDamageAppliedExactlyOncePerMatchCycletest for the full setup template. Entity.Nullin MatchResult is legal —PuzzleDamageSystemguards_pieceLookup.HasComponent(result.PieceEntity)and assigns color -1 on miss. This skips allGemDamageMappingentries, yielding a rawDamagePerGem * countfor that group. Not a bug; handle it in mappings if needed.GemDamageMappingbuffer 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). AlwaysAddBuffer<GemDamageMapping>alongsidePuzzleCombatBridge.OpponentTurnSystem.WaitForPlayerphase never auto-transitions (system renamed fromEnemyTurnSystem) — the system has no built-in mechanic to move fromWaitForPlayerback toTelegraph. Demo systems must setOpponentTurnState.Phase = OpponentTurnPhase.Telegraphand resetTimerwhen the player completes their move (e.g., onCascadeState.Phase == Idle).PuzzleOpponent.Health(renamed fromPuzzleEnemy.Health) is NOT wired toDOTSCombat.Health— they are separate components. Opponent death (Health <= 0) is detected by consumer systems;OpponentTurnSystemskips entities withHealth <= 0but does not fire any death event. Consumer must poll or add a death-tag system.OpponentTurnSystem’s Act-phase damage targets the entity carryingPuzzlePlayerTag, not a “DOTSCombat.Healthsingleton.” It queriesSystemAPI.Query<RefRW<Health>>().WithAll<PuzzlePlayerTag>()— gated by the tag, not a singleton lookup — specifically so non-playerHealthentities (future opponent HP bars, UI) are never accidentally damaged by opponent Act resolution.NativeHashMap<int, GroupAgg>usesAllocator.Temp— allocated eachOnUpdateand disposed before return. If the system is hot-patched to keep the map across frames, switch toPersistentand dispose inOnDestroy.