Guilds reference

The guild component, the stored guild data, the persistence seam and the server-side guild service. For how to use it, see Guilds.

VtUnitGuild

Component. Add it with Add Component → Vantage → Guilds → VtUnitGuild. Adds VtUnit automatically.

A player’s view of and hands on its guild. Opt in through VtUnitDefinition.useGuild; needs a VtPlayerIdentity on the same object, because guild membership belongs to the player id, not the unit.

Scripting API

Member	Description
`string PlayerId { get; }`	The player id guild membership is keyed on, or empty without an identity.
`VtGuildRecord Guild { get; }`	The player’s guild, or null.
`bool InGuild { get; }`	True while the player belongs to a guild.
`VtGuildMember Member { get; }`	The player’s roster entry, or null.
`event Action<VtGuildRecord> OnGuildChanged`	Fires when the player’s guild changed, was joined, left or disbanded. Null means no guild.
`event Action<VtGuildInvite> OnInviteReceived`	Fires when an invite arrives.
`event Action OnInviteCleared`	Fires when the pending invite was accepted, declined or expired.
`bool HasPermission(VtGuildPermissions permission)`	True when the player’s rank allows `permission`.
`bool TryGetInvite(out VtGuildInvite invite)`	The pending invite, if any.
`void Initialize()`	Cache siblings, hook guild chat and listen to the guild service and the player identity. Idempotent; call it again after adding a `VtPlayerIdentity` late.
`bool CreateGuild(string guildName, string tag, out VtGuildFailureReason reason)`	Found a guild, paying the definition’s Guild Creation Cost.
`bool Invite(string playerNameOrId, out VtGuildFailureReason reason)`	Invite the online player with this name or id.
`bool AcceptInvite(out VtGuildFailureReason reason)`	Join the guild that invited this player.
`bool DeclineInvite()`	Turn down the pending invite.
`bool Leave(out VtGuildFailureReason reason)`	Leave the guild.
`bool Kick(string memberPlayerId, out VtGuildFailureReason reason)`	Remove a lower-ranked member.
`bool Promote(string memberPlayerId, out VtGuildFailureReason reason)`	Move a lower-ranked member up one rank.
`bool Demote(string memberPlayerId, out VtGuildFailureReason reason)`	Move a lower-ranked member down one rank.
`bool TransferLeadership(string memberPlayerId, out VtGuildFailureReason reason)`	Hand leadership to a member.
`bool SetMotd(string text, out VtGuildFailureReason reason)`	Change the message of the day.
`bool Disband(out VtGuildFailureReason reason)`	End the guild. Leader only.
`void ApplyGuildFromNet(VtGuildRecord guild)`	Replace this player’s view of its guild. Used by replication; not authority-gated. Null means no guild.
`void ApplyInviteFromNet(VtGuildInvite invite, bool pending)`	Replace this player’s pending invite. Used by replication; not authority-gated.

VtGuildRecord

Serializable class.

A guild as stored: identity, ranks and roster. Plain data that serializes with JsonUtility; change it only through VtGuilds.

Inspector fields

Field	Type	Default	Description
Guild Id (`guildId`)	`string`	Empty	Unique id generated when the guild is founded.
Name (`name`)	`string`	Empty	Guild name, unique ignoring case.
Tag (`tag`)	`string`	Empty	Short tag of 2 to 5 letters or digits, stored uppercase.
Motd (`motd`)	`string`	Empty	Message of the day shown to members.
Created At (`createdAt`)	`double`	0	When the guild was founded, in UTC seconds since 1970.
Ranks (`ranks`)	List of VtGuildRank	Empty	Ranks from highest to lowest. Index 0 is the leader.
Members (`members`)	List of VtGuildMember	Empty	Every member, online or not.

Scripting API

Member	Description
`string LeaderId { get; }`	The leader’s player id, or null.
`VtGuildMember FindMember(string playerId)`	The member with `playerId`, or null.
`VtGuildRank GetRank(int index)`	The rank at `index`, or null.
`bool HasPermission(string playerId, VtGuildPermissions permission)`	True when the member may do `permission`. The leader may do everything.

