Skip to content

t1k:unity:dots-combat:modifiers

FieldValue
Moduledots-combat
Version3.33.3
Effortmedium
Tools—

Keywords: 4-scope, ActModifiers, booster modifier, consumable, modifier, PhaseModifiers, RunModifiers, status effect, StepModifiers

/t1k:unity:dots-combat:modifiers

DOTS Modifiers — com.the1studio.dots-modifiers

Section titled “DOTS Modifiers — com.the1studio.dots-modifiers”

Namespace: DOTSModifiers.* | Package: com.the1studio.dots-modifiers Depends on: DOTSCore.*, DOTSCombat.*


  • Implementing run/act/step/phase scoped stat modifiers (wagers, daily modifiers, skill-tree bonuses, set bonuses)
  • Adding status effects (Poison, Burn, Freeze, Stun, Slow) that expire over time
  • Building a consumable / booster system (one-shot items that push modifiers onto a target)
  • Looking for RequestBufferSingletonHelper — the drain-and-clear singleton-buffer pattern
  • Using ModifierKind, ModifierElement, RunModifiers, ActModifiers, StepModifiers, PhaseModifiers
  • Projecting modifier elements into StatModifier via ModifierTranslator

The library uses four DynamicBuffer components, each with a distinct lifetime:

BufferCleared whenTypical use
RunModifiersRun resetRisk offers (AcceptedRisk), hero passives selected at run start
ActModifiersAct transitionDaily modifiers, weekly events scoped to one act
StepModifiersEncounter step advanceStep-only bonuses, single-encounter cards
PhaseModifiersPhase change (consumer-owned)Short-duration status effects, booster consumables

All four buffers hold ModifierElement structs. The element carries a ModifierKind discriminator so downstream apply-systems know which feature emitted the entry.

For exact buffer attachment (singleton vs per-entity), which scope clears itself via a library-provided system vs. which is fully consumer-owned, and the real rollup-hash mix function, see references/scope-lifecycle.md.


TypeLocationNotes
ModifierElementComponents/Generic payload — Kind, SourceId, Tier, ValueA, ValueB, FlagMask, ExpiresAtSeconds
RunModifiersComponents/IBufferElementData on run-scope singleton
ActModifiersComponents/IBufferElementData on act-scope singleton
StepModifiersComponents/IBufferElementData on step-scope singleton
PhaseModifiersComponents/IBufferElementData per target — status effects and consumables write here
ModifierTargetTagComponents/Marks entities eligible for modifier application
LastAppliedRollupHashComponents/FNV-1a gate — skips StatModifier rebuild if buffer unchanged

Status Effects (DOTSModifiers.StatusEffects)

Section titled “Status Effects (DOTSModifiers.StatusEffects)”
TypeNotes
StatusEffectVariantByte enum: Poison, Burn, Freeze, Stun, Slow
StatusEffectApplyRequestSingleton-buffer entry: TargetEntity, Variant, DurationSec, Magnitude
StatusEffectRequestSingletonTagMarker tag for the request singleton entity
StatusEffectActiveStatePer-frame rollup — IsImmobilized, SpeedMultiplier
StatusEffectApplySystemDrains request buffer → pushes ModifierElement into PhaseModifiers
StatusEffectTickSystemRewrites StatusEffectActiveState from PhaseModifiers each frame — see references/status-effect-tick-system-guide.md for exact API signatures, System Ordering, and 4 worked use-cases
TypeNotes
ConsumableActivationRequestSingleton-buffer entry: TargetEntity, pre-resolved Element
ConsumableRequestSingletonTagMarker tag for the consumable request singleton entity
IConsumableRegistry<TId>Contract for consumer catalogs — IsKnown(id), BuildModifierElement(id, time)
ConsumableApplySystemDrains buffer → appends Element to target’s PhaseModifiers
TypeNotes
ModifierApplySystemProjects all four buffer scopes into StatModifier rows via ModifierTranslator
ModifierExpirySystemPrunes entries from all 4 scope buffers (RunModifiers/ActModifiers/StepModifiers/PhaseModifiers), not just PhaseModifiers, where ExpiresAtSeconds >= 0f && ElapsedTime > ExpiresAtSeconds. Entries at ModifierConstants.NoExpiry (-1f) — or any negative value — are permanent
ModifierTranslatorStatic: ToStatModifier(ModifierElement) — Tier→StatType, ValueA→value, FlagMask&0x3→ModifierType
RequestBufferSingletonHelperLazy-create pattern for singleton-tag + request-buffer drain pattern

Two distinct status-effect systems coexist by design (Phase 4, Option A):

  • DOTSCombat.StatusEffect (buffer) / DOTSCombat.LegacyStatusEffectTickSystem — the legacy combat-pipeline variant for generic live combat (MaxStacks, StackBehavior). Lives in DOTSCombat.*.
  • DOTSModifiers.StatusEffects.StatusEffectVariant — the typed roguelike variant (Poison/Burn/Freeze/Stun/Slow, DurationSec, Magnitude). Lives here.

⚠️ Corrected 2026-08-23 — there is no more name collision to resolve. DOTSCombat’s tick system was RENAMED StatusEffectTickSystem → LegacyStatusEffectTickSystem specifically to remove the type-name collision with DOTSModifiers.StatusEffects.StatusEffectTickSystem (com.the1studio.dots-combat commit 3a95689e, W4.6 action 4). It is also now [Obsolete] — migrate to DOTSModifiers.StatusEffects.StatusEffectTickSystem + PhaseModifiers. See references/status-effect-coexistence.md for the corrected migration guidance.


