Formspec defines a menu. It is a string, with a somewhat strange format.

Spaces and newlines can be inserted between the blocks, as is used in the examples.

Examples

Chest

size[8,9]
list[context;main;0,0;8,4;]
list[current_player;main;0,5;8,4;]

Furnace

size[8,9]
list[context;fuel;2,3;1,1;]
list[context;src;2,1;1,1;]
list[context;dst;5,1;2,2;]
list[current_player;main;0,5;8,4;]

Minecraft-like player inventory

size[8,7.5]
image[1,0.6;1,2;player.png]
list[current_player;main;0,3.5;8,4;]
list[current_player;craft;3,0;3,3;]
list[current_player;craftpreview;7,1;1,1;]

Elements

size[<W>,<H>,<fixed_size>]

  • Define the size of the menu in inventory slots
  • fixed_size: true/false (optional)
  • deprecated: invsize[<W>,<H>;]

container[<X>,<Y>]

  • Start of a container block, moves all physical elements in the container by (X, Y)
  • Must have matching container_end
  • Containers can be nested, in which case the offsets are added (child containers are relative to parent containers)

container_end[]

  • End of a container, following elements are no longer relative to this container

list[<inventory location>;<list name>;<X>,<Y>;<W>,<H>;]

  • Show an inventory list

list[<inventory location>;<list name>;<X>,<Y>;<W>,<H>;<starting item index>]

  • Show an inventory list

listring[<inventory location>;<list name>]

  • Allows to create a ring of inventory lists
  • Shift-clicking on items in one element of the ring will send them to the next inventory list inside the ring
  • The first occurrence of an element inside the ring will determine the inventory where items will be sent to

listring[]

  • Shorthand for doing listring[<inventory location>;<list name>] for the last two inventory lists added by list[...]

listcolors[<slot_bg_normal>;<slot_bg_hover>]

  • Sets background color of slots as ColorString
  • Sets background color of slots on mouse hovering

listcolors[<slot_bg_normal>;<slot_bg_hover>;<slot_border>]

  • Sets background color of slots as ColorString
  • Sets background color of slots on mouse hovering
  • Sets color of slots border

listcolors[<slot_bg_normal>;<slot_bg_hover>;<slot_border>;<tooltip_bgcolor>;<tooltip_fontcolor>]

  • Sets background color of slots as ColorString
  • Sets background color of slots on mouse hovering
  • Sets color of slots border
  • Sets default background color of tooltips
  • Sets default font color of tooltips

tooltip[<gui_element_name>;<tooltip_text>;<bgcolor>,<fontcolor>]

  • Adds tooltip for an element
  • <bgcolor> tooltip background color as ColorString (optional)
  • <fontcolor> tooltip font color as ColorString (optional)

image[<X>,<Y>;<W>,<H>;<texture name>]

  • Show an image
  • Position and size units are inventory slots

item_image[<X>,<Y>;<W>,<H>;<item name>]

  • Show an inventory image of registered item/node
  • Position and size units are inventory slots

bgcolor[<color>;<fullscreen>]

  • Sets background color of formspec as ColorString
  • If true, the background color is drawn fullscreen (does not effect the size of the formspec)

background[<X>,<Y>;<W>,<H>;<texture name>]

  • Use a background. Inventory rectangles are not drawn then.
  • Position and size units are inventory slots
  • Example for formspec 8x4 in 16x resolution: image shall be sized 8 times 16px times 4 times 16px.

background[<X>,<Y>;<W>,<H>;<texture name>;<auto_clip>]

  • Use a background. Inventory rectangles are not drawn then.
  • Position and size units are inventory slots
  • Example for formspec 8x4 in 16x resolution: image shall be sized 8 times 16px times 4 times 16px
  • If true the background is clipped to formspec size (x and y are used as offset values, w and h are ignored)

pwdfield[<X>,<Y>;<W>,<H>;<name>;<label>]

  • Textual password style field; will be sent to server when a button is clicked
  • When enter is pressed in field, fields.key_enter_field will be sent with the name of this field.
  • x and y position the field relative to the top left of the menu
  • w and h are the size of the field
  • Fields are a set height, but will be vertically centred on h
  • Position and size units are inventory slots
  • name is the name of the field as returned in fields to on_receive_fields
  • label, if not blank, will be text printed on the top left above the field
  • See field_close_on_enter to stop enter closing the formspec

