Everything on this page is nil in the server VM.

Client values

OPX.Toast.ICONS is the same table as OPX.Glyphs.

Scheduler loop

OPX.Scheduler.Start

Starts the client loop. Called once by client boot; further calls are ignored. The rest of OPX.Scheduler is on Shared.

OPX.Scheduler.Start()

Notes to the server journal

OPX.Note

Writes one line to the server journal as [note] <module> from player <id>: <text>, and to the client log. For failures and decisions, not ticks. Never raises.

OPX.Note(module, text)

Parameters

• module: string
• text: string — cut to 400 characters

Returns

• boolean — sent

• One net event (opx:net:runtime:note) per call, 60 per session (the last one says the budget is spent).

• The server also limits each player to 12 notes per 10 s and 60 per session.

OPX.Note('thing', 'could not open the panel: ' .. tostring(why))

WebUI bridge

One WebUI page (web/index.html, id opx) serves the whole client. target is 'overlay' or 'interactive'; both name the same page. Channel names are <module>:<verb>; the page sees them as opx:<module>:<verb> (The WebUI page). The page itself can clear the focus stack: see focus:set.

OPX.UI.Surface

The page, created on first call from SURFACE.

OPX.UI.Surface()

Returns

• table? — nil if it could not be built

OPX.UI.Overlay

Same function as Surface.

OPX.UI.Overlay()

Returns

• table?

OPX.UI.Interactive

Same function as Surface.

OPX.UI.Interactive()

Returns

• table?

OPX.UI.Send

Sends a payload to the page.

OPX.UI.Send(target, channel, payload)

Parameters

• target: 'overlay' | 'interactive'
• channel: string
• payload?: table

Returns

• sent: boolean — false until the page has said ready
• refused: boolean — true when the host rejected the payload (too large or not serialisable)

OPX.UI.Send('interactive', 'thing:open', { rows = rows })

OPX.UI.On

Adds a handler for a channel the page emits. Non-table payloads are dropped. Treat a payload as a request, never as a fact.

OPX.UI.On(target, channel, handler)

Parameters

• target: 'overlay' | 'interactive'
• channel: string
• handler: function(payload)

Returns

• function | boolean

OPX.UI.On('interactive', 'thing:close', function(payload) M.Close() end)

OPX.UI.Answer

Sends payload with ref on the reply channel. If the host refuses it, sends { ref, ok = false, error = 'error.payloadRefused' } instead.

OPX.UI.Answer(target, ref, payload)

Parameters

• target: 'overlay' | 'interactive'
• ref: any — the page's request ref; nothing is sent when nil
• payload?: table

Returns

• sent: boolean
• refused: boolean

OPX.UI.AcquireFocus

Pushes owner on the focus stack.

OPX.UI.AcquireFocus(owner, wants)

Parameters

• owner: string
• wants?: table
  • keyboard?: boolean — default true
  • cursor?: boolean — default false

Returns

• boolean

OPX.UI.AcquireFocus('thing', { cursor = true })

OPX.UI.ReleaseFocus

Removes owner; focus goes to the next owner down, or is dropped. Safe for an owner that never held it.

OPX.UI.ReleaseFocus(owner)

Parameters

• owner: string

OPX.UI.FocusOwner

The owner on top of the stack.

OPX.UI.FocusOwner()

Returns

• string?

OPX.UI.ReleaseAllFocus

Empties the focus stack and gives keyboard and cursor back at once. The client stop path calls it first, before any module's Stop, so a stop that overruns the instruction budget can no longer leave a player with the cursor held and nothing drawn.

OPX.UI.ReleaseAllFocus()

OPX.UI.Teardown

Drops focus and destroys the page. Called on resource stop.

OPX.UI.Teardown()

Toasts

Client-side toasts drawn on the runtime's own page. To toast a player from the server, use OPX.Refuse, OPX.CommandNotice or OPX.Notify. Placement: TOASTS.

OPX.Toast.Show

Shows a toast, or replaces one already up.

OPX.Toast.Show(definition)

Parameters

• definition: table
  • message: string
  • kind?: 'info' | 'success' | 'warning' | 'error' — default info
  • title?: string
  • icon?: string — must be in OPX.Glyphs
  • durationMs?: number — default 5000
  • id?: string — replaces the toast with this id
  • stinger?: { open?, close?, volume? } — bare audio file names; a bad name is dropped

Returns

• id: string?
• reason?: string — toast_must_be_a_table, invalid_toast_message, invalid_toast_icon, payload_refused, surface_unavailable

local id = OPX.Toast.Show({ message = 'Saved', kind = 'success', icon = 'folder' })

OPX.Toast.Locale

Show with the text of a locale key. A kind of 'error' or 'warning' is replaced by OPX.Result.Kind(key, kind).

OPX.Toast.Locale(key, params, kind, icon)

Parameters

• key: string
• params?: table
• kind?: string
• icon?: string

Returns

• id: string?
• reason?: string

OPX.Toast.Update

Changes fields of a toast still up. icon = '' removes the icon. A refused patch is rolled back.

OPX.Toast.Update(id, patch)

Parameters

• id: string
• patch: table — any Show fields

Returns

• ok: boolean
• reason?: string — no_such_toast, patch_must_be_a_table, invalid_toast_icon, payload_refused, surface_unavailable

OPX.Toast.Dismiss

Takes one toast down early.

OPX.Toast.Dismiss(id)

Parameters

• id: string

OPX.Toast.Clear

Takes every toast down.

OPX.Toast.Clear()

OPX.Toast.SetDown

Hides (true) or shows the toast stacks without losing them. The downed module calls it.

OPX.Toast.SetDown(down)

Parameters

• down: boolean

OPX.Toast.Attach

Wires notify:gone, notify:ready and the two server answer events (opx:net:runtime:notify, opx:net:runtime:commandAnswer). Called once by client boot.

OPX.Toast.Attach()