Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/TaylorZaneKirk/MMO-Project/llms.txt

Use this file to discover all available pages before exploring further.

These messages handle all authoritative inventory and equipment mutations. Every action follows a request→response pattern — the client sends intent, the server decides the outcome, and the client applies only the confirmed result. No inventory or equipment state is modified locally before the server responds.

​
inventory_item_use_request C→S

Sent when the player selects a primary or context-menu action on an inventory item. The server determines whether the item is equippable, consumable, or unsupported, then responds accordingly. 
{
  "type": "inventory_item_use_request",
  "payload": {
    "session_id": "a1b2c3d4-...",
    "character_id": "c9d0e1f2-...",
    "inventory_slot_index": 3,
    "use_action": "primary"
  }
}
​
session_id
string
required
The active session UUID.
​
character_id
string
required
The UUID of the character performing the action.
​
inventory_slot_index
integer
required
Zero-based index of the inventory slot containing the item to use.
​
use_action
string
required
The action identifier. Must be "primary" — only primary-use actions are supported in v1. The server resolves whether the item is equippable or consumable based on the item definition. Any other value returns "unsupported_use_action".

​
inventory_item_use_response S→C

Returned by the server with the authoritative outcome of the use action. Fields beyond use_status, use_action, and inventory_slot_index are populated depending on what the server resolved. 
{
  "type": "inventory_item_use_response",
  "payload": {
    "use_status": "ok",
    "use_action": "primary",
    "inventory_slot_index": 3,
    "item_id": "iron_sword",
    "item_name": "Iron Sword",
    "routed_behavior": "equip",
    "equipment_slot_id": "weapon",
    "unequipped_item_id": null,
    "health_restored": null,
    "chat_message": "You equip the Iron Sword."
  }
}
​
use_status
string
Authoritative outcome. One of:
  • "ok" — the action was applied successfully
  • "missing_inventory_item" — the referenced slot contained no item
  • "unsupported_use_action" — the requested use_action string is not "primary"; only primary-use actions are supported
  • "no_effect" — the item is not equippable and has no other supported use in this slice
  • "unsupported_stack_equip" — equipping a stacked item (stack count ≠ 1) is not supported
  • "missing_skill_requirement" — the character does not meet the skill requirements to equip the item; chat_message describes which requirements are unmet
  • "already_full_health" — consuming food was blocked because the character is already at maximum health
  • "missing_character_stats" — character stat record could not be found during food consumption
​
use_action
string
The action string from the originating request, echoed back for client-side routing.
​
inventory_slot_index
integer
The slot index from the originating request.
​
item_id
string | null
The ID of the item that was acted on. null on slot-empty failures.
​
item_name
string | null
The display name of the item. null on slot-empty failures.
​
routed_behavior
string | null
The server-resolved behavior that was executed, e.g. "equip" or "consume_food". Allows the client to distinguish between action types in the response.
​
equipment_slot_id
string | null
The equipment slot the item was placed into. Populated when routed_behavior is "equip".
​
unequipped_item_id
string | null
The ID of the item that was displaced from the equipment slot to make room. null if the slot was empty before the equip.
​
health_restored
integer | null
The amount of health restored. Populated when routed_behavior is "consume_food".
​
chat_message
string | null
An optional chat-panel message describing what happened, e.g. "You eat the bread and restore 10 health.". null if no message is warranted.

​
inventory_item_drop_request C→S

Sent when the player chooses to drop an inventory item onto the current tile. The server places the item in the world as a ground item and returns the result. 
{
  "type": "inventory_item_drop_request",
  "payload": {
    "session_id": "a1b2c3d4-...",
    "character_id": "c9d0e1f2-...",
    "inventory_slot_index": 5
  }
}
​
session_id
string
required
The active session UUID.
​
character_id
string
required
The UUID of the character dropping the item.
​
inventory_slot_index
integer
required
Zero-based index of the slot containing the item to drop.

​
inventory_item_drop_response S→C

Returned after the server processes a drop request. On success, the item has been removed from inventory and placed as a ground item at the character’s current tile. 
{
  "type": "inventory_item_drop_response",
  "payload": {
    "drop_status": "ok",
    "inventory_slot_index": 5,
    "ground_item_id": "gi_0001",
    "item_id": "bread",
    "item_name": "Bread",
    "map_id": "x1000y992",
    "tile_x": 15,
    "tile_y": 9,
    "stack_count": 1,
    "chat_message": "You drop the Bread."
  }
}
​
drop_status
string
Authoritative outcome. One of:
  • "ok" — item dropped; ground item fields are populated
  • "missing_inventory_item" — the referenced slot contained no item
  • "missing_presence" — the character is not currently in the world and has no map position to drop to
