Class InputBufferManager

Concrete implementation of IInputBufferManager that stores buffered input events in a fixed-capacity ring buffer and expires them based on configurable per-action or global time windows.

Inheritance
object
InputBufferManager
Implements
Inherited Members
Namespace: Scylla.Input
Assembly: ScyllaInput.dll
Syntax
public class InputBufferManager : IInputBufferManager
Remarks

Internally the manager uses a ScyllaRingBuffer<BufferedInput> which overwrites the oldest entry when the buffer reaches capacity. All read-only operations (peek, count, has) iterate the buffer non-destructively; consume operations use a single-pass RemoveWhere that matches by both action ID and exact timestamp to identify the target entry without allocating.

Timestamp comparison in ConsumeBufferedAction(string, float, out BufferedInput) uses a direct double == equality check. This is safe because the timestamp is copied verbatim from the BufferedInput found during the forward search - no arithmetic is performed on it, so no floating-point rounding occurs.

Changing MaxBufferSize after initialization triggers a buffer rebuild via RebuildBuffer. The rebuild copies existing entries to a temporary list and re-creates the ring buffer at the new capacity, discarding the oldest entries if the new size is smaller than the current count.

Properties

BufferCount

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

Declaration
public 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
public 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
public 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
public 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
public 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
public 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
public 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
public 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
public 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
public 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
public 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
public 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)

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
public 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
public 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
public 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
public 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
public 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
public 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
public 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
public 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
public 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
public 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
public 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
public 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
public 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
public event Action<BufferedInput> OnInputExpired
Event Type
Type Description
Action<BufferedInput>

Implements