ChatBuffer

Fixed-capacity ring buffer that stores ChatMessage instances. When full, new messages overwrite the oldest entries. Enumeration yields messages in reverse chronological order (newest first).

Definition

Namespace: Paragon.Townskeep.ChatSystem Assembly: Townskeep.dll

public class ChatBuffer : IEnumerable<ChatMessage>

Implements: IEnumerable<ChatMessage>

Remarks

ChatBuffer is a circular buffer with a fixed capacity of 256 messages. It operates in two phases:

1. Filling phase (count < CAPACITY) — Messages are appended sequentially. Push increments count.

2. Wrapping phase (count == CAPACITY) — New messages overwrite the oldest entry at offset, and offset advances. count stays at CAPACITY.

The indexer maps logical indices (0 = oldest) to physical positions using (offset + index) % CAPACITY. The enumerator iterates in reverse order (newest to oldest), which is the natural display order for a chat window.

Quick Lookup

Goal	How
Add a message	buffer.Push(message)
Remove the newest message	buffer.Pop()
Get message by index	buffer[index] (0 = oldest)
Get total messages	buffer.Count
Clear all messages	buffer.Clear()
Iterate newest-first	foreach (var msg in buffer)

Properties

Count

The current number of messages in the buffer. Ranges from 0 to CAPACITY.

public int Count { get; }

Constructor

public ChatBuffer()

Creates a buffer with a pre-allocated array of CAPACITY (256) ChatMessage slots.

Methods

Push

Adds a message to the buffer. If the buffer is full, overwrites the oldest message and advances the internal offset.

public void Push(ChatMessage message)

Parameter	Type	Description
message	ChatMessage	The message to add

Pop

Removes the newest message by decrementing the count. Does nothing if the buffer is empty.

public void Pop()

Pop does not clear the slot — The ChatMessage data remains in the array. Only count is decremented, so the slot will be overwritten by subsequent Push calls.

Clear

Resets the buffer to empty by setting count and offset to 0.

public void Clear()

Like Pop, Clear does not zero the array — it only resets the counters. Existing ChatMessage values remain in memory until overwritten.

GetEnumerator

Yields messages in reverse order (newest first, index Count-1 down to 0). This is the natural iteration order for chat UI display.

public IEnumerator<ChatMessage> GetEnumerator()

Constants

CAPACITY

The fixed maximum number of messages the buffer can hold.

public const int CAPACITY = 256;

Indexers

this[int index]

Gets or sets a message at the specified logical index. Index 0 is the oldest message.

public ChatMessage this[int index] { get; set; }

Parameter	Type	Description
index	int	Logical index (0 = oldest, Count-1 = newest)

Throws: ArgumentOutOfRangeException if index < 0 or index >= Count.

Usage Example

var buffer = new ChatBuffer();

// Add messages
buffer.Push(new ChatMessage(DateTime.Now, "Alice", "Hello!", "General"));
buffer.Push(new ChatMessage(DateTime.Now, "Bob", "Hi there!", "General"));

// Access by index (0 = oldest)
ChatMessage oldest = buffer[0]; // Alice's message

// Iterate newest-first (for chat UI)
foreach (ChatMessage msg in buffer)
{
    Debug.Log(msg.ToString()); // Bob's message first, then Alice's
}

// Buffer wraps at 256
for (int i = 0; i < 300; i++)
{
    buffer.Push(new ChatMessage(DateTime.Now, "Bot", $"Message {i}", "General"));
}
// buffer.Count == 256, oldest 44 messages overwritten

Common Pitfalls

Enumeration is newest-first — Unlike most collections, foreach yields messages from newest to oldest. Use the indexer (buffer[0]) to access the oldest message.

Pop reduces count but doesn't affect offset — In the wrapping phase, Pop() decrements count but does not adjust offset. This can cause logical index misalignment if Push and Pop are interleaved after wrapping.

Fixed capacity of 256 — The capacity is a compile-time constant. It cannot be changed at runtime. For larger message histories, a different data structure is needed.

See Also

• Chat — singleton service that manages channels, each containing a ChatBuffer