Effects, Attributes, and Tags: Deep Dive¶

TL;DR: What Problem This Solves¶

• ⭐ Build buff/debuff systems without writing custom code for every effect.
• Data‑driven ScriptableObjects: designers create 100s of effects, programmers build the system once.
• Reduces boilerplate with data-driven effect definitions; designers can iterate without code changes.
• Note: Attributes are optional - use the system purely for tag-based state management and timed cosmetic effects.

Data-Driven Effect Authoring¶

The Problem - Hardcoded Effects:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

public sealed class PlayerStats : MonoBehaviour { public float speed = 5f; }

// Every buff needs its own custom MonoBehaviour:

public class HasteEffect : MonoBehaviour
{
    private float duration = 5f;
    private float originalSpeed;
    private PlayerStats player;

    void Start()
    {
        player = GetComponent<PlayerStats>();
        originalSpeed = player.speed;
        player.speed *= 1.5f;  // Apply speed boost
    }

    void Update()
    {
        duration -= Time.deltaTime;
        if (duration <= 0)
        {
            player.speed = originalSpeed;  // Restore
            Destroy(this);
        }
    }
}

// 20 effects × 50 lines each = 1000 lines of repetitive code
// Designers can't create effects without programmer

The Solution - Data-Driven:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

// Programmers build system once (Unity Helpers provides this):
// - AttributesComponent base class
// - EffectHandler manages application/removal
// - ScriptableObject authoring

// Designers create effects in Editor (NO CODE):
// 1. Right-click → Create → Attribute Effect
// 2. Name: "Haste"
// 3. Add modification: Speed × 1.5
// 4. Duration: 5 seconds
// 5. Done!

// Apply at runtime (one line):
target.ApplyEffect(hasteEffect);

Designer Workflow:

1. Create the effect asset in the editor (no code)
2. Test in-game immediately
3. Tweak values and iterate freely
4. Create variations (Haste II, Haste III) by duplicating assets

Impact:

• Reduced boilerplate: Centralizes effect logic in a reusable system
• Designer workflow: Create and modify effects without code changes
• Faster iteration: Adjust values without recompiling
• Maintainability: All effects in one system vs. scattered scripts

Data‑driven gameplay effects that modify stats, apply tags, and drive cosmetic presentation.

This guide explains the concepts, how they work together, authoring patterns, recipes, best practices, and FAQs.

Visual Reference¶

Concepts¶

• Attribute: A dynamic numeric value with a base and a calculated current value. Current value applies all active modifications.
• AttributeModification: Declarative change to an Attribute. Actions: Addition, Multiplication, Override. Applied in that order.
• AttributeEffect: ScriptableObject asset bundling modifications, tags, cosmetic data, duration policy, periodic tick schedules, and optional runtime behaviours.
• EffectHandle: Opaque identifier for a specific application instance (for Duration/Infinite effects). Used to remove one stack.
• AttributesComponent: Base MonoBehaviour exposing modifiable Attribute fields (e.g., Health, Speed) on your character.
• EffectHandler: Component that applies/removes effects, tracks durations, forwards modifications to AttributesComponent, applies tags and cosmetics.
• TagHandler: Counts and queries string tags for gating gameplay (e.g., "Stunned"). Removes tags only when all sources are gone.
• CosmeticEffectData: Prefab‑like container with CosmeticEffectComponent behaviours; reused or instanced per effect application.

How It Works¶

1. You author an AttributeEffect with modifications, tags, cosmetics, and duration.
2. You apply it to a GameObject: EffectHandle? handle = target.ApplyEffect(effect);
3. EffectHandler will:
4. Create an EffectHandle (for Duration/Infinite) and track expiration
5. Apply tags via TagHandler (counted; multiple sources safe)
6. Apply cosmetic behaviours (CosmeticEffectData)
7. Forward AttributeModifications to all AttributesComponents on the GameObject
8. On removal (manual or expiration), all of the above are cleanly reversed.

Instant effects modify base values permanently and return null instead of a handle.

Authoring Guide¶

1. Define stats:

1
2
3
4
5
6
7

public class CharacterStats : AttributesComponent
{
    public Attribute MaxHealth = 100f;
    public Attribute Speed = 5f;
    public Attribute AttackDamage = 10f;
    public Attribute Defense = 10f;
}

1. Create an AttributeEffect asset (Project view → Create → Wallstop Studios → Unity Helpers → Attribute Effect):
2. modifications: e.g., { attribute: "Speed", action: Multiplication, value: 1.5f }
3. durationType: Duration with duration = 5
4. resetDurationOnReapplication: true to refresh timer on re-apply
5. effectTags: e.g., [ "Haste" ]

6. cosmeticEffects: prefab with CosmeticEffectData + CosmeticEffectComponent scripts

7. Apply/remove at runtime:

1
2
3
4
5
6
7
8

GameObject player = ...;
AttributeEffect haste = ...; // ScriptableObject reference
EffectHandle? handle = player.ApplyEffect(haste);
// ... later ...
if (handle.HasValue)
{
    player.RemoveEffect(handle.Value);
}

1. Query tags anywhere:

1
2
3
4

if (player.HasTag("Stunned"))
{
    // Disable input, play animation, etc.
}

Understanding Attributes: What to Model and What to Avoid¶

Important: Attributes are NOT required! The Effects System works well when used solely for tag-based state management and cosmetic effects.

What Makes a Good Attribute?¶

Attributes work best for values that are:

• Primarily modified by the effects system (buffs, debuffs, equipment)
• Derived from a base value (MaxHealth, Speed, AttackDamage, Defense)
• Calculated values where you need to see the result of all modifications

What Makes a Poor Attribute?¶

