mud_server.db.characters_repo

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

resolve_character_name(name, *, world_id)	Return a world-scoped character name for an exact character identity.
create_character_for_user(user_id, name, *[, ...])	Create a character for an existing account.
character_exists(name)	Return True when a character with this name exists in any world.
get_character_by_name(name)	Return a character row by name, or None when missing.
get_character_by_name_in_world(name, world_id)	Return a character row by name scoped to a specific world, or None when missing.
get_character_by_id(character_id)	Return a character row by id, or None when missing.
get_character_name_by_id(character_id)	Return the character name for an id, or None when missing.
get_user_characters(user_id, *, world_id)	Return ordered character rows owned by a user in one explicit world.
tombstone_character(character_id)	Soft-delete a character by unlinking owner and renaming tombstone row.
delete_character(character_id)	Permanently delete a character row and return whether one row changed.
get_character_room(name, *, world_id)	Return the character's current room in the requested world.
set_character_room(name, room, *, world_id)	Set the character room for a world-scoped character identity.
get_characters_in_room(room, *, world_id)	Return active character names in a room for the selected world.
get_character_inventory(name, *, world_id)	Return character inventory as a JSON-decoded list for an explicit world.
set_character_inventory(name, inventory, *, world_id)	Persist character inventory as JSON for a world-scoped character identity.

Module Contents

mud_server.db.characters_repo.resolve_character_name(name, *, world_id)

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

mud_server.db.characters_repo.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.

mud_server.db.characters_repo.character_exists(name)

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

mud_server.db.characters_repo.get_character_by_name(name)

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

mud_server.db.characters_repo.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.

Parameters:

• name (str) – Character name to search for.

• world_id (str) – World that the character must belong to.

Returns:

Character dict if a match is found, None otherwise.

Return type:

dict[str, Any] | None

mud_server.db.characters_repo.get_character_by_id(character_id)

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

mud_server.db.characters_repo.get_character_name_by_id(character_id)

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

mud_server.db.characters_repo.get_user_characters(user_id, *, world_id)

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

mud_server.db.characters_repo.tombstone_character(character_id)

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

mud_server.db.characters_repo.delete_character(character_id)

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

mud_server.db.characters_repo.get_character_room(name, *, world_id)

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

mud_server.db.characters_repo.set_character_room(name, room, *, world_id)

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

mud_server.db.characters_repo.get_characters_in_room(room, *, world_id)

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

mud_server.db.characters_repo.get_character_inventory(name, *, world_id)

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

mud_server.db.characters_repo.set_character_inventory(name, inventory, *, world_id)

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