Dialogs, menus and views

TableColumn

Fields

• title (optional) string — Up to 31 bytes, single line.
• align (optional) "left"|"center"|"right" — Defaults to "left".

TableCell

Fields

• text (optional) string — Up to 63 bytes, single line.
• color (optional) integer — 0xRRGGBB; defaults to the theme's text color.

TableSpec

Fields

• title (optional) string — Up to 63 bytes, single line.
• columns (string|TableColumn)[] — 1..8 columns.
• rows (optional) (string|number|TableCell)[][] — Up to 256 rows, one cell per column. Paginate longer tables yourself.

TableDialogSpec

Has every field of TableSpec.

Fields

• kind "table"
• button1 (optional) string — Up to 31 bytes, single line; defaults to "OK".
• button2 (optional) string — Up to 31 bytes, single line; no second button by default. Esc presses this button; without it, Esc does not close the dialog.

DialogSpec

Fields

• kind (optional) "message"|"list"|"input" — Defaults to "message". For table, use a TableDialogSpec.
• title (optional) string — Up to 63 bytes, single line.
• text (optional) string — Text of a message or input dialog, up to 1023 bytes.
• items (optional) string[] — Rows of a list dialog: 1..64 single-line rows, 1023 bytes in total.
• button1 (optional) string — Up to 31 bytes, single line; defaults to "OK".
• button2 (optional) string — Up to 31 bytes, single line; no second button by default. Esc presses this button; without it, Esc does not close the dialog.

FormField

Fields

• name string — Key of the value in the callback's values; unique within the form, single line, up to 63 bytes. Never sent to the client.
• label string — Single line, up to 63 bytes.
• type "text"|"number"|"slider"|"checkbox"|"select"
• value (optional) string|number|boolean — Initial value. Defaults: "" for text, 0 for number (or min when 0 is out of range), false for checkbox, 1 for select.
• max_length (optional) integer — Text only: 1..255 bytes; defaults to 64.
• min (optional) number — Number and slider; required for a slider. Must be within -1e12..1e12 and less than max.
• max (optional) number — Number and slider; required for a slider.
• step (optional) number — Number and slider; required for a slider. Values are min + k * step; the step must be at least 1e-6 and at least 1e-9 times the largest bound. With a fractional step, values are rounded to 9 decimal places. An integer step with an integer min yields Lua integers.
• options (optional) string[] — Select only: 1..32 options, each a single line of 1..63 bytes. value and the answer are 1-based indices.

FormSpec

Fields

• kind "form"
• title (optional) string — Up to 63 bytes, single line.
• fields FormField[] — 1..16 fields. The encoded fields must fit in 1024 bytes, and so must their longest possible answers; a text field counts as 2 + max_length bytes.
• button1 (optional) string — Up to 31 bytes, single line; defaults to "OK". Disabled while a number field holds an invalid value.
• button2 (optional) string — Up to 31 bytes, single line; no second button by default. Esc presses this button; without it, Esc does not close the dialog. Returns no values.

MenuItemSpec

Fields

• name string — Passed to the callbacks; unique within the whole menu, single line, up to 63 bytes. Never sent to the client.
• label string — Single line, up to 63 bytes.
• value (optional) string — Shown on the right side of the row; up to 31 bytes, single line.
• description (optional) string — Shown below the list while the item is selected; up to 127 bytes, single line, wrapped on display.
• disabled (optional) boolean — The item can be highlighted and read but not selected or opened.
• items (optional) MenuItemSpec[] — Makes the item a submenu: selecting it opens this level and calls no callback.
• title (optional) string — Submenu title; defaults to label.

MenuSpec

Fields

• title (optional) string — Up to 63 bytes, single line.
• items MenuItemSpec[] — 1..256 items per level, at most 4 levels deep, at most 1024 items in the whole menu.

dlmp.show_dialog

Opens a modal dialog on a player's screen; works before the player spawns. Replaces the open dialog, whose callback is then never called; the callback is also never called when the dialog is hidden or the player leaves. Stopping the resource closes its dialogs.

Parameters

• player Player
• spec DialogSpec|TableDialogSpec|FormSpec
• callback fun(player: Player, button: integer, item: integer|nil, text: string|nil, values: table<string, string|number|boolean>|nil) — button is 1 or 2. item is the 1-based row of a list or of the table's current version, also set for the second button; nil for a table with no rows. text is the input's text, sanitized like chat. values holds a form's values by field name, only for the first button, already validated against each field: text is sanitized like chat, a select's choice is 1-based.

Returns ok boolean|nil, err string|nil

dlmp.hide_dialog

Closes the player's open dialog, whichever resource showed it.

Parameters

• player Player

Returns ok boolean|nil, err string|nil

dlmp.update_dialog

Replaces the content of the table dialog this resource has open on a player's screen. The selection and scroll position are kept; a selected row past the new end moves to the last row. An answer to a replaced version is dropped and the table stays open, so a table that changes many times a second is hard to answer. Content equal to the current content is a no-op. On failure (nil, err) the old version stays current: keep the rows the callback indexes until the update succeeds.

Parameters

• player Player
• spec TableDialogSpec

Returns ok boolean|nil, err string|nil

dlmp.show_table

