API Reference asobi v#0.72.6

In-memory cache for access-token → player resolution.

Issues and revokes player auth tokens on top of nova_auth_refresh.

Pre-request plugin that caps HTTP request body size.

Generic bot process that runs a Lua AI script each tick.

Watches the matchmaker queue and fills with bots when players are waiting. Also starts bot AI processes when bots join matches.

Authorisation policy for chat channels.

Pluggable pre-auth "is this traffic allowed in" seam on the anonymous auth-create routes (asobi#158). Distinct from asobi_auth_plugin ("who is the player"): a gate carries no player identity, and the narrow return type makes identity leakage structurally impossible. An implementation runs before the password KDF (asobi#157), so a denial never pays the pbkdf2 cost.

The operator console bundle: what priv/console holds, resolved once.

HTTP surface of the operator console: the shell, its assets, and the session the browser exchanges the operator secret for.

The console's Content-Security-Policy, and the nonce it is built around.

Turns the console on from the environment, for deployments that run a release rather than write a sys.config.

Browser sessions for the operator console: an opaque cookie, and a CSRF token derived from it.

The console's shell document, rendered by Erlang.

Shared enumeration for the discovery surfaces.

The one error object.

The extension contract.

One extension's processes, with their own restart budget.

Runs every installed extension's erase path for one player.

The names core keeps for itself.

One supervisor per extension, under one supervisor for the lot.

Says which extension went dark.

The extension registry: a pure memoised function, not a process.

The core-owned write path for game config a loader declares.

Dispatch to a game module's join callback, preferring the context-carrying join/3 when the module exports it.

Game-mode configuration, and the registry that maps a mode kind to the module that provides it.

UUIDv7 generation for Asobi entities.

Bounds on the client-supplied join context.

Size-bound checks for values headed into an unbounded jsonb column.

Board-set reads: which boards exist, and one page of a board.

Installs the game.* Lua API into a Luerl state, giving Lua scripts access to engine features like economy, leaderboards, notifications, storage, messaging, spatial queries, and zone spawning.

Loads game configuration from Lua files in the game directory.

Keeps the game-mode registry (game_modes) in sync with its Lua source.

Dev-mode surfacing of Lua callback errors to the triggering client.

Reads a Lua-runtime setting from the application environment.

Emits the public [asobi, error] game-error telemetry for a failed Lua callback, and provides the bounded error-rendering helpers shared by the log and dev-error paths.

Loads Lua scripts into a hardened Luerl state.

An asobi_match implementation that delegates all callbacks to Lua scripts via Luerl.

Variant of asobi_lua_match for matches where every player sees the same world state. The match server calls get_state/1 once per tick and encodes the result once for the whole roster, instead of re-encoding once per player. asobi_presence:send_match_state/3 then hands each connected session that one binary and each bot the payload behind it as a term.

Shared phase-list decoding for the Lua match and world bridges.

Shared hot-reload primitive for Lua-backed match and world states.

Owns the vocabulary of the game.* Lua API surface.

Validates a Lua file against the asobi_lua loader without starting the runtime — load it through asobi_lua_loader:new/1 so syntax errors, sandbox violations, and require/1 traversal attempts surface as a non-zero exit. Designed for CI use.

An asobi_world implementation that delegates all callbacks to Lua scripts via Luerl.

The behaviour a game developer implements to define server-authoritative game logic. Each game mode is a module that implements this behaviour; Asobi runs one process per match and invokes these callbacks at the right moments in the match lifecycle.

Discovery for live matches.

Per-match gen_statem driving the configured game module.

The matchmaking queue. Players submit tickets with a mode and property constraints (add/2); a pluggable strategy groups compatible tickets, spawns a match, and pushes match.matched to each player. A single gen_server owns the queue and ticks it on an interval.

Behaviour for matchmaking strategies.

Delivery of notifications to players.

Core-wrapped audit for ops-plane mutations (ADR 0007).

The durable ops audit row: who acted, what they did, what to, and how it ended.

Ops-plane identity: one actor per request, one membership check (ADR 0007).

Capability classes for the ops plane, and the table that tags every route with exactly one of them (ADR 0007).

Chat reads for the ops plane: the live channel list, and one channel's messages.

HTTP surface of the ops plane: every read, plus the two account-lifecycle routes.

Economy reads for the ops plane: the item catalogue, and the store listings.

The ops plane's one extension seam: /api/v1/ops/ext/:extension/:action.

The installed feature set, as the ops read plane reports it.

The WHERE clauses an ops list endpoint builds from its query string.

Leaderboard reads for the ops plane: the board list, and one board's entries.

Fetch one row by primary key for the ops read plane.

Match-record list for the ops read plane: filter, search, sort, paginate.

The matchmaking queue for the ops plane: one row per mode.

The notifications screen: the sent-notification list, and the operator-attributed broadcast.

The one list envelope every ops read endpoint returns.

Request-input parsing for the ops read plane: query string, and the id in a bound path segment.

Player list for the ops read plane: filter, search, sort, paginate.

Live runtime stats for the operator console's dashboard.

The minted, env-scoped ops token: how a managed tenant's browser reaches this environment's ops plane.

Tournament reads for the ops plane: the list, and one tournament.

Client-IP extraction shared across HTTP and WebSocket entry points, used as the rate-limiter key.

Delete one player and everything core holds about them, in one transaction.

Everything core holds about one player, as one map.

Who is reachable, and who counts as online.

Query-string parsing helpers shared across controllers.

Whether the node is ready to serve extension traffic.

Backstop on world zone-crossing re-homes (asobi#248): bounds how often a single player's world.input can force a full interest-ring update, on top of the hysteresis margin in asobi_zone's past_zone_margin/4 (private, which only filters jitter - an attacker moving with amplitude past the margin crosses every tick regardless, so this is the actual adversarial control).

The extension RPC dispatcher: rpc.call in, rpc.ok or rpc.error out.

Bounds the rate of log lines emitted from per-tick, script-driven error paths - a game script that fails on every tick (a typo'd spawn template, a Lua callback that always raises) would otherwise log once per tick forever (asobi#252). Telemetry counters are unaffected: asobi_telemetry:game_error/2 is cheap to aggregate at any volume and callers should keep emitting it unconditionally so dashboards/alerts see the true failure rate. Only the disk/log-aggregator cost of the structured log line itself is bounded here.

Spatial query primitives over zone entities: radius and rectangle queries, nearest-neighbour, range and distance helpers. Pure functional - no process, no state - operating on entity maps, so asobi_zone and game code can call it directly.

Pure functional terrain chunk encoding and compression.

Behaviour for terrain data providers.

Kura schema for persisted vote results.

REST controller for vote history queries.

Vote lifecycle state machine.

Dynamic supervisor for asobi_vote_server processes.

Behaviour for large-session world game modules.

Single point of serialization for asobi_world_lobby:find_or_create/1.

A persistent, zoned world: the gen_statem behind large session games (game_type = "world"). It partitions space into a grid of asobi_zone processes, moves players between zones as they travel, runs a world-level post_tick, and drives voting. Use it for MMO-style shared spaces; for transient matches use asobi_match_server instead.

Top-level world supervisor.

One spatial partition of an asobi_world_server. A gen_server that owns the entities in its cell of the grid, ticks their simulation, applies player input, manages interest (subscribers), and answers spatial queries via asobi_spatial. Zones are created and reaped lazily as players move.

Shared square-ring helper for asobi_world_server's interest zones and asobi_world_chat's proximity zones - both computed the exact same bounded neighbourhood of grid coordinates around a centre, previously duplicated verbatim in both modules. See widgrensit/asobi#248.

Lazy zone lifecycle manager for the world server.

rebar3 asobi check - the primary validation gate for an extension set.