​
inventory_slot_index
integer
The slot index from the originating request.
​
ground_item_id
string | null
The server-assigned ID of the new ground item. Populated on "ok".
​
item_id
string | null
The ID of the dropped item. Populated on "ok".
​
item_name
string | null
Display name of the dropped item. Populated on "ok".
​
map_id
string | null
The map where the ground item was placed. Populated on "ok".
​
tile_x
integer | null
Tile X of the dropped item. Populated on "ok".
​
tile_y
integer | null
Tile Y of the dropped item. Populated on "ok".
​
stack_count
integer | null
Stack size of the dropped ground item. Populated on "ok".
​
chat_message
string | null
Optional chat-panel message. null if no message is warranted.

​
ground_item_pickup_request C→S

Sent when the player attempts to pick up a visible ground item. The character must be standing on the same tile as the item. 
{
  "type": "ground_item_pickup_request",
  "payload": {
    "session_id": "a1b2c3d4-...",
    "character_id": "c9d0e1f2-...",
    "ground_item_id": "gi_0001"
  }
}
​
session_id
string
required
The active session UUID.
​
character_id
string
required
The UUID of the character attempting the pickup.
​
ground_item_id
string
required
The ID of the ground item to pick up, as received from world_snapshot or ground_item_spawned.

​
ground_item_pickup_response S→C

Returned after the server evaluates the pickup request. On success, the item has been moved from the world into the character’s inventory. 
{
  "type": "ground_item_pickup_response",
  "payload": {
    "pickup_status": "ok",
    "ground_item_id": "gi_0001",
    "item_id": "bread",
    "item_name": "Bread",
    "inventory_slot_index": 5,
    "stack_count": 1,
    "chat_message": "You pick up the Bread."
  }
}
​
pickup_status
string
Authoritative outcome. One of:
  • "ok" — item picked up; inventory fields are populated
  • "missing_ground_item" — no ground item with the given ID was found
  • "not_visible" — the item exists but is not yet visible to this character (private visibility window still active)
  • "not_at_item_tile" — the character is not standing on the tile where the item is located
  • "inventory_full" — pickup was blocked because the character’s inventory has no free slots
​
ground_item_id
string
The ID of the ground item that was the subject of the request.
​
item_id
string | null
The ID of the item added to inventory. Populated on "ok".
​
item_name
string | null
Display name of the picked-up item. Populated on "ok".
​
inventory_slot_index
integer | null
The inventory slot the item landed in. Populated on "ok".
​
stack_count
integer | null
The stack size added to inventory. Populated on "ok".
​
chat_message
string | null
Optional chat-panel message. null if no message is warranted.

​
equipment_item_unequip_request C→S

Sent when the player removes an item from an equipment slot back to inventory. 
{
  "type": "equipment_item_unequip_request",
  "payload": {
    "session_id": "a1b2c3d4-...",
    "character_id": "c9d0e1f2-...",
    "equipment_slot_id": "weapon"
  }
}
​
session_id
string
required
The active session UUID.
​
character_id
string
required
The UUID of the character unequipping the item.
​
equipment_slot_id
string
required
The slot to unequip from, e.g. "weapon", "head", "chest".

​
equipment_item_unequip_response S→C

Returned after the server evaluates the unequip request. On success, the item has been moved from the equipment slot into inventory. 
{
  "type": "equipment_item_unequip_response",
  "payload": {
    "unequip_status": "ok",
    "equipment_slot_id": "weapon",
    "item_id": "iron_sword",
    "inventory_slot_index": 3
  }
}
​
unequip_status
string
Authoritative outcome. One of:
  • "ok" — item moved to inventory; item_id and inventory_slot_index are populated
  • "missing_equipment_item" — the specified equipment slot contained no item
  • "inventory_full" — unequip was blocked because inventory has no free slot
​
equipment_slot_id
string
The equipment slot that was the subject of the request.
​
item_id
string | null
The ID of the item that was unequipped. Populated on "ok".
​
inventory_slot_index
integer | null
The inventory slot the item was placed into. Populated on "ok".
After any successful inventory or equipment mutation, delta clients receive a character_state_updated message containing only the changed streams. Legacy clients (those that did not send runtime_delta_protocol: 1 on login) receive a full world_snapshot instead. See Delta Runtime for details.

Build docs developers (and LLMs) love

Get started for freeTalk to us