field[<X>,<Y>;<W>,<H>;<name>;<label>;<default>]

  • Textual field; will be sent to server when a button is clicked
  • When enter is pressed in field, fields.key_enter_field will be sent with the name of this field.
  • x and y position the field relative to the top left of the menu
  • w and h are the size of the field
  • Fields are a set height, but will be vertically centred on h
  • Position and size units are inventory slots
  • name is the name of the field as returned in fields to on_receive_fields
  • label, if not blank, will be text printed on the top left above the field
  • default is the default value of the field
    • default may contain variable references such as ${text}' which will fill the value from the metadata value text
    • Note: no extra text or more than a single variable is supported ATM.
  • See field_close_on_enter to stop enter closing the formspec

field[<name>;<label>;<default>]

  • As above, but without position/size units
  • When enter is pressed in field, fields.key_enter_field will be sent with the name of this field.
  • Special field for creating simple forms, such as sign text input
  • Must be used without a size[] element
  • A "Proceed" button will be added automatically
  • See field_close_on_enter to stop enter closing the formspec

field_close_on_enter[<name>;<close_on_enter>]

  • is the name of the field
  • if is false, pressing enter in the field will submit the form but not close it
  • defaults to true when not specified (ie: no tag for a field)

textarea[<X>,<Y>;<W>,<H>;<name>;<label>;<default>]

  • Same as fields above, but with multi-line input

label[<X>,<Y>;<label>]

  • x and y work as per field
  • label is the text on the label
  • Position and size units are inventory slots

vertlabel[<X>,<Y>;<label>]

  • Textual label drawn vertically
  • x and y work as per field
  • label is the text on the label
  • Position and size units are inventory slots

button[<X>,<Y>;<W>,<H>;<name>;<label>]

  • Clickable button. When clicked, fields will be sent.
  • x, y and name work as per field
  • w and h are the size of the button
  • Fixed button height. It will be vertically centred on h
  • label is the text on the button
  • Position and size units are inventory slots

image_button[<X>,<Y>;<W>,<H>;<texture name>;<name>;<label>]

  • x, y, w, h, and name work as per button
  • texture name is the filename of an image
  • Position and size units are inventory slots

image_button[<X>,<Y>;<W>,<H>;<texture name>;<name>;<label>;<noclip>;<drawborder>;<pressed texture name>]

  • x, y, w, h, and name work as per button
  • texture name is the filename of an image
  • Position and size units are inventory slots
  • noclip=true means the image button doesn't need to be within specified formsize
  • drawborder: draw button border or not
  • pressed texture name is the filename of an image on pressed state

item_image_button[<X>,<Y>;<W>,<H>;<item name>;<name>;<label>]

  • x, y, w, h, name and label work as per button
  • item name is the registered name of an item/node, tooltip will be made out of its description to override it use tooltip element
  • Position and size units are inventory slots

button_exit[<X>,<Y>;<W>,<H>;<name>;<label>]

  • When clicked, fields will be sent and the form will quit.

image_button_exit[<X>,<Y>;<W>,<H>;<texture name>;<name>;<label>]

  • When clicked, fields will be sent and the form will quit.

textlist[<X>,<Y>;<W>,<H>;<name>;<listelem 1>,<listelem 2>,...,<listelem n>]

  • Scrollable item list showing arbitrary text elements
  • x and y position the itemlist relative to the top left of the menu
  • w and h are the size of the itemlist
  • name fieldname sent to server on doubleclick value is current selected element
  • listelements can be prepended by #color in hexadecimal format RRGGBB (only),
    • if you want a listelement to start with "#" write "##".

textlist[<X>,<Y>;<W>,<H>;<name>;<listelem 1>,<listelem 2>,...,<listelem n>;<selected idx>;<transparent>]

  • Scrollable itemlist showing arbitrary text elements
  • x and y position the item list relative to the top left of the menu
  • w and h are the size of the item list
  • name fieldname sent to server on doubleclick value is current selected element
  • listelements can be prepended by #RRGGBB (only) in hexadecimal format
    • if you want a listelement to start with "#" write "##"
  • Index to be selected within textlist
  • true/false: draw transparent background
  • See also core.explode_textlist_event (main menu: engine.explode_textlist_event)

