mud_server.db.characters_repo
=============================

.. py:module:: mud_server.db.characters_repo

.. autoapi-nested-parse::

   Character repository operations for the SQLite backend.

   This module isolates character persistence and room/inventory state operations
   from the compatibility facade in ``mud_server.db.database``.



Functions
---------

.. autoapisummary::

   mud_server.db.characters_repo.resolve_character_name
   mud_server.db.characters_repo.create_character_for_user
   mud_server.db.characters_repo.character_exists
   mud_server.db.characters_repo.get_character_by_name
   mud_server.db.characters_repo.get_character_by_name_in_world
   mud_server.db.characters_repo.get_character_by_id
   mud_server.db.characters_repo.get_character_name_by_id
   mud_server.db.characters_repo.get_user_characters
   mud_server.db.characters_repo.tombstone_character
   mud_server.db.characters_repo.delete_character
   mud_server.db.characters_repo.get_character_room
   mud_server.db.characters_repo.set_character_room
   mud_server.db.characters_repo.get_characters_in_room
   mud_server.db.characters_repo.get_character_inventory
   mud_server.db.characters_repo.set_character_inventory


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

.. py:function:: resolve_character_name(name, *, world_id)

   Return a world-scoped character name for an exact character identity.


.. py:function:: create_character_for_user(user_id, name, *, is_guest_created = False, room_id = 'spawn', world_id, state_seed = None)

   Create a character for an existing account.

   The function enforces world-scoped slot limits and seeds both location and
   axis/snapshot state in the same transaction.


.. py:function:: character_exists(name)

   Return ``True`` when a character with this name exists in any world.


.. py:function:: get_character_by_name(name)

   Return a character row by name, or ``None`` when missing.


.. py:function:: get_character_by_name_in_world(name, world_id)

   Return a character row by name scoped to a specific world, or ``None`` when missing.

   This is the preferred lookup for the translation layer and any system that
   must avoid cross-world name collisions.  Two characters in different worlds
   may share the same name; a bare ``get_character_by_name`` lookup would
   return whichever row the DB engine happens to surface first, which is a
   silent correctness bug in multi-world contexts.

   :param name: Character name to search for.
   :param world_id: World that the character must belong to.

   :returns: Character dict if a match is found, ``None`` otherwise.


.. py:function:: get_character_by_id(character_id)

   Return a character row by id, or ``None`` when missing.


.. py:function:: get_character_name_by_id(character_id)

   Return the character name for an id, or ``None`` when missing.


.. py:function:: get_user_characters(user_id, *, world_id)

   Return ordered character rows owned by a user in one explicit world.


.. py:function:: tombstone_character(character_id)

   Soft-delete a character by unlinking owner and renaming tombstone row.


.. py:function:: delete_character(character_id)

   Permanently delete a character row and return whether one row changed.


.. py:function:: get_character_room(name, *, world_id)

   Return the character's current room in the requested world.


.. py:function:: set_character_room(name, room, *, world_id)

   Set the character room for a world-scoped character identity.


.. py:function:: get_characters_in_room(room, *, world_id)

   Return active character names in a room for the selected world.


.. py:function:: get_character_inventory(name, *, world_id)

   Return character inventory as a JSON-decoded list for an explicit world.


.. py:function:: set_character_inventory(name, inventory, *, world_id)

   Persist character inventory as JSON for a world-scoped character identity.