Skip to content
T1KTheOneKit

t1k:unity:dots-combat:boss

FieldValue
Moduledots-combat
Version2.3.8
Effortmedium
Tools—

Keywords: boss, boss arena, boss encounter, boss phase, BossAbility, BossAbilitySelectionSystem, BossArenaConfig, BossComboSystem, BossCompletionFlag, BossDefeatedEvent, BossPhase, BossPhaseThreshold, BossRewardCurrency, BossTag, BossWindUp, combo sequence, phase transition, WagerCard

How to invoke

Section titled “How to invoke”
/t1k:unity:dots-combat:boss

DOTS Boss — Phase System + Ability Combos + Rewards

Section titled “DOTS Boss — Phase System + Ability Combos + Rewards”

Package: com.the1studio.dots-combat/Runtime/Boss/ | Namespace: DOTSCombat.Boss.*

Split from t1k:unity:dots-combat:rpg (Wave 2, chaosforge-prep merge). For core damage → t1k:unity:dots-combat:core. For round phases → t1k:unity:dots-combat:autobattler. For survivor → t1k:unity:dots-combat:survivor.

Overview

Section titled “Overview”

Components

Section titled “Components”
ComponentRole
BossTagMarks entity as a boss; system queries gate on this
BossPhaseCurrent phase index (0=entry, 1..N=combat phases)
BossPhaseThreshold (buffer)HP% thresholds that trigger phase transitions (e.g. 0.75, 0.50, 0.25)
BossAbility (buffer)Ability roster per phase — AbilityType, Cooldown, TargetingMode
BossWindUpWind-up charge before ability fires — Duration, Remaining, AbilityIndex
BossArenaConfigArena bounds + teleport waypoints used by BossPhaseShakeSystem
ComboSequence (buffer)Ordered ability indices that form a combo chain
ComboStateCurrent combo progress: CurrentIndex, WindowRemaining
BossCompletionFlag (IEnableableComponent)Enabled on the killer when boss is defeated
BossDefeatedEvent (IEnableableComponent)One-frame signal — boss just died
BossDefeatedProcessedTagAdded by ECB to prevent re-fire on same corpse
BossRewardCurrency (buffer)Currencies granted to killer on defeat — CurrencyType is a DOTSEconomy.CurrencyId enum (v2 wallet, NOT the deprecated v1 int), Amount
BossVFXAnchor / BossVFXSpawnRequestVFX spawn points + request for phase-transition FX

Systems

