mud_server.core.events
======================

.. py:module:: mud_server.core.events

.. autoapi-nested-parse::

   Event Type Constants for the MUD Server

   This module defines all standard event types used in the MUD server.
   Using constants instead of string literals provides:

   1. Autocomplete support in IDEs
   2. Typo prevention (undefined constant = error)
   3. Single source of truth for event names
   4. Easy refactoring if event names change

   =============================================================================
   NAMING CONVENTION
   =============================================================================

   Events use "domain:action" format in PAST TENSE:

       Good: "player:moved", "item:picked_up", "chat:sent"
       Bad:  "player:move", "pick_up_item", "send_chat"

   The past tense emphasizes that events record FACTS about what HAPPENED,
   not requests for something to happen.

   Exception: "tick" doesn't use past tense because it's a continuous concept.

   =============================================================================
   USAGE
   =============================================================================

       from mud_server.core.events import Events
       from mud_server.core.bus import bus

       # Emit using constants
       bus.emit(Events.PLAYER_MOVED, {"username": "Gribnak", ...})

       # Subscribe using constants
       bus.on(Events.PLAYER_MOVED, handle_player_move)

   =============================================================================



Classes
-------

.. autoapisummary::

   mud_server.core.events.Events


Functions
---------

.. autoapisummary::

   mud_server.core.events.is_valid_event_type
   mud_server.core.events.get_all_event_types


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

