Formspec

Formspec defines a menu. This supports inventories and some of the typical widgets like buttons, checkboxes, text input fields, etc. It is a string, with a somewhat strange format.

A formspec is made out of formspec elements, which includes widgets like buttons but also can be used to set stuff like background color.

Many formspec elements have a name, which is a unique identifier which is used when the server receives user input. You must not use the name "quit" for formspec elements.

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

Position and size units are inventory slots unless the new coordinate system is enabled. X and Y position the formspec element relative to the top left of the menu or container. W and H are its width and height values.

If the new system is enabled, all elements have unified coordinates for all elements with no padding or spacing in between. This is highly recommended for new forms. See real_coordinates[<bool>] and Migrating to Real Coordinates.

Inventories with a player:<name> inventory location are only sent to the player named <name>.

When displaying text which can contain formspec code, e.g. text set by a player, use minetest.formspec_escape. For coloured text you can use minetest.colorize.

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

WARNING: Minetest allows you to add elements to every single formspec instance using player:set_formspec_prepend(), which may be the reason backgrounds are appearing when you don't expect them to, or why things are styled differently to normal. See [no_prepend[]] and [Styling Formspecs].

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

formspec_version[<version>]

  • Set the formspec version to a certain number. If not specified, version 1 is assumed.
  • Must be specified before size element.
  • Clients older than this version can neither show newer elements nor display elements with new arguments correctly.
  • Available since feature formspec_version_element.

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

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

position[<X>,<Y>]

  • Must be used after size element.
  • Defines the position on the game window of the formspec's anchor point.
  • For X and Y, 0.0 and 1.0 represent opposite edges of the game window, for example:
    • [0.0, 0.0] sets the position to the top left corner of the game window.
    • [1.0, 1.0] sets the position to the bottom right of the game window.
  • Defaults to the center of the game window [0.5, 0.5].

anchor[<X>,<Y>]

  • Must be used after both size and position (if present) elements.
  • Defines the location of the anchor point within the formspec.
  • For X and Y, 0.0 and 1.0 represent opposite edges of the formspec, for example:
    • [0.0, 1.0] sets the anchor to the bottom left corner of the formspec.
    • [1.0, 0.0] sets the anchor to the top right of the formspec.
  • Defaults to the center of the formspec [0.5, 0.5].

  • position and anchor elements need suitable values to avoid a formspec extending off the game window due to particular game window sizes.

no_prepend[]

  • Must be used after the size, position, and anchor elements (if present).
  • Disables player:set_formspec_prepend() from applying to this formspec.

real_coordinates[<bool>]

  • INFORMATION: Enable it automatically using formspec_version version 2 or newer.
  • When set to true, all following formspec elements will use the new coordinate system.
  • If used immediately after size, position, anchor, and no_prepend elements (if present), the form size will use the new coordinate system.
  • Note: Formspec prepends are not affected by the coordinates in the main form. They must enable it explicitly.
  • For information on converting forms to the new coordinate system, see Migrating to Real Coordinates.

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 if it has been sent to the client. Nothing will be shown if the inventory list is of size 0.
  • Note: With the new coordinate system, the spacing between inventory slots is one-fourth the size of an inventory slot.

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

  • Show an inventory list if it has been sent to the client. Nothing will be shown if the inventory list is of size 0.
  • Note: With the new coordinate system, the spacing between inventory slots is one-fourth the size of an inventory slot.

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)

tooltip[<X>,<Y>;<W>,<H>;<tooltip_text>;<bgcolor>;<fontcolor>]

  • Adds tooltip for an area. Other tooltips will take priority when present.
  • <bgcolor> tooltip background color as ColorString (optional)
  • <fontcolor> tooltip font color as ColorString (optional)

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

  • Show an image

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

  • Show an inventory image of registered item/node

