Core.Utilities.PulseTimer

PulseTimer Documentation

The PulseTimer is a utility class within the Meatcorps.Engine.Core.Utilities namespace designed to generate a fixed-duration "pulse" signal in response to a trigger. In logic design, this is often referred to as a Monostable Multivibrator or a TP (Timer Pulse).

Overview

When the input signal transitions to true, the PulseTimer sets its Output to true for a specific duration. Once this duration expires, the output returns to false. Crucially, once the pulse has started, the output remains true for the full duration regardless of whether the input stays true or becomes false.

To retrigger the pulse after it has finished, the input must first return to false (resetting the trigger mechanism) and then become true again.

API Reference

Constructor

• PulseTimer(float durationInMs): Initializes the timer with the pulse duration specified in milliseconds.

Properties

• Output (bool): Returns true while the pulse is active; otherwise false.

Methods

• Update(bool input, float deltaTime): Processes the timer logic.
  • input: The trigger signal.
  • deltaTime: The time elapsed since the last update (in seconds).
• Reset(): Immediately cancels any active pulse and resets the internal state, allowing for an immediate retrigger if the input is true on the next update.

---

Use Cases

1. Visual Effects: Triggering a muzzle flash or a "hit flash" on a character that should last for exactly 100ms.
2. Game Logic Signals: Sending a "jump" signal to an animation system that needs to stay active for a few frames to ensure the transition occurs.
3. UI Feedback: Displaying a "Saved!" notification or a button highlight for a brief, fixed period.
4. Input Buffering: Handling discrete actions that shouldn't be spammed or that require a specific active window.

---

Examples

Basic Usage in a Game Loop

In this example, we trigger a 500ms pulse when the player presses a button.

using Meatcorps.Engine.Core.Utilities;

public class PlayerEffect
{
    private PulseTimer _flashTimer = new PulseTimer(500); // 500ms pulse
    private bool _isCharacterGlowing;

    public void OnUpdate(float deltaTime)
    {
        // Assume 'isActionPressed' is true for one or more frames
        bool isActionPressed = GetInput(); 

        // Update the timer
        _flashTimer.Update(isActionPressed, deltaTime);

        // The Output will stay true for 500ms once triggered
        _isCharacterGlowing = _flashTimer.Output;
        
        if (_isCharacterGlowing)
        {
            ApplyGlowEffect();
        }
    }
}

Preventing Retriggering

The PulseTimer requires the input to go false before it can fire again. This is useful for "one-shot" actions.

// Constructor: new PulseTimer(200); // 200ms

// Frame 1: Input=true  -> Output=true, Timer starts
// Frame 2: Input=true  -> Output=true, Timer continues
// Frame 3: Input=false -> Output=true, Timer continues (Input doesn't affect active pulse)
// ... 200ms pass ...
// Frame N: Input=false -> Output=false, Pulse finished
// Frame N+1: Input=true -> Output=true, New pulse starts

Manual Reset

If you need to interrupt a pulse (e.g., a character dies while a "power-up" pulse is active), use the Reset() method.

public void OnDeath()
{
    // Stop the pulse immediately regardless of remaining time
    _flashTimer.Reset(); 
}