The extension contract.

An extension is an ordinary OTP application that depends on asobi and is a dependency of the host release, plus one module named <app>_extension implementing this behaviour. asobi never depends on an extension: every extension depends on asobi, so the reverse edge is a cycle relx and Hex both reject.

Most of what an extension provides is discovered rather than declared. Migrations and schemas come from application:get_key(App, modules), shigoto workers need no registration at all, and domain logic is just modules. This behaviour covers only what core cannot infer.

-module(asobi_quests_extension).
-behaviour(asobi_extension).
-export([info/0, rpc/0, lua/0, sup/0, owns/0, codes/0, erase_player/1]).

info() -> #{name => quests, extension_version => 1}.

rpc()  -> #{~"quests.claim" => {asobi_quests_rpc, claim, 2}}.

codes() -> #{~"quests.already_claimed" =>
               #{status => 409, message => ~"This quest was already claimed."}}.

lua()  -> #{~"quests" =>
              #{~"progress" => #{mfa     => {asobi_quests_lua, progress, 2},
                                 args    => [binary, integer],
                                 effects => write,
                                 vms     => [match, world]}}}.

sup()  -> [#{id => asobi_quests_tracker,
             start => {asobi_quests_tracker, start_link, []}}].

owns() -> #{tables => [~"quests"], rpc => [~"quests"],
            lua => [~"quests"], queues => [~"quests"]}.

erase_player(PlayerId) ->
    {ok, _} = asobi_repo:delete_all(by_player(asobi_quest_progress, PlayerId)),
    ok.

Only info/0 is required. rpc/0, lua/0, sup/0, owns/0, codes/0 and erase_player/1 default to nothing, because several are frequently empty: an extension with no processes has no sup/0, and one whose rows cascade needs no erase_player/1.

An extension declaring neither rpc/0 nor lua/0 is reachable by nobody: game logic calls game.<ns>.* from Lua, and clients call asobi.rpc("<ns>.<method>") over the wire. rebar3 asobi check warns about it rather than failing, because it is a legal state mid-development.

The two calling conventions

Both are fixed, and they are written down here because the alternative is a second extension inventing a third shape. asobi_rpc and asobi_lua_api are what call them.

An RPC handler is (Params, Ctx), so the arity in rpc/0 is always 2:

-spec claim(asobi_rpc:params(), asobi_rpc:ctx()) -> asobi_rpc:reply().
claim(#{~"quest_id" := QuestId}, #{player_id := PlayerId}) ->
    case asobi_quests:claim(PlayerId, QuestId) of
        {ok, Reward}          -> {ok, #{reward => Reward}};
        {error, already_done} -> {error, ~"quests.already_claimed"}
    end.

{ok, map()} | {error, Code} | {error, Code, Details}. The failure half is a code, never a status: the status and the whole error object are derived from it (asobi_error:status/1, asobi_error:object/2), and a code you declared in codes/0 surfaces as itself rather than as internal. Ctx is #{player_id, session, method} and may gain keys; match what you need.

A Lua binding takes the declared arguments positionally, already decoded to the types args names, and returns the same envelope every persistence-style game.* call returns:

-spec progress(binary(), integer()) -> {ok, term()} | {error, binary()}.
progress(PlayerId, Amount) ->
    case asobi_quests:progress(PlayerId, Amount) of
        {ok, Count} -> {ok, Count};
        {error, _}  -> {error, ~"progress failed"}
    end.

Lua reads result.ok or result.error. A binding that raises, or returns anything else, becomes { error = "..." } and one logged line naming the function - a game developer must never see a silent nil.

sup/0 exists so an extension can be a library application, with no mod in its .app.src. Applications in a release are permanent by default and a permanent application terminating takes the whole runtime with it, so an extension supervising itself can kill the node. See asobi_extension_sup.

Two guarantees a sup/0 child may rely on, so no extension has to reinvent a retry path around them:

• Children start in the order sup/0 returns them, and one extension's children start after every extension its application depends on. That is OTP's own child order and asobi_extensions:resolve/0's dependency order; nothing sorts either.
• init/1 may query. Extension children start after kura_migrator:migrate/1 has run to completion, so the pool is up and every table - core's and the extension's own - exists. If migrations did not complete, asobi_extension_sup starts no extension at all rather than letting each one crash-loop into its restart budget and go dark with an OTP crash report as the only explanation.

This contract is experimental and deliberately unfrozen. The wire freezes, because SDK users vendor by copying source; this module freezes when a real second consumer has said what it is missing.