Skip to content

t1k:unity:dots-combat:core

FieldValue
Moduledots-combat
Version3.33.3
Effortmedium
Tools—

Keywords: AttackConfig, BattleState, build cost, BuildRequest, CCMasks, combat, combat formulas, CombatAuthoring, CombatConstants, CurrencyId, damage, DamageEvent, dead tag, DeadTag, DemolishRequest, DerivedCombatStats, DerivedStats, DerivedStatsSystem, DerivedStatsSystem, DOTSEconomy, HealEvent, health, HitFlash, HitFlashTimer, invulnerable, kill reward, KillRewardCurrency, knockback, RangedAttack, RangedAttackConfig, RangedAttackTag, structures, WalletEntry, WalletTransaction

/t1k:unity:dots-combat:core

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

Split from t1k:unity:dots-combat:rpg (Wave 2). For auto-battler or survivor → t1k:unity:dots-combat:gamemodes. For boss → t1k:unity:dots-combat:boss.

ModuleKey Types
Combat (28c/19s)Health, Mana, Shield, DamageEvent, HealEvent, StatusEffect, DeadTag, InvulnerableTag, KnockbackEvent, BattleState, AttackConfig, OnHitEffect, OnDeathEffect, AuraEffect
Skills (11c/8s)SkillSlotState, SkillSlotConfig, ActiveCastState, ProjectileData, ParabolicArc, AreaEffect, HomingTarget, SkillBehaviorType, RangedAttackConfig (monolithic SkillSlot REMOVED — see Gotcha 9)
Synergy/Trait (5c/3s)TraitEntry, SynergyDefinition, ActiveSynergy, TeamSynergyState, SynergyModifierSource
Talent Tree (5c/2s)TalentNode, TalentProgress, TalentPoints, TalentUnlockRequest, TalentEvent
Summon (5c/4s)SummonConfig, SummonState, SummonRequest, SummonEvent, SummonedByTag

Stat pipeline: BaseStats → StatModifier[] → DerivedCombatStats / DerivedResourceStats / DerivedLocomotion → StatSyncSystem syncs Health.Max / Mana.Max.

  • Implementing or debugging damage, healing, knockback, status effects
  • Setting up unit stats (BaseStats → DerivedStatsSystem → combat pipeline)
  • Using skill casting, projectiles, AoE, homing, talent trees, synergy
  • Working with CombatAuthoring (canonical unit baker adds 15+ combat components)
