formspec

From Minetest Developer Wiki
Jump to: navigation, search

Formspec defines a menu. Currently not much else than inventories are supported. It is a string, with a somewhat strange format.

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

Contents

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

Position and size units are inventory slots.

size

Define the size of the menu in inventory slots.

size[W,H]

list

Show an inventory list.

list[inventory_location;list_name;X,Y;W,H;]
list[inventory_location;list_name;X,Y;W,H;starting_item_index]

image

Show an image.

image[X,Y;W,H;texture_name]

field

Textual field; will be sent to server when a button is clicked.

field[X,Y;W,H;name;label;default]
  • 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 centered on H
  • 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.png
Note: no extra text or more than a single variable is supported at the moment.


Another form, field[name;label;default], can be used for creating simple forms, such as sign text input. Note that there must be no size[] element and a 'Proceed' button will be added automatically.

pwdfield

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

Same as above but with a password style.

textarea

Multi-line text field

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

Parameters work as per field
You may need to use minetest.formspec_escape to avoid problems.

label

label[X,Y;label]

X and Y work as per field, label is the text on the label.

vertlabel

vertlabel[X,Y;label]

Same as above, but drawn vertically.

button

Clickable button. When clicked, fields will be sent.

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

X and Y work as per field, W and H are the size of the button, label is the text on the button

image_button

image_button[X,Y;W,H;image;name;label]

X, Y, W, H, and name work as per button, image is the filename of an image

item_image_button

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

X, Y, W, H, and name work as per button

item name is the registered name of an item/node, tooltip will be made out of its description.

button_exit

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

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

image_button_exit

image_button_exit[X,Y;W,H;image;name;label]

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

listcolors

listcolors[slot_bg_normal;slot_bg_hover]
listcolors[slot_bg_normal;slot_bg_hover;slot_border]
listcolors[slot_bg_normal;slot_bg_hover;slot_border;tooltip_bgcolor;tooltip_fontcolor]
  • slot_bg_normal Sets background color of slots in HEX-Color format
  • slot_bg_hover Sets background color of slots on mouse hovering
  • slot_border Sets color of slots border
  • tooltip_bgcolor Sets background color of tooltips
  • tooltip_fontcolor Sets font color of the tooltips

bgcolor

bgcolor[color;fullscreen;]

Sets background color of a formspec in HEX-Color format If fullscreen is true, the background color is drawn fullscreen (does not affect the size of the formspec)

background

background[X,Y;W,H;texture_name]
background[X,Y;W,H;texture_name;auto_clip]

Uses 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*16px x 4*16px. If auto_clip is true, the background is clipped to formspec size (x and y are used as offset values, w and h are ignored)

textlist

textlist[X,Y;W,H;name;listelem 1,listelem 2,...,listelem n]
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 singleclick or doubleclick value is current selected element, with a prefix of CHG: for singleclick and "DBL:" for doubleclick. Use minetest.explode_table_event(string) Listelements can be prepended by #color in hexadecimal format RRGGBB

note.png
Note: If you wish to use the character #, escape it with another # like so: ##


  • Selected idx Index to be selected within textlist
  • Transparent True/false to draw transparent background

See also: Lua Table Formspec

dropdown

dropdown[X,Y;W,H;name;item1,item2,item3...;selected_id]

Pulldown select menu that sends the name of the selected item on selection. This behavior is markedly different than the textlist, which returns the selected item's id.

Showing Formspecs

Showing a formspec can be done with minetest.show formspec.

Examples

minetest.show_formspec(player:get_player_name(), "default:team_choose", formspec)

Events

Sometimes you want to do something when a player has used a formspec. This is where minetest.register_on_player_receive_fields comes in handy!

Examples

minetest.register_on_player_receive_fields(function(player, formname, fields)
	if formname == "default:team_choose" then -- Replace this with your form name
		print("Player "..player:get_player_name().." submitted fields "..dump(fields))
	end
end)

Output: Player LemonLake submitted fields {["quit"] = "true"}

Personal tools
Namespaces

Variants
Actions
Navigation
API
Toolbox