asobi_lua_surface (asobi v0.72.5)

View Source

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

Three things live here, and only here:

  • reserved_namespaces/0 - the game.* tables the library owns. asobi_lua_api:install/2 creates exactly this list plus whatever the installed extensions declare in asobi_extension:lua/0, and asobi_lua_api_tests asserts the core half of that. Anything that later has to decide whether a name belongs to the library - validating a game-declared or extension-declared namespace, say - reads the list from here instead of repeating it.
  • effect/0 - what a game.* function does to the world. write means it mutates durable state, fans an event out to players, or moves a resource; none means it only reads or computes. Probe VMs (asobi_lua_api:install/2) suppress every write.
  • vm_kind/0 - the kinds of VM a Lua chunk runs in, and extension_vm_kinds/0, the subset an extension may bind into.

Summary

Types

effect()
namespace()
vm_kind()

Functions

effects()
extension_vm_kinds()

The VM kinds an extension's lua/0 binding may name.

is_reserved(Namespace)
name(Path)

Renders a namespace or function path as its Lua name, e.g. game.economy.grant.

reserved_namespaces()
vm_kinds()

Types

effect()

-type effect() :: write | none.

namespace()

-type namespace() :: [binary(), ...].

vm_kind()

-type vm_kind() :: match | world | zone | bot.

Functions

effects()

-spec effects() -> [effect(), ...].

extension_vm_kinds()

-spec extension_vm_kinds() -> [vm_kind(), ...].

The VM kinds an extension's lua/0 binding may name.

bot is absent, and its absence is enforced rather than documented. A bot script is loaded by asobi_lua_loader:new/1, whose PreInstall is the identity, so it never reaches asobi_lua_api:install/2 and has no game table at all - see guides/lua-bots.md. A binding declaring bot would therefore install nothing, and a declaration that silently does nothing is the failure mode this list exists to prevent: asobi_extensions refuses it at rebar3 asobi check.

Making it work instead was the alternative, and it was rejected. A bot decides from the state the match broadcasts and nothing more, so game.<ns> in a bot VM would be one extension namespace floating in a game table with no game.log, no game.economy and no game.storage under it. A bot also has no players.id - bot_Spark is not a player row - so the one argument every extension binding takes cannot be supplied. The documented route stands: put the value in the state the match broadcasts.

is_reserved(Namespace)

-spec is_reserved(namespace()) -> boolean().

name(Path)

-spec name([binary(), ...]) -> binary().

Renders a namespace or function path as its Lua name, e.g. game.economy.grant.

reserved_namespaces()

-spec reserved_namespaces() -> [namespace()].

vm_kinds()

-spec vm_kinds() -> [vm_kind(), ...].