using System;
using System.Collections.Generic;
using System.Collections.Concurrent;
using System.Globalization;
using System.Threading;
namespace AcDream.Core.Chat;
///
/// Unified chat log — mirrors every chat-bearing message the server
/// sends (local HearSpeech, broadcast ChannelBroadcast, whispered
/// Tell, system TransientMessage, PopupString).
///
///
/// Sits behind the UI chat panel (Phase D.2) and the scripting
/// plugin API so plugins can react to chat (e.g. auto-reply, loot
/// logging).
///
///
///
/// Retail keeps ~200 lines of scrollback. Our ring buffer defaults to
/// 500 and is configurable.
///
///
public sealed class ChatLog
{
private readonly ConcurrentQueue _buffer = new();
private readonly int _maxEntries;
private uint _localPlayerGuid;
private long _revision;
// Phase J follow-up: ACE often sends the same system text via two
// wire paths (GameMessageSystemChat 0xF7E0 + GameEventCommunication-
// TransientString 0x02EB) for back-compat — we wired both to
// OnSystemMessage in I.5/J, so the user saw lines like "Unknown
// command: help" twice. Dedupe within a short window: track the
// last system text + arrival time; if a second identical text
// shows up within one second, skip.
private string _lastSystemText = "";
private DateTime _lastSystemAt = DateTime.MinValue;
private static readonly TimeSpan SystemDedupWindow = TimeSpan.FromSeconds(1);
public ChatLog(int maxEntries = 500)
{
if (maxEntries < 1) throw new ArgumentOutOfRangeException(nameof(maxEntries));
_maxEntries = maxEntries;
}
///
/// OP4 review-fix round (2026-08-11, SHOULD-FIX S1): retail
/// PlayerOption DisplayTimeStamps — ClientSystem::
/// AddTextToScroll @0x00563C50 — prefixes EVERY transcript line
/// with the timestamp, not just the subset that happens to route
/// through RuntimeCommunicationState.AddText. Moved HERE
/// (from AddText) because is the ONE seam every
/// chat producer (, ,
/// , ,
/// , ,
/// , ,
/// , ) funnels
/// through — AddText's own callers (ServerMessage/WeenieError) were a
/// strict subset, so heard speech, emotes, Turbine channels, and
/// combat text never gained the prefix. The transient SpewBox
/// (RetailLogTextType.ClientLocal) never touches this class at
/// all, so it stays exempt automatically — matching retail's own
/// exemption without a special case here.
///
public Func? DisplayTimestampsSource { get; set; }
/// Fires every time a new entry is appended.
public event Action? EntryAppended;
/// Snapshot of all current entries, oldest first.
public ChatEntry[] Snapshot() => _buffer.ToArray();
public int Count => _buffer.Count;
///
/// Monotonic content revision. It advances after every successful append and
/// every explicit clear, allowing retained UI consumers to cache formatted
/// transcript layout without snapshotting the concurrent queue every frame.
///
public long Revision => Interlocked.Read(ref _revision);
///
/// Push the authoritative local-player GUID from WorldSession.
/// The host sets it after character selection and resets it at session
/// teardown. Used by to
/// recognize ACE's HearSpeech echo of our own /say (server's
/// HandleActionTalk broadcasts to all in range INCLUDING the
/// sender) and re-render it as "You say, ...".
///
public void SetLocalPlayerGuid(uint guid) => _localPlayerGuid = guid;
///
/// Reset per-session speaker classification and duplicate suppression
/// while preserving the visible transcript. Retail has an explicit
/// ChatInterface::RecvNotice_ClearChatBuffer @ 0x004F2F60 path;
/// character-session teardown does not use that clear-buffer notice.
///
public void ResetSessionIdentity()
{
_localPlayerGuid = 0u;
_lastSystemText = string.Empty;
_lastSystemAt = DateTime.MinValue;
}
// ── Inbound adapters ─────────────────────────────────────────────────────
/// Local or ranged HearSpeech (0x02BB / 0x02BC).
///
/// Phase I.5: an empty is substituted with
/// "You" — the server uses this convention to indicate that the
/// player is the speaker (e.g. their own ranged shouts echo back).
/// Port from holtburger
/// references/holtburger/.../client/messages.rs lines 476-487.
///
///
/// The wire chatType carried by HearSpeech/HearRangedSpeech
/// (speech.ChatType) — passed through VERBATIM, with zero
/// remapping, matching retail's Handle_Communication__HearSpeech
/// @0x005712A0 (the raw arg5 feeds AddTextToScroll
/// directly). Required — no production caller relies on a default;
/// retail's normal value is 0x02 (Speech) for callers that
/// don't have a wire value in hand.
///
public void OnLocalSpeech(string sender, string text, uint senderGuid, bool isRanged, uint logTextType)
{
// Phase J: ACE's HandleActionTalk broadcasts a HearSpeech echo
// back to the sender too. Detect own echo by guid match and
// substitute "" so the formatter renders "You say, ..." (single
// first-person echo) instead of "+Acdream says, ..."
// (third-person duplicate of our optimistic, already dropped).
bool isOwnEcho = _localPlayerGuid != 0 && senderGuid == _localPlayerGuid;
string effectiveSender = (isOwnEcho || string.IsNullOrEmpty(sender)) ? "You" : sender;
Append(new ChatEntry(
Kind: isRanged ? ChatKind.RangedSpeech : ChatKind.LocalSpeech,
Sender: effectiveSender,
Text: text,
SenderGuid: senderGuid,
ChannelId: 0)
{
LogTextType = logTextType,
});
}
/// EmoteText (0x01E0) — server-driven third-person emote.
public void OnEmote(string senderName, string text, uint senderGuid)
{
Append(new ChatEntry(
Kind: ChatKind.Emote,
Sender: senderName,
Text: text,
SenderGuid: senderGuid,
ChannelId: 0)
{
// Retail hard-codes Emote (0x0C) for every HearEmote line —
// ClientCommunicationSystem::HearEmote @0x0057CBE0, the
// literal constant at 0x0057CF94. Not a wire value.
LogTextType = (uint)RetailLogTextType.Emote,
});
}
/// SoulEmote (0x01E2) — complex emote (chat + paired animation).
public void OnSoulEmote(string senderName, string text, uint senderGuid)
{
Append(new ChatEntry(
Kind: ChatKind.SoulEmote,
Sender: senderName,
Text: text,
SenderGuid: senderGuid,
ChannelId: 0)
{
// HearSoulEmote tail-calls HearEmote @0x0057D096 — same
// hard-coded 0x0C.
LogTextType = (uint)RetailLogTextType.Emote,
});
}
/// PlayerKilled (0x019E) — death announcement.
///
/// Death messages are routed as so they
/// share styling with other server announcements. The
/// SenderGuid field carries the victim guid; the
/// ChannelId field carries the killer guid (a small misuse
/// of the field but avoids a schema change).
///
public void OnPlayerKilled(string deathMessage, uint victimGuid, uint killerGuid)
{
Append(new ChatEntry(
Kind: ChatKind.System,
Sender: "",
Text: deathMessage,
SenderGuid: victimGuid,
ChannelId: killerGuid)
{
// Direct anchor (corrected 2026-08-09, Opus review of
// 172c6f9a — replaces the earlier sibling-opcode analogy):
// opcode 0x019E dispatches via UIQueueManager::ProcessNet
// BlobData's byte table @0x55CB07 -> case 7 ->
// ClientCombatSystem::HandlePlayerDeathEvent @0x0056C320 ->
// AddTextToScroll(..., 0, 1, 0) @0x0056C3D8. Type 0x00 Default
// confirmed.
LogTextType = 0x00u,
});
}
// WeenieError (0x028A) / WeenieErrorWithString (0x028B) used to have a
// dedicated OnWeenieError entry point here (Phase I.5, hardcoded at
// LogTextType 0x00 pending register row AP-176). REJECT-review rework
// (SHOULD-FIX 3, docs/research/2026-08-09-ch2-review-findings.md):
// AP-176 retired at Campaign CH slice CH2 — WeenieErrorMessages.Resolve
// now resolves BOTH the display text AND the real per-code retail
// RetailLogTextType (chat vs SpewBox) from the full 344-row
// HandleFailureEvent port. Every producer of WeenieError text — the
// inbound GameEventWiring handlers AND the client-command
// ShowWeenieError sink — now resolves through WeenieErrorMessages and
// calls the AddText chokepoint (RuntimeCommunicationState.AddText /
// ChatLog.OnSystemMessage) directly instead of through a dedicated
// ChatLog method, so the single-fixed-color OnWeenieError entry point
// is deleted rather than kept as a second, narrower routing path.
///
/// Channel broadcast — legacy ChatChannel (0x0147) or the
/// TurbineChat (0xF7DE) global community channels (General,
/// Trade, LFG, Roleplay, Society, Olthoi). Pass
/// when the caller knows the
/// friendly room name (TurbineChat dispatch always does); the
/// ChatVM formatter renders entries as
/// "[ChannelName] Sender says, \"text\"" when set.
///
///
/// The retail LogTextType for this line. When
/// (the legacy 0x0147 default), it is derived
/// from via
/// as a HEARD (not
/// own-send) message — correct for this method's only production
/// caller, the inbound ChannelBroadcast GameEvent handler.
/// TurbineChat-sourced calls MUST pass an explicit value computed
/// from the room's TurbineChat.ChatType instead — the wire
/// there is an opaque per-session room
/// GUID, not a legacy channel bitflag, and the two id spaces must
/// never be conflated.
///
public void OnChannelBroadcast(
uint channelId, string sender, string text, uint? logTextType = null, string channelName = "")
{
Append(new ChatEntry(
Kind: ChatKind.Channel,
Sender: sender,
Text: text,
SenderGuid: 0,
ChannelId: channelId)
{
ChannelName = channelName,
LogTextType = logTextType ?? LegacyChannelChatType.Resolve(channelId, ownSend: false),
});
}
/// GameEvent Tell (0x02BD) — whisper received.
///
/// The wire chatType from the Tell GameEvent payload
/// (GameEvents.Tell.ChatType) — required; no production caller
/// relies on a default. Retail's normal value is 0x03 (Tell)
/// for callers without a wire value in hand.
///
public void OnTellReceived(string sender, string text, uint senderGuid, uint logTextType)
{
Append(new ChatEntry(
Kind: ChatKind.Tell,
Sender: sender,
Text: text,
SenderGuid: senderGuid,
ChannelId: 0)
{
LogTextType = logTextType,
});
}
///
/// System chat — covers GameMessageSystemChat (0xF7E0
/// ServerMessage) and GameEventCommunicationTransientString
/// (0x02EB). Phase J follow-up: dedupe identical text arriving
/// within so flows that fire on
/// both opcodes (e.g. "Unknown command: help" via help-command
/// failure path) only show once.
///
public void OnSystemMessage(string text, uint chatType)
{
var now = DateTime.UtcNow;
if (text == _lastSystemText && (now - _lastSystemAt) < SystemDedupWindow)
{
// Suppress the dup — the wire-level duplicate isn't a
// user-meaningful signal. Reset the timer so a long burst
// of the same text still skips.
_lastSystemAt = now;
return;
}
_lastSystemText = text;
_lastSystemAt = now;
Append(new ChatEntry(
Kind: ChatKind.System,
Sender: "",
Text: text,
SenderGuid: 0,
ChannelId: chatType)
{
// `chatType` IS the retail LogTextType here — every caller
// (ServerMessage.ChatType, GameEventWiring's transient/
// query-age/use-done sites, App's client-command echoes)
// already passes the wire/retail-correct value.
LogTextType = chatType,
});
}
///
/// GameEvent PopupString (0x0004) — modal dialog text.
///
///
/// Retail shows PopUpString as a MODAL DIALOG
/// (Handle_Communication__PopUpString @0x0057FE80), never as a
/// chat-log line — acdream's choice to render it in chat at all is a
/// registered divergence (register row AP-175). Fixed at LogTextType
/// 0x00 (Default/green) to preserve the color this entry has
/// always rendered with; retail has no chat color for this type since
/// it never reaches the chat log.
///
public void OnPopup(string text)
{
Append(new ChatEntry(
Kind: ChatKind.Popup,
Sender: "",
Text: text,
SenderGuid: 0,
ChannelId: 0)
{
LogTextType = 0x00u,
});
}
///
/// Phase I.7: combat-translator emits a pre-formatted line. The
/// translator () subscribes to
/// events and renders the retail
/// template (e.g. "You hit Mosswart for 12 slashing damage (54.0%)
/// Critical hit.") and decorates the entry with a
/// so the panel can color the
/// line. Maps to holtburger's info().combat() /
/// warning().combat() / error().combat() tag flow at
/// chat.rs:221-308.
///
/// The pre-formatted combat line text.
///
/// The retail LogTextType for this combat line — required; no
/// production caller relies on a default. Callers should pass one of
/// the ACE-cited combat types (0x16 Combat_Self for lines about
/// the local player's OWN offensive action, 0x15 Combat_Enemy
/// for lines about an enemy's action against the local player — see
/// ), 0x00 Default for
/// retail's decompiled kill/death-notification color
/// (HandleKillerNotificationEvent @0x0056C410), or 0x06
/// (the generic Combat slot) when no more specific classification is
/// in hand — the generic-slot choice is a registered approximation of
/// retail's per-message dispatch (register row AP-176).
///
///
/// Severity bucket for panel coloring; defaults to
/// .
///
public void OnCombatLine(
string text, uint logTextType, Combat.CombatLineKind kind = Combat.CombatLineKind.Info)
{
Append(new ChatEntry(
Kind: ChatKind.Combat,
Sender: "",
Text: text,
SenderGuid: 0,
ChannelId: 0)
{
CombatKind = kind,
LogTextType = logTextType,
});
}
///
/// Echo the player's own outbound message after local send.
///
///
///
/// - Say: pass as
/// empty; the formatter renders "You say, \"text\"".
/// - Tell: pass the target name; the formatter
/// renders "You tell {target}, \"text\"".
/// - Channel: do not call for global community
/// channels — the server (ACE TurbineChatHandler) echoes the
/// broadcast back to the sender already, so optimistic-echoing
/// would double-print. For legacy channels (Fellowship,
/// Allegiance) where the server may not echo, pass the
/// channel name as ; it
/// becomes the entry's ChannelName.
///
/// SenderGuid == 0 on the resulting entry is the
/// discriminator the formatter uses to render outgoing-vs-incoming
/// (a real incoming Tell carries the sender's player guid).
///
///
/// The retail LogTextType for this self-sent line — required;
/// no production caller relies on a default (the old null-fallback
/// ternary is retired). Pass 0x04 Speech_Direct_Send for Tell
/// (retail's own-echo "You tell ..." type — cross-check ACE's
/// ChatMessageType.OutgoingTell comment "You tell ...") or, for
/// Channel, the precise per-channel-bit value from
/// — the
/// LiveSessionCommandRouter production caller does exactly this.
///
public void OnSelfSent(ChatKind kind, string text, uint logTextType, string targetOrChannel = "")
{
Append(new ChatEntry(
Kind: kind,
// For Tell, Sender carries the target name (so the formatter
// can render "You tell {Sender}..."). For LocalSpeech, we
// leave Sender empty and let the formatter substitute "You".
// For Channel callers, Sender stays empty too — ChannelName
// (below) carries the friendly name.
Sender: kind == ChatKind.Tell ? targetOrChannel : "",
Text: text,
SenderGuid: 0,
ChannelId: 0)
{
ChannelName = kind == ChatKind.Channel ? targetOrChannel : "",
LogTextType = logTextType,
});
}
private void Append(ChatEntry entry)
{
// OP4 re-review R1 (2026-08-11): the timestamp prefix does NOT touch
// entry.Text here. Retail composes the display line FIRST and carries
// the timestamp as a SEPARATE leading string at display time
// (AddTextToScroll @0x00563C50 receives already-composed lines;
// fprintf("%ls%ls\n", ts, text) @0x00563e5b) — prefixing the raw body
// put the stamp INSIDE the quotes of composed kinds
// ('Alice says, "13:05:09 hi"'). ChatVM's display composition applies
// FormatTimestampPrefix(entry.Received) around FormatEntry instead.
_buffer.Enqueue(entry);
while (_buffer.Count > _maxEntries)
_buffer.TryDequeue(out _);
Interlocked.Increment(ref _revision);
EntryAppended?.Invoke(entry);
}
///
/// SF-1/S4 (OP4 review-fix round, 2026-08-11): retail's constructor
/// default "%#H:%M:%S " (PlayerModule::PlayerModule
/// @0x005D51F0, BN-sourced string literal — wire research doc U6,
/// NOT byte-verified) is non-zero-padded 24h hour, then zero-padded
/// minute:second, trailing space. H\:mm\:ss with the colons
/// ESCAPED (not the culture-dependent DateTimeFormatInfo.
/// TimeSeparator placeholder) plus is the exact .NET equivalent — the CRT's
/// strftime always emits a literal colon regardless of locale.
/// acdream hardcodes this constructor default rather than reading the
/// per-character override retail sources from
/// GenericQualitiesData::InqString(m_pPlayerOptionsData, 1, ...)
/// — see register row AP-197.
///
public static string FormatTimestampPrefix(DateTime receivedUtc) =>
receivedUtc.ToLocalTime().ToString(
@"H\:mm\:ss ", CultureInfo.InvariantCulture);
public void Clear()
{
while (_buffer.TryDequeue(out _)) { /* drain */ }
Interlocked.Increment(ref _revision);
}
}
public enum ChatKind
{
LocalSpeech,
RangedSpeech,
Channel,
Tell,
System,
Popup,
Emote,
SoulEmote,
///
/// Phase I.7: a combat feedback line emitted by
/// from
/// events. The accompanying field
/// drives panel coloring (info / warning / error per holtburger
/// chat.rs:221-308).
///
Combat,
}
public readonly record struct ChatEntry(
ChatKind Kind,
string Sender,
string Text,
uint SenderGuid,
uint ChannelId)
{
public DateTime Received { get; init; } = DateTime.UtcNow;
///
/// Phase I.7: severity bucket for
/// entries. Null for every other kind. Carried through to the transcript
/// on FormattedLine; the per-message colour itself now comes from
/// the retail colour table keyed by LogTextType.
///
public Combat.CombatLineKind? CombatKind { get; init; }
///
/// Friendly name of the channel for
/// entries (e.g. "General", "Trade", "LFG", "Fellowship"). Empty
/// for non-Channel kinds. Used by ChatVM.FormatEntry to
/// render lines as "[ChannelName] Sender says, \"text\"".
/// Falls back to "ch {ChannelId}" if not populated.
///
public string ChannelName { get; init; } = "";
///
/// Campaign CH slice CH1: the retail wire LogTextType
/// (0x00-0x21) that keys
/// RetailChatColorTable/ChatInterface::BuildChatColorLookupTable
/// @0x004F31C0. This is the FULL 34-value retail index space, NOT
/// — retail colors by this integer, never by our
/// synthetic 9-value . Populated by every
/// OnXxx ingestion method above; defaults to 0x00
/// (Default/green, retail's own unfilled-slot default) for any entry
/// constructed without setting it explicitly.
///
public uint LogTextType { get; init; } = 0x00u;
}