Collectibles & Power-ups

namespace InfiniteRunner.Core
{
    /// <summary>
    /// Interface for objects that can be managed by the ObjectPool.
    /// Any pooled object must implement these two lifecycle methods.
    /// </summary>
    public interface IPoolable
    {
        /// <summary>
        /// Called when this object is taken from the pool and placed in the world.
        /// Use this to reset state, enable visuals, and start behavior.
        /// </summary>
        void OnSpawnFromPool();

        /// <summary>
        /// Called when this object is returned to the pool.
        /// Use this to disable visuals, stop coroutines, and clean up.
        /// </summary>
        void OnReturnToPool();
    }
}

using UnityEngine;
using InfiniteRunner.Core;

namespace InfiniteRunner.Gameplay
{
    /// <summary>
    /// Represents a single collectible coin in the game world.
    /// Coins spin to attract the player's attention, detect collection
    /// via trigger colliders, and return themselves to the object pool
    /// when collected or when the chunk they belong to is recycled.
    /// </summary>
    [RequireComponent(typeof(Collider))]
    public class Coin : MonoBehaviour, IPoolable
    {
        // ---------------------------------------------------------------
        // Inspector Fields
        // ---------------------------------------------------------------

        [Header("Spin Animation")]
        [Tooltip("How fast the coin rotates around its Y-axis in degrees per second.")]
        [SerializeField] private float spinSpeed = 180f;

        [Header("Hover Animation")]
        [Tooltip("How far up and down the coin bobs (in Unity units).")]
        [SerializeField] private float hoverAmplitude = 0.15f;

        [Tooltip("How fast the coin bobs up and down (cycles per second).")]
        [SerializeField] private float hoverFrequency = 2f;

        [Header("Collection")]
        [Tooltip("How many base points this coin is worth.")]
        [SerializeField] private int coinValue = 1;

        [Tooltip("Tag that identifies the player GameObject.")]
        [SerializeField] private string playerTag = "Player";

        // ---------------------------------------------------------------
        // Private State
        // ---------------------------------------------------------------

        // The Y position where this coin was originally placed.
        // We use this as the center point for the hover animation.
        private float baseYPosition;

        // Tracks how far along the hover sine wave we are.
        // Randomized on spawn so not all coins bob in sync.
        private float hoverTimer;

        // Whether this coin is currently active and collectible.
        // Prevents double-collection if two triggers overlap.
        private bool isActive;

        // Cached reference to our visual child (the mesh/sprite).
        // We disable this on collection for an instant visual response.
        private GameObject visual;

        // ---------------------------------------------------------------
        // Unity Lifecycle
        // ---------------------------------------------------------------

        private void Awake()
        {
            // Cache the visual child. We assume the first child is the
            // coin's visual representation (mesh or sprite).
            if (transform.childCount > 0)
            {
                visual = transform.GetChild(0).gameObject;
            }

            // Make sure our collider is set to trigger mode.
            // Triggers detect overlap without causing physics collisions.
            Collider col = GetComponent<Collider>();
            if (col != null)
            {
                col.isTrigger = true;
            }
        }

        private void Update()
        {
            // Only animate while the coin is active.
            if (!isActive) return;

            // --- Spin Animation ---
            // Rotate around the Y-axis (up) each frame.
            // Time.deltaTime ensures smooth, frame-rate-independent rotation.
            transform.Rotate(Vector3.up, spinSpeed * Time.deltaTime, Space.Self);

            // --- Hover Animation ---
            // Advance the hover timer by the elapsed frame time.
            hoverTimer += Time.deltaTime;

            // Calculate a new Y position using a sine wave.
            // Sin oscillates between -1 and 1, so multiplying by amplitude
            // gives us smooth up-and-down motion centered on baseYPosition.
            float newY = baseYPosition
                + Mathf.Sin(hoverTimer * hoverFrequency * Mathf.PI * 2f)
                * hoverAmplitude;

            // Apply the new position, keeping X and Z unchanged.
            Vector3 pos = transform.position;
            pos.y = newY;
            transform.position = pos;
        }

        // ---------------------------------------------------------------
        // Trigger Detection
        // ---------------------------------------------------------------

        /// <summary>
        /// Called by Unity's physics system when another collider enters
        /// our trigger volume. We check if it is the player and, if so,
        /// collect this coin.
        /// </summary>
        private void OnTriggerEnter(Collider other)
        {
            // Ignore if we have already been collected.
            if (!isActive) return;

            // Only the player can collect coins.
            if (!other.CompareTag(playerTag)) return;

            Collect();
        }

        // ---------------------------------------------------------------
        // Collection Logic
        // ---------------------------------------------------------------

        /// <summary>
        /// Handles the collection of this coin. Fires an event so other
        /// systems (scoring, audio, particles) can react, then returns
        /// this coin to the object pool.
        /// </summary>
        private void Collect()
        {
            // Mark as inactive to prevent double-collection.
            isActive = false;

            // Fire the coin collected event so the ScoreManager,
            // AudioManager, and particle systems can respond.
            GameEvents.OnCoinCollected?.Invoke(coinValue);

            // Hide the visual immediately for instant feedback.
            // The actual pool return can happen a frame later if needed.
            if (visual != null)
            {
                visual.SetActive(false);
            }

            // Return this coin to the object pool.
            // The pool will deactivate the entire GameObject.
            ObjectPool.Instance.Return(gameObject);
        }

        // ---------------------------------------------------------------
        // IPoolable Implementation
        // ---------------------------------------------------------------