tabheader[<X>,<Y>;<name>;<caption 1>,<caption 2>,...,<caption n>;<current_tab>;<transparent>;<draw_border>]

  • Show a tabheader at specific position (ignores formsize)
  • x and y position the itemlist relative to the top left of the menu
  • name fieldname data is transferred to Lua
  • caption 1...: name shown on top of tab
  • current_tab: index of selected tab 1...
  • transparent (optional): show transparent
  • draw_border (optional): draw border

box[<X>,<Y>;<W>,<H>;<color>]

  • Simple colored semitransparent box
  • x and y position the box relative to the top left of the menu
  • w and h are the size of box
  • color is color specified as a ColorString
  • Show a dropdown field
  • Important note: There are two different operation modes:
    1. handle directly on change (only changed dropdown is submitted)
    2. read the value on pressing a button (all dropdown values are available)
  • x and y position of dropdown
  • Width of dropdown
  • Fieldname data is transferred to Lua
  • Items to be shown in dropdown
  • Index of currently selected dropdown item

checkbox[<X>,<Y>;<name>;<label>;<selected>]

  • Show a checkbox
  • x and y: position of checkbox
  • name fieldname data is transferred to Lua
  • label to be shown left of checkbox
  • selected (optional): true/false

scrollbar[<X>,<Y>;<W>,<H>;<orientation>;<name>;<value>]

  • Show a scrollbar
  • There are two ways to use it:
    1. handle the changed event (only changed scrollbar is available)
    2. read the value on pressing a button (all scrollbars are available)
  • x and y: position of trackbar
  • w and h: width and height
  • orientation: vertical/horizontal
  • Fieldname data is transferred to Lua
  • Value this trackbar is set to (0-1000)
  • See also core.explode_scrollbar_event (main menu: engine.explode_scrollbar_event)

table[<X>,<Y>;<W>,<H>;<name>;<cell 1>,<cell 2>,...,<cell n>;<selected idx>]

  • Show scrollable table using options defined by the previous tableoptions[]
  • Displays cells as defined by the previous tablecolumns[]
  • x and y: position the itemlist relative to the top left of the menu
  • w and h are the size of the itemlist
  • name: fieldname sent to server on row select or doubleclick
  • cell 1...cell n: cell contents given in row-major order
  • selected idx: index of row to be selected within table (first row = 1)
  • See also core.explode_table_event (main menu: engine.explode_table_event)

tableoptions[<opt 1>;<opt 2>;...]

  • Sets options for table[]
  • color=#RRGGBB
    • default text color (ColorString), defaults to #FFFFFF
  • background=#RRGGBB
    • table background color (ColorString), defaults to #000000
  • border=<true/false>
    • should the table be drawn with a border? (default: true)
  • highlight=#RRGGBB
    • highlight background color (ColorString), defaults to #466432
  • highlight_text=#RRGGBB
    • highlight text color (ColorString), defaults to #FFFFFF
  • opendepth=<value>
    • all subtrees up to depth < value are open (default value = 0)
    • only useful when there is a column of type "tree"

tablecolumns[<type 1>,<opt 1a>,<opt 1b>,...;<type 2>,<opt 2a>,<opt 2b>;...]

  • Sets columns for table[]
  • Types: text, image, color, indent, tree
    • text: show cell contents as text
    • image: cell contents are an image index, use column options to define images
    • color: cell contents are a ColorString and define color of following cell
    • indent: cell contents are a number and define indentation of following cell
    • tree: same as indent, but user can open and close subtrees (treeview-like)
  • Column options:
    • align=<value>
      • for text and image: content alignment within cells. Available values: left (default), center, right, inline
    • width=<value>
      • for text and image: minimum width in em (default: 0)
      • for indent and tree: indent width in em (default: 1.5)
    • padding=<value>: padding left of the column, in em (default 0.5). Exception: defaults to 0 for indent columns
    • tooltip=<value>: tooltip text (default: empty)
    • image column options:
      • 0=<value> sets image for image index 0
      • 1=<value> sets image for image index 1
      • 2=<value> sets image for image index 2
      • and so on; defined indices need not be contiguous empty or non-numeric cells are treated as 0.
    • color column options:
      • span=<value>: number of following columns to affect (default: infinite)

Note: do not use a element name starting with key_; those names are reserved to pass key press events to formspec!