Friends reference

The friends component, the stored friend data, the persistence and platform seams, the server-side friends service and the player directory that finds offline players. For how to use it, see Friends.

VtUnitFriends

Component. Add it with Add Component → Vantage → Friends → VtUnitFriends. Adds VtUnit automatically.

A player’s friends list: in-game friends and requests from the server, plus platform friends such as Steam from the local client, merged by GetView. Opt in through VtUnitDefinition.useFriends; needs a VtPlayerIdentity on the same object.

Scripting API

Member	Description
`string PlayerId { get; }`	The player id friendships are keyed on, or empty without an identity.
`VtFriendRecord Record { get; }`	This player’s record: the server’s on the authority, the replicated one on a client. Null without an id.
`IReadOnlyList<VtFriendLink> Friends { get; }`	In-game friends.
`IReadOnlyList<VtFriendRequest> Incoming { get; }`	Requests waiting for this player’s answer.
`IReadOnlyList<VtFriendRequest> Outgoing { get; }`	Requests this player sent that are still open.
`event Action<VtFriendRecord> OnFriendsChanged`	Fires when friends or requests changed. The argument is the new record, or null.
`event Action<string, bool> OnFriendPresenceChanged`	Fires when an in-game friend came online or went offline: (friend id, online).
`void Initialize()`	Cache the identity and listen to the friends service. Idempotent; call again after adding an identity late.
`bool IsOnline(string friendId)`	True when the in-game friend `friendId` is online.
`void GetView(List<VtFriendView> results)`	Fill `results` with in-game and platform friends merged into one list.
`bool SendRequest(string playerNameOrId, out VtFriendsFailureReason reason)`	Send a friend request to a player by name or id, online or offline.
`bool Accept(string fromPlayerId, out VtFriendsFailureReason reason)`	Accept the request from `fromPlayerId`.
`bool Decline(string fromPlayerId, out VtFriendsFailureReason reason)`	Decline the request from `fromPlayerId`.
`bool Cancel(string toPlayerId, out VtFriendsFailureReason reason)`	Withdraw the request sent to `toPlayerId`.
`bool Remove(string friendPlayerId, out VtFriendsFailureReason reason)`	End the friendship with `friendPlayerId`.
`void ApplyFriendsFromNet(VtFriendRecord record, IEnumerable<string> onlineFriendIds)`	Replace this player’s view of its friends and which of them are online. Used by replication; not authority-gated.
`void ApplyPresenceFromNet(string friendId, bool online)`	Update one friend’s presence on a client. Used by replication; not authority-gated.

VtFriendRecord

Serializable class.

One player’s friends and pending requests. Plain data that serializes with JsonUtility; change it only through VtFriends.

Inspector fields

Field	Type	Default	Description
Player Id (`playerId`)	`string`	Empty	Player id this record belongs to.
Friends (`friends`)	List of VtFriendLink	Empty	Accepted friends.
Incoming (`incoming`)	List of VtFriendRequest	Empty	Requests other players sent to this player, waiting for an answer.
Outgoing (`outgoing`)	List of VtFriendRequest	Empty	Requests this player sent, waiting for an answer.

Scripting API

Member	Description
`VtFriendLink FindFriend(string otherId)`	The friendship with `otherId`, or null.
`bool IsFriend(string otherId)`	True when `otherId` is a friend.
`VtFriendRequest FindIncoming(string otherId)`	The request received from `otherId`, or null.
`VtFriendRequest FindOutgoing(string otherId)`	The request sent to `otherId`, or null.

VtFriendLink

Serializable class.

An accepted friendship, as seen from one side.

Inspector fields

Field	Type	Default	Description
Player Id (`playerId`)	`string`	Empty	Player id of the friend.
Display Name (`displayName`)	`string`	Empty	The friend’s name when last seen. Updated when the friend renames.
Since (`since`)	`double`	0	When the friendship began, in UTC seconds since 1970.

VtFriendRequest

Serializable class.

A pending friend request, as seen from one side.

Inspector fields

