Scarlet

Scarlet (Saner Coordinates and Rational Layouts Expression Translator) is a thin-wrapper library that provides consistent and uniform layout of all elements within Minetest formspecs. Being a purely Lua-based implementation has the advantage that backwards compatibility even with legacy versions of Minetest is assured. No patches and/or upgrades to the engine are required.

Overview

Here is a quick summary of the various oddities and inconsistencies (many of which are still undocumented) that I have addressed:

• Strange, fractional offsets
  With the exception of pwdfield[], field[], and textarea[], all other elements are offset from the form origin. As a result, precise alignments must be achieved through trial-and-error. Therefore, I added an optional border parameter to the margin[] element.

• Image ratios, only sometimes
  For some reason, background images and button images are scaled according to inventory slot spacing whereas images and item images are scaled by inventory image dimensions. Therefore, I provided a means to specify either unit of measurement.

• Overloading of elements
  Certain elements like background[] and tooltip[] accept different lists of parameters. This is both error-prone and difficult to remember. Therefore, I separated these into distinct elements: background[] vs. bgimage[] and tooltip[] vs. area_tooltip[], etc.

• Height restriction of buttons
  Text-only buttons are constrained to a uniform height. However, an undocumented feature of image_button[] exists to bypass this limitation. Therefore, I mapped the button[] element to image_button[] with the appropriate parameters behind the scenes.

• Backwards ordering of parameters
  All named elements expect the name parameter to follow the position and dimension parameters, except for image_button[] and item_image_button[] where the texture name or item name takes precedence. Therefore, I reversed these two parameters.

Scarlet has been successfully tested with Minetest 0.4.15, 0.4.17, and 5.0.0. This mod is still in alpha and changes are to be expected. However, I will make every effort to reduce breakage between versions whenever possible.

Usage Instructions

Formspec elements in Minetest 0.4.x and Minetest 5.0 do not conform to any standard units of measurement. In fact, positions and dimensions can vary widely as illustrated in the following table.

A cell unit represents the interval between the left (or top) edge of one inventory slot to the left (or top) edge of a subsequent inventory slot. An image size unit represents the width (or height) of one or more inventory images. A slot unit represents the interval between the left (or top) edge of one inventory slot to the right (or bottom) edge of a subsequent inventory slot.

For simplicity and convenience, Scarlet provides six interchangeable units of measurement: dot, point, slot, cell, image size, and button height. Button heights, of course, only apply to y-axis position and dimension values. And slots pertain solely to dimension values.

For each of the following elements, <w>,<h> is a dimension value and <x>,<y> is a position value. Note that a few elements only accept a <w> dimension value.

• size[<w>,<h>]

• size[<w>,<h>;<border_x>,border_y]

• container[<x>,<y>]

• margin[<margin_x>,<margin_y>]

• list[<inventory_location>;<list_name>;<x>,<y>;<columns>,<rows>;<starting_item_index>]

• box[<x>,<y>;<w>,<h>;<color>]

• image[<x>,<y>;<w>,<h>;<texture_name>]

• item_image[<x>,<y>;<w>,<h>;<item_name>]

• bgimage[<x>,<y>;<w>,<h>;<texture_name>]

• background[<w>,<h>;<texture name>]

• label[<x>,<y>;<label_text>]

• vertlabel[<x>,<y>;<label_text>]

• checkbox[<x>,<y>;<name>;<label>;<selected>]

• button[<x>,<y>;<w>,<h>;<name>;<label>]

• button[<x>,<y>;<w>,<h>;<name>;<label>;<noclip>;<border>]

• button_exit[<x>,<y>;<w>,<h>;<name>;<label>]

• button_exit[<x>,<y>;<w>,<h>;<name>;<label>;<noclip>;<border>]

• image_button[<x>,<y>;<w>,<h>;<name>;<texture_name>;<label>]

• image_button[<x>,<y>;<w>,<h>;<name>;<texture_name>;<label>;<noclip>;<border>;<pressed_texture_name>]

• item_image_button[<x>,<y>;<w>,<h>;<name>;<item_name>;<label>]

• dropdown[<x>,<y>;<w>;<name>;<item_1>,...;<selected_idx>]

• textlist[<x>,<y>;<w>,<h>;<name>;<item_1>,...;<selected_idx>]

• pwdfield[<x>,<y>;<w>;<name>]

• field[<x>,<y>;<w>;<name>;<default_text>]

• caption[<x>,<y>;<w>,<h>;<caption>]

• textarea[<x>,<y>;<w>,<h>;<name>;<default>]

• horz_scrollbar[<x>,<y>;<w>,<h>;<name>;<value>]

• vert_scrollbar[<x>,<y>;<w>,<h>;<name>;<value>]

• table[<x>,<y>;<w>,<h>;<name>;<cell_1>,...;<selected_idx>]

• tabheader[<x>,<y>;<w>,<h>;<name>;<value>]

• area_tooltip[<x>,<y>;<w>,<h>;<tooltip_text>;<bgcolor>;<fontcolor>]

Measurements may be expressed as integers or floating points, with the exception of dots which are always integers. Each value may be suffixed by a single letter indicating the unit of measurement. Here are some examples:

• box[0p,0p;100p,10d;#FFFFFF]
  Box 100 points wide and 10 dots tall.

• button[0c,0c;2s,1b;clickme;Click Me!]
  Button 2 slots wide and 1 button height tall

Position values are signed, whereas dimension values are unsigned. This permits placement of elements anywhere relative to the form origin and any parent containers.

All units of measurement are independent of pixel density, with the exception of dots which have a 1:1 correspondence to pixels. Hence, if you need pixel-based precision, then you should use dots with the correct translator above. Points will scale to maintain a consistent dot pitch of 72 points per inch, in accordance with the official standard (this assumes that the client's screen_dpi setting is correct).

An interactive GUI-based calculator can be accessed by issuing the /scarlet command (requires "server" privilege).