Chat reference

The chat component, the player identity every social module keys on, the chat line data and the server-side chat router. For how to use it, see Chat.

VtUnitChat

Component. Add it with Add Component → Vantage → Chat → VtUnitChat. Adds VtUnit automatically.

A player’s chat: sends lines, receives the lines routed to it, keeps a short history, and holds the player’s ignore list. Opt in through VtUnitDefinition.useChat; VtUnit attaches it.

Scripting API

Member	Description
`VtUnit Unit { get; }`	The unit this chat belongs to.
`string PlayerId { get; }`	The sender id used for ignores and mutes: the player id, or a per-unit id without an identity.
`string DisplayName { get; }`	The name other players see.
`IReadOnlyList<VtChatMessage> History { get; }`	Recent received lines, oldest first, capped at `VtTuning.chatHistorySize`.
`IReadOnlyCollection<string> Ignored { get; }`	Player ids whose lines this player does not receive.
`event Action<VtChatMessage> OnMessageReceived`	Fires for every line delivered to this player.
`event Action OnIgnoreListChanged`	Fires after the ignore list changed.
`void Initialize()`	Cache the sibling unit and player identity. Safe to call more than once; call it after adding the component or a `VtPlayerIdentity` at runtime.
`bool Send(VtChatChannel channel, string text, out VtChatFailureReason reason)`	Send `text` on `channel`. On a networked client it is forwarded and this returns false.
`bool Send(VtChatChannel channel, string text, string whisperTo, out VtChatFailureReason reason)`	Send `text` on `channel`; `whisperTo` names the player for whispers.
`bool Whisper(string playerNameOrId, string text, out VtChatFailureReason reason)`	Whisper `text` to the online player with this name or id.
`bool Ignore(string playerId)`	Stop receiving lines from `playerId`. Forwards on a networked client.
`bool Unignore(string playerId)`	Receive lines from `playerId` again. Forwards on a networked client.
`bool IsIgnoring(string playerId)`	True when lines from `playerId` are ignored.
`void Deliver(VtChatMessage message)`	Hand a routed line to this player: stores it in the history and raises `OnMessageReceived`. The router calls it on the server; your transport calls it on the owning client.
`void ClearHistory()`	Empty the history.
`void ApplyIgnoreListFromNet(IEnumerable<string> playerIds)`	Replace the ignore list. Used by loading and replication; not authority-gated.

VtPlayerIdentity

Component. Add it with Add Component → Vantage → Social → VtPlayerIdentity.

Who a player unit belongs to: a stable player id and a display name that outlive the unit, the scene and the session. Chat whispers, guilds, friends and mail address players through it.

Inspector fields

Field	Type	Default	Description
Player Id (`playerId`)	`string`	Empty	Stable player id: a Steam ID, an account id or a local profile id. Assigned by the server.
Display Name (`displayName`)	`string`	Empty	Name other players see. Empty shows the player id.

Scripting API

Member	Description
`string PlayerId { get; }`	The stable player id, or empty before one is assigned.
`string DisplayName { get; }`	The name to show; the player id when no name is set.
`bool HasId { get; }`	True once a player id is assigned.
`VtUnit Unit { get; }`	The unit on the same object, or null.
`static IReadOnlyCollection<VtPlayerIdentity> Online { get; }`	Every online identity.
`event Action<VtPlayerIdentity> OnIdentityChanged`	Fires after `Assign` changed the id or name.
`static event Action<VtPlayerIdentity> OnPlayerOnline`	Fires when a player id comes online in this process.
`static event Action<VtPlayerIdentity> OnPlayerOffline`	Fires when a player id goes offline in this process.
`static VtPlayerIdentity FindById(string id)`	The online identity with `id`, or null.
`static VtPlayerIdentity FindByName(string name)`	The online identity whose display name matches `name` ignoring case, or null.
`static VtPlayerIdentity Find(string idOrName)`	The online identity matching `idOrName` by id first, then by name.
`void Assign(string newPlayerId, string newDisplayName)`	Set the player id and display name. The server calls this at login; replication calls it on clients.

VtChatMessage

Serializable struct.

One delivered chat line. System and Npc lines are usually localization keys; read DisplayText and DisplaySender so each client shows them in its own language.

Inspector fields