.. py:class:: Events

   All standard event types in the MUD server.

   These are class attributes (not instance attributes) because event
   types are global constants, not per-instance values.

   Organized by domain for easy navigation.


   .. py:attribute:: SERVER_STARTED
      :value: 'server:started'


      Emitted once when the server has finished initialization and is ready
      to accept connections.

      Detail: {}


   .. py:attribute:: SERVER_STOPPING
      :value: 'server:stopping'


      Emitted when the server begins shutdown sequence.

      Detail: {"reason": str}  # Why the server is stopping


   .. py:attribute:: SERVER_STOPPED
      :value: 'server:stopped'


      Emitted after the server has completed shutdown.

      Detail: {}


   .. py:attribute:: TICK
      :value: 'tick'


      Emitted every game tick (typically once per second).
      Drives time-based systems: weather, NPC AI, cooldowns, etc.

      Detail: {
          "delta": float,  # Seconds since last tick (usually 1.0)
          "tick_number": int  # Monotonic tick counter
      }


   .. py:attribute:: PLAYER_CREATED
      :value: 'player:created'


      Emitted when a new player account is created (registration).

      Detail: {
          "username": str,
          "role": str  # "player", "worldbuilder", "admin", "superuser"
      }


   .. py:attribute:: PLAYER_LOGGED_IN
      :value: 'player:logged_in'


      Emitted when a player successfully logs in.

      Detail: {
          "username": str,
          "session_id": str,
          "room": str,  # The room they logged into
          "role": str
      }


   .. py:attribute:: PLAYER_LOGGED_OUT
      :value: 'player:logged_out'


      Emitted when a player logs out (voluntarily or session expired).

      Detail: {
          "username": str,
          "room": str,  # The room they were in
          "reason": str  # "voluntary", "timeout", "kicked"
      }


   .. py:attribute:: PLAYER_MOVED
      :value: 'player:moved'


      Emitted when a player successfully moves to a new room.

      Detail: {
          "username": str,
          "from_room": str,
          "to_room": str,
          "direction": str  # "north", "south", "east", "west"
      }


   .. py:attribute:: PLAYER_MOVE_FAILED
      :value: 'player:move_failed'


      Emitted when a player's movement attempt fails.

      Detail: {
          "username": str,
          "room": str,  # Current room (didn't change)
          "direction": str,  # Attempted direction
          "reason": str  # Why it failed
      }


   .. py:attribute:: ROOM_ENTERED
      :value: 'room:entered'


      Emitted when a player enters a room (from any source).
      Includes login, movement, teleport, etc.

      Detail: {
          "username": str,
          "room": str,
          "source": str  # "login", "movement", "teleport"
      }


   .. py:attribute:: ROOM_EXITED
      :value: 'room:exited'


      Emitted when a player exits a room.

      Detail: {
          "username": str,
          "room": str,
          "destination": str,  # Where they went (or "logout")
          "direction": str | None  # Direction if movement, None otherwise
      }


   .. py:attribute:: ROOM_DESCRIBED
      :value: 'room:described'


      Emitted when a room description is generated (for 'look' command).
      Plugins can react by emitting additional description events.

      Detail: {
          "username": str,  # Who requested the description
          "room": str,
          "description": str  # The base description
      }


   .. py:attribute:: ITEM_PICKED_UP
      :value: 'item:picked_up'


      Emitted when a player picks up an item.

      Detail: {
          "username": str,
          "item_id": str,
          "item_name": str,
          "room": str  # Where they picked it up
      }


   .. py:attribute:: ITEM_PICKUP_FAILED
      :value: 'item:pickup_failed'


      Emitted when a player fails to pick up an item.

      Detail: {
          "username": str,
          "item_name": str,  # What they tried to pick up
          "room": str,
          "reason": str  # Why it failed
      }


   .. py:attribute:: ITEM_DROPPED
      :value: 'item:dropped'


      Emitted when a player drops an item.

      Detail: {
          "username": str,
          "item_id": str,
          "item_name": str,
          "room": str  # Where they dropped it
      }


   .. py:attribute:: ITEM_DROP_FAILED
      :value: 'item:drop_failed'


      Emitted when a player fails to drop an item.

      Detail: {
          "username": str,
          "item_name": str,
          "reason": str
      }


   .. py:attribute:: CHAT_SAID
      :value: 'chat:said'


      Emitted when a player says something in their current room.

      Detail: {
          "username": str,
          "message": str,  # The sanitized message
          "room": str
      }


   .. py:attribute:: CHAT_YELLED
      :value: 'chat:yelled'


      Emitted when a player yells (reaches adjacent rooms).

      Detail: {
          "username": str,
          "message": str,
          "origin_room": str,
          "rooms_reached": list[str]  # All rooms that heard it
      }


   .. py:attribute:: CHAT_WHISPERED
      :value: 'chat:whispered'


      Emitted when a player whispers to another player.

      Detail: {
          "username": str,  # Sender
          "target": str,  # Recipient
          "message": str,
          "room": str
      }


   .. py:attribute:: CHAT_FAILED
      :value: 'chat:failed'


      Emitted when a chat action fails.

      Detail: {
          "username": str,
          "action": str,  # "say", "yell", "whisper"
          "reason": str
      }


   .. py:attribute:: COMMAND_EXECUTED
      :value: 'command:executed'


      Emitted when a command is successfully executed.

      Detail: {
          "username": str,
          "command": str,  # The command name
          "args": list[str],  # Command arguments
          "result": str  # Success message
      }


   .. py:attribute:: COMMAND_FAILED
      :value: 'command:failed'


      Emitted when a command fails.

      Detail: {
          "username": str,
          "command": str,
          "args": list[str],
          "error": str  # Error message
      }


   .. py:attribute:: COMMAND_UNKNOWN
      :value: 'command:unknown'


      Emitted when an unknown command is entered.
      Plugins can listen to this to implement custom commands.

      Detail: {
          "username": str,
          "command": str,
          "args": list[str]
      }


.. py:function:: is_valid_event_type(event_type)

   Check if an event type is a known standard event.

   This doesn't prevent custom events - it just checks if an event
   type is one of the predefined constants.

   :param event_type: The event type string to check

   :returns: True if this is a standard event type, False otherwise


.. py:function:: get_all_event_types()

   Get a list of all standard event types.

   Useful for documentation, debugging, or validation.

   :returns: List of all standard event type strings