        /// <summary>
        /// Called when this coin is spawned from the pool.
        /// Resets all state so it behaves like a fresh coin.
        /// </summary>
        public void OnSpawnFromPool()
        {
            // Mark as active and collectible.
            isActive = true;

            // Show the visual.
            if (visual != null)
            {
                visual.SetActive(true);
            }

            // Record the starting Y position for the hover animation.
            baseYPosition = transform.position.y;

            // Randomize the hover timer so coins placed in a line
            // do not all bob in perfect sync. This looks more natural.
            hoverTimer = Random.Range(0f, 2f);

            // Reset rotation so every coin starts facing the same way.
            transform.rotation = Quaternion.identity;
        }

        /// <summary>
        /// Called when this coin is returned to the pool.
        /// Cleans up state and stops animations.
        /// </summary>
        public void OnReturnToPool()
        {
            isActive = false;

            if (visual != null)
            {
                visual.SetActive(false);
            }
        }

        // ---------------------------------------------------------------
        // Public API
        // ---------------------------------------------------------------

        /// <summary>
        /// Returns the point value of this coin.
        /// Used by external systems that need to know coin worth.
        /// </summary>
        public int GetValue()
        {
            return coinValue;
        }
    }
}

namespace InfiniteRunner.Gameplay
{
    /// <summary>
    /// Defines the different arrangements coins can be placed in.
    /// Each pattern creates a distinct visual shape that guides the player.
    /// </summary>
    public enum CoinPatternType
    {
        /// <summary>A straight line of coins along a single lane.</summary>
        Line,

        /// <summary>An arc of coins that rises and falls, suggesting a jump.</summary>
        Arc,

        /// <summary>Coins that alternate between two lanes, forming a zigzag.</summary>
        Zigzag,

        /// <summary>A cluster of coins grouped tightly together.</summary>
        Cluster,

        /// <summary>No coins for this section (used for spacing).</summary>
        None
    }
}

using UnityEngine;

namespace InfiniteRunner.Gameplay
{
    /// <summary>
    /// ScriptableObject that defines a coin placement pattern.
    /// Each pattern stores an array of local offsets where coins
    /// should be placed relative to the pattern's origin point.
    /// </summary>
    [CreateAssetMenu(
        fileName = "NewCoinPattern",
        menuName = "Infinite Runner/Coin Pattern"
    )]
    public class CoinPatternData : ScriptableObject
    {
        [Tooltip("Human-readable name for this pattern.")]
        public string patternName = "New Pattern";

        [Tooltip("The type of pattern for categorization.")]
        public CoinPatternType patternType = CoinPatternType.Line;

        [Tooltip("Local position offsets for each coin in this pattern. " +
                 "X = lane offset, Y = height, Z = forward distance.")]
        public Vector3[] coinOffsets;

        [Tooltip("How likely this pattern is to be selected (higher = more common).")]
        [Range(0f, 1f)]
        public float spawnWeight = 0.5f;

        [Tooltip("Minimum difficulty level before this pattern can appear.")]
        [Range(0f, 1f)]
        public float minDifficulty = 0f;
    }
}

// Coins spaced 2 units apart along the Z-axis (forward)
// All at Y=1 (comfortable collection height)
coinOffsets = new Vector3[]
{
    new Vector3(0f, 1f, 0f),
    new Vector3(0f, 1f, 2f),
    new Vector3(0f, 1f, 4f),
    new Vector3(0f, 1f, 6f),
    new Vector3(0f, 1f, 8f)
};

// Coins form an arch shape - great for placing over obstacles
// Y values rise to a peak at the center, then fall back down
coinOffsets = new Vector3[]
{
    new Vector3(0f, 1.0f, 0f),
    new Vector3(0f, 1.5f, 1.5f),
    new Vector3(0f, 2.2f, 3f),
    new Vector3(0f, 2.8f, 4.5f),  // Peak of the arc
    new Vector3(0f, 2.2f, 6f),
    new Vector3(0f, 1.5f, 7.5f),
    new Vector3(0f, 1.0f, 9f)
};

// Coins alternate left and right on the X-axis
// laneWidth is typically 2.0 units in our game
coinOffsets = new Vector3[]
{
    new Vector3(-2f, 1f, 0f),    // Left lane
    new Vector3( 0f, 1f, 2f),    // Center lane
    new Vector3( 2f, 1f, 4f),    // Right lane
    new Vector3( 0f, 1f, 6f),    // Center lane
    new Vector3(-2f, 1f, 8f),    // Left lane
    new Vector3( 0f, 1f, 10f)    // Center lane
};

using System.Collections.Generic;
using UnityEngine;
using InfiniteRunner.Core;

namespace InfiniteRunner.Gameplay
{
    /// <summary>
    /// Places coins on world chunks using predefined patterns.
    /// Works with the ObjectPool to borrow and return coin instances.
    ///
    /// Attach this to the same GameObject as the WorldGenerator,
    /// or any persistent manager object.
    /// </summary>
    public class CoinSpawner : MonoBehaviour
    {
        // ---------------------------------------------------------------
        // Inspector Fields
        // ---------------------------------------------------------------

        [Header("Coin Prefab")]
        [Tooltip("The coin prefab registered with the ObjectPool.")]
        [SerializeField] private GameObject coinPrefab;

        [Header("Patterns")]
        [Tooltip("All available coin patterns. The spawner will randomly " +
                 "select from these based on weight and difficulty.")]
        [SerializeField] private CoinPatternData[] availablePatterns;

