GuildSystem - jimdroberts/FishMMO GitHub Wiki

The GuildSystem is a server-side system in FishMMO responsible for managing all aspects of player guilds, including creation, invitations, membership, rank changes, and synchronization of guild data. It registers and handles network broadcasts for all guild actions, tracks online guild members, processes guild updates from the database, and ensures that all guild-related events are validated and synchronized between the server, database, and client.

• private LocalConnectionState serverState

  Current connection state of the server.

• private DateTime lastFetchTime

  Timestamp of the last successful fetch from the database.

• private float nextPump

  Time remaining until the next database poll for guild updates.

• public int MaxGuildSize

  Maximum number of members allowed in a guild.

• public int MaxGuildNameLength

  Maximum length allowed for a guild name.

• public float UpdatePumpRate

  The server guild update pump rate limit in seconds.

• private Dictionary<long, HashSet> guildMemberTracker

  Tracks all of the members for a guild if any of the guild members are logged in to this server.

• private Dictionary<long, HashSet> guildCharacterTracker

  Tracks all active guilds and currently online guild members on this scene server.

• private readonly Dictionary<long, long> pendingInvitations

  Tracks pending guild invitations by client ID and guild ID.

• private Dictionary<string, ChatCommand> guildChatCommands

  Registered chat commands for guild actions.

• public bool OnGuildInvite(IPlayerCharacter sender, ChatBroadcast msg)

  Handles guild invite chat commands, sending an invite to the target character. sender (IPlayerCharacter): The character sending the invite. msg (ChatBroadcast): Chat broadcast message containing the target character name. Returns: bool - True if invite was sent, false otherwise.

• public override void InitializeOnce()

  Initializes the guild system, registering chat commands and broadcast handlers, and character events.

• public override void Destroying()

  Cleans up the guild system, unregistering broadcast handlers and character events.

• void LateUpdate()

  Unity LateUpdate callback. Polls the database for guild updates at the specified rate and processes them.

• private List FetchGuildUpdates()

  Fetches new guild updates from the database since the last fetch. Returns: List - List of new guild update entities.

• private void ProcessGuildUpdates(List updates)

  Processes a list of guild updates, synchronizing guild membership and broadcasting changes to clients. updates (List): List of guild update entities to process.

• public void AddGuildCharacterTracker(long guildID, long characterID)

  Adds a mapping for the Guild to Guild Members connected to this Scene Server. guildID (long): ID of the guild. characterID (long): ID of the character to add.

• public void RemoveGuildCharacterTracker(long guildID, long characterID)

  Removes the mapping of Guild to Guild Members connected to this Scene Server. guildID (long): ID of the guild. characterID (long): ID of the character to remove.

• public void CharacterSystem_OnConnect(NetworkConnection conn, IPlayerCharacter character)

  Handles character connect event, adding the character to the guild tracker and saving guild update. conn (NetworkConnection): Network connection of the character. character (IPlayerCharacter): The character that connected.

• public void CharacterSystem_OnDisconnect(NetworkConnection conn, IPlayerCharacter character)

  Handles character disconnect event, removing the character from the guild tracker and saving guild update. conn (NetworkConnection): Network connection of the character. character (IPlayerCharacter): The character that disconnected.

• public void OnServerGuildCreateBroadcastReceived(NetworkConnection conn, GuildCreateBroadcast msg, Channel channel)

  Handles guild creation broadcast, validates and creates a new guild for the requesting character. conn (NetworkConnection): Network connection of the requester. msg (GuildCreateBroadcast): Message containing guild creation details. channel (Channel): Network channel used for the broadcast.

• public void OnServerGuildInviteBroadcastReceived(NetworkConnection conn, GuildInviteBroadcast msg, Channel channel)

  Handles guild invitation broadcast, validates inviter and target, and sends invitation to the target character. conn (NetworkConnection): Network connection of the inviter. msg (GuildInviteBroadcast): Message containing inviter and target IDs. channel (Channel): Network channel used for the broadcast.

• public void OnServerGuildAcceptInviteBroadcastReceived(NetworkConnection conn, GuildAcceptInviteBroadcast msg, Channel channel)

  Handles acceptance of a guild invitation, validates the invite, adds the character to the guild, and broadcasts the update. conn (NetworkConnection): Network connection of the accepting character. msg (GuildAcceptInviteBroadcast): Message containing acceptance details. channel (Channel): Network channel used for the broadcast.

• public void OnServerGuildDeclineInviteBroadcastReceived(NetworkConnection conn, GuildDeclineInviteBroadcast msg, Channel channel)

  Handles decline of a guild invitation, removes pending invitation for the character. conn (NetworkConnection): Network connection of the declining character. msg (GuildDeclineInviteBroadcast): Message containing decline details. channel (Channel): Network channel used for the broadcast.

• public void OnServerGuildLeaveBroadcastReceived(NetworkConnection conn, GuildLeaveBroadcast msg, Channel channel)

  Handles guild leave broadcast, validates character, transfers leadership if needed, removes member from guild, and updates or deletes guild as appropriate. conn (NetworkConnection): Network connection of the leaving character. msg (GuildLeaveBroadcast): Message containing leave details. channel (Channel): Network channel used for the broadcast.

• public void OnServerGuildRemoveBroadcastReceived(NetworkConnection conn, GuildRemoveBroadcast msg, Channel channel)

  Handles guild member removal broadcast, validates and removes a member from the guild in the database. conn (NetworkConnection): Network connection of the requester. msg (GuildRemoveBroadcast): Message containing member ID to remove. channel (Channel): Network channel used for the broadcast.

• public void OnServerGuildChangeRankBroadcastReceived(NetworkConnection conn, GuildChangeRankBroadcast msg, Channel channel)

  Handles guild rank change broadcast, validates leader and target, and updates ranks in the database. conn (NetworkConnection): Network connection of the requester. msg (GuildChangeRankBroadcast): Message containing target member ID and new rank. channel (Channel): Network channel used for the broadcast.

1. Requires the server to be running and the guild system to be initialized as part of the server startup.
2. All guild-related broadcast handlers and chat commands are registered automatically by the system.
3. The system automatically polls the database for new guild updates and processes them at the configured rate.
4. No manual registration is required unless extending or customizing guild logic.

// Example 1: Creating a guild (server-side)
// This is handled automatically by the system when a GuildCreateBroadcast is received from a client.
// No manual invocation is required unless extending or customizing the logic.

// Example 2: Inviting a player to a guild (server-side)
// This is handled automatically by the system when a GuildInviteBroadcast is received from a client or via chat command.
// No manual invocation is required unless extending or customizing the logic.

• Always validate all guild actions and membership changes to prevent exploits and errors.
• Use the provided broadcast handlers and chat commands to extend or customize guild logic if needed.
• Ensure all guild data is properly synchronized between the server, database, and client.
• Avoid direct manipulation of guild membership or data outside of the provided interfaces and system methods.
• Periodically poll and process guild updates to keep all clients in sync with the latest guild state.