In this chapter we will learn how to create a formspec and display it to the user. A formspec is the specification code for a form. In Minetest, forms are windows like the Inventory which allow you to move your mouse and enter information. You should consider using Heads Up Display (HUD) elements if you do not need to get user input - notifications, for example - as unexpected windows tend to disrupt game play.
Formspecs have a rather weird syntax. They consist of a series of tags which are in the following form:
Firstly the element type is declared, and then the attributes are given in square brackets.
(An element is an item such as a text box or button, or it is meta data such as size or background).
Here are two elements, of types foo and bar.
Nearly all forms have a size tag. They are used to declare the size of the window required. Forms don’t use pixels as co-ordinates, they use a grid, based on inventories. A size of (1, 1) means the form is big enough to host a 1x1 inventory. The reason this is used is because it is independent on screen resolution - The form should work just as well on large screens as small screens. You can use decimals in sizes and co-ordinates.
Co-ordinates and sizes only use one attribute. The x and y values are separated by a comma, as you can see above.
This is a textbox element. Most other elements have a similar style of attributes. The “name” attribute is used in callbacks to get the submitted information. The others are pretty self-explaintary.
It is perfectly valid to not define an attribute, like above.
You should look in lua_api.txt for a list of all possible elements, just search for “Formspec”. It is near line 1019, at time of writing.
Here is a generalized way to show a formspec
minetest.show_formspec(playername, formname, formspec)
Formnames should be itemnames, however that is not enforced. There is no need to override a formspec here, formspecs are not registered like nodes and items are, instead the formspec code is sent to the player’s client for them to see, along with the formname. Formnames are used in callbacks to identify which form has been submitted, and see if the callback is relevant.
The above example shows a formspec to a player when they use the /formspec command.
Note: the .. is used to join two strings together. The following two lines are equivalent:
Let’s expand on the above example.
The function given in minetest.register_on_player_receive_fields is called everytime a user submits a form. Most callbacks will check the formname given to the function, and exit if it is not the right form. However, some callbacks may need to work on multiple forms, or all forms - it depends on what you want to do.
The fields parameter to the function is a table, index by string, of the values submitted by the user. You can access values in the table by doing fields.name, where ‘name’ is the name of the element.
As well as having the values of each element, you can also get which button was clicked. In this case, the button called ‘exit’ was clicked, so fields.exit will be true.
Some elements can submit the form without the user having to click a button, such as a check box. You can detect for these cases by looking for a clicked button.
In quite a lot of cases you want your minetest.show_formspec to give information to the callback which you don’t want to have to send to the client. Information such as what a chat command was called with, or what the dialog is about.
Let’s say you are making a form to handle land protection information.
minetest.show_formspec is not the only way to show a formspec, you can also add formspecs to a node’s meta data. This is used on nodes such as chests to allow for faster opening times - you don’t need to wait for the server to send the player the chest formspec.
Formspecs set this way do not trigger the same callback. In order to
receive form input for meta formspecs, you must include an
on_receive_fields entry when registering the node.
This style of callback can trigger the callback when you press enter
in a field, which is impossible with
however, this kind of form can only be shown by right-clicking on a
node. It cannot be triggered programmatically.