❌ DON'T use Attributes for "current" values like CurrentHealth, CurrentMana, or CurrentAmmo!

Why? These values are frequently modified by multiple systems:

• Combat system subtracts health upon damage
• Healing system adds health
• Regeneration ticks add health over time
• Death system resets health to zero
• Save/load system restores health

The Problem:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

// ❌ BAD: CurrentHealth as an Attribute
public class PlayerStats : AttributesComponent
{
    public Attribute CurrentHealth = 100f; // DON'T DO THIS!
    public Attribute MaxHealth = 100f;     // This is fine
}

// Multiple systems modify CurrentHealth:
void TakeDamage(float damage)
{
    // Direct mutation bypasses the effects system
    playerStats.CurrentHealth.BaseValue -= damage;

    // Problem 1: If an effect was modifying CurrentHealth,
    //           it still applies! Now calculations are wrong.
    // Problem 2: If you remove an effect, it may restore
    //           the ORIGINAL base value, undoing damage taken.
    // Problem 3: Save/load becomes complicated - do you save
    //           base or current? What about active modifiers?
}

The Solution - Separate Current and Max:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48

// ✅ GOOD: CurrentHealth is a regular field, MaxHealth is an Attribute
public class PlayerStats : AttributesComponent
{
    // Regular field - modified by combat/healing systems directly
    private float currentHealth = 100f;

    // Attribute - modified by buffs/effects
    public Attribute MaxHealth = 100f;

    public float CurrentHealth
    {
        get => currentHealth;
        set => currentHealth = Mathf.Clamp(value, 0, MaxHealth.Value);
    }

    protected override void Awake()
    {
        base.Awake();
        // Initialize current health to max
        currentHealth = MaxHealth.Value;

        // When max health changes, clamp current health
        OnAttributeModified += (attributeName, oldVal, newVal) =>
        {
            if (attributeName == nameof(MaxHealth))
            {
                // If max decreased, ensure current doesn't exceed new max
                if (currentHealth > newVal)
                {
                    currentHealth = newVal;
                }
            }
        };
    }
}

// Combat system can now safely modify current health
void TakeDamage(float damage)
{
    playerStats.CurrentHealth -= damage; // Simple and correct
}

// Effects system modifies max health
void ApplyHealthBuff()
{
    // MaxHealth × 1.5 (buffs max, current stays same)
    player.ApplyEffect(healthBuffEffect);
}

Attribute Best Practices¶

✅ DO use Attributes for:

• MaxHealth, MaxMana, MaxStamina - caps that buffs modify
• Speed, MovementSpeed - continuous values modified by effects
• AttackDamage, Defense, CritChance - combat stats
• CooldownReduction, CastSpeed - multiplicative modifiers
• CarryCapacity, JumpHeight - gameplay parameters

❌ DON'T use Attributes for:

• CurrentHealth, CurrentMana - depleting resources with complex mutation
• Position, Rotation - physics/transform state
• Inventory count, Currency - discrete counts from multiple sources
• Quest progress, Level - progression state
• Input state, UI state - transient application state

Saving and Loading an Attribute¶

Only BaseValue and CurrentValue are serialized (the active modifications are not), so the two restore paths deliberately differ:

• JSON (Serializer.JsonStringify / JsonDeserialize) keeps the CurrentValue that was written. An attribute saved while buffed loads with the buff still in the number, because recalculating from a base value with no modifications would silently drop it.
• Unity serialization (a [SerializeField] on a MonoBehaviour or ScriptableObject) recalculates from the base value on the first read, because the modifications that produced the saved number belong to a session that has ended.

Call ClearCache() after a JSON load if you intend to rebuild the modifications yourself and want the value to follow them.

The cache also follows the base value. Writing BaseValue through the Inspector, a prefab apply or an undo assigns the field without running any code, so CurrentValue recalculates on the next read rather than reporting a number computed from the old base.

Why This Matters¶

When you use Attributes for frequently mutated "current" values:

1. State conflicts - The effects system and other systems fight over the value
2. Save/load bugs - Unclear whether to save base value or current value with modifiers
3. Unexpected restorations - Removing an effect may restore old base value, losing damage/healing
4. Performance overhead - Recalculating modifications on every damage tick
5. Complexity - Need to carefully coordinate between effects and direct mutations

The Golden Rule: If a value is modified by systems outside the effects system regularly (combat, regeneration, consumption), it should NOT be an Attribute. Use a regular field instead and let Attributes handle the maximums/limits.

Using Tags WITHOUT Attributes¶

Even without any Attributes, the Effects System is useful for tag-based state management and cosmetic effects.

When to Use Tags Without Attributes¶

You should consider tag-only effects when:

• Managing categorical states ("Stunned", "Invisible", "InDialogue")
• Implementing temporary permissions ("CanDash", "CanDoubleJump")
• Coordinating system interactions ("InCombat", "InCutscene")
• Creating purely visual effects (particles, overlays) with timed lifetimes
• Building capability systems without numeric modifiers

Example: Pure Tag Effects¶

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

// No AttributesComponent needed!
public class StealthCharacter : MonoBehaviour
{
    [SerializeField] private AttributeEffect invisibilityEffect;
    [SerializeField] private AttributeEffect stunnedEffect;

    void Start()
    {
        // Apply invisibility for 5 seconds
        // InvisibilityEffect.asset:
        //   - durationType: Duration (5 seconds)
        //   - effectTags: ["Invisible", "Stealthy"]
        //   - modifications: (EMPTY - no attributes needed!)
        //   - cosmeticEffects: shimmer particles
        this.ApplyEffect(invisibilityEffect);
    }

