mud_server.services.character_provisioning

Shared character provisioning service used by admin and player APIs.

Why this module exists:

The codebase previously duplicated character creation logic across route handlers. This service centralizes deterministic name generation, DB create retries, and optional entity-state seeding so every caller follows one canonical behavior.

Attributes

logger

Classes

CharacterProvisioningResult

Result payload for generated-character provisioning.

Functions

generate_provisioning_seed()	Generate a replayable, non-zero seed for provisioning flows.
fetch_generated_full_name(seed)	Generate a deterministic first last character name for provisioning.
fetch_entity_state_for_seed(seed, *[, world_id])	Fetch an optional entity-state payload for a provisioning seed.
get_world_slot_capacity(user_id, world_id)	Return (current_count, slot_limit) for account ownership in one world.
provision_generated_character_for_user(*, user_id, ...)	Create a generated-name character with optional entity-state axis seeding.

Module Contents

mud_server.services.character_provisioning.logger

class mud_server.services.character_provisioning.CharacterProvisioningResult

Result payload for generated-character provisioning.

success

True when provisioning completed and DB rows were persisted.

reason

Stable reason key for caller-level error mapping.

message

Human-readable status message.

character_id

Created character id when successful.

character_name

Created character name when successful.

world_id

Target world id for the created character.

seed

Deterministic provisioning seed used for name/entity generation.

entity_state

Raw entity payload when fetched successfully.

entity_state_error

Non-fatal warning when entity seeding fails.

success: bool

reason: str

message: str

character_id: int | None = None

character_name: str | None = None

world_id: str | None = None

seed: int | None = None

entity_state: dict[str, Any] | None = None

entity_state_error: str | None = None

mud_server.services.character_provisioning.generate_provisioning_seed()

Generate a replayable, non-zero seed for provisioning flows.

We intentionally use secrets.randbelow rather than module-global RNG state to avoid coupling name/entity generation to gameplay randomness.

mud_server.services.character_provisioning.fetch_generated_full_name(seed)

Generate a deterministic first last character name for provisioning.

The same base seed is used for both lookups with an offset for the surname so retry attempts remain deterministic across deployments.

mud_server.services.character_provisioning.fetch_entity_state_for_seed(seed, *, world_id=None)

Fetch an optional entity-state payload for a provisioning seed.

Entity-state integration is non-fatal: character creation continues even if the upstream call fails.

mud_server.services.character_provisioning.get_world_slot_capacity(user_id, world_id)

Return (current_count, slot_limit) for account ownership in one world.

mud_server.services.character_provisioning.provision_generated_character_for_user(*, user_id, world_id, max_attempts=8)

Create a generated-name character with optional entity-state axis seeding.

The flow is intentionally deterministic per retry sequence:

1. Resolve slot capacity early and fail fast if world budget is full.

2. Generate first last names from deterministic seeds.

3. Retry on unique-name collisions.

4. Apply optional entity-state deltas as a non-fatal post-step.