Field	Type	Default	Description
Player Id (`playerId`)	`string`	Empty	Player id of the other side: the requester on an incoming request, the recipient on an outgoing one.
Display Name (`displayName`)	`string`	Empty	The other side’s name when last seen.
Sent At (`sentAt`)	`double`	0	When the request was sent, in UTC seconds since 1970. It drops after Friend Request Expiry Days.

VtFriendView

Serializable struct.

One row of a merged friends window: in-game friends and platform friends combined.

Inspector fields

Field	Type	Default	Description
Player Id (`playerId`)	`string`	Empty	Player id of the friend. For a platform-only friend, its platform id mapped through VtFriends.PlatformIdToPlayerId.
Display Name (`displayName`)	`string`	Empty	Name to show.
In Game Friend (`inGameFriend`)	`bool`	Off	On when the player is an in-game friend.
Platform Friend (`platformFriend`)	`bool`	Off	On when the player is a friend on the platform, such as Steam.
Online (`online`)	`bool`	Off	On while the friend is online, in game or on the platform.
Playing This Game (`playingThisGame`)	`bool`	Off	On while the friend is running this game.

VtPlatformFriend

Serializable struct.

A friend on an external platform such as Steam, as reported on the local client.

Inspector fields

Field	Type	Default	Description
Platform Id (`platformId`)	`string`	Empty	The platform’s id for the friend, such as a SteamID as a string.
Display Name (`displayName`)	`string`	Empty	The friend’s name on the platform.
Online (`online`)	`bool`	Off	On while the friend is online on the platform.
Playing This Game (`playingThisGame`)	`bool`	Off	On while the friend is running this game.

VtPlayerRecord

Serializable class.

A player the server has seen: id, last known name, when last online.

Inspector fields

Field	Type	Default	Description
Player Id (`playerId`)	`string`	Empty	Stable player id.
Display Name (`displayName`)	`string`	Empty	The name the player had when last seen.
Last Seen At (`lastSeenAt`)	`double`	0	When the player was last seen online, in UTC seconds since 1970.

IVtFriendsStore

Interface. Implemented by VtJsonFriendsStore, VtMemoryFriendsStore.

Where friend records persist, one record per player. VtFriends loads a record 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
`VtFriendRecord Load(string playerId)`	The stored record for `playerId`, or null when there is none.
`void Save(VtFriendRecord record)`	Persist `record`.

VtJsonFriendsStore

Class.

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

Scripting API

Member	Description
`VtFriendRecord Load(string playerId)`	The record in the player’s file, or null when the file does not exist.
`void Save(VtFriendRecord record)`	Write the record to the player’s JSON file, creating the folder when needed.

IVtPlatformFriendsProvider

Interface.

Supplies the local user’s friends from a platform such as Steam. Platform friends are known only on the user’s own machine, so set a provider on the client through VtFriends.PlatformProvider; the server never uses it.

Scripting API

Member	Description
`string PlatformName { get; }`	Name shown next to platform friends, such as “Steam”.
`event Action OnChanged`	Fires when the platform friends or their presence changed.
`void GetFriends(List<VtPlatformFriend> results)`	Fill `results` with the local user’s platform friends.

IVtPlayerDirectoryStore

Interface. Implemented by VtJsonPlayerDirectoryStore, VtMemoryPlayerDirectoryStore.

Where the player directory persists. The service writes after every change.

Scripting API

Member	Description
`IEnumerable<VtPlayerRecord> LoadAll()`	Every known player, read once when the directory loads.
`void Save(VtPlayerRecord record)`	Persist one player’s record.

VtJsonPlayerDirectoryStore

Class.

Stores each player record as a JSON file in a folder.

Scripting API

Member	Description
`IEnumerable<VtPlayerRecord> LoadAll()`	Every record file in the folder. Empty when the folder does not exist yet.
`void Save(VtPlayerRecord record)`	Write the record to its own JSON file, creating the folder when needed.

VtFriends

Static class.

The friends service. Runs on the authority: friend requests to online or offline players, accepting, declining, cancelling and removing, with both sides kept in step and persisted through Store. Raises presence events when a friend comes online or goes offline. Players reach it through VtUnitFriends.