// Damage formula — never inline
float dmg = CombatFormulas.ComputeAutoAttackDamage(atk, def, level);
float cd = CombatFormulas.EffectiveCooldown(baseCd, haste);
uint seed = CombatFormulas.FrameRngSeed(entity, frame);
// Events — per-entity IBufferElementData
buffer.Add(DamageEvent.Create(source, amount, type));
buffer.Add(new HealEvent { Amount = 20 });
buffer.Add(new KnockbackEvent { Direction = dir, Force = 5f });
// CC masks
if ((state.ActiveCC & CCMasks.MoveBlock) != 0) return; // unit is CC'd
// Custom unit baker (MUST include HitFlashTimer if bypassing CombatAuthoring)
this.AddComponent(entity, new HitFlashTimer
{
Duration = VisualConstants.HitFlashDuration,
OriginalScale = bakedLocalTransform.Scale, // MUST match baked scale
});
// Ranged: BOTH Tag AND Config required
this.AddComponent<RangedAttackTag>(entity);
this.AddComponent(entity, new RangedAttackConfig { ... });
  1. Combat tint/palette constants are stored LINEAR, not authored sRGB. StatusEffectVisualConstants.*Tint (10 constants) and GameplayConstants.MageAoEColor / TowerAoEColor feed SpriteColor.Value, which is always linear — see t1k-unity-dots-core-ecs § “Colour contract” for the full rule and t1k-unity-dots-core-jobs-burst § “Burst restricts statics” for why they are pinned literals with derivation tests.

    Two combat specifics worth knowing before you touch them:

    • StatusEffectTintSystem blends, it does not construct. It math.lerps an existing SpriteColor.Value against a raw tint constant through a ref, so a SpriteColor.FromGamma factory never runs in that path. Converting only at construction would have made this system newly wrong. The tint table therefore converts at its own definition.
    • CasterAttackSystem, TowerAttackSystem and ProjectileCollisionSystem needed no change — they read constants that are now already linear, so they are correct by inheritance. Each carries an explicit comment saying so; do not “fix” them into a double-convert.

    Getting this wrong is invisible to state-side checks: the ECS data reads exactly to spec while the pixel renders wrong. Shipped in The1Studio/unity-dots-library#72.

  2. ⛔ Every SubScene with stat-bearing units MUST contain a StatFormulaConfigAuthoring — or every unit’s derived stats (max health, damage, speed) freeze at their baked zero forever. Symptom: the demo appears to spawn nothing, with no console error.

    Units baked by StatsAuthoring carry DOTSCore.BlobConfig.DefId (modern blob path, DefaultFormulaDefId = 0). Resolving it needs a BlobConfigRegistry<StatFormulaBlob> scene singleton, emitted only by a StatFormulaConfigAuthoring GameObject. Without it the failure is silent:

    no registry → DerivedStatsSystem skips its blob job (m_FormulaBlob.IsCreated == false, no warning) → DerivedResourceStats.MaxHealth (and every other derived stat — PhysAtk, MagAtk, MoveSpeed, …) stays at its baked 0 → the unit sits on the field dealing 0 damage at 0 speed.

    ⚠️ Updated 2026-08-22 (unity-dots-library@b780a830 + @f94069d6): StatSyncSystem.SyncHealthJob no longer runs unconditionally — it now guards if (resource.MaxHealth <= 0f) return;, treating an exact 0 as “never derived this session” rather than a real value (DerivedStatsSystem’s clamp always floors a genuinely-derived MaxHealth to >= 1, so 0 is unambiguous). An unresolved unit therefore no longer gets Health stomped to 0/0 and killed by DeathSystem — it idles instead of dying. DirtyTagClearSystem was fixed in the same session to match: it now only clears DirtyTag once derivation actually succeeded (same MaxHealth <= 0 gate), so a registry that resolves LATE (e.g. SubScene streaming latency) keeps the unit retrying every frame instead of getting permanently frozen the instant a clear pass ran before the registry existed. Full pattern write-up: t1k-unity-dots-core-ecs/references/dirty-tag-guide.md § Gotchas #4.

    Two traps remain even with the fix: the authored Health (e.g. 300) is now preserved rather than overwritten, so “the unit looks alive” proves nothing about whether it can actually fight or move; and the legacy path cannot cover for the missing registry, because DerivedStatsJob requires in StatFormulaConfig, which blob-path units deliberately lack.

    Wire it via the library helper — never hand-roll per demo:

    SceneSetupUtility.EnsureStatFormulaConfig(subScene, ".../Generated/StatFormulaConfig.asset");

    Guard: StatFormulaRegistryGuardSystem (dots-core) logs one console error naming the missing singleton + affected entity count. Audit with grep -c StatFormulaConfig <SubScene>.unity — 0 means broken.

  3. Ranged: BOTH RangedAttackTag AND RangedAttackConfig required. AutoAttackSystem excludes RangedAttackTag — adding only RangedAttackConfig silently falls back to melee.

  4. RangedAttackSystem is no-op without ProjectileRegistryTag singleton + TeamProjectilePrefab buffer. Every team needs its own entry; missing-team archers fire 0 projectiles. (Wave-4 rename: was ArrowRegistryTag / TeamArrowPrefab — old names kept as [Obsolete]/[MovedFrom] shims for un-migrated demos.)

  5. RangedAttackSystem.LookRotationSafe makes 2D projectile quads invisible in sideview — normal points along flight direction (perpendicular to sideview camera). Fix: add a [UpdateAfter(ParabolicArcSystem), OrderLast] system in SkillsSystemGroup that overrides rotation to quaternion.identity.

  6. RangedKitingDistance MUST be ≤ hero AttackRange — hero parked beyond its own range idles indefinitely.

  7. ISystem for TalentUnlockSystem → use SystemBase — Entities 1.4 BufferTypeHandle two-pass invalidation.

  8. SetComponentEnabled before buffer reads invalidates BufferTypeHandle — complete all buffer reads first.

  9. Combat reward + structures systems consume the v2 DOTSEconomy wallet — NOT the deprecated DOTSInventory.CurrencyWallet/CurrencyTransaction/CurrencyWalletUtility. Reward systems enqueue DOTSEconomy.WalletTransaction; structures systems read/mutate WalletEntry via WalletUtility; currency keys are now DOTSEconomy.CurrencyId enums, not int. The Wallet tag is now REQUIRED on any reward/cost target — missing it means WalletSystem skips the entity and rewards/costs silently no-op. Full v1→v2 contract detail: references/migration-history.md § “Combat reward + structures systems”.

  10. SkillSlot is split into SkillSlotState (hot) + SkillSlotConfig (cold) — the monolithic SkillSlot buffer is REMOVED. Query BOTH parallel-indexed buffers (int n = math.min(states.Length, configs.Length)), read from each, write back ONLY State. SkillCooldownSystem queries SkillSlotState ONLY. Full field lists + the baker invariant: references/migration-history.md § “SkillSlot is split”.

  11. Generic component naming — name the ROLE, not the instance. (RESOLVED in Wave-4.) The Arrow* family (ArrowRegistryTag, TeamArrowPrefab, ArrowPrefabAuthoring) and Mage* attack family were over-specific concrete-instance names — really “the projectile a ranged attacker fires” and “an AoE caster’s attack” — while the library ALREADY had generic ProjectileData/ProjectileCollisionSystem. Wave-4 (lib v3 post-ship) renamed them to the generic ROLE: Arrow*→Projectile*, Mage*→Caster*, with [MovedFrom]/[Obsolete] back-compat shims (see combat-rpg combat-v5-migration.md § “Wave-4 Neutrality Renames (genre-neutral type names)”). The principle still holds for all NEW code: name the generic role (Projectile, Caster, Agent), never one concrete instance (Arrow, Mage, Sword) — a concrete instance belongs in an enum value or demo content. SSOT: rules/library-quality-mandate-unity.md § “Naming charter”.

  12. DamageBucketAggregationSystem formula is (flatBucket + percentAddBucket) * percentMulProduct, with percentMul defaulting to 1.0 — NOT flat*(1+add)*mul. These buckets are percentage bonuses, not stats scaled from a base, so a lone +30% PercentAdd buff must yield (0 + 0.30) * 1.0 = 0.30 (30%). The old flat*(1+add)*mul shape multiplied a zero flat base and zeroed out every pure-percent buff (PercentAdd-only modifiers silently did nothing). Each bucket (DamagePct, RangedDamagePct, MeleeDamagePct, SkillDamagePct) is clamped to CombatConstants.DamagePercentBucketCap (180%); DefensePct is a 0..1 fraction clamped tighter. Each entity writes only its own bucket component — parallel-safe.

  13. The stat dirty flag is DOTSCore.DirtyTag, NOT a per-package StatsDirtyTag. DOTSCore.StatsDirtyTag is now [Obsolete] (a separate, back-compat ECS type scheduled for removal); the canonical enableable flag every package shares is DOTSCore.DirtyTag. The stat-recompute loop is one SSOT chain — ALL of: the baker (bakes the flag enabled for the first-frame pass), the consumer (DerivedStatsSystem — recomputes it, does NOT itself disable the flag), the clear system (DirtyTagClearSystem, OrderLast — disables the flag, and only after a successful recalc), AND every producer that mutates a StatModifier buffer must set/read the SAME DOTSCore.DirtyTag. In dots-combat the producers are PartyBuffSystem, SynergyResolutionSystem, DamageBucketAggregationSystem, StageCurveSystem, TalentUnlockSystem — each calls SetComponentEnabled<DirtyTag>(entity, true) after applying its modifier. A producer that forgets to raise DirtyTag causes a silent stat-miss: the recompute never triggers, so the buff lands in the buffer but never reaches DerivedCombatStats. When adding a new modifier-writing system, raising DirtyTag is part of the contract, not an afterthought.