    void Update()
    {
        // Check tags to gate behavior
        if (this.HasTag("Stunned"))
        {
            // Prevent all actions
            return;
        }

        // AI can't detect invisible characters
        if (!this.HasTag("Invisible"))
        {
            BroadcastPosition();
        }
    }
}

Example: Tag Lifetimes for Cosmetics¶

Tags with durations provide automatic cleanup for visual effects:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

// Create a "ShowDamageIndicator" effect:
// DamageIndicator.asset:
//   - durationType: Duration (1.5 seconds)
//   - effectTags: ["DamageIndicator"]
//   - modifications: (EMPTY)
//   - cosmeticEffects: DamageNumbersPrefab

public class CombatFeedback : MonoBehaviour
{
    [SerializeField] private AttributeEffect damageIndicator;

    public void ShowDamage(float amount)
    {
        // Apply effect - cosmetic spawns automatically
        this.ApplyEffect(damageIndicator);

        // After 1.5 seconds, cosmetic is automatically cleaned up
        // No manual cleanup code needed!
    }
}

Benefits of Tag-Only Usage¶

• ✅ Simpler setup - No AttributesComponent required
• ✅ Automatic cleanup - Duration-based tags clean up themselves
• ✅ Reference counting - Multiple sources work naturally
• ✅ Cosmetic integration - Visual effects lifecycle managed automatically
• ✅ System decoupling - Any system can query tags without dependencies

Tag-Only Patterns¶

1. Temporary Permissions:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

// PowerUpEffect.asset:
//   - durationType: Duration (10 seconds)
//   - effectTags: ["CanDash", "CanDoubleJump", "PoweredUp"]
//   - modifications: (EMPTY)

public void GrantPowerUp()
{
    player.ApplyEffect(powerUpEffect);
    // Player now has special abilities for 10 seconds
}

2. State Management:

1
2
3
4
5
6
7

// DialogueStateEffect.asset:
//   - durationType: Infinite
//   - effectTags: ["InDialogue", "InputDisabled"]

EffectHandle? dialogueHandle = player.ApplyEffect(dialogueState);
// ... dialogue system runs ...
player.RemoveEffect(dialogueHandle.Value);

3. Visual-Only Effects:

1
2
3
4
5
6
7

// LevelUpEffect.asset:
//   - durationType: Duration (2 seconds)
//   - effectTags: ["LevelingUp"]
//   - cosmeticEffects: GlowParticles, LevelUpSound

player.ApplyEffect(levelUpEffect);
// Particles and sound play, then clean up automatically

Cosmetic Effects - Complete Guide¶

Cosmetic effects handle the visual and audio presentation of effects. They provide a clean separation between gameplay logic (tags, attributes) and presentation (particles, sounds, UI).

Architecture Overview¶

Component Hierarchy:

1
2
3
4
5
6
7

CosmeticEffectData (Container GameObject/Prefab)
  └─ CosmeticEffectComponent (Base class - abstract)
       └─ Your custom implementations:
           - ParticleCosmeticEffect
           - AudioCosmeticEffect
           - UICosmeticEffect
           - AnimationCosmeticEffect

Creating a Cosmetic Effect¶

Step 1: Create a prefab with CosmeticEffectData¶

1. Create a new GameObject in the scene
2. Add Component → CosmeticEffectData
3. Add your custom cosmetic components (particle systems, audio sources, etc.)
4. Save as prefab
5. Reference this prefab in your AttributeEffect.cosmeticEffects list

Step 2: Implement CosmeticEffectComponent subclasses¶

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

using UnityEngine;
using WallstopStudios.UnityHelpers.Tags;

public class ParticleCosmeticEffect : CosmeticEffectComponent
{
    [SerializeField] private ParticleSystem particles;

    // RequiresInstance = true creates a new instance per application
    // RequiresInstance = false shares one instance across all applications
    public override bool RequiresInstance => true;

    // CleansUpSelf = true means you handle destruction yourself
    // CleansUpSelf = false means EffectHandler destroys the GameObject
    public override bool CleansUpSelf => false;

    public override void OnApplyEffect(GameObject target)
    {
        base.OnApplyEffect(target);

        // Attach cosmetic to target
        transform.SetParent(target.transform);
        transform.localPosition = Vector3.zero;

        // Start visual effect
        particles.Play();
    }

    public override void OnRemoveEffect(GameObject target)
    {
        base.OnRemoveEffect(target);

        // Stop particles
        particles.Stop();

        // If CleansUpSelf = false, GameObject is destroyed automatically
        // If CleansUpSelf = true, you must handle destruction
    }
}

RequiresInstance: Shared vs Instanced¶

RequiresInstance = false (Shared):

• One cosmetic instance is reused for all applications
• Best for: UI overlays, status icons, shared audio managers
• Lower memory footprint
• All targets share the same cosmetic GameObject

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

public class StatusIconCosmetic : CosmeticEffectComponent
{
    public override bool RequiresInstance => false; // SHARED

    [SerializeField] private Image iconImage;
    private int activeCount = 0;

    public override void OnApplyEffect(GameObject target)
    {
        base.OnApplyEffect(target);
        activeCount++;

        // Show icon if this is first application
        if (activeCount == 1)
        {
            iconImage.enabled = true;
        }
    }

    public override void OnRemoveEffect(GameObject target)
    {
        base.OnRemoveEffect(target);
        activeCount--;

        // Hide icon when no more applications
        if (activeCount == 0)
        {
            iconImage.enabled = false;
        }
    }
}

RequiresInstance = true (Instanced):

• New cosmetic instance created for each application
• Best for: Particles, per-effect animations, independent visuals
• Each application has an isolated state
• Higher memory cost, but full independence

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

public class FireParticleCosmetic : CosmeticEffectComponent
{
    public override bool RequiresInstance => true; // INSTANCED

