Modules and contracts

Last updated on

A module is one gameplay concern in its own folder, modules/<id>/. Modules never reach into each other's files; they talk through contracts — a table of functions one module publishes and others ask for by name. The registry (core/shared/registry.lua) and the lifecycle (core/shared/lifecycle.lua) run all of this.

Declaring a module

modules/<id>/module.lua is a shared_script, so it runs on both sides.

local M = OPX.Modules.Declare{
	id = 'thing',
	side = 'both',                -- 'server', 'client' or 'both'
	fatal = false,                -- true: the resource reports a failed boot if this module fails
	requires = { 'character' },   -- hard dependencies
	optional = { 'downed' },      -- soft dependencies: only change the order
}

• Declare returns the module's own table (M). Its other files get it back with OPX.Modules.Get('<id>') and hang their functions on it.
• The runtime only reads Settings and the four phase functions from M.

API: OPX.Modules.Declare.

Settings

M.Settings is OPX.Config.MODULES[id], the table set by config/<id>.lua.

enabled = false in the config turns the module off: it is marked disabled and its dependants become unavailable.

The lifecycle

Phases run in dependency order (a module runs after everything it requires or lists as optional). A cycle is refused at boot with module dependency cycle: a -> b -> a.

• Between Api and Start the server publishes the tunables and applies the schema, so Start is the first phase that may touch the database.
• Each phase yields one frame (Wait(0)) after each module, resetting the client's instruction budget (Two runtimes).

Module states

/opx.modules (server) and /opx.client (client) print one line per module with its state and reason — see diagnostics.

When a module fails, every contract it already published is withdrawn and its dependants are dropped after the phase.

Contracts

A plain table of functions with a name and a version — the only supported way for one module to use another.

-- modules/thing/server/main.lua
function M.Api()
	OPX.Api.Provide('thing', 1, {
		DoIt = function(source) ... end,
	})
end

-- another module
local thing = OPX.Api.Get('thing')   -- nil when 'thing' is not running
if thing then thing.DoIt(source) end

• Contracts live in one Lua VM: server and client each have their own set, and a separate resource cannot call them.
• Each module documents its contract on its server and client pages (module list).