Interface IInputBufferManager

Manages a time-windowed ring buffer of BufferedInput entries that allows game systems to detect and consume player inputs that occurred slightly before the system was ready to process them.

Namespace: Scylla.Input

Assembly: ScyllaInput.dll

Syntax

public interface IInputBufferManager

Remarks

Input buffering solves the classic "missed input" problem in action games: the player presses a button a few frames before the game can act on it (e.g., pressing Jump just before landing, or queuing an attack during a recovery animation). Without buffering, those inputs are silently dropped. With buffering, the press is recorded and can be consumed within a configurable time window.

The core workflow is:

1. Call BufferAction(string, float) when a relevant input event occurs (typically from an input action callback or a bridge query).
2. Call ConsumeBufferedAction(string, float) each frame from the system that processes the action (e.g., the jump handler). If an entry is found within the configured window, it is removed from the buffer and the return value is true.

Use HasBufferedAction(string, float) for non-destructive checks and PeekBufferedAction(string, float, out BufferedInput) to inspect the most recent entry without removing it.

The buffer is a fixed-capacity ring buffer (default 32 entries). When the buffer is full, the oldest entry is overwritten. Entries are automatically expired by Update() each frame. Per-action windows can be configured via SetActionBufferWindow(string, float) to give different actions different leniency.

All operations are no-ops when IsEnabled is false, providing a clean way to disable buffering globally without removing buffer calls from game code.

Properties

BufferCount

Gets the total number of entries currently in the buffer, including expired ones that have not yet been removed by ExpireOldInputs().

Declaration

int BufferCount { get; }

Property Value

Type	Description
int	An integer in the range [0, MaxBufferSize]. Returns 0 if the buffer has not been initialized.

DefaultBufferWindow

Gets or sets the default time window used when no per-action override is configured.

Declaration

float DefaultBufferWindow { get; set; }

Property Value

Type	Description
float	Maximum age in seconds before a buffered input is considered expired. The setter clamps the value to a minimum of 0.001 seconds to avoid zero-length windows. Defaults to 0.15 seconds (150 ms), which corresponds to roughly 9 frames at 60 Hz - a commonly used value in action game input systems.

IsEnabled

Gets or sets whether input buffering is active.

Declaration

bool IsEnabled { get; set; }

Property Value

Type

Description

bool

When false, calls to BufferAction(string, float) are silently ignored and all query methods (ConsumeBufferedAction(string, float), HasBufferedAction(string, float), PeekBufferedAction(string, float, out BufferedInput)) return their default no-result values. ExpireOldInputs() is also skipped during Update(). Setting to false does not clear already-buffered entries; they remain and will be available again if buffering is re-enabled before they expire.

IsInitialized

Gets whether Initialize() has been called and the buffer is ready.

Declaration

bool IsInitialized { get; }

Property Value

Type	Description
bool	true after a successful Initialize() call and before Shutdown() is called; false otherwise. Buffer operations require IsInitialized to be true.

MaxBufferSize

Gets or sets the maximum number of inputs that the ring buffer can hold at once.

Declaration

int MaxBufferSize { get; set; }

Property Value

Type	Description
int	Must be at least 1. Defaults to 32. When the buffer is full and a new entry is written, the oldest entry is silently overwritten. Changing this value after initialization causes the buffer to be rebuilt; entries that do not fit the new smaller capacity are discarded oldest-first. Values less than 1 are ignored.

Methods

BufferAction(string, float)

Records an action input event in the buffer, using 1.0 as the default value and no device information.

Declaration

void BufferAction(string actionID, float value = 1)

Parameters

Type	Name	Description
string	actionID	The identifier of the action to record. Must not be null or empty; invalid IDs are silently rejected with a warning. The same string must be used in subsequent ConsumeBufferedAction(string, float) calls for the entry to be found.
float	value	The magnitude of the input; defaults to 1.0 for a standard button press. Use an analog value (e.g., trigger depth in [0, 1]) for analog actions.

Remarks

This overload does not capture device information. Use the two- or three-argument overloads if Device or DeviceType must be inspected by the consumer. This method is a no-op when IsEnabled is false.

BufferAction(string, float, InputDevice)

Records an action input event in the buffer, capturing the originating device. The InputDeviceType is derived automatically from the device.

Declaration

void BufferAction(string actionID, float value, InputDevice device)

Parameters

Type	Name	Description
string	actionID	The identifier of the action to record. Must not be null or empty.
float	value	The magnitude of the input; typically 1.0 for buttons.
InputDevice	device	The Unity Input System device that generated the input, or null if the originating device is not known. When null, the device type is stored as Unknown.

