Mail reference

The mailbox component, drafts and stored mail, the persistence seam and the server-side mail service. For how to use it, see Mail.

VtUnitMail

Component. Add it with Add Component → Vantage → Mail → VtUnitMail. Adds VtUnit automatically.

A player’s mailbox: sends mail with item and currency attachments, reads, takes attachments, deletes and returns mail. Opt in through VtUnitDefinition.useMail; needs a VtPlayerIdentity on the same object.

Scripting API

Member	Description
`string PlayerId { get; }`	The player id the mailbox belongs to, or empty without an identity.
`IReadOnlyList<VtMailMessage> Mailbox { get; }`	This player’s mails, newest last: the server’s on the authority, the replicated copy on a client.
`int UnreadCount { get; }`	Mails not yet read.
`event Action<IReadOnlyList<VtMailMessage>> OnMailboxChanged`	Fires when the mailbox changed.
`event Action<VtMailMessage> OnMailArrived`	Fires when a mail arrives, including returned mail.
`void Initialize()`	Cache siblings and listen to the mail service. Idempotent.
`bool Send(VtMailDraft draft, out VtMailFailureReason reason)`	Send `draft`, taking its attachments and the postage from this unit.
`bool TakeAttachments(string mailId, out VtMailFailureReason reason)`	Take a mail’s currency and as many of its items as fit.
`bool MarkRead(string mailId, out VtMailFailureReason reason)`	Mark a mail read.
`bool Delete(string mailId, out VtMailFailureReason reason)`	Delete a mail whose attachments were taken.
`bool ReturnToSender(string mailId, out VtMailFailureReason reason)`	Send a player’s mail back with its attachments.
`void ApplyMailboxFromNet(IEnumerable<VtMailMessage> messages)`	Replace this player’s view of its mailbox. Used by replication; not authority-gated.
`void ApplyArrivalFromNet(VtMailMessage message)`	Raise `OnMailArrived` on a client. Used by replication; not authority-gated.

VtMailDraft

Serializable class.

A mail being written: recipient, subject, body and attachments. Build it with Create, WithItem and WithCurrency, then hand it to VtUnitMail.Send.

Inspector fields

Field	Type	Default	Description
To (`to`)	`string`	Empty	Recipient by name or player id. Offline players are found through the player directory.
Subject (`subject`)	`string`	Empty	Subject line. Must not be empty; capped at Mail Subject Max Length.
Body (`body`)	`string`	Empty	Body text. Capped at Mail Body Max Length.
Items (`items`)	List of VtMailItem	Empty	Items to attach, taken from the sender’s inventory on send.
Currency (`currency`)	List of VtMailCurrency	Empty	Currency to attach, taken from the sender’s wallet on send.

Scripting API

Member	Description
`static VtMailDraft Create(string to, string subject, string body)`	A draft to a player by name or id.
`VtMailDraft WithItem(VtItemDefinition item, int count)`	Attach `count` of `item` from the sender’s inventory.
`VtMailDraft WithCurrency(VtCurrencyDefinition currencyDefinition, int amount)`	Attach `amount` of `currencyDefinition` from the sender’s wallet.

VtMailMessage

Serializable class.

One mail in a mailbox. Plain data that serializes with JsonUtility; change it only through VtMail.

Inspector fields

Field	Type	Default	Description
Mail Id (`mailId`)	`string`	Empty	Unique id generated on delivery.
From Id (`fromId`)	`string`	Empty	Player id of the sender. Empty for system mail.
From Name (`fromName`)	`string`	Empty	Sender name to show. Empty for system mail.
To Id (`toId`)	`string`	Empty	Player id of the mailbox owner.
Subject (`subject`)	`string`	Empty	Subject line, cleaned of markup and line breaks.
Body (`body`)	`string`	Empty	Body text, cleaned of markup. Keeps line breaks.
Sent At (`sentAt`)	`double`	0	When the mail arrived, in UTC seconds since 1970.
Expires At (`expiresAt`)	`double`	0	When the mail expires, in UTC seconds since 1970: Mail Expiry Days after it arrived.
Read (`read`)	`bool`	Off	On once the recipient read the mail or took its attachments.
Is System (`isSystem`)	`bool`	Off	Sent by the game rather than a player. Cannot be returned.
Returned (`returned`)	`bool`	Off	Came back to its sender. Cannot be returned again.
Items (`items`)	List of VtMailItem	Empty	Attached items still waiting to be taken.
Currency (`currency`)	List of VtMailCurrency	Empty	Attached currency still waiting to be taken.

Scripting API

Member	Description
`bool HasAttachments { get; }`	True while items or currency are still attached.

VtMailItem

Serializable class.

Items attached to a mail, by item id.

Inspector fields

Field	Type	Default	Description
Item Id (`itemId`)	`string`	Empty	Id of the item definition. Resolves through the Definition Catalog when taken.
Count (`count`)	`int`	0	How many of the item are attached.

VtMailCurrency

Serializable class.

Currency attached to a mail, by currency id.

Inspector fields

Field	Type	Default	Description
Currency Id (`currencyId`)	`string`	Empty	Id of the currency definition. Resolves through the Definition Catalog when taken.
Amount (`amount`)	`int`	0	How much of the currency is attached.

VtMailboxSnapshot