    [SerializeField] private ParticleSystem fireParticles;

    public override void OnApplyEffect(GameObject target)
    {
        base.OnApplyEffect(target);

        // Each instance is independent
        transform.SetParent(target.transform);
        transform.localPosition = Vector3.zero;
        fireParticles.Play();
    }
}

CleansUpSelf: Automatic vs Manual Cleanup¶

CleansUpSelf = false (Automatic - Default):

• EffectHandler destroys the GameObject when an effect is removed
• Simplest option for most cases
• Immediate cleanup

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

public class SimpleParticleEffect : CosmeticEffectComponent
{
    public override bool CleansUpSelf => false; // AUTOMATIC

    public override void OnRemoveEffect(GameObject target)
    {
        base.OnRemoveEffect(target);
        // GameObject destroyed automatically by EffectHandler
    }
}

CleansUpSelf = true (Manual Cleanup):

• You are responsible for destroying the GameObject
• Use when you need delayed cleanup (fade out animations, particle finish)
• More control over cleanup timing

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

public class FadeOutEffect : CosmeticEffectComponent
{
    public override bool CleansUpSelf => true; // MANUAL

    [SerializeField] private float fadeOutDuration = 1f;
    private bool isRemoving = false;

    public override void OnRemoveEffect(GameObject target)
    {
        base.OnRemoveEffect(target);

        if (!isRemoving)
        {
            isRemoving = true;
            StartCoroutine(FadeOutAndDestroy());
        }
    }

    private IEnumerator FadeOutAndDestroy()
    {
        // Fade out over time
        float elapsed = 0f;
        SpriteRenderer sprite = GetComponent<SpriteRenderer>();
        Color originalColor = sprite.color;

        while (elapsed < fadeOutDuration)
        {
            elapsed += Time.deltaTime;
            float alpha = 1f - (elapsed / fadeOutDuration);
            sprite.color = new Color(originalColor.r, originalColor.g, originalColor.b, alpha);
            yield return null;
        }

        // Now safe to destroy
        Destroy(gameObject);
    }
}

Complete Cosmetic Examples¶

Example 1: Buff Visual with Particles and Sound¶

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

public class BuffCosmetic : CosmeticEffectComponent
{
    [SerializeField] private ParticleSystem buffParticles;
    [SerializeField] private AudioSource audioSource;
    [SerializeField] private AudioClip applySound;
    [SerializeField] private AudioClip removeSound;

    public override bool RequiresInstance => true;
    public override bool CleansUpSelf => false;

    public override void OnApplyEffect(GameObject target)
    {
        base.OnApplyEffect(target);

        // Position cosmetic on target
        transform.SetParent(target.transform);
        transform.localPosition = Vector3.zero;

        // Play effects
        buffParticles.Play();
        audioSource.PlayOneShot(applySound);
    }

    public override void OnRemoveEffect(GameObject target)
    {
        base.OnRemoveEffect(target);

        audioSource.PlayOneShot(removeSound);
        buffParticles.Stop();
        // Automatic cleanup after this
    }
}

Example 2: Status UI Overlay (Shared)¶

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

public class StatusOverlayCosmetic : CosmeticEffectComponent
{
    [SerializeField] private SpriteRenderer overlaySprite;
    [SerializeField] private Color overlayColor = Color.red;

    public override bool RequiresInstance => false; // SHARED
    public override bool CleansUpSelf => false;

    private SpriteRenderer targetSprite;

    public override void OnApplyEffect(GameObject target)
    {
        base.OnApplyEffect(target);

        targetSprite = target.GetComponent<SpriteRenderer>();
        if (targetSprite != null)
        {
            // Tint the sprite
            targetSprite.color = overlayColor;
        }
    }

    public override void OnRemoveEffect(GameObject target)
    {
        base.OnRemoveEffect(target);

        if (targetSprite != null)
        {
            // Restore original color
            targetSprite.color = Color.white;
        }
    }
}

Example 3: Animation Trigger¶

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

public class AnimationCosmetic : CosmeticEffectComponent
{
    [SerializeField] private string applyTrigger = "BuffApplied";
    [SerializeField] private string removeTrigger = "BuffRemoved";

    public override bool RequiresInstance => false;

    public override void OnApplyEffect(GameObject target)
    {
        base.OnApplyEffect(target);

        Animator animator = target.GetComponent<Animator>();
        if (animator != null)
        {
            animator.SetTrigger(applyTrigger);
        }
    }

    public override void OnRemoveEffect(GameObject target)
    {
        base.OnRemoveEffect(target);

        Animator animator = target.GetComponent<Animator>();
        if (animator != null)
        {
            animator.SetTrigger(removeTrigger);
        }
    }
}

Combining Multiple Cosmetics¶

A single effect can have multiple cosmetic components with different behaviors:

1
2
3
4
5

// PoisonEffect prefab:
//   - CosmeticEffectData
//   - PoisonParticles (RequiresInstance = true)  // One per stack
//   - PoisonStatusIcon (RequiresInstance = false) // Shared UI element
//   - PoisonAudioLoop (RequiresInstance = true)   // One audio loop per stack

Cosmetic Lifecycle¶

Application Flow:

1. AttributeEffect applied to GameObject
2. EffectHandler checks cosmeticEffects list
3. For each CosmeticEffectData:
4. If RequiresInstancing = true: Instantiate and parent to target
5. If RequiresInstancing = false: Reuse existing instance
6. Call OnApplyEffect(target) on all components
7. Cosmetics remain active while an effect is active

Removal Flow:

1. Effect expires or is manually removed
2. EffectHandler calls OnRemoveEffect(target) on all components
3. For each component:
4. If CleansUpSelf = false: EffectHandler destroys GameObject immediately
5. If CleansUpSelf = true: Component handles its own destruction

