Documentation pass, part 1

- Also added more optional parameters to the gui api
This commit is contained in:
Hugues Ross 2020-06-13 07:41:56 -04:00
parent a6b96fa28f
commit ca910ad29d
6 changed files with 242 additions and 29 deletions

View File

@ -1,5 +1,9 @@
-- Audio API (Internal)
--
-- Contains functions for providing audio feedback
local audio = { local audio = {
-- Play a feedback sound localized on the given player -- Play a feedback sound localized on the given player
--
-- sound: The sound to play -- sound: The sound to play
-- player: The player who triggered the sound -- player: The player who triggered the sound
play_feedback = function(sound, player) play_feedback = function(sound, player)

View File

@ -1,3 +1,7 @@
-- Arguments
-- chunk: The chunk coordinate conversion API
-- scanner: The map scanning API
-- maps: The map API
local chunk, scanner, maps = ...; local chunk, scanner, maps = ...;
-- Periodically-called function to fill in maps and queue chunks for manual -- Periodically-called function to fill in maps and queue chunks for manual

View File

@ -1,9 +1,13 @@
-- Arguments
-- util: API for uncategorized utility methods
local util = ...; local util = ...;
local biome_lookup = {}; local biome_lookup = {};
-- Contains functions for registering and getting biome-related mapping information
return { return {
-- Register a biome with textures to display -- Register a biome with textures to display
--
-- name: A string containing the biome name -- name: A string containing the biome name
-- textures: A table of texture names. -- textures: A table of texture names.
-- These should correspond with detail levels, -- These should correspond with detail levels,
@ -20,9 +24,11 @@ return {
end, end,
-- Get the texture name (minus index/extension) for the given biome, height, and detail level. -- Get the texture name (minus index/extension) for the given biome, height, and detail level.
--
-- name: A string containing the biome name -- name: A string containing the biome name
-- height: A number representing the Y position of the biome -- height: A number representing the Y position of the biome
-- detail: The detail level -- detail: The detail level
--
-- Returns a string with a texture name, or nil if no matching biome entry was found. -- Returns a string with a texture name, or nil if no matching biome entry was found.
get_texture = function (name, height, detail) get_texture = function (name, height, detail)
for _,biome in ipairs(biome_lookup) do for _,biome in ipairs(biome_lookup) do

View File

@ -1,3 +1,7 @@
-- Arguments
-- chunk: The chunk coordinate conversion API
-- audio: The audio playback API
-- map_formspec: The map display API
local chunk, audio, map_formspec = ...; local chunk, audio, map_formspec = ...;
local MAXINT = 2147483647; local MAXINT = 2147483647;

View File

@ -1,5 +1,19 @@
local gui = {}; -- Gui API (Internal)
--
-- Contains functions for building formspec-based uis
local gui = {
};
-- Create a formspec
--
-- w: The width of the window
-- h: The height of the window
-- (Optional) version: The formspec version. Defaults to 3.
-- (Optional) bg: A 9-slice background skin object
-- Additional arguments are added as additional formspec elements
--
-- Returns a table. Calling table.concat on the result will produce
-- a usable formspec string.
function gui.formspec(args) function gui.formspec(args)
local data = string.format("formspec_version[%d] size[%f,%f]", args.version or 3, args.w, args.h); local data = string.format("formspec_version[%d] size[%f,%f]", args.version or 3, args.w, args.h);
@ -17,51 +31,129 @@ function gui.formspec(args)
return data; return data;
end end
-- Create an animated image formspec element
--
-- animation: An animation skin object
-- (Optional) x: The x position of the element. Defaults to 0.
-- (Optional) y: The y position of the element. Defaults to 0.
-- (Optional) w: The width of the element. Defaults to 1.
-- (Optional) h: The height of the element. Defaults to 1.
-- (Optional) size: Multiplies the width and height. Defaults to 1.
-- (Optional) id: The element id
--
-- Returns a formspec string
function gui.animated_image(args) function gui.animated_image(args)
local x = args.x or 0;
local y = args.y or 0;
local w = args.w or 1 * (args.size or 1);
local h = args.h or 1 * (args.size or 1);
return string.format("animated_image[%f,%f;%f,%f;%s;%s;%d;%d]", return string.format("animated_image[%f,%f;%f,%f;%s;%s;%d;%d]",
args.x, args.y, x, y,
args.w, args.h, w, h,
args.id or "", args.id or "",
args.animation.texture .. ".png", args.animation.texture .. ".png",
args.animation.frame_count, args.animation.frame_count,
args.animation.frame_duration); args.animation.frame_duration);
end end
-- Create a 9-slice background formspec element
--
-- skin: A 9-slice background skin object
-- (Optional) x: The x position of the element. Defaults to 0.
-- (Optional) y: The y position of the element. Defaults to 0.
-- (Optional) w: The width of the element. Defaults to 1.
-- (Optional) h: The height of the element. Defaults to 1.
-- (Optional) size: Multiplies the width and height. Defaults to 1.
-- (Optional) fullsize: Whether or not to fill the parent formspec. Defaults to false.
--
-- Returns a formspec string
function gui.bg9(args) function gui.bg9(args)
local x = args.x or 0;
local y = args.y or 0;
local w = args.w or 1 * (args.size or 1);
local h = args.h or 1 * (args.size or 1);
return string.format("background9[%f,%f;%f,%f;%s;%s;%s]", return string.format("background9[%f,%f;%f,%f;%s;%s;%s]",
args.x or 0, args.y or 0, x, y,
args.w or 1 * (args.size or 1), args.h or 1 * (args.size or 1), w, h,
args.skin.texture .. ".png", args.skin.texture .. ".png",
args.fullsize or false, args.fullsize or false,
tostring(args.skin.radius)); tostring(args.skin.radius));
end end
-- Create a button formspec element
--
-- (Optional) text: The text to display on the button
-- (Optional) x: The x position of the element. Defaults to 0.
-- (Optional) y: The y position of the element. Defaults to 0.
-- (Optional) w: The width of the element. Defaults to 1.
-- (Optional) h: The height of the element. Defaults to 1.
-- (Optional) size: Multiplies the width and height. Defaults to 1.
-- (Optional) id: The element id
-- (Optional) tooltip: The tooltip to display when hovering this element.
-- (Optional) disabled: Replaces the id with "disabled_button", allowing it to
-- receive a specific style
--
-- Returns a formspec string
function gui.button(args) function gui.button(args)
local x = args.x or 0;
local y = args.y or 0;
local w = args.w or 1 * (args.size or 1);
local h = args.h or 1 * (args.size or 1);
if args.disabled then if args.disabled then
return string.format("button[%f,%f;%f,%f;disabled_button;%s]", args.x, args.y, args.w, args.h, args.text); return string.format("button[%f,%f;%f,%f;disabled_button;%s]", x, y, w, h, args.text or "");
end end
local data = string.format("button[%f,%f;%f,%f;%s;%s]", args.x, args.y, args.w, args.h, args.id, args.text); local data = string.format("button[%f,%f;%f,%f;%s;%s]", x, y, w, h, args.id or "", args.text or "");
if args.tooltip then if args.tooltip then
data = data .. gui.tooltip { if args.id and not args.disabled then
id = args.id, data = data .. gui.tooltip {
text = args.tooltip id = args.id,
}; text = args.tooltip
};
else
data = data .. gui.tooltip {
x = x,
y = y,
w = w,
h = h,
text = args.tooltip
};
end
end end
return data; return data;
end end
-- Create a formspec container
--
-- (Optional) x: The x offset of the container. Defaults to 0.
-- (Optional) y: The y offset of the container. Defaults to 0.
-- (Optional) w: The width of the container (for drawing a background). Defaults to 1.
-- (Optional) h: The height of the container (for drawing a background). Defaults to 1.
-- (Optional) size: Multiplies the width and height. Defaults to 1.
-- (Optional) bg: A 9-slice background skin object
--
-- Additional arguments are added as the container's child elements
--
-- Returns a formspec string
function gui.container(args) function gui.container(args)
local data = string.format("container[%f,%f]", args.x, args.y); local x = args.x or 0;
local y = args.y or 0;
local w = args.w or 1 * (args.size or 1);
local h = args.h or 1 * (args.size or 1);
local data = string.format("container[%f,%f]", x, y);
if args.bg then if args.bg then
data = data .. gui.bg9 { data = data .. gui.bg9 {
x = 0, x = 0,
y = 0, y = 0,
w = args.w, w = w,
h = args.h, h = h,
skin = args.bg, skin = args.bg,
}; };
@ -74,28 +166,93 @@ function gui.container(args)
return data .. "container_end[]"; return data .. "container_end[]";
end end
-- Create an image formspec element
--
-- image: The image to display.
-- (Optional) x: The x offset of the container. Defaults to 0.
-- (Optional) y: The y offset of the container. Defaults to 0.
-- (Optional) w: The width of the container (for drawing a background). Defaults to 1.
-- (Optional) h: The height of the container (for drawing a background). Defaults to 1.
-- (Optional) size: Multiplies the width and height. Defaults to 1.
--
-- Returns a formspec string
function gui.image(args) function gui.image(args)
return string.format("image[%f,%f;%f,%f;%s]", args.x, args.y, args.w, args.h, args.image); local x = args.x or 0;
local y = args.y or 0;
local w = args.w or 1 * (args.size or 1);
local h = args.h or 1 * (args.size or 1);
return string.format("image[%f,%f;%f,%f;%s]", x, y, w, h, args.image);
end end
-- Create an image button formspec element
--
-- image: The image to display on the button
-- (Optional) text: The text to display on the button
-- (Optional) x: The x position of the element. Defaults to 0.
-- (Optional) y: The y position of the element. Defaults to 0.
-- (Optional) w: The width of the element. Defaults to 1.
-- (Optional) h: The height of the element. Defaults to 1.
-- (Optional) size: Multiplies the width and height. Defaults to 1.
-- (Optional) id: The element id
-- (Optional) tooltip: The tooltip to display when hovering this element.
-- (Optional) disabled: Replaces the id with "disabled_button", allowing it to
-- receive a specific style
--
-- Returns a formspec string
function gui.image_button(args) function gui.image_button(args)
local x = args.x or 0;
local y = args.y or 0;
local w = args.w or 1 * (args.size or 1);
local h = args.h or 1 * (args.size or 1);
if args.disabled then
return string.format("image_button[%f,%f;%f,%f;%s;disabled_button;%s]",
x, y,
w, h,
args.image,
args.text or "");
end
local data = string.format("image_button[%f,%f;%f,%f;%s;%s;%s]", local data = string.format("image_button[%f,%f;%f,%f;%s;%s;%s]",
args.x, args.y, x, y,
args.w, args.h, w, h,
args.image, args.image,
args.id, args.id or "",
args.text or ""); args.text or "");
if args.tooltip then if args.tooltip then
data = data .. gui.tooltip { if args.id and not args.disabled then
id = args.id, data = data .. gui.tooltip {
text = args.tooltip id = args.id,
}; text = args.tooltip
};
else
data = data .. gui.tooltip {
x = x,
y = y,
w = w,
h = h,
text = args.tooltip
};
end
end end
return data; return data;
end end
-- Create an inventory list formspec element
--
-- location: The location of the inventory
-- id: The id of the inventory list
-- w: The number of columns in the inventory list
-- h: The number of rows in the inventory list
-- (Optional) x: The x position of the element. Defaults to 0.
-- (Optional) y: The y position of the element. Defaults to 0.
-- (Optional) bg: A 9-slice background skin object (To display under each slot)
-- (Optional) tooltip: The tooltip to display when hovering this element.
--
-- Returns a formspec string
function gui.inventory(args) function gui.inventory(args)
local data = ""; local data = "";
@ -112,7 +269,10 @@ function gui.inventory(args)
end end
end end
data = data .. string.format("list[%s;%s;%f,%f;%f,%f;]", args.location, args.id, args.x, args.y, args.w, args.h); data = data .. string.format("list[%s;%s;%f,%f;%f,%f;]",
args.location, args.id,
args.x or 0, args.y or 0,
args.w, args.h);
if args.tooltip then if args.tooltip then
data = data .. gui.tooltip { data = data .. gui.tooltip {
@ -127,19 +287,27 @@ function gui.inventory(args)
return data; return data;
end end
-- Create a label formspec element
--
-- text: The text of the label
-- (Optional) textcolor: The color of the label
-- (Optional) x: The x position of the element. Defaults to 0.
-- (Optional) y: The y position of the element. Defaults to 0.
--
-- Returns a formspec string
function gui.label(args) function gui.label(args)
if args.textcolor then if args.textcolor then
return string.format("label[%f,%f;%s%s]", return string.format("label[%f,%f;%s%s]",
args.x, args.x or 0,
args.y, args.y or 0,
minetest.get_color_escape_sequence(args.textcolor), minetest.get_color_escape_sequence(args.textcolor),
args.text); args.text);
end end
return string.format("label[%f,%f;%s]", args.x, args.y, args.text); return string.format("label[%f,%f;%s]", args.x or 0, args.y or 0, args.text);
end end
function gui.style_internal(selector, properties) local function style_internal(selector, properties)
local data = "[" .. selector; local data = "[" .. selector;
for name,value in pairs(properties) do for name,value in pairs(properties) do
data = data .. string.format(";%s=%s", name, tostring(value)); data = data .. string.format(";%s=%s", name, tostring(value));
@ -147,14 +315,37 @@ function gui.style_internal(selector, properties)
return data .. "]"; return data .. "]";
end end
-- Create a formspec style
--
-- selector: A valid comma-separated list of id-based style selectors
-- properties: A table of property names and values
--
-- Returns a formspec string
function gui.style(args) function gui.style(args)
return "style" .. gui.style_internal(args.selector, args.properties); return "style" .. style_internal(args.selector, args.properties);
end end
-- Create a formspec style
--
-- selector: A valid comma-separated list of type-based style selectors
-- properties: A table of property names and values
--
-- Returns a formspec string
function gui.style_type(args) function gui.style_type(args)
return "style_type" .. gui.style_internal(args.selector, args.properties); return "style_type" .. style_internal(args.selector, args.properties);
end end
-- Create a formspec tooltip element
--
-- text: The text of the tooltip
-- (Optional) id: The ID of the element to display on
--
-- (Required when id == nil) x: The x position of the element
-- (Required when id == nil) y: The y position of the element
-- (Required when id == nil) w: The width of the element
-- (Required when id == nil) h: The height of the element
--
-- Returns a formspec string
function gui.tooltip(args) function gui.tooltip(args)
if args.id then if args.id then
return string.format("tooltip[%s;%s]", args.id, args.text); return string.format("tooltip[%s;%s]", args.id, args.text);

View File

@ -27,6 +27,7 @@ local function map_get_marker(map, x, y)
end end
-- Get the variant of the tile at a given position -- Get the variant of the tile at a given position
--
-- prefix: The part of the tile texture name before the variant -- prefix: The part of the tile texture name before the variant
-- x: The X position of the tile (in map coordinates) -- x: The X position of the tile (in map coordinates)
-- z: The Z position of the tile (in map coordinates) -- z: The Z position of the tile (in map coordinates)
@ -38,6 +39,7 @@ local function get_variant(prefix, x, z, noise)
end end
-- Generate formspec markup for a given map -- Generate formspec markup for a given map
--
-- x: The X position of the map (in map coordinates) -- x: The X position of the map (in map coordinates)
-- y: The Z position of the map (in map coordinates) -- y: The Z position of the map (in map coordinates)
-- w: The width of the map (in map coordinates) -- w: The width of the map (in map coordinates)
@ -157,6 +159,7 @@ end
local map_formspec = {}; local map_formspec = {};
-- Get the formspec for a given map segment -- Get the formspec for a given map segment
--
-- x: The X position of the map, in map coordinates -- x: The X position of the map, in map coordinates
-- y: The Y position of the map, in map coordinates -- y: The Y position of the map, in map coordinates
-- w: The width of the map, in map coordinates -- w: The width of the map, in map coordinates
@ -179,6 +182,7 @@ function map_formspec.from_coords(x, y, w, h, detail, scale, height_mode)
end end
-- Get the formspec for a given map table -- Get the formspec for a given map table
--
-- map: The map to use -- map: The map to use
-- x: The X position of the player marker, in map coordinates -- x: The X position of the player marker, in map coordinates
-- y: The Y position of the player marker, in map coordinates -- y: The Y position of the player marker, in map coordinates