Serializable class.

A mailbox as one JSON-friendly object, for stores and replication.

Inspector fields

Field	Type	Default	Description
Player Id (`playerId`)	`string`	Empty	Player id of the mailbox owner.
Messages (`messages`)	List of VtMailMessage	Empty	Every mail in the mailbox, oldest first.

IVtMailStore

Interface. Implemented by VtJsonMailStore, VtMemoryMailStore.

Where mailboxes persist, one per player. VtMail loads a mailbox the first time it is needed and saves after every change, so an implementation may write asynchronously. An online game implements this against its database.

Scripting API

Member	Description
`List<VtMailMessage> LoadMailbox(string playerId)`	The stored mails for `playerId`; empty when there are none.
`void SaveMailbox(string playerId, List<VtMailMessage> messages)`	Persist `playerId`’s mails.

VtJsonMailStore

Class.

Stores each player’s mailbox as a JSON file in a folder.

Scripting API

Member	Description
`List<VtMailMessage> LoadMailbox(string playerId)`	The mails in the player’s file; empty when the file does not exist.
`void SaveMailbox(string playerId, List<VtMailMessage> messages)`	Write the player’s mails to their JSON file, creating the folder when needed.

VtMail

Static class.

The mail service. Runs on the authority: delivers mail to online or offline players, lets recipients read, take attachments, delete and return mail, expires old mail, and persists mailboxes through Store. Players send through VtUnitMail, which takes the attached items, currency and postage from the sender first. Server code sends rewards and notices with SendSystem.

Scripting API

Member	Description
`static IVtMailStore Store { get; set; }`	Where mailboxes persist. Setting it clears the cache.
`static Func<double> Clock { get; set; }`	Wall-clock seconds for send and expiry times. Null restores UTC time.
`static event Action<string, IReadOnlyList<VtMailMessage>> OnMailboxChanged`	Fires after a mailbox changed: (player id, mails).
`static event Action<string, VtMailMessage> OnMailArrived`	Fires when a mail lands in a mailbox, including returns: (player id, mail).
`static VtDefinitionCatalog Catalog`	Resolves attachment ids. Null uses `VtDefinitionCatalog.Instance`.
`static IReadOnlyList<VtMailMessage> GetMailbox(string playerId)`	The mails for `playerId`, newest last, with expired mail handled.
`static VtMailMessage Find(string playerId, string mailId)`	The mail with `mailId` in `playerId`’s mailbox, or null.
`static int UnreadCount(string playerId)`	Unread mails for `playerId`.
`static bool CanSend(string fromId, VtMailDraft draft, out VtPlayerRecord recipient, out VtMailFailureReason reason)`	Check everything about a player’s draft except the sender’s items and money, and clean its subject and body in place.
`static VtMailMessage Deliver(string fromId, string fromName, string toPlayerId, VtMailDraft draft, bool isSystem)`	Put a checked draft in the recipient’s mailbox. `VtUnitMail` calls this after taking the attachments from the sender; call it yourself only with attachments already paid for.
`static VtMailMessage SendSystem(string toPlayerId, string subject, string body, VtMailDraft attachments = null)`	Send a mail from the game, such as a reward that did not fit or a notice. Ignores the mailbox cap and needs no directory entry. Attachments are created, not taken from anyone.
`static bool MarkRead(string playerId, string mailId, out VtMailFailureReason reason)`	Mark a mail read.
`static bool Delete(string playerId, string mailId, out VtMailFailureReason reason)`	Delete a mail without attachments.
`static bool TakeAttachments(string playerId, string mailId, VtUnitInventory inventory, VtUnitWallet wallet, out VtMailFailureReason reason)`	Move a mail’s currency into `wallet` and its items into `inventory` until one does not fit. Also marks it read.
`static bool ReturnToSender(string playerId, string mailId, out VtMailFailureReason reason)`	Send a player’s mail back to its sender with its attachments.
`static void ResetState()`	Forget cached mailboxes and seams, and return to an empty in-memory store.

Enums

VtMailFailureReason

Why a mail call refused.

Value	Description
`None`	The call succeeded.
`NoIdentity`	The player has no player identity.
`RecipientNotFound`	No known player by that name or id.
`CannotMailSelf`	A player cannot mail itself.
`RecipientMailboxFull`	The recipient has `VtTuning.mailboxMaxCount` mails.
`SubjectEmpty`	The subject is empty after cleaning.
`TooLong`	The subject or body is longer than allowed.
`TooManyAttachments`	More attachment lines than `VtTuning.mailMaxAttachments`.
`UnknownDefinition`	An attached item or currency id is not in the Definition Catalog.
`NoInventory`	The sender has no inventory for item attachments.
`MissingItems`	The sender holds fewer items than attached.
`ItemNotTradeable`	An attached item cannot be traded.
`NoWallet`	The sender has no wallet for currency or postage.
`CannotAfford`	The sender cannot pay the attached currency plus postage.
`MailNotFound`	No mail with that id in the mailbox.
`AttachmentsRemaining`	Take the attachments before deleting.
`InventoryFull`	Some attached items did not fit; the rest stay attached.
`NotReturnable`	System mail and returned mail cannot be returned.
`AuthorityNotLocal`	Not the authority; the request was forwarded.