gameplay-mechanics

What this skill does

# Gameplay Mechanics Implementation

## Core Mechanics Framework

```
┌─────────────────────────────────────────────────────────────┐
│                    ACTION → EFFECT LOOP                      │
├─────────────────────────────────────────────────────────────┤
│  INPUT          PROCESS          OUTPUT          FEEDBACK   │
│  ┌─────┐       ┌─────────┐      ┌─────────┐    ┌─────────┐ │
│  │Press│──────→│Validate │─────→│Update   │───→│Visual   │ │
│  │Button│      │& Execute│      │State    │    │Audio    │ │
│  └─────┘       └─────────┘      └─────────┘    │Haptic   │ │
│                                                 └─────────┘ │
│                                                              │
│  TIMING REQUIREMENTS:                                        │
│  • Input → Response: < 100ms (feels responsive)             │
│  • Animation start: < 50ms (feels instant)                  │
│  • Audio feedback: < 20ms (in sync with action)             │
└─────────────────────────────────────────────────────────────┘
```

## Feedback Loop Design

```
FEEDBACK TIMING LAYERS:
┌─────────────────────────────────────────────────────────────┐
│  IMMEDIATE (0-100ms):                                        │
│  ├─ Button press sound                                      │
│  ├─ Animation start                                         │
│  ├─ Screen shake                                            │
│  └─ Controller vibration                                    │
│                                                              │
│  SHORT-TERM (100ms-1s):                                      │
│  ├─ Damage numbers appear                                   │
│  ├─ Health bar updates                                      │
│  ├─ Enemy reaction animation                                │
│  └─ Particle effects                                        │
│                                                              │
│  LONG-TERM (1s+):                                            │
│  ├─ XP/Score increase                                       │
│  ├─ Level up notification                                   │
│  ├─ Achievement unlock                                      │
│  └─ Story progression                                       │
└─────────────────────────────────────────────────────────────┘
```

## Combat Mechanics

```csharp
// ✅ Production-Ready: Combat State Machine
public class CombatStateMachine : MonoBehaviour
{
    public enum CombatState { Idle, Attacking, Blocking, Recovering, Staggered }

    [Header("Combat Parameters")]
    [SerializeField] private float attackDamage = 10f;
    [SerializeField] private float attackRange = 2f;
    [SerializeField] private float attackCooldown = 0.5f;
    [SerializeField] private float blockDamageReduction = 0.7f;
    [SerializeField] private float staggerDuration = 0.3f;

    private CombatState _currentState = CombatState.Idle;
    private float _stateTimer;

    public event Action<CombatState> OnStateChanged;
    public event Action<float> OnDamageDealt;
    public event Action<float> OnDamageTaken;

    public bool TryAttack()
    {
        if (_currentState != CombatState.Idle) return false;

        TransitionTo(CombatState.Attacking);
        StartCoroutine(AttackSequence());
        return true;
    }

    private IEnumerator AttackSequence()
    {
        // Wind-up phase
        yield return new WaitForSeconds(0.1f);

        // Active hit frame
        var hits = Physics.OverlapSphere(transform.position + transform.forward, attackRange);
        foreach (var hit in hits)
        {
            if (hit.TryGetComponent<IDamageable>(out var target))
            {
                target.TakeDamage(attackDamage);
                OnDamageDealt?.Invoke(attackDamage);
            }
        }

        // Recovery phase
        yield return new WaitForSeconds(attackCooldown);
        TransitionTo(CombatState.Idle);
    }

    public float TakeDamage(float damage)
    {
        float finalDamage = _currentState == CombatState.Blocking
            ? damage * (1f - blockDamageReduction)
            : damage;

        OnDamageTaken?.Invoke(finalDamage);

        if (finalDamage > 5f) // Stagger threshold
        {
            TransitionTo(CombatState.Staggered);
            StartCoroutine(RecoverFromStagger());
        }

        return finalDamage;
    }

    private void TransitionTo(CombatState newState)
    {
        _currentState = newState;
        _stateTimer = 0f;
        OnStateChanged?.Invoke(newState);
    }
}
```

## Resource Economy System

```
ECONOMY BALANCE FORMULA:
┌─────────────────────────────────────────────────────────────┐
│  INCOME vs EXPENDITURE:                                      │
│                                                              │
│  Hourly Income = (Enemies/hr × Gold/Enemy) + PassiveIncome  │
│  Hourly Spend  = (Upgrades + Consumables + Deaths)          │
│                                                              │
│  BALANCE RATIO:                                              │
│  • < 0.8: Too scarce (frustrating)                          │
│  • 0.8-1.2: Balanced (meaningful choices)                   │
│  • > 1.2: Too abundant (no tension)                         │
│                                                              │
│  EXAMPLE STAMINA SYSTEM:                                     │
│  ┌───────────────────────────────────────────────────────┐  │
│  │  Max: 100  │  Regen: 20/sec  │  On Hit: +10           │  │
│  ├───────────────────────────────────────────────────────┤  │
│  │  Light Attack: -10  │  Heavy Attack: -25              │  │
│  │  Dodge: -15         │  Block: -5/hit                  │  │
│  │  Sprint: -5/sec     │  Jump: -8                       │  │
│  └───────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
```

## Progression Systems

```
PROGRESSION CURVE:
┌─────────────────────────────────────────────────────────────┐
│  Power                                                       │
│    ↑                                                         │
│    │                                    ╱───── Late Game     │
│    │                              ╱────╱       (slow, goals) │
│    │                        ╱────╱                           │
│    │                  ╱────╱                                 │
│    │            ╱────╱       Mid Game                        │
│    │      ╱────╱             (steady progress)               │
│    │ ╱───╱                                                   │
│    │╱ Early Game (fast, hook player)                        │
│    └────────────────────────────────────────────────→ Time   │
│                                                              │
│  XP CURVE FORMULA:                                           │
│  XP_needed(level) = base_xp × (level ^ growth_rate)         │
│  • growth_rate 1.5: Gentle curve (casual)                   │
│  • growth_rate 2.0: Standard curve (balanced)               │
│  • growth_rate 2.5: Steep curve (hardcore)                  │
└─────────────────────────────────────────────────────────────┘
```

```csharp
// ✅ Production-Ready: Progression Manager
public class ProgressionManager : MonoBehaviour
{
    [Header("Progression Config")]
    [SerializeField] private int baseXP = 100;
    [SerializeField] private float growthRate = 2.0f;
    [SerializeField] private int maxLevel = 50;

    private int _currentLevel = 1;
    private int _currentXP = 0;

    public event Action<int> OnLevelUp;
    public event Action<int, int> OnXPGained; // current, required

    public int XPForLevel(int level)
    {
        return Mathf.RoundToInt(baseXP * Mathf.Pow(level, growthRate));
    }

    public void AddXP(int amount)
    {
        _currentXP += amount;
        int required = XPForLevel(_currentLevel);

        OnXPGained?.Invoke(_currentXP, required);

        while (_currentXP >= required && _currentLevel < maxLevel)
        {