CharacterInventorySystem - jimdroberts/FishMMO GitHub Wiki

Description

The CharacterInventorySystem is a server-side system in FishMMO responsible for managing all player inventory, equipment, and bank actions. It registers and handles network broadcasts for item removal, slot swapping, equipping, and unequipping, ensuring all actions are validated, persisted to the database, and synchronized with the client. The system also manages the logic for moving items between inventory, equipment, and bank containers, and validates interactions with banker NPCs.

API Access

Methods

  • public override void InitializeOnce()

    Initializes the character inventory system, registering broadcast handlers for inventory, equipment, and bank actions.

  • public override void Destroying()

    Cleans up the character inventory system, unregistering broadcast handlers for inventory, equipment, and bank actions.

  • public bool SwapContainerItems(NpgsqlDbContext dbContext, long characterID, IItemContainer container, int fromIndex, int toIndex, Action<NpgsqlDbContext, long, Item> onDatabaseUpdateSlot)

    Swaps two items within the same container and updates the database slots. dbContext (NpgsqlDbContext): Database context for updates. characterID (long): ID of the character owning the container. container (IItemContainer): Item container to swap items in. fromIndex (int): Source slot index. toIndex (int): Target slot index. onDatabaseUpdateSlot (Action): Callback to update database slot for each item. Returns: bool - True if swap succeeded, false otherwise.

  • public bool SwapContainerItems(NpgsqlDbContext dbContext, long characterID, IItemContainer from, IItemContainer to, int fromIndex, int toIndex, Action<NpgsqlDbContext, long, Item> onDatabaseSetOldSlot = null, Action<NpgsqlDbContext, long, long> onDatabaseDeleteOldSlot = null, Action<NpgsqlDbContext, long, Item> onDatabaseSetNewSlot = null)

    Swaps items between two containers and updates the database slots as needed. dbContext (NpgsqlDbContext): Database context for updates. characterID (long): ID of the character owning the containers. from (IItemContainer): Source item container. to (IItemContainer): Target item container. fromIndex (int): Source slot index. toIndex (int): Target slot index. onDatabaseSetOldSlot, onDatabaseDeleteOldSlot, onDatabaseSetNewSlot (Action): Callbacks for database updates. Returns: bool - True if swap succeeded, false otherwise.

  • private void OnServerInventoryRemoveItemBroadcastReceived(NetworkConnection conn, InventoryRemoveItemBroadcast msg, Channel channel)

    Handles broadcast to remove an item from the player's inventory, updates the database and notifies the client. conn (NetworkConnection): Network connection of the client. msg (InventoryRemoveItemBroadcast): Broadcast message. channel (Channel): Network channel used for the broadcast.

  • private void OnServerInventorySwapItemSlotsBroadcastReceived(NetworkConnection conn, InventorySwapItemSlotsBroadcast msg, Channel channel)

    Handles broadcast to swap item slots in the player's inventory or bank, updates the database and notifies the client. conn (NetworkConnection): Network connection of the client. msg (InventorySwapItemSlotsBroadcast): Broadcast message. channel (Channel): Network channel used for the broadcast.

  • private void OnServerEquipmentEquipItemBroadcastReceived(NetworkConnection conn, EquipmentEquipItemBroadcast msg, Channel channel)

    Handles broadcast to equip an item from inventory or bank, updates the database and notifies the client. conn (NetworkConnection): Network connection of the client. msg (EquipmentEquipItemBroadcast): Broadcast message. channel (Channel): Network channel used for the broadcast.

  • private void OnServerEquipmentUnequipItemBroadcastReceived(NetworkConnection conn, EquipmentUnequipItemBroadcast msg, Channel channel)

    Handles broadcast to unequip an item to inventory or bank, updates the database and notifies the client. conn (NetworkConnection): Network connection of the client. msg (EquipmentUnequipItemBroadcast): Broadcast message. channel (Channel): Network channel used for the broadcast.

  • private void OnServerBankRemoveItemBroadcastReceived(NetworkConnection conn, BankRemoveItemBroadcast msg, Channel channel)

    Handles broadcast to remove an item from the player's bank, updates the database and notifies the client. conn (NetworkConnection): Network connection of the client. msg (BankRemoveItemBroadcast): Broadcast message. channel (Channel): Network channel used for the broadcast.

  • private void OnServerBankSwapItemSlotsBroadcastReceived(NetworkConnection conn, BankSwapItemSlotsBroadcast msg, Channel channel)

    Handles broadcast to swap item slots in the player's bank, updates the database and notifies the client. conn (NetworkConnection): Network connection of the client. msg (BankSwapItemSlotsBroadcast): Broadcast message. channel (Channel): Network channel used for the broadcast.

  • private bool ValidateBankerSceneObject(long sceneObjectID, IPlayerCharacter character)

    Validates that the banker scene object is present, in the correct scene, and the character is in range. sceneObjectID (long): ID of the scene object to validate. character (IPlayerCharacter): Player character interacting with the banker. Returns: bool - True if validation succeeds, false otherwise.

Basic Usage

Setup

  1. Requires the server to be running and the inventory system to be initialized as part of the server startup.
  2. All item containers (inventory, equipment, bank) must implement the appropriate interfaces and be registered with the character.
  3. The system automatically registers broadcast handlers for all supported inventory, equipment, and bank actions.
  4. No manual registration is required unless extending or customizing inventory logic.

Example

// Example 1: Swapping two items in the player's inventory
characterInventorySystem.SwapContainerItems(dbContext, character.ID, inventoryController, 0, 1, (db, id, item) => {
    CharacterInventoryService.Update(db, id, item);
});

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

Best Practices

  • Always validate all item movements and container interactions to prevent exploits or errors.
  • Use database transactions to ensure atomicity of inventory, equipment, and bank operations.
  • Extend the system by implementing new item container types or broadcast handlers as needed.
  • Avoid direct manipulation of inventory data outside of the provided interfaces and system methods.
  • Ensure all banker interactions are validated for scene and range before allowing bank actions.
⚠️ **GitHub.com Fallback** ⚠️