Debounce

UNihiloDebounceTask is a utility for rate-limiting a callback so it only fires after a burst of triggers has settled. Each call to Trigger resets the delay timer — the callback only executes once the triggers stop coming in and the delay elapses uninterrupted.

info

A common use case is reacting to rapid input or state changes without firing on every individual event — for example, saving player settings after a slider stops moving, or rebuilding a UI list after a series of fast collection updates.

How It Works

The task holds two timers: a delay timer and an optional timeout timer. Every call to Trigger clears and restarts the delay timer. If triggers keep coming in faster than the delay window, the callback is continuously deferred. Once a full Delay seconds passes without another trigger, the callback fires and the timeout timer (if running) is cancelled.

The timeout is a safety valve. If Timeout is set and the callback has not fired naturally within that window, the timeout callback fires instead. This prevents the debounce from deferring indefinitely in situations where triggers arrive in a continuous stream with no natural gap — for example, if you need a guarantee that something happens within 5 seconds regardless of how active the trigger source is.

The timeout timer is started on the first trigger and does not reset on subsequent ones, so it represents a hard deadline from the moment the burst began.

Usage

UNihiloDebounceTask uses a fluent builder pattern. Construct one, chain the configuration methods, store it, then call Trigger whenever the event you want to debounce occurs.

cpp

RetriggerableDelay = NewObject<UNihiloDebounceTask>(this);
RetriggerableDelay->Task([this]() { ExecuteSave(); })
	    ->OnTimeout([this](){ ExecuteSave(); })
	    ->DelayTime(InSettings.DelayTime)
	    ->TimeoutTime(InSettings.TimeoutTime);

The task should be stored as a member variable — not a local — so its timers remain valid between triggers. Since it is a UObject, keep it alive with a UPROPERTY to prevent garbage collection.

API Reference

Configuration

Function	Description
Task	Sets the callback to execute when the debounce delay elapses. Returns this for chaining.
DelayTime	Sets how long to wait after the last trigger before firing. Returns this for chaining.
TimeoutTime	Sets the maximum time before the timeout callback fires, measured from the first trigger. Optional — leave unset for no timeout. Returns this for chaining.
OnTimeout	Sets the callback to execute if the timeout elapses before the delay completes. Returns this for chaining.

Control

Function	Description
Trigger	Resets the delay timer. Starts the timeout timer if one is configured and it is not already running.
Force	Cancels both timers and immediately executes the task callback. Useful when you need to flush a pending debounce — for example, on level transition or component shutdown.
Cancel	Cancels both timers without executing any callback. The task returns to an idle state and can be triggered again.