Best Practices¶

Performance:

• ✅ Prefer RequiresInstance = false when possible (lower overhead)
• ✅ Use object pooling for frequently spawned instanced cosmetics
• ✅ Keep OnApplyEffect and OnRemoveEffect lightweight
• ❌ Avoid expensive operations in these callbacks

Architecture:

• ✅ One responsibility per cosmetic component (particles, audio, UI separate)
• ✅ Store references in OnApplyEffect, use them in OnRemoveEffect
• ✅ Always call base.OnApplyEffect() and base.OnRemoveEffect()
• ❌ Don't access gameplay logic from cosmetics (maintain separation)

Cleanup:

• ✅ Use CleansUpSelf = false unless you need delayed cleanup
• ✅ If using CleansUpSelf = true, ensure you always destroy the GameObject
• ✅ Handle null targets gracefully (target may be destroyed early)
• ❌ Don't leak GameObjects by forgetting to clean up

Recipes¶

1) Buff with % Speed for 5s (refreshable)¶

• Effect: Multiplication Speed *= 1.5f, Duration=5, resetDurationOnReapplication=true, tag Haste.
• Apply to extend: reapply before expiry to reset the timer.

2) Poison: "Poisoned" tag 10s with periodic damage¶

• periodicEffects: add a definition with interval = 1s, maxTicks = 10, and an empty modifications array (ticks drive behaviours)
• behaviors: attach a PoisonDamageBehavior that applies damage during OnPeriodicTick (sample below)
• durationType: Duration 10s (or Infinite if the periodic schedule should drive expiry)
• effectTags: [ "Poisoned" ]
• cosmetics: particles + UI icon
• Optional: add an immediate modification for on-apply burst damage

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

public sealed class PlayerHealth : MonoBehaviour
{
    public void ApplyDamage(float amount) { }
}

[CreateAssetMenu(menuName = "Combat/Effects/Poison Damage")]
public sealed class PoisonDamageBehavior : EffectBehavior
{
    [SerializeField]
    private float damagePerTick = 5f;

    public override void OnPeriodicTick(
        EffectBehaviorContext context,
        PeriodicEffectTickContext tickContext
    )
    {
        if (!context.Target.TryGetComponent(out PlayerHealth health))
        {
            return;
        }

        health.ApplyDamage(damagePerTick);
    }
}

Pair this with a health component that owns mutable current-health state instead of modelling CurrentHealth as an Attribute.

Current Resource Ownership Pattern¶

For health, mana, stamina, ammo, shields, and similar resources, keep one component responsible for mutable current state and use Attributes only for caps or rates. This avoids hidden restore bugs when an effect expires.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52

public sealed class PlayerHealth : AttributesComponent
{
    [SerializeField]
    private float currentHealth = 100f;

    public Attribute MaxHealth = 100f;

    public float CurrentHealth => currentHealth;

    public float NormalizedHealth =>
        MaxHealth.CurrentValue <= 0f ? 0f : currentHealth / MaxHealth.CurrentValue;

    protected override void Awake()
    {
        base.Awake();
        currentHealth = Mathf.Clamp(currentHealth, 0f, MaxHealth.CurrentValue);
        OnAttributeModified += HandleAttributeModified;
    }

    public void ApplyDamage(float amount)
    {
        if (amount <= 0f)
        {
            return;
        }

        SetCurrentHealth(currentHealth - amount);
    }

    public void ApplyHealing(float amount)
    {
        if (amount <= 0f)
        {
            return;
        }

        SetCurrentHealth(currentHealth + amount);
    }

    private void SetCurrentHealth(float value)
    {
        currentHealth = Mathf.Clamp(value, 0f, MaxHealth.CurrentValue);
    }

    private void HandleAttributeModified(string attributeName, float oldValue, float newValue)
    {
        if (attributeName == nameof(MaxHealth))
        {
            SetCurrentHealth(currentHealth);
        }
    }
}

3) Equipment Aura: +10 Defense while equipped¶

• durationType: Infinite
• modifications: Addition { attribute: "Defense", value: 10f }
• Apply on equip, store the handle, remove on unequip.

4) One‑off Permanent Bonus¶

• durationType: Instant (returns null)
• modifications: Addition or Override on base value (no handle; cannot be removed).

5) Stacking Multiple Instances¶

• Set stackingMode on the effect asset to control reapplication:
• Stack keeps separate handles (respecting maximumStacks, trimming the oldest when the cap is reached).
• Refresh reuses the first handle; set resetDurationOnReapplication = true if the timer should reset on reapplication.
• Replace removes existing handles in the same group before adding a new one.
• Ignore rejects duplicate applications.
• Use stackGroup = CustomKey with a shared stackGroupKey when different assets should share a stack identity.
• Inspect active stacks with EffectHandler.GetEffectStackCount(effect) or tag counts for debugging and UI.
• An OnEffectRemoved subscriber that re-applies the same effect can leave a Stack eviction no smaller than it started. ApplyEffect then returns null and logs a warning rather than registering a handle past maximumStacks, so a Stack application is one of the two cases where a non-instant effect answers null.

6) Shared vs. Instanced Cosmetics¶

• In CosmeticEffectData, set a component’s RequiresInstance = true for per‑application instances (e.g., particles).
• Keep RequiresInstance = false for shared presenters (e.g., status icon overlay).

Periodic Tick Payloads¶

• Populate the periodicEffects list on an AttributeEffect to schedule damage/heal-over-time, resource regen, or scripted pulses without external coroutines.
• Each definition supports initialDelay, interval, and maxTicks (0 = infinite) plus its own AttributeModification bundle applied on every tick.
• Periodic payloads run only for Duration/Infinite effects; they automatically stop after maxTicks or when the effect handle is removed.
• Combine multiple definitions for mixed cadences (e.g., fast minor regen + slower burst heals).