Remarks

This method is a no-op when IsEnabled is false.

BufferAction(string, float, InputDevice, InputDeviceType)

Records an action input event in the buffer with full device metadata.

Declaration

void BufferAction(string actionID, float value, InputDevice device, InputDeviceType deviceType)

Parameters

Type	Name	Description
string	actionID	The identifier of the action to record. Must not be null or empty.
float	value	The magnitude of the input; typically 1.0 for buttons.
InputDevice	device	The Unity Input System device that generated the input, or null if unknown.
InputDeviceType	deviceType	The pre-classified device category. Use this overload when the type is already known to avoid redundant classification. Pass Unknown when device is null.

Remarks

This method is a no-op when IsEnabled is false.

ClearActionBufferWindow(string)

Removes the per-action buffer window override for the given action, causing future queries to fall back to DefaultBufferWindow.

Declaration

void ClearActionBufferWindow(string actionID)

Parameters

Type	Name	Description
string	actionID	The identifier whose override should be removed. If null, empty, or no override exists, the call is a safe no-op.

ClearBuffer()

Removes all entries from the buffer immediately, regardless of their age or action ID.

Declaration

void ClearBuffer()

Remarks

Useful when transitioning between game states (e.g., entering a menu, completing a combo) to prevent stale inputs from being consumed in the new state. Does not fire OnInputExpired; entries are discarded silently.

ClearBufferedAction(string)

Removes all buffered entries for a specific action ID, regardless of their age.

Declaration

void ClearBufferedAction(string actionID)

Parameters

Type	Name	Description
string	actionID	The identifier of the action whose buffered entries should be removed. If null, empty, or no entries exist for the given ID, the call is a safe no-op. Does not fire OnInputExpired.

ConsumeBufferedAction(string, float)

Finds and removes the most recently buffered entry for the given action within the specified time window, returning whether an entry was found.

Declaration

bool ConsumeBufferedAction(string actionID, float windowSeconds = -1)

Parameters

Type	Name	Description
string	actionID	The identifier of the action to consume. Must match the string passed to BufferAction(string, float). Returns false immediately if null or empty.
float	windowSeconds	The maximum acceptable age in seconds for the consumed entry. Pass -1 to use the per-action window configured via SetActionBufferWindow(string, float), or the DefaultBufferWindow if no override exists. A value of 0 or greater overrides both.

Returns

Type	Description
bool	true if a buffered entry for actionID was found within the window and removed from the buffer; false if no entry matched, the buffer is empty, or the manager is disabled or uninitialized.

See Also

ConsumeBufferedAction(string, float, out BufferedInput)

ConsumeBufferedAction(string, float, out BufferedInput)

Finds and removes the most recently buffered entry for the given action within the specified time window, returning both the success flag and the consumed entry data.

Declaration

bool ConsumeBufferedAction(string actionID, float windowSeconds, out BufferedInput bufferedInput)

Parameters

Type	Name	Description
string	actionID	The identifier of the action to consume. Returns false immediately if null or empty, with bufferedInput set to Invalid.
float	windowSeconds	The maximum acceptable age in seconds. Pass -1 to use the per-action or default window. See ConsumeBufferedAction(string, float) for details.
BufferedInput	bufferedInput	When this method returns true, contains the consumed BufferedInput entry (the most recent one within the window). When false, contains Invalid.

Returns

Type	Description
bool	true if an entry was found and consumed; false otherwise.

ExpireOldInputs()

Scans the buffer and removes all entries that have exceeded their configured time window, firing OnInputExpired for each removed entry.

Declaration

void ExpireOldInputs()

Remarks

This method is called automatically by Update() once per frame when the manager is initialized and IsEnabled is true. It can also be called manually to force immediate expiry, for example when fast-forwarding game state. Each action's effective window is resolved individually, respecting per-action overrides configured via SetActionBufferWindow(string, float).

GetActionBufferWindow(string)

Returns the effective buffer window for a specific action.

Declaration

float GetActionBufferWindow(string actionID)

Parameters

Type	Name	Description
string	actionID	The identifier of the action to query. If null or empty, the DefaultBufferWindow is returned.

Returns

Type	Description
float	The per-action override window if one was set via SetActionBufferWindow(string, float); otherwise DefaultBufferWindow.

GetBufferedActionCount(string, float)

Returns the number of buffered entries for the given action that are still within the specified time window, without removing any entries.