        [Header("Spawn Settings")]
        [Tooltip("Probability (0-1) that a chunk will have coins at all.")]
        [Range(0f, 1f)]
        [SerializeField] private float spawnChance = 0.7f;

        [Tooltip("Maximum number of coins that can be active at once. " +
                 "Prevents performance issues from too many coins.")]
        [SerializeField] private int maxActiveCoins = 50;

        // ---------------------------------------------------------------
        // Private State
        // ---------------------------------------------------------------

        // Tracks all currently active coins so we can return them
        // when their parent chunk is recycled.
        private List<GameObject> activeCoins = new List<GameObject>();

        // Reference to the current difficulty level (0 to 1).
        // Updated by the DifficultyManager.
        private float currentDifficulty = 0f;

        // ---------------------------------------------------------------
        // Unity Lifecycle
        // ---------------------------------------------------------------

        private void OnEnable()
        {
            // Listen for chunk activation events from the WorldGenerator.
            GameEvents.OnChunkActivated += HandleChunkActivated;

            // Listen for chunk deactivation so we can reclaim coins.
            GameEvents.OnChunkDeactivated += HandleChunkDeactivated;

            // Listen for difficulty changes to filter patterns.
            GameEvents.OnDifficultyChanged += HandleDifficultyChanged;
        }

        private void OnDisable()
        {
            GameEvents.OnChunkActivated -= HandleChunkActivated;
            GameEvents.OnChunkDeactivated -= HandleChunkDeactivated;
            GameEvents.OnDifficultyChanged -= HandleDifficultyChanged;
        }

        // ---------------------------------------------------------------
        // Event Handlers
        // ---------------------------------------------------------------

        /// <summary>
        /// Called when a new chunk enters the world.
        /// Decides whether to spawn coins and, if so, which pattern to use.
        /// </summary>
        /// <param name="chunkTransform">The transform of the activated chunk.</param>
        /// <param name="spawnPoints">Collectible spawn points on the chunk.</param>
        private void HandleChunkActivated(
            Transform chunkTransform,
            Transform[] spawnPoints)
        {
            // Roll the dice - should this chunk have coins?
            if (Random.value > spawnChance) return;

            // Don't exceed our coin budget.
            if (activeCoins.Count >= maxActiveCoins) return;

            // No spawn points? Nothing to do.
            if (spawnPoints == null || spawnPoints.Length == 0) return;

            // Pick a pattern that matches the current difficulty.
            CoinPatternData pattern = SelectPattern();
            if (pattern == null) return;

            // Place coins at the spawn point using the chosen pattern.
            // We use the first spawn point as the pattern origin.
            SpawnPattern(pattern, spawnPoints[0].position);
        }

        /// <summary>
        /// Called when a chunk is recycled. Returns all coins that
        /// were on that chunk back to the object pool.
        /// </summary>
        private void HandleChunkDeactivated(Transform chunkTransform)
        {
            // We need to return coins that are children of this chunk
            // or within its bounds. For simplicity, we track coins by
            // their parent association.
            ReturnCoinsForChunk(chunkTransform);
        }

        /// <summary>
        /// Updates our local difficulty reference.
        /// </summary>
        private void HandleDifficultyChanged(float newDifficulty)
        {
            currentDifficulty = newDifficulty;
        }

        // ---------------------------------------------------------------
        // Pattern Selection
        // ---------------------------------------------------------------

        /// <summary>
        /// Selects a coin pattern based on spawn weights and current
        /// difficulty. Patterns with higher weights are more likely
        /// to be chosen. Patterns with a minDifficulty above the
        /// current level are excluded.
        /// </summary>
        /// <returns>A suitable pattern, or null if none qualify.</returns>
        private CoinPatternData SelectPattern()
        {
            // Build a list of eligible patterns.
            float totalWeight = 0f;
            List<CoinPatternData> eligible = new List<CoinPatternData>();

            for (int i = 0; i < availablePatterns.Length; i++)
            {
                CoinPatternData pattern = availablePatterns[i];

                // Skip patterns that require higher difficulty than current.
                if (pattern.minDifficulty > currentDifficulty) continue;

                eligible.Add(pattern);
                totalWeight += pattern.spawnWeight;
            }

            if (eligible.Count == 0) return null;

            // Weighted random selection.
            float roll = Random.Range(0f, totalWeight);
            float cumulative = 0f;

            for (int i = 0; i < eligible.Count; i++)
            {
                cumulative += eligible[i].spawnWeight;
                if (roll <= cumulative)
                {
                    return eligible[i];
                }
            }

            // Fallback (should not reach here, but just in case).
            return eligible[eligible.Count - 1];
        }

        // ---------------------------------------------------------------
        // Spawning
        // ---------------------------------------------------------------

        /// <summary>
        /// Spawns coins in the world according to the given pattern,
        /// anchored at the specified origin position.
        /// </summary>
        private void SpawnPattern(CoinPatternData pattern, Vector3 origin)
        {
            for (int i = 0; i < pattern.coinOffsets.Length; i++)
            {
                // Don't exceed our coin budget mid-pattern.
                if (activeCoins.Count >= maxActiveCoins) break;

                // Calculate world position from pattern offset.
                Vector3 worldPos = origin + pattern.coinOffsets[i];

                // Get a coin from the pool.
                GameObject coin = ObjectPool.Instance.Get(coinPrefab);
                if (coin == null) continue;

                // Position the coin in the world.
                coin.transform.position = worldPos;

                // Initialize the coin via IPoolable.
                IPoolable poolable = coin.GetComponent<IPoolable>();
                poolable?.OnSpawnFromPool();

                // Track this coin.
                activeCoins.Add(coin);
            }
        }