// Producer (managed, in UI layer):
var registry = this.container.Resolve<IConsumableRegistry<BoosterId>>();
var element = registry.BuildModifierElement(boosterId, (float)World.DefaultGameObjectInjectionWorld.Time.ElapsedTime);
var buffer = RequestBufferSingletonHelper.GetOrCreate<ConsumableRequestSingletonTag, ConsumableActivationRequest>(ref state);
buffer.Add(new ConsumableActivationRequest { TargetEntity = playerEntity, Element = element });
var buffer = RequestBufferSingletonHelper.GetOrCreate<StatusEffectRequestSingletonTag, StatusEffectApplyRequest>(ref state);
buffer.Add(new StatusEffectApplyRequest
{
TargetEntity = enemyEntity,
Variant = StatusEffectVariant.Poison,
DurationSec = 5f,
Magnitude = 10f, // 10 damage/second
});

Reference: references/4-scope-guide.md, references/consumable-pattern.md, references/status-effect-coexistence.md, references/scope-lifecycle.md, references/status-effect-tick-system-guide.md, references/adding-a-new-effect-type.md


  • ExpiresAtSeconds uses monotonic SystemAPI.Time.ElapsedTime — not per-encounter clock. Run-reset does NOT reset this clock. Use short durations or a custom expiry pass for encounter-scoped effects.
  • RequestBufferSingletonHelper is NOT Burst-compatible — it calls typeof(T).Name (managed). Call it from a non-Burst entry point; access the buffer directly in Burst code.
  • ModifierApplySystem cleans up its own rows using ModifierSource.Aura as the discriminator. Do NOT manually remove rows emitted by this system — the next apply pass overwrites them.
  • StatusEffectTickSystem fully rewrites StatusEffectActiveState each frame — it is a derived component, not a persistent source. Do not read it outside of the frame it was written.
  • No qualification needed any more — DOTSCombat’s tick system is LegacyStatusEffectTickSystem (renamed 2026, [Obsolete]), not StatusEffectTickSystem; only DOTSModifiers.StatusEffects.StatusEffectTickSystem carries that short name today. See references/status-effect-coexistence.md.
  • ConsumableApplySystem acquires the EndSimulationEntityCommandBufferSystem singleton LAZILY — only on the cold (structural-change) branch, never unconditionally at OnUpdate start. The system has two paths: a hot path (target already has the PhaseModifiers buffer → inline buffer.Add, no ECB) and a cold path (target lacks the buffer → ecb.AddBuffer<PhaseModifiers> + AppendToBuffer). Calling SystemAPI.GetSingleton<EndSimulationEntityCommandBufferSystem.Singleton>() at the top of OnUpdate makes the system hard-depend on EndSimulationEntityCommandBufferSystem existing in every world — it throws in worlds that don’t register the EndSim ECB (minimal / registry-contract test worlds, custom bootstrap worlds), silently failing the entire system update for BOTH paths. Correct pattern: gate the acquire behind the cold-path branch with a one-shot guard.
    EntityCommandBuffer ecb = default;
    bool ecbAcquired = false;
    // hot path: inline buffer.Add(), no ECB
    // cold path:
    if (!ecbAcquired)
    {
    ecb = SystemAPI.GetSingleton<EndSimulationEntityCommandBufferSystem.Singleton>()
    .CreateCommandBuffer(state.WorldUnmanaged);
    ecbAcquired = true;
    }
    ecb.AddBuffer<PhaseModifiers>(req.TargetEntity);
    General rule: only acquire an ECB singleton inside the branch that actually performs the structural change — an unconditional acquire couples the system to that ECB system’s presence in every world. See t1k:unity:dots-core:entity-command-buffer. (Fixed in unity-dots-library d42be59.)
  • Rollup hash now mixes ValueB — modifiers differing ONLY in ValueB no longer collide — ModifierApplyJob.MixElement (called from ModifierApplySystem) FNV-1a-folds (Kind, SourceId, Tier, ValueA-bits, ValueB-bits). Previously ValueB was omitted, so two ModifierElements identical except for ValueB (e.g. a Burn whose tick-interval differs but damage matches) hashed equal → the second was silently dropped from dirty detection and never re-applied. Both floats are bit-cast via math.asint (Burst-safe; avoids BitConverter). If you add a new identity-bearing field to ModifierElement, mix it into MixElement too or it won’t trigger a rollup.
  • DoT damage requires a DotDamageAccumulator on the target AND a consumer-side drain — the package no longer writes Health directly (Wave-B decoupling). StatusEffectTickSystem accumulates per-tick Burn/Poison damage into DotDamageAccumulator.Pending only if the target carries one; the accumulator is optional so non-combat worlds can run modifiers without depending on DOTSCombat.Health. The drain — DOTSCombat.DotDamageToHealthSystem (lives in dots-combat, not here) — reads Pending, applies it to Health, clears it to zero. Failure mode: Burn/Poison on an entity lacking the accumulator ticks, expires, and inflicts zero damage — silently, no error. Control effects (Freeze/Stun/Slow) route through StatusEffectActiveState, unaffected. (Seam — StatusEffectTickSystem.cs AccumulatorLookup.GetRefRW(entity).ValueRW.Pending += dotDamage.)
  • Extending the system with a new effect type = an enum value, not a new component per type — see references/adding-a-new-effect-type.md. A dedicated Acid/Burn/Poison IComponentData per DoT type is an archetype-fragmentation anti-pattern (§ W4.1, t1k-unity-dots-core-architecture/references/archetype-design.md); and “compose from a Timer + Damage component” silently caps an entity at ONE concurrent DoT, which is why the apply channel is the [InternalBufferCapacity(8)] StatusEffectApplyRequest buffer element, not a component. Also relevant: that reference proves a consumer with an incompatible health model can run the full DoT pipeline TODAY via its own drain (the package’s Runtime/ has zero Health references).