bgcolor[<color>;<fullscreen>]

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

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

  • 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>]

  • Example for formspec 8x4 in 16x resolution: image shall be sized 8 times 16px times 4 times 16px
  • If auto_clip is true, the background is clipped to the formspec size (x and y are used as offset values, w and h are ignored)

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

  • 9-sliced background. See https://en.wikipedia.org/wiki/9-slice_scaling
  • Middle is a rect which defines the middle of the 9-slice.
    • x - The middle will be x pixels from all sides.
    • x,y - The middle will be x pixels from the horizontal and y from the vertical.
    • x,y,x2,y2 - The middle will start at x,y, and end at x2, y2. Negative x2 and y2 values will be added to the width and height of the texture, allowing it to be used as the distance from the far end.
    • All numbers in middle are integers.
  • Example for formspec 8x4 in 16x resolution: image shall be sized 8 times 16px times 4 times 16px
  • If auto_clip is true, the background is clipped to the formspec size (x and y are used as offset values, w and h are ignored)
  • Available since formspec version 2

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.
  • With the old coordinate system, fields are a set height, but will be vertically centred on H. With the new coordinate system, H will modify the height.
  • 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.
  • With the old coordinate system, fields are a set height, but will be vertically centred on H. With the new coordinate system, H will modify the height.
  • 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
  • If the text overflows, a vertical scrollbar is added.
  • If the name is empty, the textarea is read-only and the background is not shown, which corresponds to a multi-line label.

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

  • The label formspec element displays the text set in label at the specified position.
  • Note: If the new coordinate system is enabled, labels are positioned from the center of the text, not the top.
  • The text is displayed directly without automatic line breaking, so label should not be used for big text chunks. Newlines can be used to make labels multiline.
  • Note: With the new coordinate system, newlines are spaced with half a coordinate. With the old system, newlines are spaced 2/5 of an inventory slot.

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

  • Textual label drawn vertically
  • label is the text on the label
  • Note: If the new coordinate system is enabled, vertlabels are positioned from the center of the text, not the left.

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

  • Clickable button. When clicked, fields will be sent.
  • With the old coordinate system, buttons are a set height, but will be vertically centred on H. With the new coordinate system, H will modify the height.
  • label is the text on the button

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

  • texture name is the filename of an image
  • Note: Height is supported on both the old and new coordinate systems for image_buttons.

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

  • texture name is the filename of an image
  • 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>]

  • item name is the registered name of an item/node
  • The item description will be used as the tooltip. This can be overridden with a tooltip element.

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

  • When clicked, fields will be sent and the form will quit.
  • Same as button in all other respects.

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

  • When clicked, fields will be sent and the form will quit.
  • Same as image_button in all other respects.

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

  • Scrollable item list showing arbitrary text elements
  • 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
  • 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 minetest.explode_textlist_event (main menu: core.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 of the tabheader
  • Note: Width and height are automatically chosen with this syntax
  • 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

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

  • Show a tabheader at specific position (ignores formsize)
  • Important note: This syntax for tabheaders can only be used with the new coordinate system.
  • X and Y: position of the tabheader
  • H: height of the tabheader. Width is automatically determined with this syntax.
  • 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

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

  • Show a tabheader at specific position (ignores formsize)
  • Important note: This syntax for tabheaders can only be used with the new coordinate system.
  • X and Y: position of the tabheader
  • W and H: width and height of the tabheader
  • 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 box
  • color is color specified as a ColorString. If the alpha component is left blank, the box will be semitransparent.
  • 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 the dropdown
  • W: width of the dropdown. Height is automatically chosen with this syntax.
  • Fieldname data is transferred to Lua
  • Items to be shown in dropdown
  • Index of currently selected dropdown item
  • Show a dropdown field
  • Important note: This syntax for dropdowns can only be used with the new coordinate system.
  • 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 the dropdown
  • W and H: width and height of the 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
  • name fieldname data is transferred to Lua
  • label to be shown left of checkbox
  • selected (optional): true/false
  • Note: If the new coordinate system is enabled, checkboxes are positioned from the center of the checkbox, not the top.

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)
  • orientation: vertical/horizontal
  • Fieldname data is transferred to Lua
  • Value this trackbar is set to (0-1000)
  • See also minetest.explode_scrollbar_event (main menu: core.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[]
  • 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 minetest.explode_table_event (main menu: core.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).

style[<name>;<prop1>;<prop2>;...]

  • Set the style for the named element name.
  • Note: this must be before the element is defined.
  • See [Styling Formspecs].

style_type[<type>;<prop1>;<prop2>;...]

  • Sets the style for all elements of type type which appear after this element.
  • See [Styling Formspecs].

Migrating to Real Coordinates

In the old system, positions included padding and spacing. Padding is a gap between the formspec window edges and content, and spacing is the gaps between items. For example, two 1x1 elements at 0,0 and 1,1 would have a spacing of 5/4 between them, and a padding of 3/8 from the formspec edge. It may be easiest to recreate old layouts in the new coordinate system from scratch.

To recreate an old layout with padding, you'll need to pass the positions and sizes through the following formula to re-introduce padding:

pos = (oldpos + 1)*spacing + padding
where
    padding = 3/8
    spacing = 5/4

You'll need to change the size[] tag like this:

size = (oldsize-1)*spacing + padding*2 + 1

A few elements had random offsets in the old system. Here is a table which shows these offsets when migrating:

Element Position Size Notes
box +0.3, +0.1 0, -0.4
button Buttons now support height, so set h = 2 * 15/13 * 0.35, and reposition if h ~= 15/13 * 0.35 before
list Spacing is now 0.25 for both directions, meaning lists will be taller in height
label 0, +0.3 The first line of text is now positioned centered exactly at the position specified

Styling Formspecs

Formspec elements can be themed using the style elements:

style[<name>;<prop1>;<prop2>;...]
style_type[<type>;<prop1>;<prop2>;...]

Where a prop is:

property_name=property_value

For example:

style_type[button;bgcolor=#006699]
style[world_delete;bgcolor=red;textcolor=yellow]
button[4,3.95;2.6,1;world_delete;Delete]

Setting a property to nothing will reset it to the default value. For example:

style_type[button;bgimg=button.png;bgimg_pressed=button_pressed.png;border=false]
style[btn_exit;bgimg=;bgimg_pressed=;border=;bgcolor=red]

Supported Element Types

Some types may inherit styles from parent types.

  • button
  • button_exit, inherits from button
  • checkbox
  • scrollbar
  • table
  • textlist
  • dropdown
  • field
  • pwdfield, inherits from field
  • textarea
  • label
  • vertlabel, inherits from field
  • image_button
  • item_image_button, inherits from image_button
  • tabheader

Valid Properties

  • button, button_exit
    • alpha - boolean, whether to draw alpha in bgimg. Default true.
    • bgcolor - color, sets button tint.
    • bgcolor_hovered - color when hovered. Defaults to a lighter bgcolor when not provided.
    • bgcolor_pressed - color when pressed. Defaults to a darker bgcolor when not provided.
    • bgimg - standard image. Defaults to none.
    • bgimg_hovered - image when hovered. Defaults to bgimg when not provided.
    • bgimg_pressed - image when pressed. Defaults to bgimg when not provided.
    • border - boolean, draw border. Set to false to hide the bevelled button pane. Default true.
    • noclip - boolean, set to true to allow the element to exceed formspec bounds.
    • textcolor - color, default white.
  • checkbox
    • noclip - boolean, set to true to allow the element to exceed formspec bounds.
  • scrollbar
    • noclip - boolean, set to true to allow the element to exceed formspec bounds.
  • table, textlist
    • noclip - boolean, set to true to allow the element to exceed formspec bounds.
  • dropdown
    • noclip - boolean, set to true to allow the element to exceed formspec bounds.
  • field, pwdfield, textarea
    • border - set to false to hide the textbox background and border. Default true.
    • noclip - boolean, set to true to allow the element to exceed formspec bounds.
    • textcolor - color. Default white.
  • label, vertlabel
    • noclip - boolean, set to true to allow the element to exceed formspec bounds.
  • image_button
    • alpha - boolean, whether to draw alpha in bgimg. Default true.
    • border - boolean, draw border. Set to false to hide the bevelled button pane. Default false.
    • noclip - boolean, set to true to allow the element to exceed formspec bounds.
  • item_image_button
    • border - boolean, draw border. Set to false to hide the bevelled button pane. Default false.
    • noclip - boolean, set to true to allow the element to exceed formspec bounds.
  • tabheader
    • noclip - boolean, set to true to allow the element to exceed formspec bounds.
    • textcolor - color. Default white.