        /// <summary>
        /// Returns all coins associated with a deactivated chunk
        /// back to the object pool.
        /// </summary>
        private void ReturnCoinsForChunk(Transform chunkTransform)
        {
            // Get the chunk's Z range to determine which coins belong to it.
            float chunkStartZ = chunkTransform.position.z;
            float chunkLength = 50f; // Should match your chunk length.
            float chunkEndZ = chunkStartZ + chunkLength;

            for (int i = activeCoins.Count - 1; i >= 0; i--)
            {
                if (activeCoins[i] == null)
                {
                    activeCoins.RemoveAt(i);
                    continue;
                }

                float coinZ = activeCoins[i].transform.position.z;

                // If this coin is within the chunk's Z range, return it.
                if (coinZ >= chunkStartZ && coinZ <= chunkEndZ)
                {
                    IPoolable poolable =
                        activeCoins[i].GetComponent<IPoolable>();
                    poolable?.OnReturnToPool();

                    ObjectPool.Instance.Return(activeCoins[i]);
                    activeCoins.RemoveAt(i);
                }
            }
        }

        // ---------------------------------------------------------------
        // Public API
        // ---------------------------------------------------------------

        /// <summary>
        /// Returns all active coins to the pool. Called on game restart.
        /// </summary>
        public void ReturnAllCoins()
        {
            for (int i = activeCoins.Count - 1; i >= 0; i--)
            {
                if (activeCoins[i] == null) continue;

                IPoolable poolable =
                    activeCoins[i].GetComponent<IPoolable>();
                poolable?.OnReturnToPool();

                ObjectPool.Instance.Return(activeCoins[i]);
            }

            activeCoins.Clear();
        }
    }
}

using UnityEngine;
using InfiniteRunner.Core;

namespace InfiniteRunner.Gameplay
{
    /// <summary>
    /// The type of power-up. Used to identify power-ups throughout
    /// the codebase and prevent stacking of the same type.
    /// </summary>
    public enum PowerUpType
    {
        Magnet,
        Shield,
        ScoreMultiplier
    }

    /// <summary>
    /// Base class for all power-up pickups in the game world.
    /// Handles the common behavior: trigger detection, pool lifecycle,
    /// spinning animation, and event firing.
    ///
    /// Subclasses define the specific effect by overriding
    /// GetPowerUpType() and GetDuration().
    /// </summary>
    [RequireComponent(typeof(Collider))]
    public abstract class PowerUp : MonoBehaviour, IPoolable
    {
        // ---------------------------------------------------------------
        // Inspector Fields
        // ---------------------------------------------------------------

        [Header("Pickup Settings")]
        [Tooltip("How long the power-up effect lasts in seconds.")]
        [SerializeField] protected float duration = 8f;

        [Tooltip("How fast the pickup spins in the world.")]
        [SerializeField] private float spinSpeed = 120f;

        [Tooltip("Tag that identifies the player.")]
        [SerializeField] private string playerTag = "Player";

        [Header("Visuals")]
        [Tooltip("The glow or particle effect shown on the pickup.")]
        [SerializeField] private GameObject glowEffect;

        // ---------------------------------------------------------------
        // Private State
        // ---------------------------------------------------------------

        private bool isActive;

        // ---------------------------------------------------------------
        // Abstract Methods (subclasses must implement)
        // ---------------------------------------------------------------

        /// <summary>
        /// Returns the type of this power-up.
        /// Each subclass provides its own type.
        /// </summary>
        public abstract PowerUpType GetPowerUpType();

        /// <summary>
        /// Returns how long this power-up's effect lasts.
        /// </summary>
        public virtual float GetDuration()
        {
            return duration;
        }

        // ---------------------------------------------------------------
        // Unity Lifecycle
        // ---------------------------------------------------------------

        private void Awake()
        {
            // Ensure the collider is a trigger.
            Collider col = GetComponent<Collider>();
            if (col != null)
            {
                col.isTrigger = true;
            }
        }

        private void Update()
        {
            if (!isActive) return;

            // Spin the pickup to make it visually distinct from coins.
            transform.Rotate(Vector3.up, spinSpeed * Time.deltaTime);
        }

        // ---------------------------------------------------------------
        // Trigger Detection
        // ---------------------------------------------------------------

        private void OnTriggerEnter(Collider other)
        {
            if (!isActive) return;
            if (!other.CompareTag(playerTag)) return;

            PickUp();
        }

        // ---------------------------------------------------------------
        // Pickup Logic
        // ---------------------------------------------------------------

        /// <summary>
        /// Called when the player collects this power-up.
        /// Fires an event and returns the pickup to the pool.
        /// </summary>
        private void PickUp()
        {
            isActive = false;

            // Notify the PowerUpManager that a power-up was collected.
            // The manager handles activating the effect and managing timers.
            GameEvents.OnPowerUpCollected?.Invoke(
                GetPowerUpType(),
                GetDuration()
            );

            // Return to pool.
            ObjectPool.Instance.Return(gameObject);
        }

        // ---------------------------------------------------------------
        // IPoolable Implementation
        // ---------------------------------------------------------------

        public void OnSpawnFromPool()
        {
            isActive = true;

            if (glowEffect != null)
            {
                glowEffect.SetActive(true);
            }

            transform.rotation = Quaternion.identity;
        }