Scripting API

Member	Description
`static IVtFriendsStore Store { get; set; }`	Where records persist. Setting it clears the cache.
`static Func<double> Clock { get; set; }`	Wall-clock seconds for request times and expiry. Null restores UTC time.
`static event Action<VtFriendRecord> OnRecordChanged`	Fires after a player’s record changed.
`static event Action<string, string, bool> OnFriendPresenceChanged`	Fires when a friend came online or went offline: (player whose friend it is, friend id, online).
`static IVtPlatformFriendsProvider PlatformProvider`	The local user’s platform friends, such as Steam. Client-side only; null when none.
`static Func<string, string> PlatformIdToPlayerId`	Maps a platform id to a player id so a platform friend who plays the game merges with the in-game friendship. Default: the ids are the same, as when player ids are SteamIDs.
`static VtFriendRecord GetRecord(string playerId)`	The record for `playerId`, loaded or created, with expired requests dropped.
`static bool IsOnline(string playerId)`	True while `playerId` is online in this process.
`static bool SendRequest(string fromId, string targetIdOrName, out VtFriendsFailureReason reason)`	Send a friend request from `fromId` to a player by name or id, online or not. A request the other player already sent is accepted instead.
`static bool Accept(string playerId, string fromId, out VtFriendsFailureReason reason)`	Accept the request `playerId` received from `fromId`.
`static bool Decline(string playerId, string fromId, out VtFriendsFailureReason reason)`	Turn down the request `playerId` received from `fromId`.
`static bool Cancel(string playerId, string toId, out VtFriendsFailureReason reason)`	Withdraw the request `playerId` sent to `toId`.
`static bool Remove(string playerId, string friendId, out VtFriendsFailureReason reason)`	End the friendship between the two players, on both sides.
`static void Rename(string playerId, string displayName)`	Update the name every friend and requester sees for `playerId`.
`static void BuildView(VtFriendRecord record, Func<string, bool> isOnline, List<VtFriendView> results)`	Merge in-game friends from `record` with the local platform friends into `results`. Rows for the same player combine; online is true when either side reports it.
`static void EnsureHooked()`	Start watching identities for presence and the directory. Idempotent; the friends component calls it.
`static void ResetState()`	Clear the cache, unhook, and return to an empty in-memory store.

VtPlayerDirectory

Static class.

Every player the server has seen, online or not, so friend requests and mail can find a player by name after they logged off. Filled automatically from VtPlayerIdentity once any social component initializes; persists through Store.

Scripting API

Member	Description
`static IVtPlayerDirectoryStore Store { get; set; }`	Where records persist. Setting it reloads from the new store.
`static Func<double> Clock { get; set; }`	Wall-clock seconds for last-seen times. Null restores UTC time.
`static IReadOnlyCollection<VtPlayerRecord> All { get; }`	Every known player.
`static event Action<VtPlayerRecord> OnRecordChanged`	Fires after a record was added or changed.
`static void EnsureHooked()`	Start recording players as they come online. Idempotent; social components call it.
`static VtPlayerRecord Record(string playerId, string displayName)`	Add or update a player and stamp the last-seen time.
`static VtPlayerRecord FindById(string playerId)`	The record for `playerId`, or null.
`static bool TryFind(string idOrName, out VtPlayerRecord record)`	Find a player by id, or by name ignoring case: online first, then most recently seen.
`static void ResetState()`	Forget memory, unhook, and return to an empty in-memory store.

Enums

VtFriendsFailureReason

Why a friends call refused.

Value	Description
`None`	The call succeeded.
`NoIdentity`	The player has no player identity.
`PlayerNotFound`	No known player by that name or id.
`CannotBefriendSelf`	A player cannot befriend itself.
`AlreadyFriends`	Already friends.
`RequestPending`	A request to that player is already waiting.
`FriendListFull`	The player has `VtTuning.friendsMaxCount` friends.
`TargetFull`	The other player’s friend list or request inbox is full.
`NoRequest`	No such pending request.
`NotFriends`	The players are not friends.
`AuthorityNotLocal`	Not the authority; the request was forwarded.