VtGuildMember

Serializable class.

One member of a guild, online or not.

Inspector fields

Field	Type	Default	Description
Player Id (`playerId`)	`string`	Empty	Stable player id of the member.
Display Name (`displayName`)	`string`	Empty	The member’s name when last seen.
Rank (`rank`)	`int`	0	Index into the guild’s ranks. 0 is the leader; a higher index is a lower rank.
Joined At (`joinedAt`)	`double`	0	When the member joined, in UTC seconds since 1970.
Last Seen At (`lastSeenAt`)	`double`	0	When the member was last seen online, in UTC seconds since 1970.

Scripting API

Member	Description
`bool IsOnline { get; }`	True while the member’s player identity is online in this process.

VtGuildRank

Serializable class.

A rank name and its permissions.

Inspector fields

Field	Type	Default	Description
Name (`name`)	`string`	Empty	Rank name shown on the roster.
Permissions (`permissions`)	VtGuildPermissions	`None`	What members of this rank may do. The leader rank may do everything regardless.

VtGuildInvite

Serializable struct.

A pending invite to a guild.

Inspector fields

Field	Type	Default	Description
Guild Id (`guildId`)	`string`	Empty	Id of the inviting guild.
Guild Name (`guildName`)	`string`	Empty	Name of the inviting guild.
Inviter Id (`inviterId`)	`string`	Empty	Player id of the member who sent the invite.
Inviter Name (`inviterName`)	`string`	Empty	Name of the member who sent the invite.
Expires At (`expiresAt`)	`double`	0	When the invite runs out, in UTC seconds since 1970.

IVtGuildStore

Interface. Implemented by VtJsonGuildStore, VtMemoryGuildStore.

Where guilds persist. VtGuilds keeps every guild in memory and calls Save after each change, so an implementation may write asynchronously. The package ships an in-memory store and VtJsonGuildStore; an online game implements this against its database.

Scripting API

Member	Description
`IEnumerable<VtGuildRecord> LoadAll()`	Every stored guild, read once when the service loads.
`void Save(VtGuildRecord guild)`	Persist the current state of `guild`.
`void Delete(string guildId)`	Remove a disbanded guild.

VtJsonGuildStore

Class.

Stores each guild as a JSON file in a folder. Suits single-player, a listen server or a small dedicated server; an online game with several servers needs a database behind IVtGuildStore instead.

Scripting API

Member	Description
`string Folder { get; }`	The folder guild files live in.
`IEnumerable<VtGuildRecord> LoadAll()`	Every guild file in the folder. Empty when the folder does not exist yet.
`void Save(VtGuildRecord guild)`	Write the guild to its own JSON file, creating the folder when needed.
`void Delete(string guildId)`	Delete the guild’s file.

VtGuilds

Static class.

The guild service. Owns every guild on the authority: creation, invites, membership, ranks, the message of the day and disbanding, and persists each change through Store. Players reach it through VtUnitGuild; server code and tools may call it directly with player ids, which works for offline members too.

Scripting API