        public void OnReturnToPool()
        {
            isActive = false;

            if (glowEffect != null)
            {
                glowEffect.SetActive(false);
            }
        }
    }
}

using UnityEngine;

namespace InfiniteRunner.Gameplay
{
    /// <summary>
    /// Magnet power-up pickup. When collected, nearby coins are
    /// attracted toward the player for the duration.
    /// </summary>
    public class MagnetPowerUp : PowerUp
    {
        [Header("Magnet Settings")]
        [Tooltip("The radius within which coins are attracted to the player.")]
        [SerializeField] private float attractRadius = 8f;

        [Tooltip("How fast coins move toward the player when attracted.")]
        [SerializeField] private float attractSpeed = 15f;

        /// <summary>
        /// Identifies this as a Magnet power-up.
        /// </summary>
        public override PowerUpType GetPowerUpType()
        {
            return PowerUpType.Magnet;
        }

        /// <summary>
        /// Returns the attraction radius for the PowerUpManager to use.
        /// </summary>
        public float GetAttractRadius()
        {
            return attractRadius;
        }

        /// <summary>
        /// Returns the attraction speed for the PowerUpManager to use.
        /// </summary>
        public float GetAttractSpeed()
        {
            return attractSpeed;
        }
    }
}

namespace InfiniteRunner.Gameplay
{
    /// <summary>
    /// Shield power-up pickup. When collected, the player can
    /// survive one obstacle collision without dying.
    /// The shield breaks on the first hit and the visual disappears.
    /// </summary>
    public class ShieldPowerUp : PowerUp
    {
        /// <summary>
        /// Identifies this as a Shield power-up.
        /// </summary>
        public override PowerUpType GetPowerUpType()
        {
            return PowerUpType.Shield;
        }
    }
}

using UnityEngine;

namespace InfiniteRunner.Gameplay
{
    /// <summary>
    /// Score Multiplier power-up pickup. When collected, all score
    /// gains are multiplied for the duration.
    /// </summary>
    public class ScoreMultiplierPowerUp : PowerUp
    {
        [Header("Multiplier Settings")]
        [Tooltip("The score multiplier applied while this power-up is active.")]
        [SerializeField] private int multiplierValue = 2;

        /// <summary>
        /// Identifies this as a Score Multiplier power-up.
        /// </summary>
        public override PowerUpType GetPowerUpType()
        {
            return PowerUpType.ScoreMultiplier;
        }

        /// <summary>
        /// Returns the multiplier value (e.g., 2 for double points).
        /// </summary>
        public int GetMultiplierValue()
        {
            return multiplierValue;
        }
    }
}

using System.Collections.Generic;
using UnityEngine;
using InfiniteRunner.Core;

namespace InfiniteRunner.Gameplay
{
    /// <summary>
    /// Manages all active power-up effects. Listens for power-up
    /// collection events, activates effects, counts down timers,
    /// and fires events when power-ups start or expire.
    ///
    /// Attach this to a persistent manager GameObject.
    /// </summary>
    public class PowerUpManager : MonoBehaviour
    {
        // ---------------------------------------------------------------
        // Singleton
        // ---------------------------------------------------------------

        public static PowerUpManager Instance { get; private set; }

        // ---------------------------------------------------------------
        // Inspector Fields
        // ---------------------------------------------------------------

        [Header("Magnet Settings")]
        [Tooltip("The radius within which the magnet attracts coins.")]
        [SerializeField] private float magnetRadius = 8f;

        [Tooltip("How fast coins are pulled toward the player.")]
        [SerializeField] private float magnetSpeed = 15f;

        [Header("References")]
        [Tooltip("Reference to the player's transform for magnet logic.")]
        [SerializeField] private Transform playerTransform;

        // ---------------------------------------------------------------
        // Internal Data Structure
        // ---------------------------------------------------------------

        /// <summary>
        /// Tracks the state of a single active power-up effect.
        /// </summary>
        private class ActivePowerUp
        {
            public PowerUpType Type;
            public float RemainingTime;
            public float TotalDuration;

            public ActivePowerUp(PowerUpType type, float duration)
            {
                Type = type;
                RemainingTime = duration;
                TotalDuration = duration;
            }

            /// <summary>
            /// Returns 0-1 indicating how much time is left (1 = just started).
            /// Used for UI display.
            /// </summary>
            public float GetNormalizedTimeRemaining()
            {
                if (TotalDuration <= 0f) return 0f;
                return Mathf.Clamp01(RemainingTime / TotalDuration);
            }
        }

        // ---------------------------------------------------------------
        // Private State
        // ---------------------------------------------------------------

        // All currently active power-ups, keyed by type.
        // Using a dictionary ensures only one of each type at a time.
        private Dictionary<PowerUpType, ActivePowerUp> activePowerUps
            = new Dictionary<PowerUpType, ActivePowerUp>();

        // Reusable list for collecting expired power-ups to remove.
        // Avoids allocating a new list every frame.
        private List<PowerUpType> expiredTypes = new List<PowerUpType>();

        // The current score multiplier (1 when no multiplier is active).
        private int currentMultiplier = 1;

        // ---------------------------------------------------------------
        // Unity Lifecycle
        // ---------------------------------------------------------------

        private void Awake()
        {
            // Singleton setup.
            if (Instance != null && Instance != this)
            {
                Destroy(gameObject);
                return;
            }
            Instance = this;
        }