Declaration

int GetBufferedActionCount(string actionID, float windowSeconds = -1)

Parameters

Type	Name	Description
string	actionID	The identifier of the action to count. Returns 0 immediately if null or empty.
float	windowSeconds	The maximum acceptable age in seconds. Pass -1 to use the per-action or default window.

Returns

Type	Description
int	The count of non-expired entries for actionID; 0 if none are found or the manager is disabled or uninitialized.

HasActionBufferWindow(string)

Returns whether a per-action buffer window override exists for the given action.

Declaration

bool HasActionBufferWindow(string actionID)

Parameters

Type	Name	Description
string	actionID	The identifier of the action to check.

Returns

Type	Description
bool	true if a custom window has been set via SetActionBufferWindow(string, float) for actionID; false if the default window is in use or if actionID is null or empty.

HasBufferedAction(string, float)

Returns whether at least one buffered entry for the given action exists within the time window, without removing any entries.

Declaration

bool HasBufferedAction(string actionID, float windowSeconds = -1)

Parameters

Type	Name	Description
string	actionID	The identifier of the action to check. Returns false immediately if null or empty.
float	windowSeconds	The maximum acceptable age in seconds. Pass -1 to use the per-action or default window.

Returns

Type	Description
bool	true if at least one valid entry exists within the window; false otherwise or if the manager is disabled or uninitialized.

Initialize()

Initializes the buffer manager, allocating the internal ring buffer. Must be called before any other operation.

Declaration

void Initialize()

Remarks

Calling Initialize() a second time without an intervening Shutdown() emits a warning and returns without reinitializing.

PeekBufferedAction(string, float, out BufferedInput)

Retrieves the most recent buffered entry for the given action within the time window without removing it from the buffer.

Declaration

bool PeekBufferedAction(string actionID, float windowSeconds, out BufferedInput bufferedInput)

Parameters

Type	Name	Description
string	actionID	The identifier of the action to inspect. Returns false immediately if null or empty, with bufferedInput set to Invalid.
float	windowSeconds	The maximum acceptable age in seconds. Pass -1 to use the per-action or default window.
BufferedInput	bufferedInput	When this method returns true, contains the most recent BufferedInput entry for actionID within the window. When false, contains Invalid.

Returns

Type	Description
bool	true if a matching entry was found; false otherwise. The entry is not removed - call ConsumeBufferedAction(string, float) to also remove it.

SetActionBufferWindow(string, float)

Configures a custom buffer window for a specific action, overriding the DefaultBufferWindow for that action only.

Declaration

void SetActionBufferWindow(string actionID, float windowSeconds)

Parameters

Type	Name	Description
string	actionID	The identifier of the action to configure. Ignored if null or empty.
float	windowSeconds	The maximum age in seconds for buffered entries of this action. Clamped to a minimum of 0.001 seconds. For example, pass 0.3f to allow 300 ms of buffer leniency for a specific action.

Remarks

Per-action overrides are consulted whenever a windowSeconds of -1 is passed to any consume, peek, or count method. Remove the override via ClearActionBufferWindow(string) to revert to the default.

Shutdown()

Shuts down the buffer manager, clearing all buffered entries, per-action window overrides, and releasing the internal ring buffer.

Declaration

void Shutdown()

Remarks

Safe to call on an already-shut-down manager. After this call, IsInitialized returns false and all buffer operations become no-ops until Initialize() is called again.

Update()

Advances the buffer manager by one frame, expiring all entries that have exceeded their configured time window. Should be called once per frame.

Declaration

void Update()

Remarks

Internally delegates to ExpireOldInputs(). Skipped when IsEnabled is false or the manager is not initialized.

Events

OnInputBuffered

Raised immediately after a new entry is added to the buffer by any BufferAction(string, float) overload.

Declaration

event Action<BufferedInput> OnInputBuffered

Event Type

Type	Description
Action<BufferedInput>

OnInputConsumed

Raised immediately after a buffered entry is removed by a successful ConsumeBufferedAction(string, float) call. The argument contains the data of the entry that was consumed.

Declaration

event Action<BufferedInput> OnInputConsumed

Event Type

Type	Description
Action<BufferedInput>

OnInputExpired

Raised for each entry that is removed by ExpireOldInputs() because its age exceeded its configured window. Not raised by ClearBuffer() or ClearBufferedAction(string).

Declaration

event Action<BufferedInput> OnInputExpired

Event Type

Type	Description
Action<BufferedInput>