Interface API

#Forms

The form system provides a way to open modal dialogs with dynamic input fields from Lua. Forms are blocking, the calling thread yields until the player submits or cancels. The return value is a table of input values keyed by name, or nil if cancelled.

#Usage

local result = Z.openForm(title, inputs, options)

• title (string, required) -- text displayed in the modal header.
• inputs (table[], required) -- array of input definitions.
• options (table, optional) -- modal-level configuration.

Returns a table of values keyed by each input's name, or nil if cancelled.

#Helpers

Z.isFormOpen()          -- returns true if a form is currently open
Z.getOpenFormId()       -- returns the active form's ID, or nil
Z.closeForm()           -- close the active form (resolves as nil)
Z.closeFormById(formId) -- close a specific form by ID (resolves as nil)

#Options

The third parameter controls the modal itself. All fields are optional.

• icon (string) -- icon shown in the header next to the title.
• width (string, default "30rem") -- CSS width of the modal.
• showCancel (boolean, default true) -- whether to show a cancel button.
• disableClickOutside (boolean, default false) -- prevent closing by clicking the backdrop.
• buttons (table[]) -- array of submit buttons to render in the footer (see Buttons).

Pressing Enter submits the form with the first button's action. Pressing Escape cancels it.

#Buttons

The buttons array defines one or more submit buttons rendered in the form footer. Each entry is a table:

• text (string, required) -- button label.
• icon (string) -- icon rendered before the label.
• color (string, default "var(--blue1)") -- CSS color for the button.
• action (string) -- identifier forwarded to the caller via result._action.

When a button is clicked, the returned table will contain _action matching that button's action field. This lets you branch on which button the player chose:

local result = Z.openForm("Import", inputs, {
    buttons = {
        { text = "Import", icon = "confirm", color = "var(--blue1)", action = "import" },
        { text = "Generate Blank", icon = "copy", color = "var(--green1)", action = "blank" },
    },
})

if (not result) then return end -- cancelled

if (result._action == "import") then
    -- handle import
elseif (result._action == "blank") then
    -- handle blank generation
end

Legacy submit fields

Deprecated -- prefer buttons[] for new code.

The following fields are kept for backward compatibility. If buttons is not provided, a single submit button is generated from these:

• submitText (string, default "Confirm") -- label on the submit button.
• submitIcon (string) -- icon on the submit button.
• submitColor (string, default "var(--blue1)") -- CSS color for the submit button.

These are ignored when buttons is present.

#Input Types

Each entry in the inputs array is a table with a type field and additional properties depending on the type.

#Common Properties

These apply to all input types.

• type (string, required) -- one of: text, number, select, select-player, checkbox, slider, textarea.
• name (string, required) -- key used in the returned values table.
• label (string) -- label shown above the input.
• description (string) -- secondary text below the label.
• icon (string) -- icon displayed in the input (select and text types).
• disabled (boolean) -- prevent interaction.
• defaultValue (any) -- initial value.

#text

Standard single-line text input.

• placeholder (string) -- placeholder text when empty.

{ type = "text", name = "plate", label = "License Plate", placeholder = "ABC 123", icon = "label" }

Returns string.

#number

Numeric input.

• placeholder (string) -- placeholder text.
• min (number) -- minimum allowed value.
• max (number) -- maximum allowed value.

{ type = "number", name = "amount", label = "Amount", min = 1, max = 100, icon = "money" }

Returns number.

#select

Dropdown selection with optional search filtering.

• content (table[]) -- array of { label = "...", value = "..." } options.
• searchable (boolean) -- enable search filtering.
• multiselect (boolean) -- allow multiple selections.
• placeholder (string) -- placeholder text.

{
    type = "select",
    name = "garage",
    label = "Garage",
    icon = "garage",
    searchable = true,
    content = {
        { label = "Legion Square", value = "legion" },
        { label = "Pillbox", value = "pillbox" },
    },
    defaultValue = "legion",
}

Returns string (selected value) or table (array of values if multiselect).

#select-player

A select dropdown automatically populated with all connected players. Each entry renders as (id) Firstname Lastname with the player's identifier as the value. Searchable by default. Defaults to the person icon if none is specified.

All standard select properties (searchable, multiselect, placeholder, defaultValue) are supported.

{ type = "select-player", name = "target", label = "Target Player" }

Returns string (player identifier).

#checkbox

Boolean toggle with a label.

{ type = "checkbox", name = "agree", label = "I agree to the terms" }

Returns boolean.

#slider

Range slider with optional step marks.

• min (number) -- minimum value.
• max (number) -- maximum value.
• step (number) -- step increment.
• marks (table[]) -- array of { value = n, label = "..." } tick marks.

{ type = "slider", name = "rating", label = "Rating", min = 0, max = 10, step = 1 }

Returns number.

#textarea

Multi-line text input with auto-resize.

• placeholder (string) -- placeholder text.
• minRows (number, default 3) -- minimum visible rows.
• maxRows (number, default 6) -- maximum visible rows.
• maxLength (number) -- character limit.

{ type = "textarea", name = "notes", label = "Notes", placeholder = "Write here...", maxLength = 500 }

Returns string.

#Icons

Icons can be specified by name as a string on any icon field (inputs and options). Resolution works in two layers:

1. Icon Registry -- SVG icons from MUI and react-icons. These are the same icons used throughout zyke_garages and render as crisp vector graphics.
2. Material Icons (fallback) -- if the name is not found in the registry, it is treated as a Material Icons font name.

#Registry Icons

#Material Icons Fallback

Any string not found in the registry is treated as a Material Icons font name. Browse the available icons at fonts.google.com/icons.

icon = "directions_boat"  -- not in registry, renders via Material Icons font

#Full Example

local result = Z.openForm("Report Player", {
    {
        type = "select-player",
        name = "target",
        label = "Player",
    },
    {
        type = "select",
        name = "reason",
        label = "Reason",
        icon = "warning",
        searchable = true,
        content = {
            { label = "Cheating", value = "cheating" },
            { label = "Harassment", value = "harassment" },
            { label = "Bug Abuse", value = "bug_abuse" },
        },
    },
    {
        type = "textarea",
        name = "details",
        label = "Details",
        placeholder = "Describe what happened...",
        maxLength = 500,
    },
}, {
    icon = "info",
    buttons = {
        { text = "Submit Report", icon = "confirm", action = "submit" },
        { text = "Save as Draft", icon = "save", color = "var(--green1)", action = "draft" },
    },
})

if (not result) then return end

if (result._action == "submit") then
    print("Submitted:", result.target, result.reason, result.details)
elseif (result._action == "draft") then
    print("Saved as draft:", result.target, result.reason, result.details)
end