        private void OnEnable()
        {
            // Listen for power-up collection events.
            GameEvents.OnPowerUpCollected += HandlePowerUpCollected;

            // Listen for game over to clear all power-ups.
            GameEvents.OnGameOver += HandleGameOver;

            // Listen for obstacle hits to consume shields.
            GameEvents.OnObstacleHit += HandleObstacleHit;
        }

        private void OnDisable()
        {
            GameEvents.OnPowerUpCollected -= HandlePowerUpCollected;
            GameEvents.OnGameOver -= HandleGameOver;
            GameEvents.OnObstacleHit -= HandleObstacleHit;
        }

        private void Update()
        {
            // Tick down all active power-up timers.
            UpdateTimers();

            // If the magnet is active, attract nearby coins.
            if (IsPowerUpActive(PowerUpType.Magnet))
            {
                AttractNearbyCoins();
            }
        }

        // ---------------------------------------------------------------
        // Timer Management
        // ---------------------------------------------------------------

        /// <summary>
        /// Updates all active power-up timers. Removes expired ones.
        /// </summary>
        private void UpdateTimers()
        {
            expiredTypes.Clear();

            // Iterate over all active power-ups and count down.
            foreach (var kvp in activePowerUps)
            {
                ActivePowerUp powerUp = kvp.Value;
                powerUp.RemainingTime -= Time.deltaTime;

                // Fire a timer update event for UI.
                GameEvents.OnPowerUpTimerUpdated?.Invoke(
                    kvp.Key,
                    powerUp.GetNormalizedTimeRemaining()
                );

                // Check if expired.
                if (powerUp.RemainingTime <= 0f)
                {
                    expiredTypes.Add(kvp.Key);
                }
            }

            // Remove expired power-ups.
            // We do this in a separate pass because you cannot modify
            // a dictionary while iterating over it.
            for (int i = 0; i < expiredTypes.Count; i++)
            {
                DeactivatePowerUp(expiredTypes[i]);
            }
        }

        // ---------------------------------------------------------------
        // Activation / Deactivation
        // ---------------------------------------------------------------

        /// <summary>
        /// Handles a power-up being collected by the player.
        /// If the same type is already active, refreshes the timer.
        /// Otherwise, activates a new power-up.
        /// </summary>
        private void HandlePowerUpCollected(
            PowerUpType type,
            float duration)
        {
            if (activePowerUps.ContainsKey(type))
            {
                // Refresh: reset the timer to the new duration.
                activePowerUps[type].RemainingTime = duration;
                activePowerUps[type].TotalDuration = duration;

                Debug.Log($"[PowerUpManager] Refreshed {type} " +
                          $"for {duration}s");
            }
            else
            {
                // Activate a new power-up.
                activePowerUps[type] =
                    new ActivePowerUp(type, duration);

                // Apply the effect.
                ApplyEffect(type);

                Debug.Log($"[PowerUpManager] Activated {type} " +
                          $"for {duration}s");
            }

            // Notify UI and other systems.
            GameEvents.OnPowerUpActivated?.Invoke(type, duration);
        }

        /// <summary>
        /// Removes a power-up and reverses its effect.
        /// </summary>
        private void DeactivatePowerUp(PowerUpType type)
        {
            if (!activePowerUps.ContainsKey(type)) return;

            // Remove the effect.
            RemoveEffect(type);

            // Remove from active tracking.
            activePowerUps.Remove(type);

            // Notify UI and other systems.
            GameEvents.OnPowerUpExpired?.Invoke(type);

            Debug.Log($"[PowerUpManager] Expired: {type}");
        }

        /// <summary>
        /// Applies the gameplay effect of a power-up.
        /// </summary>
        private void ApplyEffect(PowerUpType type)
        {
            switch (type)
            {
                case PowerUpType.Magnet:
                    // Magnet effect is applied in Update() via
                    // AttractNearbyCoins(). Nothing to set here.
                    break;

                case PowerUpType.Shield:
                    // Show the shield visual on the player.
                    GameEvents.OnShieldActivated?.Invoke(true);
                    break;

                case PowerUpType.ScoreMultiplier:
                    // Set the score multiplier.
                    currentMultiplier = 2;
                    GameEvents.OnMultiplierChanged?.Invoke(currentMultiplier);
                    break;
            }
        }

        /// <summary>
        /// Removes the gameplay effect when a power-up expires.
        /// </summary>
        private void RemoveEffect(PowerUpType type)
        {
            switch (type)
            {
                case PowerUpType.Magnet:
                    // Nothing to clean up - Update() checks IsActive.
                    break;

                case PowerUpType.Shield:
                    // Hide the shield visual.
                    GameEvents.OnShieldActivated?.Invoke(false);
                    break;

                case PowerUpType.ScoreMultiplier:
                    // Reset the multiplier.
                    currentMultiplier = 1;
                    GameEvents.OnMultiplierChanged?.Invoke(currentMultiplier);
                    break;
            }
        }

        // ---------------------------------------------------------------
        // Magnet Logic
        // ---------------------------------------------------------------

        /// <summary>
        /// Finds all coins within the magnet radius and moves them
        /// toward the player. Uses Physics.OverlapSphere for detection.
        /// </summary>
        private void AttractNearbyCoins()
        {
            if (playerTransform == null) return;

            Vector3 playerPos = playerTransform.position;

            // Find all colliders within the magnet radius.
            Collider[] nearby = Physics.OverlapSphere(
                playerPos,
                magnetRadius
            );

            for (int i = 0; i < nearby.Length; i++)
            {
                // Check if this collider is a coin.
                Coin coin = nearby[i].GetComponent<Coin>();
                if (coin == null) continue;

                // Move the coin toward the player.
                Vector3 direction =
                    (playerPos - coin.transform.position).normalized;

                coin.transform.position += direction
                    * magnetSpeed
                    * Time.deltaTime;
            }
        }