Shows a passive table, such as a scoreboard shown while a key is held. It has no buttons, returns no answer, does not capture input and is independent of the modal dialog. Replaces the player's passive table. The table is removed when the player dies or disconnects, or when this resource stops.

Parameters

• player Player
• spec TableSpec

Returns ok boolean|nil, err string|nil

dlmp.update_table

Replaces the content of the passive table this resource shows on a player's screen.

Parameters

• player Player
• spec TableSpec

Returns ok boolean|nil, err string|nil

dlmp.hide_table

Hides the player's passive table, whichever resource showed it.

Parameters

• player Player

Returns ok boolean|nil, err string|nil

dlmp.show_menu

Shows a menu at the side of a player's screen; works before the player spawns. The menu does not block game input: the player keeps moving and navigates it with their menu key bindings. Replaces the open menu, whose callbacks are then never called; on error the open menu stays, and hide_menu closes it. A dialog can appear on top of it. Stopping the resource closes its menus; the player's death does not.

Parameters

• player Player
• spec MenuSpec
• callbacks (optional) MenuCallbacks

Returns ok boolean|nil, err string|nil

dlmp.hide_menu

Closes the player's open menu, whichever resource showed it.

Parameters

• player Player

Returns ok boolean|nil, err string|nil

OfferSpec

A card the player must answer before it times out; text is required, title is optional.

Fields

• text string — Up to 255 bytes, single line; wrapped on the card.
• title string|nil
• accept string|nil — Label of the accept option; defaults to "Accept".
• decline string|nil — Label of the decline option; defaults to "Decline".
• duration_ms integer — 1000..300000

dlmp.show_offer

Shows an offer on a player's screen. It does not block game input; the player answers with their own keys. A player has at most one offer: while one is open, the next call fails with nil, err, and the gamemode decides whether to retry later. on_answer(player, "accept"|"decline"|"timeout") is called once. hide_offer, stopping this resource or the player leaving ends the offer without a call; the player's death does not end it. A player handle kept in the callback refers to no one after that player leaves. The answer may arrive while the player is dead or elsewhere: check the player's state first.

Parameters

• player Player
• spec OfferSpec
• on_answer (optional) fun(player: Player, answer: "accept"|"decline"|"timeout")

Returns ok boolean|nil, err string|nil

dlmp.hide_offer

Hides the player's open offer, whichever resource showed it.

Parameters

• player Player

Returns ok boolean|nil, err string|nil

ViewFieldRule

An action field: a type name or a rule.

Type: "boolean"|"number"|"integer"|"string"|ViewFieldSpec

ViewFieldSpec

Fields

• type "boolean"|"number"|"integer"|"string"
• optional (optional) boolean — The page may omit the field; fields are required by default.
• min (optional) number — For a number or an integer; defaults to -(2^53 - 1).
• max (optional) number — For a number or an integer; defaults to 2^53 - 1.
• max_len (optional) integer — Maximum string length in bytes, 0..255; defaults to 255. Control characters are always rejected.

ViewSpec

Fields

• entry string — The page: an .html path listed in this resource's [client].files.
• input (optional) "full"|"regions"|"none" — full (default) captures the mouse and keyboard while the view is shown. regions shows a cursor and the mouse no longer turns the camera or fires: over the rectangles the page declares, mouse input goes to the page; elsewhere it is ignored (in an edit session, it goes to the edit tool). The keyboard stays with the game unless a text field on the page has focus; Esc takes the focus back. none only displays the page.
• actions (optional) table<string, table<string, ViewFieldRule>> — Actions the page may send: maps an action name ([a-z0-9_], 1..31 bytes) to its fields by name. Up to 64 actions with up to 16 fields each.

ViewCallbacks

Fields

• on_ready (optional) fun(view: View) — Called when the page has loaded; actions are accepted from then on.
• on_action (optional) fun(view: View, name: string, args: table<string, boolean|number|string>, revision: integer) — Called for a declared action after validation against its fields: no undeclared fields, every required field present, numbers finite and in range (an integral value arrives as a Lua integer), strings within their maximum length. Only actions sent at the view's current revision arrive; revision is that one.
• on_close (optional) fun(view: View, reason: "replaced"|"download"|"integrity"|"unavailable"|"page") — Called when the view closes other than through view:close(): another view was opened for the player, a file could not be downloaded or failed verification, the client build has no browser, or the page failed.

MenuCallbacks

Fields

• on_hover (optional) fun(player: Player, name: string) — Called when the player settles on an item, including the first item of each level they open. While the player scrolls through the list, not every item triggers it.
• on_select (optional) fun(player: Player, name: string) — Called when the player selects an item that was enabled when the menu was shown. The menu stays open, so this can fire again: close it with hide_menu, and check any cost or requirement of the selection here.
• on_close (optional) fun(player: Player) — Called when the player backs out of the root level; not called when the menu is replaced, hidden or closed because the player left.

dlmp.open_view

Opens a view from this resource's client files on a player's client; works before the player spawns. Replaces the player's open view. Stopping or reloading the resource closes its views, and so does the player leaving; their callbacks are then never called. Invalid arguments raise an error.

Parameters

• player Player
• spec ViewSpec
• callbacks (optional) ViewCallbacks

Returns view View|nil, err string|nil