Member	Description
`static IVtGuildStore Store { get; set; }`	Where guilds persist. Setting it reloads every guild from the new store.
`static Func<double> Clock { get; set; }`	Wall-clock seconds used for invites and member times. Null restores UTC time.
`static IReadOnlyCollection<VtGuildRecord> All { get; }`	Every guild.
`static event Action<VtGuildRecord> OnGuildChanged`	Fires after a guild was created or changed: roster, ranks, names or message of the day.
`static event Action<VtGuildRecord> OnGuildDisbanded`	Fires after a guild was disbanded, with its last state.
`static event Action<string, string> OnMembershipChanged`	Fires when a player joined or left a guild: (player id, guild id or null).
`static event Action<string, VtGuildInvite, bool> OnInviteChanged`	Fires when a player’s pending invite was set or cleared: (player id, invite, pending).
`static Func<string, bool> NameFilterFn`	Refuse a guild name for reasons beyond the built-in rules, such as a word list. Return false to refuse.
`static VtGuildRecord FindById(string guildId)`	The guild with `guildId`, or null.
`static VtGuildRecord FindByName(string name)`	The guild named `name` ignoring case, or null.
`static VtGuildRecord GuildOf(string playerId)`	The guild `playerId` belongs to, or null.
`static bool TryGetInvite(string playerId, out VtGuildInvite invite)`	The unexpired invite waiting for `playerId`.
`static void Reload()`	Drop every guild and invite from memory and load again from the store.
`static bool Create(string founderId, string founderName, string name, string tag, out VtGuildRecord guild, out VtGuildFailureReason reason)`	Found a guild with `founderId` as leader.
`static bool Invite(string inviterId, string targetId, out VtGuildFailureReason reason)`	Invite `targetId` to the inviter’s guild. Replaces an older invite.
`static bool Accept(string playerId, string displayName, out VtGuildFailureReason reason)`	Join the guild that invited `playerId`.
`static bool Decline(string playerId)`	Turn down a pending invite. False when there is none.
`static bool Leave(string playerId, out VtGuildFailureReason reason)`	Leave the guild. A leader with other members must hand over leadership first; a leader alone disbands the guild.
`static bool Kick(string actorId, string targetId, out VtGuildFailureReason reason)`	Remove `targetId`. Needs Kick and a higher rank than the target.
`static bool Promote(string actorId, string targetId, out VtGuildFailureReason reason)`	Move `targetId` one rank up, never to leader. Needs Promote and a rank at least two above the target.
`static bool Demote(string actorId, string targetId, out VtGuildFailureReason reason)`	Move `targetId` one rank down. Needs Promote and a higher rank than the target.
`static bool TransferLeadership(string actorId, string targetId, out VtGuildFailureReason reason)`	Make `targetId` the leader; the old leader becomes the next rank. Leader only.
`static bool SetMotd(string actorId, string text, out VtGuildFailureReason reason)`	Set the message of the day, cleaned like chat and capped at `VtTuning.guildMotdMaxLength`. Needs Edit Motd.
`static bool Disband(string actorId, out VtGuildFailureReason reason)`	End the guild and free every member. Leader only.
`static void TouchMember(string playerId, string displayName)`	Record a member’s current display name and last-seen time. Called when a player logs in or renames.
`static bool IsValidName(string name)`	True when `name` passes the length, character and filter rules.
`static void EnsureChatHook()`	Route guild chat through the guild roster. Called by `VtUnitGuild`; call it yourself in a headless server.
`static void ResetState()`	Clear memory, invites and seams, and return to an empty in-memory store.

Enums

VtGuildPermissions

What a guild rank may do. Rank 0 is the leader and may do everything.

Flags: values can be combined.

Value	Description
`None`	No permissions.
`Invite`	Invite players.
`Kick`	Remove members of a lower rank.
`Promote`	Promote and demote members of a lower rank.
`EditMotd`	Change the message of the day.
`All`	Every permission.

VtGuildFailureReason

Why a guild call refused.

Value	Description
`None`	The call succeeded.
`NoIdentity`	The player has no player identity.
`AlreadyInGuild`	The player already belongs to a guild.
`NotInGuild`	The player belongs to no guild.
`NameInvalid`	The name is too short, too long, or has characters other than letters, digits and single spaces.
`NameTaken`	Another guild has this name.
`TagInvalid`	The tag is not 2 to 5 letters or digits.
`CannotAfford`	The founder cannot pay the creation cost.
`NoPermission`	The player’s rank lacks the permission.
`TargetNotFound`	No online player by that name or id.
`TargetInGuild`	The invited player already belongs to a guild.
`TargetNotMember`	The player acted on is not a member of this guild.
`GuildFull`	The guild has `VtTuning.guildMaxMembers` members.
`NoInvite`	No invite is pending, or it expired.
`RankTooLow`	The target’s rank is not below the acting member’s.
`LeaderCannotLeave`	The leader must hand over leadership before leaving a guild with other members.
`AuthorityNotLocal`	Not the authority; the request was forwarded.