Scarlet Mod v1.4 Beta
scarlet by sorcerykid
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.
Q: Do I need to add Scarlet as a dependency to my mods?
It is entirely possible to use Scarlet to generate Minetest-compatible formspec strings during development and then place those strings into the code. Scarlet need not be a runtime dependency. While intended as a wrapper library, it is ultimately just a preprocessor.
Q: Is Scarlet a bitmapped GUI, or are forms scalable?
Scarlet supports multiple units (cell, point, and image) that all scale to the user's screen DPI. Pixel precision is not even the goal of Scarlet, although a unit is provided for this purpose (dot).
Q: What future plans are in the works for Scarlet?
The forthcoming release of Scarlet will add support for themeable in-line templates and user-defined element parsers in addition to helper functions for text formatting and input processing.
Q: Is Scarlet becoming obsolete as Rubenwardy claims?
Scarlet is a preprocessor that supports multiple units of measurement, embedded arithmetic expressions, and a variety of aliased and enhanced elements. Scarlet includes a command-line calculator, in-game calculator, and DPI visualization tool. Scarlet is backward compatible and tested on all versions of Minetest as far back as 0.4.14. So it is nowhere near obsolete, and I intend to maintain it as long as possible.
- 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.
Repository:
https://bitbucket.org/sorcerykid/scarlet
Download Archive (.zip)
Download Archive (.tar.gz)
Dependencies:
ActiveFormspecs (optional)
Source Code License:
The MIT License (MIT)
Installation:
- Unzip the archive into the mods directory of your game
- Rename the scarlet-master directory to "scarlet"
- Add "scarlet" as a dependency for any mods using the API
Formspec elements in Minetest currently do not conform to any standard units of measurement. In fact, positions and dimensions can vary widely as illustrated in the following table.
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.
- 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>]
- 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
A handy in-game tool is provided to check your screen DPI settings by typing /dpi into chat.
There may be cases when you need to calculate position or dimension values from different units of measurement. Below is a conversion table for this purpose:
- 1.0b = 0.3c (y-axis)
- 1.0i = 0.8c (x-axis), 0.866c (y-axis)
- 1.0p = 0.020c (x-axis), 0.022c (y-axis)
- Form padding:
0.3c (x-axis), 0.325c (y-axis) - Slot spacing:
0.2c (x-axis), 0.133c (y-axis)
The numeric button pad is fairly self-explanatory. The bottom rows of buttons are grouped by units and variables respectively. Below that are two drop-down menus to switch between x-axis vs y-axis and 72 dpi and 96 dpi.
All standard units of measurement are supported (except for slots) in addition to the following four preset variables:
- $B = button height
- $P = form padding width or form padding height
- $S = slot spacing width or slot spacing height
- $R = the result from the previous calculation
The "C" button clears the input field in preparation for a new entry. The "CE" button reverts the input field to the last recorded entry (which can be useful for undoing a typo as well as recalling an expression after evaluation).
I also included a command line unit-conversion calculator. This is particularly convenient for working offline, rather than repeatedly launching the Minetest client. Aside from the GUI, this tool offers most of the same functionality as the in-game calculator, in addition to nine user-settable variables.
To launch the calculator, just switch to the Scarlet subdirectory and type awk -f calc.awk from the shell.
The script reads from STDIN, so you can feed it a plain text file with a list of commands or you can enter each command manually, in which case a prompt will appear. Here are the available commands:
- dpi <dpi_spec>
Specifies the screen dpi to be used in subsequent calculations.
axis <axis_spec>
Specifies the axis of measurement to be used in subsequent calculations.
eval <expr>
Evaluates the given arithmetic expression, displays the result, and stores the result in preset variable $R.
set <var_spec>
Sets the given user variable to the previous result
add <var_spec>
Sets the given user variable to the sum with previous result
sub <var_spec>
Sets the given user variable to the difference with the previous result
get <var_spec>
Displays the value of the given user variable (similar to eval <var_spec> but the preset variable $R is unchanged).
Scarlet provides two preset translators that can be used immediately in your mods. Both functions return a Minetest-compatible formspec string:
- scarlet.translate_96dpi( fs )
scarlet.translate_72dpi( fs )
- scarlet.translate( fs, screen_dpi, gui_scaling, has_padding )
- fs - the formspec string to be processed
- screen_dpi - pixel density of the client display in dots per inch (72 is default)
- gui_scaling - scaling factor by which to render the GUI widgets (1.0 is default)
- has_padding - whether to maintain the legacy padding (false is default)
Here is an example of a seemingly basic formspec that would ordinarily take some trial and error to layout properly due the numerous inconsistencies described earlier. But, with Scarlet it is very straightforward.
Code: Select all
local fs = scarlet.translate_72dpi(
"size[4.0s,3.3s]" ..
"no_prepend[]" ..
"bgcolor[#333333;false]" ..
"caption[0c,0c;4s,1c;Please enter your credentials to access this restricted area:]" ..
"label[0c,1c;Username:]" ..
"field[0c,1.5c;2s;username;]" ..
"label[2c,1c;Passcode:]" ..
"pwdfield[2c,1.5c;2s;passcode]" ..
"button[1c,2.5c;2c,1b;confirm;Confirm]"
)
Code: Select all
size[4.000,3.067]
no_prepend[]
bgcolor[#333333;false]
textarea[0.300,-0.025;4.000,1.483;;Please enter your credentials to access this restricted area:;]
label[0.000,1.117;Username:]
field[0.300,2.175;2.000,0.000;username;;]
label[2.000,1.117;Passcode:]
pwdfield[2.300,2.175;2.000,0.000;passcode;]
image_button[1.000,2.500;2.200,0.833;;confirm;Confirm]