mud_server.admin_gradio.api.game
================================

.. py:module:: mud_server.admin_gradio.api.game

.. autoapi-nested-parse::

   Game API client for MUD Server.

   This module handles all game-related API operations:
   - Sending game commands (movement, inventory, chat, etc.)
   - Retrieving chat messages from current room
   - Fetching player status (location, inventory, active players)
   - Refreshing game displays

   All functions follow a consistent pattern:
       - Validate session state
       - Validate input
       - Make API request using BaseAPIClient
       - Return standardized response dictionaries

   Response Format:
       All functions return dictionaries with:
       {
           "success": bool,         # Whether operation succeeded
           "message": str,          # User-facing message or data
           "data": dict | None,     # Additional structured data if applicable
           "error": str | None,     # Error details if failed
       }



Classes
-------

.. autoapisummary::

   mud_server.admin_gradio.api.game.GameAPIClient


Module Contents
---------------

.. py:class:: GameAPIClient(server_url = None)

   Bases: :py:obj:`mud_server.admin_gradio.api.base.BaseAPIClient`


   API client for game operations.

   This client handles in-game interactions including commands, chat,
   and status queries.

   .. admonition:: Example

      >>> client = GameAPIClient()
      >>> result = client.send_command("look", session_id="abc123")
      >>> if result["success"]:
      ...     print(result["message"])

   Initialize the base API client.

   :param server_url: Optional server URL override. If not provided,
                      uses MUD_SERVER_URL environment variable or defaults
                      to http://localhost:8000


   .. py:method:: send_command(command, session_id)

      Send a game command to the backend for execution.

      Commands can be:
      - Movement: north, south, east, west, n, s, e, w
      - Inventory: take <item>, drop <item>, inventory, i
      - Chat: say <message>
      - Information: look, status, help

      :param command: Command string to execute
      :param session_id: User's session ID from login

      :returns:

                {
                    "success": bool,
                    "message": str,          # Command result/output
                    "data": None,
                    "error": str | None,
                }
      :rtype: Dictionary with structure

      .. admonition:: Examples

         >>> client = GameAPIClient()
         >>> result = client.send_command("look", session_id="abc123")
         >>> result["success"]
         True
         >>> "You are in" in result["message"]
         True



   .. py:method:: get_chat(session_id)

      Retrieve recent chat messages from the current room.

      :param session_id: User's session ID from login

      :returns:

                {
                    "success": bool,
                    "message": str,          # Formatted chat messages
                    "data": None,
                    "error": str | None,
                }
      :rtype: Dictionary with structure

      .. admonition:: Examples

         >>> client = GameAPIClient()
         >>> result = client.get_chat(session_id="abc123")
         >>> result["success"]
         True



   .. py:method:: get_status(session_id, username, role)

      Retrieve and format player status information.

      Returns detailed status including:
      - Username and role
      - Current room location
      - Active players in the game
      - Inventory contents

      :param session_id: User's session ID from login
      :param username: User's username
      :param role: User's role (player/worldbuilder/admin/superuser)

      :returns:

                {
                    "success": bool,
                    "message": str,          # Formatted status display
                    "data": None,
                    "error": str | None,
                }
      :rtype: Dictionary with structure

      .. admonition:: Examples

         >>> client = GameAPIClient()
         >>> result = client.get_status("abc123", "alice", "player")
         >>> result["success"]
         True
         >>> "Player Status" in result["message"]
         True



   .. py:method:: refresh_display(session_id)

      Refresh both room and chat displays by fetching current data.

      This is a convenience method that calls both send_command("look")
      and get_chat() to refresh the game display.

      :param session_id: User's session ID from login

      :returns:

                {
                    "success": bool,
                    "message": str,          # Not used for this method
                    "data": {
                        "room": str,         # Room description
                        "chat": str,         # Chat messages
                    },
                    "error": str | None,
                }
      :rtype: Dictionary with structure

      .. admonition:: Examples

         >>> client = GameAPIClient()
         >>> result = client.refresh_display(session_id="abc123")
         >>> result["success"]
         True
         >>> "room" in result["data"]
         True
         >>> "chat" in result["data"]
         True