-spec create_world(binary()) -> {ok, pid(), map()} | {error, term()}.

Create a new world for the given mode (no owner — anonymous create).

-spec create_world(binary(), binary() | undefined) -> {ok, pid(), map()} | {error, term()}.

Create a new world for the given mode and tag the player as owner.

Refuses with {error, world_capacity_reached} when the global cap (asobi:world_max, default 1000) is hit, and {error, player_world_limit_reached} when the player is already at the per-player cap (asobi:world_max_per_player, default 5). The cap is enforced via a pg group joined on creation so it naturally clears when the world process dies.

-spec find_or_create(binary()) -> {ok, pid(), map()} | {error, term()}.

Find a running world with capacity for the given mode, or create one.

Calls go through asobi_world_lobby_server to serialize concurrent requests. The naive list-then-create sequence has a TOCTOU race: two callers both see list_worlds = [], both call create_world, and both clients end up in different worlds despite asking for the same mode. Serializing closes the window.

-spec find_or_create_unsafe(binary()) -> {ok, pid(), map()} | {error, term()}.

The non-serialized implementation. Only asobi_world_lobby_server should call this — direct callers race. Exposed because the serializer holds no state and just delegates back here.

-spec list_worlds() -> [map()].

List all running worlds.

-spec list_worlds(map()) -> [map()].

List running worlds with optional filters: mode, has_capacity.