Field	Type	Default	Description
Channel (`channel`)	VtChatChannel	`Say`	Channel the line was sent on.
Sender Id (`senderId`)	`string`	Empty	Player id of the sender. Empty for System and Npc lines.
Sender Name (`senderName`)	`string`	Empty	Sender name as sent; a localization key on localizable lines. Show DisplaySender instead.
Recipient Id (`recipientId`)	`string`	Empty	Player id of the whisper target. Empty on other channels.
Recipient Name (`recipientName`)	`string`	Empty	Display name of the whisper target. Empty on other channels.
Text (`text`)	`string`	Empty	The line as sent, or a localization key on localizable lines. Show DisplayText instead.
Localizable (`localizable`)	`bool`	Off	On when text and sender name are localization keys that each client resolves in its own language.
Time (`time`)	`double`	0	When the line was routed, in seconds on the chat clock.

Scripting API

Member	Description
`string DisplayText { get; }`	The text to show, localized when the message is localizable.
`string DisplaySender { get; }`	The sender name to show, localized when the message is localizable.

VtChat

Static class.

The chat router. Runs on the authority: cleans and checks a message, finds the recipients for its channel, and delivers it to each recipient’s VtUnitChat. Players reach it through VtUnitChat.Send; server code posts system and NPC lines with SendSystem and SendNpc.

Scripting API

Member	Description
`static Func<double> Clock { get; set; }`	Seconds used for rate limits, mutes and message times. Null restores real time.
`static event Action<VtChatMessage, int> OnMessageRouted`	Fires on the authority for every routed message, with the number of recipients.
`static Func<VtUnitChat, string, string> FilterFn`	Rewrite or refuse player text after the built-in checks. Return the text to send, or null to refuse with `VtChatFailureReason.Filtered`. Null filter sends as is.
`static Func<VtUnitChat, List<VtUnitChat>, bool> GuildRecipientsFn`	Fill the list with the online guild members who should receive the sender’s guild chat, the sender included, and return true; return false when the sender has no guild. Set by the guild module.
`static void Mute(string playerId, float seconds)`	Mute `playerId` for `seconds`. A negative duration mutes until `Unmute`.
`static void Unmute(string playerId)`	Lift a mute.
`static bool IsMuted(string playerId)`	True while `playerId` is muted.
`static void ResetState()`	Forget every sender’s rate budget and every mute.
`static bool TrySend(VtUnitChat sender, VtChatChannel channel, string text, string whisperTo, out VtChatFailureReason reason)`	Route a player’s message. Called by `VtUnitChat.Send` on the authority.
`static int SendSystem(string keyOrText, IEnumerable<VtUnitChat> to = null, bool localizable = true)`	Post a server announcement to `to`, or to every chat component when null.
`static int SendNpc(VtUnit speaker, string keyOrText, Vector3 center, float radius, bool localizable = true)`	Post a line spoken by `speaker` to chat components within `radius` of `center`. A radius of 0 reaches everyone.
`static string Clean(string text)`	The cleaned form of `text`: trimmed, single line, markup stripped unless allowed.

Enums

VtChatChannel

Where a chat message goes. Serialized as int; append-only.

Value	Description
`Say`	Players within `VtTuning.chatSayRange` of the sender.
`Yell`	Players within `VtTuning.chatYellRange` of the sender.
`Party`	The sender’s party.
`Guild`	The sender’s guild. Needs the guild module.
`Whisper`	One player by name or id, echoed to the sender.
`System`	Server announcements. Players cannot send on it.
`Npc`	Lines spoken by non-player units, such as boss yells. Players cannot send on it.

VtChatFailureReason

Why a chat send refused.

Value	Description
`None`	The message was sent.
`EmptyText`	Nothing left after trimming and stripping markup.
`TooLong`	Longer than `VtTuning.chatMaxLength`.
`RateLimited`	Sent faster than the chat limit allows.
`Muted`	The sender is muted.
`Filtered`	The filter rejected the text.
`NoRecipient`	The whisper target is not online, or is the sender.
`NotInParty`	Party chat without a party.
`NotInGuild`	Guild chat without a guild.
`ChannelNotAllowed`	Players cannot send on System or Npc.
`AuthorityNotLocal`	Not the authority; the message was forwarded.