mud_server.admin_gradio.api.game

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

GameAPIClient

API client for game operations.

Module Contents

class mud_server.admin_gradio.api.game.GameAPIClient(server_url=None)[source]

Bases: mud_server.admin_gradio.api.base.BaseAPIClient

API client for game operations.

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

Example

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

Initialize the base API client.

Parameters:: server_url (str | None) – Optional server URL override. If not provided, uses MUD_SERVER_URL environment variable or defaults to http://localhost:8000

send_command(command, session_id)[source]

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

Parameters:

command (str) – Command string to execute
session_id (str | None) – User’s session ID from login

Returns:

{: “success”: bool, “message”: str, # Command result/output “data”: None, “error”: str | None,

}

Return type:

Dictionary with structure

Examples

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

get_chat(session_id)[source]

Retrieve recent chat messages from the current room.

Parameters:

session_id (str | None) – User’s session ID from login

Returns:

{: “success”: bool, “message”: str, # Formatted chat messages “data”: None, “error”: str | None,

}

Return type:

Dictionary with structure

Examples

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

get_status(session_id, username, role)[source]

Retrieve and format player status information.

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

Parameters:

session_id (str | None) – User’s session ID from login
username (str) – User’s username
role (str) – User’s role (player/worldbuilder/admin/superuser)

Returns:

{: “success”: bool, “message”: str, # Formatted status display “data”: None, “error”: str | None,

}

Return type:

Dictionary with structure

Examples

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

refresh_display(session_id)[source]

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.

Parameters:

session_id (str | None) – 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,

}

Return type:

Dictionary with structure

Examples

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