Effect Behaviours¶

• Attach EffectBehavior ScriptableObjects to the behaviors list for per-handle runtime logic.
• The system clones behaviours on application and calls OnApply, OnTick (each frame), OnPeriodicTick (after periodic payloads fire), and OnRemove.
• Behaviours are ideal for integrating bespoke systems (e.g., camera shakes, AI hooks, quest tracking) while keeping designer-authored effects data-driven.
• Keep behaviours stateless or store per-handle state on the cloned instance; clean up in OnRemove.

Removal Is Two-Phase¶

Removing an effect happens in two steps, and callbacks only ever run in the second.

1. Detach. The handle leaves every index the handler keeps -- active effects, stack group, expiration, periodic schedule, behaviours and cosmetics -- before a single line of your code runs.
2. Notify and release. Attribute modifications are removed, then tags, then cosmetics, then OnEffectRemoved, then EffectBehavior.OnRemove on each cloned behaviour.

What that buys you:

• Queries tell the truth from inside teardown. IsEffectActive, GetEffectStackCount and GetActiveEffects all report the handle as gone by the time your first callback runs.
• Removing twice is a no-op, and so is removing a handle that was never applied. A callback that calls RemoveEffect on its own handle -- directly, or through RemoveAllEffects -- returns immediately instead of recursing.
• Re-applying during teardown gives you a new, independent handle. The old one stays removed, and RemoveAllEffects leaves the new effect active rather than silently forgetting it.
• Self-removal stops the rest of the pass. A behaviour that removes its own handle from OnTick or OnPeriodicTick gets no further tick callbacks for that handle this frame, and neither do the other behaviours cloned alongside it.
• A callback that throws still leaves the handler consistent. The remaining phases run, every behaviour clone and cosmetic instance is destroyed, and the first exception is rethrown afterwards. The same holds while applying: if a callback throws during ApplyEffect, the partial application is unwound before the exception reaches you.
• One throwing subscriber does not strand its siblings. Removal isolates per unit of work: per AttributesComponent, per attribute modification, per tag, per cosmetic component and per behaviour. Every modification comes off and every tag's count drops even when the first notification throws, because the handle has already left every index and nothing could remove them on a retry. Application and ticking are the other way round -- the first exception abandons the rest of that pass, because an application unwinds to nothing and a tick runs again next frame.

1
2
3
4
5
6
7
8
9

public override void OnPeriodicTick(EffectBehaviorContext context, PeriodicEffectTickContext tick)
{
    if (3 <= tick.executedTicks)
    {
        // Safe from inside the callback. This behaviour and its siblings receive OnRemove before
        // control returns here, and no further ticks are delivered for this handle.
        context.handler.RemoveEffect(context.handle);
    }
}

Best Practices¶

• Use Addition for flat changes; Multiplication for percentage changes; Override sparingly (wins last).
• Use the Attribute Metadata Cache generator to power editor dropdowns for attribute names and avoid typos.
• Centralize tag strings as constants to prevent mistakes and improve refactor safety.
• Prefer shared cosmetics where feasible; instantiate only when the state must be isolated per application.
• If reapplication should refresh timers, set resetDurationOnReapplication = true on the effect.

Type-Safe Effect References with Enums¶

Instead of managing effects through inspector references or Resources.Load calls, consider using an enum-based registry for centralized, type-safe access to all your effects:

The Pattern:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51

// 1. Define an enum for all your effects
public enum EffectType
{
    HastePotion,
    StrengthBuff,
    PoisonDebuff,
    ShieldBuff,
    FireDamageOverTime,
}

// 2. Create a centralized registry
public class EffectRegistry : ScriptableObject
{
    [System.Serializable]
    private class EffectEntry
    {
        public EffectType type;
        public AttributeEffect effect;
    }

    [SerializeField] private EffectEntry[] effects;
    private Dictionary<EffectType, AttributeEffect> effectLookup;

    private void OnEnable()
    {
        effectLookup = effects.ToDictionary(e => e.type, e => e.effect);
    }

    public AttributeEffect GetEffect(EffectType type)
    {
        return effectLookup.TryGetValue(type, out AttributeEffect effect)
            ? effect
            : null;
    }
}

// 3. Usage - type-safe and refactorable
public class PlayerAbilities : MonoBehaviour
{
    [SerializeField] private EffectRegistry effectRegistry;

    public void DrinkHastePotion()
    {
        // Compiler ensures this effect exists
        AttributeEffect haste = effectRegistry.GetEffect(EffectType.HastePotion);
        this.ApplyEffect(haste);

        // Typos are caught at compile time
        // effectRegistry.GetEffect(EffectType.HastPotoin); // ❌ Won't compile
    }
}

Using DisplayName for Editor-Friendly Names:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

using System.ComponentModel;

public enum EffectType
{
    [Description("Haste Potion")]
    HastePotion,

    [Description("Strength Buff (10s)")]
    StrengthBuff,

    [Description("Poison DoT")]
    PoisonDebuff,

    [Description("Shield (+50 Defense)")]
    ShieldBuff,
}

// Custom PropertyDrawer can display Description in inspector
// Or use Unity's [InspectorName] attribute in Unity 2021.2+:
// [InspectorName("Haste Potion")] HastePotion,

Cached Name Pattern for Performance:

If you're doing frequent lookups or displaying effect names in UI, cache the enum-to-string mappings:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

public static class EffectTypeExtensions
{
    private static readonly Dictionary<EffectType, string> DisplayNames = new()
    {
        { EffectType.HastePotion, "Haste Potion" },
        { EffectType.StrengthBuff, "Strength Buff" },
        { EffectType.PoisonDebuff, "Poison" },
        { EffectType.ShieldBuff, "Shield" },
    };

