From 4b9afcf97d7c56485f07d88ecb16d3f2f89eea1a Mon Sep 17 00:00:00 2001 From: Vanic Date: Tue, 20 Jan 2026 14:11:22 +0300 Subject: [PATCH] Formspec: add some methods. #8 --- mods/CORE/Formspec/src/Formspec.lua | 262 +++++++++++++++++++++++++--- 1 file changed, 236 insertions(+), 26 deletions(-) diff --git a/mods/CORE/Formspec/src/Formspec.lua b/mods/CORE/Formspec/src/Formspec.lua index f5c0b20..a785ad4 100644 --- a/mods/CORE/Formspec/src/Formspec.lua +++ b/mods/CORE/Formspec/src/Formspec.lua @@ -7,22 +7,38 @@ local Formspec = { ---@class FormspecDef ---Set the formspec version to a certain number. If not specified, version `10` is assumed. +--- +---**Element:** `formspec_version[]` ---@field version? number ----Define the size of the menu in inventory slots. `fixed_size` is optional, default `true` +---Define the size of the menu in inventory slots. `fixed_size` is optional, default `true`. +--- +---**Element:** `size[,,]` ---@field size? {x:number, y:number, fixed_size:boolean?} ---Defines the position on the game window of the formspec's anchor point. +--- +---**Element:** `position[,]` ---@field position? {x:number, y:number} ---Defines the location of the anchor point within the formspec. +--- +---**Element:** `anchor[,]` ---@field anchor? {x:number, y:number} ---Defines how much space is padded around the formspec if the formspec tries to increase ---past the size of the screen and coordinates have to be shrunk. +--- +---**Element:** `padding[,]` ---@field padding? {x:number, y:number} ---Disables player:set_formspec_prepend() from applying to this formspec. +--- +---**Element:** `no_prepend[]` ---@field noPrepend? boolean ---When set to true, all following formspec elements will use the new coordinate system. +--- +---**Element:** `real_coordinates[]` ---@field realCoordinates? boolean ---When set to false, the formspec will not close when the user tries to close ---it with the Escape key or similar. Default true. +--- +---**Element:** `allow_close[]` ---@field allowClose? boolean ---@param def FormspecDef? @@ -115,6 +131,8 @@ end ---Start of a container block, moves all physical elements in the container by (X, Y). ---Containers can be nested, in which case the offsets are added (child containers are relative to parent containers). +--- +---**Elements:** `container[,]` & `container_end[]` ---@param container Formspec ---@param x number ---@param y number @@ -129,6 +147,8 @@ end ---be additionally moved by the current value of the scrollbar with ---the name `scrollbar name` times `scroll factor` along the orientation `orientation` and ---be clipped to the rectangle defined by `X`, `Y`, `W` and `H`. +--- +---**Elements:** `scroll_container[,;,;;;;]` & `scroll_container_end[]` ---@param container Formspec ---@param x number ---@param y number @@ -148,25 +168,31 @@ end ---@alias Formspec.ListDef {inventoryLocation:string, listName:string, x:number, y:number, w:number, h:number,startingItemIndex:number} +---Show an inventory list if it has been sent to the client. +---If the inventory list changes (eg. it didn't exist before, it's resized, +---or its items are moved) while the formspec is open, the formspec element may +---(but is not guaranteed to) adapt to the new inventory list. +---Item slots are drawn in a grid from left to right, +---then up to down, ordered according to the slot index. +--- +---**Element:** `list[;;,;,;]` ---@param inventoryLocation string ---@param listName string ---@param x number ---@param y number ----@param w number Are in inventory slots, not in coordinates. ----@param h number Are in inventory slots, not in coordinates. ----@param startingItemIndex number? -function Formspec:list(inventoryLocation, listName, x, y, w, h,startingItemIndex) - if startingItemIndex == nil then - startingItemIndex = 0 - end - +---@param w number Are in inventory slots, not in coordinates. +---@param h number Are in inventory slots, not in coordinates. +---@param startingItemIndex number? The index of the first (upper-left) item to draw. Indices start at `0`. Default is `0`. +function Formspec:list(inventoryLocation, listName, x, y, w, h, startingItemIndex) local element = ('list[%s;%s;%s,%s;%s,%s;%s]'):format( - inventoryLocation, listName, x, y, w, h,startingItemIndex) + inventoryLocation, listName, x, y, w, h,startingItemIndex or '') self:addElement(element) end ---TODO: немного отличается от листринга луанти, так что надо дописать подробности +--- +---**Elements:** `listring[;]` or `listring[]` ---@param lists [string, string][]? List of looping lists in the format `[inventory location, list name]` function Formspec:listring(lists) if lists == nil then @@ -209,6 +235,8 @@ function Formspec:listColors(slotBackgroundNormal, slotBackgroundHover, slotBord end ---Adds tooltip for an element. +--- +---**Element:** `tooltip[;;;]` ---@param elementName string ---@param tooltipText string ---@param bgcolor ColorString? @@ -221,6 +249,8 @@ function Formspec:tooltipForElement(elementName, tooltipText, bgcolor, fontcolor end ---Adds tooltip for an area. Other tooltips will take priority when present. +--- +---**Element:** `tooltip[,;,;;;]` ---@param x number ---@param y number ---@param w number @@ -236,6 +266,8 @@ function Formspec:tooltipForArea(x, y, w, h, tooltipText, bgcolor, fontcolor) end ---Show an image. +--- +---**Element:** `image[,;,;;]` ---@param x number ---@param y number ---@param w number @@ -251,6 +283,8 @@ end ---Show an animated image. The image is drawn like a "vertical_frames" tile animation ---(See Tile animation definition), but uses a frame count/duration for simplicity. +--- +---**Element:** `animated_image[,;,;;;;;;]` ---@param x number ---@param y number ---@param w number @@ -272,6 +306,8 @@ function Formspec:animatedImage(x, y, w, h, textureName, frameCount, frameDurati end ---Show a mesh model. +--- +---**Element:** `model[,;,;;;;;;;;]` ---@param x number ---@param y number ---@param w number @@ -292,6 +328,8 @@ function Formspec:model(x, y, w, h, name, mesh, textures, rotation, continuous, end ---Show an inventory image of registered item/node. +--- +---**Element:** `item_image[,;,;]` ---@param x number ---@param y number ---@param w number @@ -311,6 +349,8 @@ end --- * `true`: Only the fullscreen background color is drawn. --- * `both`: The non-fullscreen and the fullscreen background color are drawn. --- * `neither`: No background color is drawn. +--- +---**Element:** `bgcolor[;;]` ---@param bgcolor ColorString Define the color of the non-fullscreen and the fullscreen background. ---@param fullscreen 'false'|'true'|'both'|'neither' ---@param fbgcolor ColorString? Define the color of the non-fullscreen and the fullscreen background. @@ -322,6 +362,8 @@ function Formspec:bgcolor(bgcolor, fullscreen, fbgcolor) end ---Example for formspec 8x4 in 16x resolution: image shall be sized 8 times 16px times 4 times 16px. +--- +---**Element:** `background[,;,;]` or `background[,;,;;]` ---@param x number ---@param y number ---@param w number @@ -345,6 +387,8 @@ function Formspec:background(x, y, w, h, textureName, autoClip) end ---9-sliced background. See https://en.wikipedia.org/wiki/9-slice_scaling +--- +---**Element:** `background9[,;,;;;]` ---@param x number ---@param y number ---@param w number @@ -373,6 +417,8 @@ end ---With the new coordinate system, `H` will modify the height. --- ---See field_close_on_enter to stop enter closing the formspec. +--- +---**Element:** `pwdfield[,;,;;