        // ---------------------------------------------------------------
        // Shield Hit Logic
        // ---------------------------------------------------------------

        /// <summary>
        /// Called when the player hits an obstacle. If a shield is
        /// active, consumes it instead of killing the player.
        /// </summary>
        private void HandleObstacleHit()
        {
            if (IsPowerUpActive(PowerUpType.Shield))
            {
                // Consume the shield.
                DeactivatePowerUp(PowerUpType.Shield);

                // Notify systems that the shield absorbed the hit.
                GameEvents.OnShieldConsumed?.Invoke();

                Debug.Log("[PowerUpManager] Shield absorbed a hit!");
            }
        }

        // ---------------------------------------------------------------
        // Game Over
        // ---------------------------------------------------------------

        /// <summary>
        /// Clears all active power-ups when the game ends.
        /// </summary>
        private void HandleGameOver()
        {
            // Build a list of all active types to deactivate.
            List<PowerUpType> toRemove =
                new List<PowerUpType>(activePowerUps.Keys);

            for (int i = 0; i < toRemove.Count; i++)
            {
                DeactivatePowerUp(toRemove[i]);
            }
        }

        // ---------------------------------------------------------------
        // Public API
        // ---------------------------------------------------------------

        /// <summary>
        /// Checks whether a specific power-up type is currently active.
        /// </summary>
        public bool IsPowerUpActive(PowerUpType type)
        {
            return activePowerUps.ContainsKey(type);
        }

        /// <summary>
        /// Returns the current score multiplier.
        /// Returns 1 if no multiplier power-up is active.
        /// </summary>
        public int GetCurrentMultiplier()
        {
            return currentMultiplier;
        }

        /// <summary>
        /// Returns the normalized time remaining (0-1) for a power-up.
        /// Returns 0 if the power-up is not active.
        /// </summary>
        public float GetTimeRemaining(PowerUpType type)
        {
            if (activePowerUps.TryGetValue(type, out ActivePowerUp powerUp))
            {
                return powerUp.GetNormalizedTimeRemaining();
            }
            return 0f;
        }
    }
}

using UnityEngine;
using InfiniteRunner.Core;

namespace InfiniteRunner.Gameplay
{
    /// <summary>
    /// Spawns power-up pickups on world chunks. Power-ups are much
    /// rarer than coins and their spawn rate is influenced by the
    /// current difficulty level.
    ///
    /// Attach this to the same manager object as CoinSpawner.
    /// </summary>
    public class PowerUpSpawner : MonoBehaviour
    {
        // ---------------------------------------------------------------
        // Inspector Fields
        // ---------------------------------------------------------------

        [Header("Power-up Prefabs")]
        [Tooltip("Prefab for the Magnet pickup.")]
        [SerializeField] private GameObject magnetPrefab;

        [Tooltip("Prefab for the Shield pickup.")]
        [SerializeField] private GameObject shieldPrefab;

        [Tooltip("Prefab for the Score Multiplier pickup.")]
        [SerializeField] private GameObject multiplierPrefab;

        [Header("Spawn Probability")]
        [Tooltip("Base chance (0-1) that a chunk contains a power-up. " +
                 "This is very low - power-ups are rare!")]
        [Range(0f, 1f)]
        [SerializeField] private float baseSpawnChance = 0.08f;

        [Tooltip("How much difficulty increases the spawn chance. " +
                 "At max difficulty, chance = baseChance + difficultyBonus.")]
        [Range(0f, 0.2f)]
        [SerializeField] private float difficultyBonus = 0.05f;

        [Header("Type Weights")]
        [Tooltip("Relative weight for Magnet spawning.")]
        [SerializeField] private float magnetWeight = 1f;

        [Tooltip("Relative weight for Shield spawning.")]
        [SerializeField] private float shieldWeight = 1f;

        [Tooltip("Relative weight for Score Multiplier spawning.")]
        [SerializeField] private float multiplierWeight = 0.7f;

        [Header("Placement")]
        [Tooltip("Height above ground to place power-ups.")]
        [SerializeField] private float spawnHeight = 1.5f;

        // ---------------------------------------------------------------
        // Private State
        // ---------------------------------------------------------------

        private float currentDifficulty = 0f;

        // ---------------------------------------------------------------
        // Unity Lifecycle
        // ---------------------------------------------------------------

        private void OnEnable()
        {
            GameEvents.OnChunkActivated += HandleChunkActivated;
            GameEvents.OnDifficultyChanged += d => currentDifficulty = d;
        }

        private void OnDisable()
        {
            GameEvents.OnChunkActivated -= HandleChunkActivated;
        }

        // ---------------------------------------------------------------
        // Spawning Logic
        // ---------------------------------------------------------------