    public static string GetDisplayName(this EffectType type)
    {
        return DisplayNames.TryGetValue(type, out string name)
            ? name
            : type.ToString();
    }
}

// Usage in UI
void UpdateEffectTooltip(EffectType effectType)
{
    tooltipText.text = effectType.GetDisplayName();
    // No allocations, no typos, refactor-safe
}

Benefits:

• ✅ Type safety - Compiler catches typos and missing effects
• ✅ Refactoring - Rename effects across the entire codebase reliably
• ✅ Autocomplete - IDE suggests all available effects
• ✅ Performance - Dictionary lookup avoids Resources.Load overhead
• ✅ No magic strings - Effect references are code symbols, not brittle strings

Drawbacks:

• ⚠️ Centralization - All effects must be registered in the enum and registry
• ⚠️ Designer friction - Programmers must add enum entries for new effects
• ⚠️ Scalability - With 100+ effects, enum becomes unwieldy (consider categories)
• ⚠️ Asset decoupling - Effects are tied to code enum, harder to add via mods/DLC

When to Use:

• ✅ Small to medium projects (< 50 effects)
• ✅ Programmer-driven effect creation
• ✅ Need strong refactoring safety
• ✅ Want compile-time validation

When to Avoid:

• ❌ Designer-driven workflows (they can't add enum entries)
• ❌ Modding/DLC systems (effects defined outside codebase)
• ❌ Very large effect catalogs (enums become bloated)
• ❌ Rapid prototyping (slows iteration)

Integration with Unity Helpers' Built-in Enum Utilities:

This package already includes high-performance EnumDisplayNameAttribute and ToCachedName() extensions (see EnumExtensions.cs:437-478). You can use these for better performance:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

using WallstopStudios.UnityHelpers.Core.Attributes;
using WallstopStudios.UnityHelpers.Core.Extension;

public enum EffectType
{
    [EnumDisplayName("Haste Potion")]
    HastePotion,

    [EnumDisplayName("Strength Buff (10s)")]
    StrengthBuff,

    [EnumDisplayName("Poison DoT")]
    PoisonDebuff,
}

// High-performance cached display name (zero allocation after first call)
void UpdateEffectTooltip(EffectType effectType)
{
    tooltipText.text = effectType.ToDisplayName(); // Uses EnumDisplayNameCache<T>
}

// Or use ToCachedName() for the enum's field name without attributes
void LogEffect(EffectType effectType)
{
    Debug.Log($"Applied: {effectType.ToCachedName()}"); // Uses EnumNameCache<T>
}

Performance characteristics:

• ToDisplayName(): O(1) lookup, zero allocations (array-based for enums ≤256 values)
• ToCachedName(): O(1) lookup, zero allocations, thread-safe with concurrent dictionary
• Both use aggressive inlining and avoid boxing

This eliminates the need to manually maintain a DisplayNames dictionary as shown in the earlier example; the package already provides optimized caching infrastructure.

API Reference¶

AttributeEffect Query Methods¶

Checking for Tags:

1
2
3
4
5
6

// Check if effect has a specific tag
bool hasTag = effect.HasTag("Haste");

// Check if effect has any of the specified tags
bool hasAny = effect.HasAnyTag(new[] { "Haste", "Speed", "Boost" });
bool hasAnyFromList = effect.HasAnyTag(myTagList); // IReadOnlyList<string> overload

Checking for Attribute Modifications:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

// Check if effect modifies a specific attribute
bool modifiesSpeed = effect.ModifiesAttribute("Speed");

// Get all modifications for a specific attribute
using var lease = Buffers<AttributeModification>.List.Get(out List<AttributeModification> mods);
effect.GetModifications("Speed", mods);
foreach (AttributeModification mod in mods)
{
    Debug.Log($"Action: {mod.action}, Value: {mod.value}");
}

TagHandler Query Methods¶

Basic Tag Queries:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

// Check if a single tag is active
if (player.HasTag("Stunned"))
{
    DisableInput();
}

// Check if any of the tags are active
if (player.HasAnyTag(new[] { "Stunned", "Frozen", "Sleeping" }))
{
    PreventMovement();
}

// Check if all tags are active
if (player.HasAllTags(new[] { "Wet", "Grounded" }))
{
    ApplyElectricShock();
}

// Check if none of the tags are active
if (player.HasNoneOfTags(new[] { "Invulnerable", "Untargetable" }))
{
    AllowDamage();
}

Tag Count Queries:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

// Get the active count for a tag
if (player.TryGetTagCount("Poisoned", out int stacks) && stacks >= 3)
{
    TriggerCriticalPoisonWarning();
}

// Get all active tags
List<string> activeTags = player.GetActiveTags();
foreach (string tag in activeTags)
{
    Debug.Log($"Active tag: {tag}");
}

Collection Type Support:

All tag query methods support multiple collection types with optimized implementations:

• IReadOnlyList<string> (optimized with index-based iteration)
• List<string>
• HashSet<string>
• SortedSet<string>
• Queue<string>
• Stack<string>
• LinkedList<string>
• Any IEnumerable<string>

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

// Example with different collection types
HashSet<string> immunityTags = new() { "Invulnerable", "Immune" };
if (player.HasAnyTag(immunityTags))
{
    PreventDamage();
}

List<string> crowdControlTags = new() { "Stunned", "Rooted", "Silenced" };
if (player.HasNoneOfTags(crowdControlTags))
{
    EnableAllAbilities();
}

EffectHandler Query Methods¶

Effect State Queries:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

// Check if a specific effect is currently active
if (effectHandler.IsEffectActive(hasteEffect))
{
    ShowHasteIndicator();
}

// Get the stack count for an effect
int hasteStacks = effectHandler.GetEffectStackCount(hasteEffect);
Debug.Log($"Haste stacks: {hasteStacks}");

// Get remaining duration for a specific effect instance
if (effectHandler.TryGetRemainingDuration(effectHandle, out float remaining))
{
    UpdateDurationUI(remaining);
}

Effect Manipulation:

1
2
3
4
5
6
7
8

// Refresh an effect's duration
if (effectHandler.RefreshEffect(effectHandle))
{
    Debug.Log("Effect duration refreshed");
}

// Refresh effect ignoring reapplication policy
effectHandler.RefreshEffect(effectHandle, ignoreReapplicationPolicy: true);

FAQ¶

Q: Should I use an Attribute for CurrentHealth?

• No! Use Attributes for values primarily modified by the effects system (MaxHealth, Speed, AttackDamage). CurrentHealth is modified by multiple systems (combat, healing, regeneration) and should be a regular field. See "Understanding Attributes: What to Model and What to Avoid" section above for details. Mixing direct mutations with effect modifications causes state conflicts and save/load bugs.

Q: Why didn't I get an EffectHandle?

• Instant effects modify the base value permanently and do not return a handle (null). Duration/Infinite do.

Q: Do modifications stack across multiple effects?

• Yes. Each Attribute applies all active modifications ordered by action: Addition → Multiplication → Override.

Q: How do I remove just one instance of an effect?

• Keep the EffectHandle returned from ApplyEffect and pass it to RemoveEffect(handle).

Q: Can a callback remove or re-apply an effect while that effect is being removed?

• Yes. See Removal Is Two-Phase above. The handle is detached before any callback runs, so removing it again is a no-op, queries report it inactive, and re-applying produces a new independent handle.

Q: Two systems apply the same tag. Who owns removal?

• The tag is reference‑counted. Each application increments the count; removal decrements it. The tag is removed when the count reaches 0.

Q: When should I use tags vs. checking stats?

• Use tags to represent categorical states (e.g., Stunned/Poisoned/Invulnerable) independent of numeric values. Check stats for numeric thresholds or calculations.

Q: How do I check if an effect modifies a specific attribute?

• Use effect.ModifiesAttribute("AttributeName") to check if an effect contains modifications for a specific attribute, or effect.GetModifications("AttributeName", buffer) to retrieve all modifications for that attribute.

Q: How do I query tag counts or check multiple tags at once?

• Use TryGetTagCount(tag, out int count) to get the active count for a tag, HasAllTags(tags) to check if all tags are active, or HasNoneOfTags(tags) to check if none are active.

Troubleshooting¶

• Attribute name doesn’t apply
• Ensure the attribute field matches a public/private Attribute field name on an AttributesComponent subclass.

• Regenerate the Attribute Metadata Cache to update editor dropdowns.

• Effect didn’t clean up cosmetics

• Confirm RequiresInstance is set correctly and components either clean up themselves (CleansUpSelf) or are destroyed by EffectHandler.

• Duration didn’t refresh on reapplication

• Set resetDurationOnReapplication = true on the AttributeEffect.

• "defines periodic or behaviour data but is Instant"

• An Instant effect returns no handle, so its periodicEffects and behaviors can never run. Either give the effect a Duration/Infinite duration type or clear those lists. The message appears in the Inspector when the effect is edited, and once per effect on the first application.

• "has an unassigned CosmeticEffectData entry"

• A slot in the effect's Cosmetic Effects list is empty. Empty slots cannot be instanced and are skipped; remove the slot or assign a prefab.

• A saved attribute loads without its buff

• JSON keeps the written CurrentValue; Unity serialization recalculates from the base value. See Saving and Loading an Attribute.

Advanced Scenarios: Beyond Buffs and Debuffs¶

While the Effects System handles traditional buff/debuff mechanics well, it can also be used to build capability systems that drive complex gameplay decisions across your entire codebase. This section explores advanced patterns that use tags extensively for architectural purposes.

Understanding the Capability Pattern¶

The Problem with Flags:

Many developers start with hardcoded boolean flags:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

// ❌ OLD WAY: Scattered boolean flags
public class PlayerController : MonoBehaviour
{
    public bool isInvulnerable;
    public bool canDash;
    public bool hasDoubleJump;
    public bool isInvisible;
    // 50+ booleans later...

    void TakeDamage(float damage)
    {
        if (isInvulnerable) return;
        // ...
    }

    void Update()
    {
        if (Input.GetKeyDown(KeyCode.Space) && canDash)
            Dash();
    }
}

// Problems:
// 1. Every system needs direct references to check flags
// 2. Adding temporary effects requires custom timers
// 3. Multiple sources granting same capability = conflicts
// 4. No centralized place to see what capabilities exist
// 5. Difficult to debug "why can't I do X?"

The Solution - Tag-Based Capabilities:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

// ✅ NEW WAY: Tag-based capability system
public class PlayerController : MonoBehaviour
{
    void TakeDamage(float damage)
    {
        // Any system can grant "Invulnerable" tag
        if (this.HasTag("Invulnerable")) return;
        // ...
    }

    void Update()
    {
        // Check capability before allowing action
        if (Input.GetKeyDown(KeyCode.Space) && this.HasTag("CanDash"))
            Dash();
    }
}

// Benefits:
// 1. Decoupled - systems query tags, don't need direct references
// 2. Multiple sources work automatically (reference-counted)
// 3. Temporary effects are free - just apply/remove tag
// 4. Debuggable - inspect TagHandler to see all active tags
// 5. Designer-friendly - add capabilities via ScriptableObjects