t1k:unity:dots-combat:boss
| Field | Value |
|---|---|
| Module | dots-combat |
| Version | 3.33.3 |
| Effort | medium |
| Tools | — |
Keywords: AcceptedRisk, boss, boss arena, boss encounter, boss phase, BossAbility, BossAbilitySelectionSystem, BossArenaConfig, BossComboSystem, BossCompletionFlag, BossDefeatedEvent, BossPhase, BossPhaseThreshold, BossRewardCurrency, BossTag, BossWindUpSystem, combo sequence, phase transition, RiskOffer, RiskOfferSystem, WindUpVisualCueRequest
How to invoke
Section titled “How to invoke”/t1k:unity:dots-combat:bossDOTS 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 or survivor → t1k:unity:dots-combat:gamemodes.
Overview
Section titled “Overview”Overview
Section titled “Overview”Components
Section titled “Components”Regenerated against source 2026-08-23 —
RiskModifierKind(flagged for review) verified correct as documented, real since the H5 Wager→Risk rename; not touched. Several OTHER rows in this table were wrong and are corrected below.
| Component | Role |
|---|---|
BossTag | Marks entity as a boss; system queries gate on this |
BossPhase | Current phase index (0=entry, 1..N=combat phases) |
BossPhaseThreshold (buffer, cap 3) | float HealthPercent, int PhaseIndex — not HPFraction (never existed; see Core API fix below) |
BossAbility (buffer, cap 4) | int SkillId, float Cooldown, Timer, int RequiredPhase (-1 = always), Priority (higher wins) — not AbilityType/TargetingMode (neither ever existed) |
CooldownTimer (dots-core) + WindUpVisualCueRequest (tag, IEnableableComponent, int CueId) | The real wind-up mechanism — BossWindUp never existed as a component. The filename BossWindUp.cs holds the WindUpVisualCueRequest type; BossWindUpSystem ticks the shared CooldownTimer.RemainingTime and toggles the visual-cue enable bit while winding up |
BossArenaConfig | float3 Center, Size, BossSpawnPoint (a single spawn point), Entity BossPrefab — no teleport waypoints; nothing in the Boss subsystem teleports the boss on phase change (see Systems fix below) |
ComboSequence (buffer, cap 4) | int SkillId, float Delay — one scripted combo step |
ComboState | int CurrentIndex (-1 = not in combo), float Timer, bool IsExecuting, int RequiredPhase, float ComboCooldown, ComboCooldownTimer — not WindowRemaining (never existed) |
BossCompletionFlag (IEnableableComponent) | Enabled on the killer (resolved via LastAttacker) when any boss in the run is defeated; a run-controller disables it between runs |
BossDefeatedEvent (IEnableableComponent) | One-frame signal — boss just died. Enabled by BossDefeatedEventSystem, disabled OrderFirst next frame by BossEventCleanupSystem |
BossDefeatedProcessedTag | Added by ECB to prevent re-fire on same corpse |
BossRewardCurrency (buffer, cap 4) | int CurrencyType (a plain int DefId, see DOTSEconomy.CurrencyDefIds), int Amount (> 0 to process). Read by BossRewardSystem, written into WalletTransaction.CurrencyDefId |
BossVFXAnchor (buffer, cap 8) / BossVFXSpawnRequest (buffer, cap 8) | World-space VFX anchor points bound to a PhaseIndex (-1 = any/fallback) + the pending-spawn-request queue; VfxKind is an int against BossVFXKind constants (not an enum, Burst-safe) |
Systems
Section titled “Systems”Regenerated 2026-08-23 — group attributions were all correct (
CombatSystemGroupthroughout), but two roles were fabricated:BossPhaseShakeSystem’s “teleports boss to waypoint” never existed, and itsCameraShakeEventchannel was retired the same day this audit ran (fix(dots-core,dots-combat): retire CameraShakeEvent— screen-shake reconciliation Option E; seeplans/reports/scout-260822-screen-shake-reconciliation.md).
| System | Group | Role |
|---|---|---|
BossPhaseSystem | CombatSystemGroup, [UpdateAfter(DamageProcessingSystem)] | Monitors HP%, fires BossPhaseTransitionEvent (renamed from PhaseTransitionEvent, see Gotcha #7), increments BossPhase |
BossAbilitySelectionSystem | CombatSystemGroup, [UpdateAfter(BossPhaseSystem)] | Picks the highest-Priority off-cooldown BossAbility available at the boss’s current phase |
BossWindUpSystem | CombatSystemGroup, [UpdateAfter(BossPhaseSystem)] | Ticks the boss’s CooldownTimer.RemainingTime; toggles WindUpVisualCueRequest enabled while winding up, disables it (and lets combat commit the slam) when the timer resolves. Skips DeadTag entities |
BossComboSystem | CombatSystemGroup, [UpdateAfter(BossAbilitySelectionSystem)] | Drives ComboSequence execution: advances steps on timer expiry, resets on completion, applies ComboCooldown between combos, starts new combos when phase requirements are met |
BossPhaseShakeSystem | CombatSystemGroup, [UpdateAfter(BossPhaseSystem)] | On a phase-transition frame: accumulates CameraTrauma.Current (gated by CameraAccessibility.ReduceMotion) and enables HitStopRequest for BossConstants.PhaseTransitionHitStopFrames. Does NOT emit CameraShakeEvent (that legacy branch was removed 2026-08-23 — it had no decay system and fired every frame forever once enabled) and does NOT teleport the boss anywhere — BossArenaConfig has no waypoint list, only a single BossSpawnPoint |
BossDefeatedEventSystem | CombatSystemGroup, OrderLast=true | Detects DeadTag on a BossTag entity for the first time, fires BossDefeatedEvent, adds BossCompletionFlag to the killer |
BossRewardSystem | CombatSystemGroup, OrderLast=true, [UpdateAfter(BossDefeatedEventSystem)] | Drains BossRewardCurrency, appends a DOTSEconomy.WalletTransaction (v2, CurrencyDefId int) to the killer’s wallet — killer needs the Wallet tag + full v2 buffer set |
BossVFXTriggerSystem | CombatSystemGroup, [UpdateAfter(BossPhaseSystem)] | Picks the BossVFXAnchor matching the current/triggering phase (falls back to round-robin), writes a BossVFXSpawnRequest |
BossEventCleanupSystem | CombatSystemGroup, OrderFirst=true | Disables BossDefeatedEvent each frame |
Risk System (sub-feature) — namespace DOTSCombat.Boss.Risk
Section titled “Risk System (sub-feature) — namespace DOTSCombat.Boss.Risk”⚠️ Renamed from “Wager” (H5 genre rename). The Boss/Wager/ directory and every Wager* type (WagerCardComponents, WagerCardSystem, WagerEffectApplyJob) are removed — there is no [Obsolete] alias, so old using DOTSCombat.Boss.Wager; code is a hard compile error, not a deprecation warning.
| Type | Role |
|---|---|
RiskModifierKind (enum) | None, AtkPct, ArmorPct, CritChancePct, HpPct, GoldDropPct |
RiskOffer | A single offered option: OfferId, ModifierKind, MagnitudePct, DecayImmune |
RiskOfferEvent (buffer, cap 5) | One row per drawn option; UI renders the buffer, then it collapses to one accepted offer |
RiskSelection (IEnableableComponent) | Player commit — UI writes ChosenOfferId and enables it. -1 = decline |
AcceptedRisk | Permanent run record of what was accepted; read by reward-decay to honour DecayImmune |
RunStartedTag / RiskOfferedTag / DecayImmuneTag (all IEnableableComponent) | Draw trigger / re-offer suppression / decay-immunity flag |
RiskOfferSystem | CombatSystemGroup. Observes RunStartedTag, waits for commit, applies effect, then enables RiskOfferedTag |
RiskEffectApplyJob | Burst IJobEntity applying the stat multiplier. Static Apply(ref BaseStats, kind, magnitudePct) is public for sync/main-thread and test use |
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 run-start risk/challenge offers that modify the player’s baseline 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 plain int DefId (DOTSEconomy.// CurrencyDefIds), NOT the CurrencyId enum. CurrencyId is now [Obsolete] (H5 Phase-2); the// previous revision of this sample had the v1/v2 guidance BACKWARDS — CurrencyId.Soft would// not even compile into an int field without an explicit cast, and using it triggers an// obsolete-API warning either way. Use the CurrencyDefIds constants:this.AppendToBuffer(entity, new BossRewardCurrency { CurrencyType = CurrencyDefIds.Soft, Amount = 500 });this.AppendToBuffer(entity, new BossRewardCurrency { CurrencyType = CurrencyDefIds.Hard, Amount = 3 });
// Build a 3-phase threshold — the field is HealthPercent, NOT HPFraction (never existed).this.AddBuffer<BossPhaseThreshold>(entity);this.AppendToBuffer(entity, new BossPhaseThreshold { HealthPercent = 0.75f, PhaseIndex = 1 });this.AppendToBuffer(entity, new BossPhaseThreshold { HealthPercent = 0.50f, PhaseIndex = 2 });this.AppendToBuffer(entity, new BossPhaseThreshold { HealthPercent = 0.25f, PhaseIndex = 3 });Hard rules
Section titled “Hard rules”-
BossDefeatedEventSystemusesBossDefeatedProcessedTagfor one-shot semantics — once added, the event never re-fires even if the corpse lingers (fade-out delay). Do NOT removeBossDefeatedProcessedTagto “reset” a boss — destroy/re-create the entity. -
BossRewardSystemappends aDOTSEconomy.WalletTransaction(v2) on the KILLER entity — NOT the deprecatedDOTSInventory.CurrencyTransaction. Two silent-drop failure modes: (a) if the demo’s damage system doesn’t setLastAttacker, the killer lookup fails; (b) if the killer lacks the v2 wallet buffer set (Wallettag +WalletEntry+WalletTransaction+WalletLedger+ 3 event buffers — easiest viaDOTSEconomy.WalletAuthoring),HasBuffer<WalletTransaction>is false and the reward never lands. Seet1k:unity:dots-combat:coregotcha #8 for the full v2 wallet contract. -
BossWindUpwindow is non-interruptible by design — there is no cancellation API. If a demo needs interruptible wind-ups, it must disableBossWindUpSystemand implement its own. -
RiskOfferSystemmutates the PLAYER’sBaseStatsat RUN START — not boss stats, and not at battle start. (This corrects the pre-renameWagerCardSystemdescription, which claimed boss-stat application atBossArenaConfig.BattleStartEvent; that was never what the system did.) The flow is: host primes theRiskOfferEventbuffer + enablesRunStartedTag→ UI writesRiskSelection.ChosenOfferIdand enables it → the system addsAcceptedRiskand applies the modifier. Three consequences:- The multiplier lands on
BaseStats(Strength/Vitality/Dexterity/Luck), not on theStatModifierbuffer — deliberately, so the risk reads as a permanent run baseline that other modifiers stack on top of. It therefore flows throughDerivedStatsSystem(e.g.ArmorPct/HpPctboth scaleVitality;GoldDropPctscalesLuckas the drop proxy). - It is one-shot per run.
RiskOfferedTagis enabled after accept or decline and suppresses re-offers until run reset. Re-enablingRunStartedTagalone will not re-trigger a draw. - Declining is
ChosenOfferId = -1, not “don’t enableRiskSelection”. LeavingRiskSelectiondisabled stalls the flow forever — the system waits for a commit that never arrives.
- The multiplier lands on
-
BossVFXTriggerSystemdepends onVFXSpawnRequestbuffer — the VFX bridge must be wired or phase-transition FX silently skip. Pair witht1k:unity:dots-core:bridges→ VFXBridge.