asobi_match_lobby (asobi v0.84.0)

Discovery for live matches.

GET /api/v1/matches reads the asobi_match_record table: finished matches, an audit trail, nothing a player can join. This module enumerates the running asobi_match_server processes instead, which is what a client choosing a match actually needs.

Matches are unlisted by default. A match spawned by the matchmaker is already assigned to its players and has no reason to appear in a browser, so a mode opts in with listed = true (a Lua global, or listed => true in the operator's game_modes config). This is the inverse of worlds, which default to listed because their browser already shipped.

Summary

Functions

list_matches()

List live matches. Unfiltered - callers that serve clients want list_matches/1.

list_matches(Filters)

List live matches with optional filters: mode, has_capacity, listed, joinable.

list_matches_cached(Filters)

Cached list_matches/1 for request paths, mirroring asobi_world_lobby:list_worlds_cached/1.

Functions

list_matches()

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

List live matches. Unfiltered - callers that serve clients want list_matches/1.

list_matches(Filters)

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

List live matches with optional filters: mode, has_capacity, listed, joinable.

Only waiting and running matches are returned; a finished match is history and a paused one cannot be joined.

has_capacity and joinable are separate questions and both have to be asked to find a match that will actually take a player: a match with room can still have closed itself to new joins, and a full match is not locked - it may free a slot on the next leave.

list_matches_cached(Filters)

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

Cached list_matches/1 for request paths, mirroring asobi_world_lobby:list_worlds_cached/1.

Each uncached call issues one gen_statem:call per live match. That cost is paid even when every match is unlisted and the result is empty, so a flood of match.list messages would stall every match's mailbox. Keyed on has_capacity and joinable only - both are bounded, so the table stays small, while mode is client-controlled and unbounded and keying on it would miss on every request and grow the table without bound.