InteractableSystem - jimdroberts/FishMMO GitHub Wiki

The InteractableSystem is a central server-side system in FishMMO responsible for managing all interactable objects and their interactions within a world scene. It handles registration and invocation of interactable handlers, processes client broadcasts for interactions (such as merchants, dungeons, abilities, and world items), and coordinates the logic for adding items, learning abilities, and managing dungeon entrances. This system ensures that all interactable-related events are validated, processed, and broadcasted to clients in a secure and consistent manner.

• private static Dictionary<Type, IInteractableHandler> interactableHandlers

  Holds registered interactable handlers for each interactable type. Used for static handler management.

• private static List handlerInitializers

  Holds registered handler initializers for interactable handlers. Used for static handler initialization.

• private readonly ServerSystem Server

  Reference to the main server system, used for broadcasting and database access.

• private readonly CurrencyTemplate CurrencyTemplate

  Reference to the currency template used for purchases and ability learning.

• private readonly int MaxAbilityCount

  Maximum number of abilities a character can learn.

• public static void RegisterHandler(Type type, IInteractableHandler handler)

  Registers a handler for a specific interactable type. type (Type): The interactable type. handler (IInteractableHandler): The handler instance to register.

• public static void RegisterHandlerInitializer(IInteractableHandlerInitializer initializer)

  Registers a handler initializer for interactable handlers. initializer (IInteractableHandlerInitializer): The initializer instance to register.

• public static void InitializeHandlers(ServerSystem server)

  Initializes all registered handler initializers with the server instance. server (ServerSystem): The server system instance.

• public bool SendNewItemBroadcast(NpgsqlDbContext dbContext, NetworkConnection conn, ICharacter character, IInventoryController inventoryController, Item newItem)

  Attempts to add a new item to a character's inventory and broadcasts the update to the client. dbContext (NpgsqlDbContext): Database context for persistence. conn (NetworkConnection): The network connection to the client. character (ICharacter): The character receiving the item. inventoryController (IInventoryController): The inventory controller for the character. newItem (Item): The item to add. Returns: bool - True if the item was added and broadcasted, false otherwise.

• private void OnServerInteractableBroadcastReceived(NetworkConnection conn, InteractableBroadcast msg, Channel channel)

  Handles interactable broadcasts received from a client, validates, and invokes the appropriate handler. conn (NetworkConnection): The network connection. msg (InteractableBroadcast): The broadcast message. channel (Channel): The network channel.

• public void OnInteractNPC(IPlayerCharacter character, IInteractable interactable)

  Handles NPC interaction logic, such as making the NPC look at the player and transition to idle state. character (IPlayerCharacter): The player character. interactable (IInteractable): The NPC interactable.

• private void OnServerMerchantPurchaseBroadcastReceived(NetworkConnection conn, MerchantPurchaseBroadcast msg, Channel channel)

  Handles merchant purchase requests from clients, validates purchase, and processes item or ability acquisition. conn (NetworkConnection): The network connection. msg (MerchantPurchaseBroadcast): The purchase broadcast message. channel (Channel): The network channel.

• private void LearnAbilityGeneric<TTemplate, TBroadcast>(...)

  Generic method for learning abilities or ability events, handling validation, currency deduction, and broadcasting. dbContext (NpgsqlDbContext): Database context. conn (NetworkConnection): Network connection. character (IPlayerCharacter): The player character. template (TTemplate): The ability or event template. knowsFunc, learnFunc, addToDbFunc, idSelector, priceSelector, broadcastFactory: Delegates for logic.

• public void LearnAbilityTemplate(NpgsqlDbContext dbContext, NetworkConnection conn, IPlayerCharacter character, T template) where T : BaseAbilityTemplate

  Handles learning a new ability template for a character. dbContext, conn, character, template: See above.

• public void LearnAbilityEvent(NpgsqlDbContext dbContext, NetworkConnection conn, IPlayerCharacter character, T template) where T : AbilityEvent

  Handles learning a new ability event for a character. dbContext, conn, character, template: See above.

• public void OnServerAbilityCraftBroadcastReceived(NetworkConnection conn, AbilityCraftBroadcast msg, Channel channel)

  Handles ability crafting requests from clients, validates, and processes new ability creation. conn, msg, channel: See above.

• public void OnServerDungeonFinderBroadcastReceived(NetworkConnection conn, DungeonFinderBroadcast msg, Channel channel)

  Handles dungeon finder requests, validates, and manages instance assignment for dungeon entrances. conn, msg, channel: See above.

• public bool CheckCharacterPartyInstance(NpgsqlDbContext dbContext, IPlayerCharacter character)

  Checks if any party member of a character has a valid dungeon instance. dbContext (NpgsqlDbContext): Database context. character (IPlayerCharacter): The player character. Returns: bool - True if a party member has an instance, false otherwise.

• public Ability LearnAbility(IAbilityController abilityController, AbilityTemplate abilityTemplate, List abilityEvents)

  Creates and learns a new ability for a character, persists it, and returns the new ability. abilityController (IAbilityController): The ability controller. abilityTemplate (AbilityTemplate): The ability template. abilityEvents (List): List of event IDs. Returns: Ability - The newly learned ability, or null if failed.

• private bool ValidateSceneObject(long sceneObjectID, int characterSceneHandle, out ISceneObject sceneObject)

  Validates that a scene object exists and matches the character's scene handle. sceneObjectID (long): The scene object ID. characterSceneHandle (int): The character's scene handle. sceneObject (out ISceneObject): The validated scene object. Returns: bool - True if valid, false otherwise.

1. Requires the server to be running and all interactable handler initializers registered before world scene startup.
2. Register custom interactable handlers using RegisterHandler and initializers using RegisterHandlerInitializer before calling InitializeHandlers.
3. CurrencyTemplate and MaxAbilityCount should be configured in the server's configuration or via dependency injection.
4. The system is initialized automatically as part of the world scene server startup.

// Example 1: Registering a custom interactable handler
InteractableSystem.RegisterHandler(typeof(MyCustomInteractable), new MyCustomInteractableHandler());

// Example 2: Handling a merchant purchase broadcast (server-side)
// This is handled automatically by the system when a MerchantPurchaseBroadcast is received from a client.
// No manual invocation is required unless extending or customizing the logic.

• Always register all interactable handlers and initializers before initializing the system.
• Validate all client input and scene object references to prevent exploits or errors.
• Use dependency injection or configuration files to manage currency templates and ability limits.
• Extend the system by implementing new IInteractableHandler and registering them for new interactable types.
• Avoid direct manipulation of static handler dictionaries outside of the provided registration methods.