Section titled “Systems”
SystemGroupRole
BossPhaseSystemCombatSystemGroupMonitors HP%, fires BossPhaseTransitionEvent (renamed from PhaseTransitionEvent, see Gotcha #7), increments BossPhase
BossAbilitySelectionSystemCombatSystemGroupPicks next ability from phase roster when cooldown expires
BossWindUpSystemCombatSystemGroupTicks BossWindUp, fires actual ability entity via ECB on expiry
BossComboSystemCombatSystemGroupTracks ComboSequence progress, resets window on chain break
BossPhaseShakeSystemCombatSystemGroupEmits CameraShakeEvent + teleports boss to waypoint on phase change
BossDefeatedEventSystemCombatSystemGroup, OrderLastDetects DeadTag, fires BossDefeatedEvent, adds BossCompletionFlag to killer
BossRewardSystemCombatSystemGroupDrains BossRewardCurrency buffer, appends DOTSEconomy.WalletTransaction (v2) to killer wallet — killer needs the Wallet tag + full v2 buffer set
BossVFXTriggerSystemCombatSystemGroupSpawns VFX anchored to phase-transition positions
BossEventCleanupSystemCombatSystemGroup, OrderFirstClears BossDefeatedEvent IEnableableComponent each frame

Wager System (sub-feature)

Section titled “Wager System (sub-feature)”
TypeRole
WagerCardComponentsCard payload: WagerType, Modifier, Duration
WagerCardSystemPlayer selects a risk/reward card pre-boss; applies modifier to boss stats
WagerEffectApplyJobBurst job applying wager stat multipliers at battle start

When to use

Section titled “When to use”
  • Setting up boss encounters with HP-threshold phase transitions
  • Implementing boss ability wind-up + combo chains
  • Wiring boss defeat → currency reward + realm progression
  • Adding wager/challenge cards that modify boss stats

Core API

Section titled “Core API”
// Authoring — BossPhaseAuthoring handles baking
// Components added: BossTag, BossPhase, BossPhaseThreshold[], BossAbility[], BossArenaConfig, BossRewardCurrency[]


// React to boss defeated in a managed bridge
// BossDefeatedEvent is IEnableableComponent — check via bridge or polling:
foreach (var (evt, entity) in SystemAPI.Query<EnabledRefRO<BossDefeatedEvent>>()
    .WithAll<BossTag>())
{
    // grant rewards, open victory screen
    bridgeQueue.Enqueue(new BossDefeatedSignal { BossEntity = entity });
}

Examples

Section titled “Examples”
// Add reward currencies during authoring — CurrencyType is a DOTSEconomy.CurrencyId enum (v2).
// Use named tiers (Soft/Hard/Premium/Energy/EventToken) or Custom0..Custom7 for game-specific currencies.
this.AppendToBuffer(entity, new BossRewardCurrency { CurrencyType = CurrencyId.Soft, Amount = 500 });
this.AppendToBuffer(entity, new BossRewardCurrency { CurrencyType = CurrencyId.Hard, Amount = 3 });


// Build a 3-phase threshold
this.AddBuffer<BossPhaseThreshold>(entity);
this.AppendToBuffer(entity, new BossPhaseThreshold { HPFraction = 0.75f, PhaseIndex = 1 });
this.AppendToBuffer(entity, new BossPhaseThreshold { HPFraction = 0.50f, PhaseIndex = 2 });
this.AppendToBuffer(entity, new BossPhaseThreshold { HPFraction = 0.25f, PhaseIndex = 3 });

Gotchas

Section titled “Gotchas”

  1. BossDefeatedEventSystem uses BossDefeatedProcessedTag for one-shot semantics — once added, the event never re-fires even if the corpse lingers (fade-out delay). Do NOT remove BossDefeatedProcessedTag to “reset” a boss — destroy/re-create the entity.

  2. BossRewardSystem appends a DOTSEconomy.WalletTransaction (v2) on the KILLER entity — NOT the deprecated DOTSInventory.CurrencyTransaction. Two silent-drop failure modes: (a) if the demo’s damage system doesn’t set LastAttacker, the killer lookup fails; (b) if the killer lacks the v2 wallet buffer set (Wallet tag + WalletEntry + WalletTransaction + WalletLedger + 3 event buffers — easiest via DOTSEconomy.WalletAuthoring), HasBuffer<WalletTransaction> is false and the reward never lands. See t1k:unity:dots-combat:core gotcha #8 for the full v2 wallet contract.

  3. BossPhaseShakeSystem fires CameraShakeEvent — requires the Camera module (DOTSCore) to be present in the world. Without it, no shake occurs but no error fires either.

  4. BossWindUp window is non-interruptible by design — there is no cancellation API. If a demo needs interruptible wind-ups, it must disable BossWindUpSystem and implement its own.

  5. WagerCardSystem applies BEFORE battle start — wager modifiers are baked into boss stats via WagerEffectApplyJob at BossArenaConfig.BattleStartEvent. Changing wager mid-battle has no effect.

  6. BossVFXTriggerSystem depends on VFXSpawnRequest buffer — the VFX bridge must be wired or phase-transition FX silently skip. Pair with t1k:unity:dots-core:bridges → VFXBridge.

  7. PhaseTransitionEvent was RENAMED to BossPhaseTransitionEvent (de-dup pass 2026-05-31, demo commit 44d95b4e). The old PhaseTransitionEvent survives one cycle as a distinct [Obsolete] struct — it is NOT an alias, it is a SEPARATE type. BossPhaseSystem now queries WithPresent<BossPhaseTransitionEvent>(), so any entity still carrying the old PhaseTransitionEvent is never matched and the event never raises. Silent failure mode: phase-threshold logic (and tests gated on the event) report 0 transitions instead of the expected 1/2/3. Migration: in bakers, add BossPhaseTransitionEvent (not PhaseTransitionEvent); in any consumer system that reads phase transitions (e.g. HitStopSystem, ScreenShakeOnDeathSystem), query BossPhaseTransitionEvent. Update tests’ component references too. Remove all PhaseTransitionEvent references before the obsolete alias is dropped next cycle.