        /// <summary>
        /// Decides whether to spawn a power-up on the given chunk.
        /// </summary>
        private void HandleChunkActivated(
            Transform chunkTransform,
            Transform[] spawnPoints)
        {
            // Calculate effective spawn chance based on difficulty.
            float effectiveChance =
                baseSpawnChance + (currentDifficulty * difficultyBonus);

            // Roll the dice.
            if (Random.value > effectiveChance) return;

            // No spawn points? Can't place anything.
            if (spawnPoints == null || spawnPoints.Length == 0) return;

            // Pick a random spawn point on the chunk.
            Transform spawnPoint =
                spawnPoints[Random.Range(0, spawnPoints.Length)];

            // Select which power-up type to spawn.
            GameObject prefab = SelectPowerUpPrefab();
            if (prefab == null) return;

            // Get from pool and position.
            GameObject pickup = ObjectPool.Instance.Get(prefab);
            if (pickup == null) return;

            Vector3 position = spawnPoint.position;
            position.y = spawnHeight;
            pickup.transform.position = position;

            // Initialize via IPoolable.
            IPoolable poolable = pickup.GetComponent<IPoolable>();
            poolable?.OnSpawnFromPool();
        }

        /// <summary>
        /// Selects a power-up prefab using weighted random selection.
        /// </summary>
        private GameObject SelectPowerUpPrefab()
        {
            float totalWeight =
                magnetWeight + shieldWeight + multiplierWeight;

            float roll = Random.Range(0f, totalWeight);

            if (roll < magnetWeight)
                return magnetPrefab;

            roll -= magnetWeight;
            if (roll < shieldWeight)
                return shieldPrefab;

            return multiplierPrefab;
        }
    }
}

using UnityEngine;
using InfiniteRunner.Core;

namespace InfiniteRunner.Gameplay
{
    /// <summary>
    /// Controls the visual representation of the shield power-up
    /// on the player. Shows a semi-transparent bubble when active.
    /// </summary>
    public class ShieldVisual : MonoBehaviour
    {
        [Tooltip("The shield mesh/particle child object.")]
        [SerializeField] private GameObject shieldEffect;

        [Tooltip("How fast the shield pulses (scale oscillation).")]
        [SerializeField] private float pulseSpeed = 2f;

        [Tooltip("How much the shield scales during pulse (1 +/- this).")]
        [SerializeField] private float pulseAmount = 0.05f;

        private bool isShieldActive;
        private Vector3 baseScale;

        private void Awake()
        {
            if (shieldEffect != null)
            {
                baseScale = shieldEffect.transform.localScale;
                shieldEffect.SetActive(false);
            }
        }

        private void OnEnable()
        {
            GameEvents.OnShieldActivated += SetShieldActive;
            GameEvents.OnShieldConsumed += PlayBreakEffect;
        }

        private void OnDisable()
        {
            GameEvents.OnShieldActivated -= SetShieldActive;
            GameEvents.OnShieldConsumed -= PlayBreakEffect;
        }

        private void Update()
        {
            if (!isShieldActive || shieldEffect == null) return;

            // Gentle pulsing effect to show the shield is alive.
            float pulse = 1f + Mathf.Sin(Time.time * pulseSpeed) * pulseAmount;
            shieldEffect.transform.localScale = baseScale * pulse;
        }

        /// <summary>
        /// Shows or hides the shield visual.
        /// </summary>
        private void SetShieldActive(bool active)
        {
            isShieldActive = active;

            if (shieldEffect != null)
            {
                shieldEffect.SetActive(active);
                shieldEffect.transform.localScale = baseScale;
            }
        }

        /// <summary>
        /// Plays a break/shatter effect when the shield is consumed.
        /// For now, we just deactivate. Add particle burst here later.
        /// </summary>
        private void PlayBreakEffect()
        {
            isShieldActive = false;

            if (shieldEffect != null)
            {
                // TODO: Instantiate a shield-break particle effect here.
                shieldEffect.SetActive(false);
            }
        }
    }
}

using System;

namespace InfiniteRunner.Core
{
    /// <summary>
    /// Add these new events to your existing GameEvents class.
    /// </summary>
    public static partial class GameEvents
    {
        // --- Coin Events ---
        /// <summary>Fired when a coin is collected. Parameter: coin value.</summary>
        public static Action<int> OnCoinCollected;

        // --- Power-up Events ---
        /// <summary>Fired when a power-up pickup is collected.</summary>
        public static Action<PowerUpType, float> OnPowerUpCollected;

        /// <summary>Fired when a power-up becomes active.</summary>
        public static Action<PowerUpType, float> OnPowerUpActivated;

        /// <summary>Fired when a power-up's timer expires.</summary>
        public static Action<PowerUpType> OnPowerUpExpired;

        /// <summary>Fired every frame with normalized time remaining.</summary>
        public static Action<PowerUpType, float> OnPowerUpTimerUpdated;

        // --- Shield Events ---
        /// <summary>Fired to show/hide the shield visual.</summary>
        public static Action<bool> OnShieldActivated;

        /// <summary>Fired when the shield absorbs a hit.</summary>
        public static Action OnShieldConsumed;

        // --- Multiplier Events ---
        /// <summary>Fired when the score multiplier changes.</summary>
        public static Action<int> OnMultiplierChanged;

        // --- Obstacle Events ---
        /// <summary>Fired when the player hits an obstacle.</summary>
        public static Action OnObstacleHit;

        // --- Chunk Events ---
        /// <summary>Fired when a chunk is activated in the world.</summary>
        public static Action<Transform, Transform[]> OnChunkActivated;

        /// <summary>Fired when a chunk is deactivated/recycled.</summary>
        public static Action<Transform> OnChunkDeactivated;

        // --- Difficulty Events ---
        /// <summary>Fired when the difficulty level changes (0-1).</summary>
        public static Action<float> OnDifficultyChanged;
    }
}