diff --git a/classes/AreaStore.lua b/classes/AreaStore.lua index 7a35941..5261dda 100644 --- a/classes/AreaStore.lua +++ b/classes/AreaStore.lua @@ -1,7 +1,9 @@ +--- @diagnostic disable: missing-return + ---- @class AreaStore --- `AreaStore` is a data structure to calculate intersections of 3D cuboid volumes and points. --- Despite its name, mods must take care of persisting AreaStore data. They may use the provided load and write functions for this. +--- @class AreaStore --- @field data string may be used to store and retrieve any mod-relevant information to the specified area. AreaStore = {} diff --git a/classes/HTTPApiTable.lua b/classes/HTTPApiTable.lua index 77b79f3..1c7e1ad 100644 --- a/classes/HTTPApiTable.lua +++ b/classes/HTTPApiTable.lua @@ -1,3 +1,6 @@ +--- @diagnostic disable: missing-return + + --- @class HTTPRequestHandle --- @class HTTPApiTable diff --git a/classes/InvRef.lua b/classes/InvRef.lua index 55d1d4d..96d82c7 100644 --- a/classes/InvRef.lua +++ b/classes/InvRef.lua @@ -1,3 +1,6 @@ +--- @diagnostic disable: missing-return + + --- @class InvRef InvRef = {} diff --git a/classes/ItemStack.lua b/classes/ItemStack.lua index 6ff884f..1e69b0f 100644 --- a/classes/ItemStack.lua +++ b/classes/ItemStack.lua @@ -1,11 +1,14 @@ ----@class ItemStack +--- @diagnostic disable: missing-return + + +--- @class ItemStack ItemStack = {} --- @class ItemStackTable: table --- @field name string --- @field count number --- @field wear number ---- @field metadata string| +--- @field metadata string --- @alias ItemStackString string diff --git a/classes/MetaDataRef.lua b/classes/MetaDataRef.lua index 31c3c42..fe5540a 100644 --- a/classes/MetaDataRef.lua +++ b/classes/MetaDataRef.lua @@ -1,3 +1,6 @@ +--- @diagnostic disable: missing-return + + --- Base class used by [`StorageRef`], [`NodeMetaRef`], [`ItemStackMetaRef`], --- and [`PlayerMetaRef`]. --- @@ -62,6 +65,6 @@ function MetaDataRef:to_table() end function MetaDataRef:from_table(value) end --- * returns `true` if this metadata has the same key-value pairs as `other` ---- @param other +--- @param other any --- @return boolean function MetaDataRef:equals(other) end diff --git a/classes/MetaDataRef/NodeMetaRef.lua b/classes/MetaDataRef/NodeMetaRef.lua index e688c29..3e8ee47 100644 --- a/classes/MetaDataRef/NodeMetaRef.lua +++ b/classes/MetaDataRef/NodeMetaRef.lua @@ -1,3 +1,6 @@ +--- @diagnostic disable: missing-return + + --- Node metadata: reference extra data and functionality stored in a node. --- Can be obtained via `minetest.get_meta(pos)`. --- diff --git a/classes/NodeTimerRef.lua b/classes/NodeTimerRef.lua index 71855f7..d601390 100644 --- a/classes/NodeTimerRef.lua +++ b/classes/NodeTimerRef.lua @@ -1,3 +1,6 @@ +--- @diagnostic disable: missing-return + + --- Node Timers: a high resolution persistent per-node timer. --- Can be gotten via `core.get_node_timer(pos)`. --- @class NodeTimerRef diff --git a/classes/ObjectRef.lua b/classes/ObjectRef.lua index e1ed970..80e0913 100644 --- a/classes/ObjectRef.lua +++ b/classes/ObjectRef.lua @@ -1,3 +1,6 @@ +--- @diagnostic disable: missing-return + + --- @class ObjectRef ObjectRef = {} @@ -29,9 +32,10 @@ function ObjectRef:add_velocity(vel) end --- @param pos Position --- @param continuous boolean function ObjectRef:move_to(pos, continuous) end ---- @param puncher ObjectRef another `ObjectRef`, +--- Arguments `time_from_last_punch`, `tool_capabilities`, and `direction` will be replaced with a default value when the caller sets them to nil. +--- @param puncher ObjectRef|Entity|Player another `ObjectRef` --- @param time_from_last_punch number? time since last punch action of the puncher ---- @param direction`: can be `nil` +--- @param direction Position the direction from which the punch came, normalized vector function ObjectRef:punch(puncher, time_from_last_punch, tool_capabilities, direction) end --- @param clicker ObjectRef function ObjectRef:right_click(clicker) end @@ -69,17 +73,20 @@ function ObjectRef:set_animation(frame_range, frame_speed, frame_blend, frame_lo function ObjectRef:get_animation() end --- @param frame_speed number default: `15.0` function ObjectRef:set_animation_frame_speed(frame_speed) end + +--- Attaches object to `parent`. +--- See 'Attachments' section for details. +--- This command may fail silently (do nothing) when it would result in circular attachments. --- @overload fun(parent:ObjectRef) --- @param parent ObjectRef to attach to --- @param bone string default `""` (the root bone) --- @param position Position relative position, default `{x=0, y=0, z=0}` --- @param rotation Position|vector relative rotation in degrees, default `{x=0, y=0, z=0}` --- @param forced_visible boolean to control whether the attached entity should appear in first person, default `false`. ---- * Please also read the [Attachments] section above. ---- * This command may fail silently (do nothing) when it would result ---- in circular attachments. function ObjectRef:set_attach(parent, bone, position, rotation, forced_visible) end ---- @return ObjectRef,string,Position,Position,boolean parent, bone, position, rotation, forced_visible, or nil if it isn't attached. +--- Returns current attachment parameters or nil if it isn't attached. +--- If attached, returns `parent`, `bone`, `position`, `rotation`, `forced_visible`. +--- @return ObjectRef,string,Position,Position,boolean|nil function ObjectRef:get_attach() end --- @return ObjectRef[]|table a list of ObjectRefs that are attached to the object. function ObjectRef:get_children() end diff --git a/classes/ObjectRef/Entity.lua b/classes/ObjectRef/Entity.lua index 5e5e35f..c422a6e 100644 --- a/classes/ObjectRef/Entity.lua +++ b/classes/ObjectRef/Entity.lua @@ -1,3 +1,6 @@ +--- @diagnostic disable: missing-return + + ---@class Entity: ObjectRef Entity = {} diff --git a/classes/ObjectRef/Player.lua b/classes/ObjectRef/Player.lua index 7a311b0..af7eb7d 100644 --- a/classes/ObjectRef/Player.lua +++ b/classes/ObjectRef/Player.lua @@ -1,12 +1,12 @@ +--- @diagnostic disable: missing-return + + --- @class Player: ObjectRef Player = {} ---- @return string -function Player:get_player_name() end --- @return InvRef function Player:get_inventory() end ---TODO: --- returns `""` if is not a player --- @return string function Player:get_player_name() end @@ -120,6 +120,8 @@ function Player:get_player_control() end --- * 8 - place --- * 9 - zoom --- * Returns `0` (no bits set) if the object is not a player. +--- @return number +function Player:get_player_control_bits() end --- @class physics_override_table --- @field speed number multiplier to default walking speed value (default: `1`) @@ -129,8 +131,7 @@ function Player:get_player_control() end --- @field sneak_glitch number whether player can use the new move code replications of the old sneak side-effects: sneak ladders and 2 node sneak jump (default: `false`) --- @field new_move number use new move/sneak code. When `false` the exact old code is used for the specific old sneak behavior (default: `true`) ---- @return physics_override_table -function Player:get_player_control_bits() end +--- set physics override for player --- * `override_table` is a table with the following fields: --- * `speed`: multiplier to default walking speed value (default: `1`) --- * `jump`: multiplier to default jump value (default: `1`) @@ -144,6 +145,7 @@ function Player:get_player_control_bits() end --- @param override_table physics_override_table function Player:set_physics_override(override_table) end --- returns the table given to `set_physics_override` +--- @return physics_override_table function Player:get_physics_override() end --- add a HUD element described by HUD def, returns ID --- number on success @@ -214,8 +216,11 @@ function Player:set_minimap_modes(modes_list, selected_mode) end --- whether `set_sky` accepts this format. Check the legacy format otherwise. --- * Passing no arguments resets the sky to its default values. --- * `sky_parameters` is a table with the following optional fields: ---- * `base_color`: ColorSpec, changes fog in "skybox" and "plain". ---- (default: `#ffffff`) +--- * `base_color`: ColorSpec, changes fog in "skybox" and "plain". (default: `#ffffff`) +--- * `body_orbit_tilt`: Float, rotation angle of sun/moon orbit in degrees. +--- By default, orbit is controlled by a client-side setting, and this field is not set. +--- After a value is assigned, it can only be changed to another float value. +--- Valid range [-60.0,60.0] (default: not set) --- * `type`: Available types: --- * `"regular"`: Uses 0 textures, `base_color` ignored --- * `"skybox"`: Uses 6 textures, `base_color` used as fog. @@ -256,6 +261,18 @@ function Player:set_minimap_modes(modes_list, selected_mode) end --- abides by, `"custom"` uses `sun_tint` and `moon_tint`, while --- `"default"` uses the classic Minetest sun and moon tinting. --- Will use tonemaps, if set to `"default"`. (default: `"default"`) +--- * `fog`: A table containing the following values: +--- * `fog_distance`: integer, set an upper bound for the client's viewing_range. +--- Any value >= 0 sets the desired upper bound for viewing_range, disables range_all and prevents disabling fog (F3 key by default). +--- Any value < 0 resets the behavior to being client-controlled. (default: -1) +--- * `fog_start`: float, override the client's fog_start. +--- Fraction of the visible distance at which fog starts to be rendered. +--- Any value between [0.0, 0.99] set the fog_start as a fraction of the viewing_range. +--- Any value < 0, resets the behavior to being client-controlled. (default: -1) +--- * `fog_color`: ColorSpec, override the color of the fog. +--- Unlike `base_color` above this will apply regardless of the skybox type. +--- (default: `"#00000000"`, which means no override) +--- @param sky_parameters table function Player:set_sky(sky_parameters) end --- * Deprecated. Use `set_sky(sky_parameters)` --- * `base_color`: ColorSpec, defaults to white @@ -274,6 +291,7 @@ function Player:set_sky(base_color, type, texture_names, clouds) end function Player:get_sky(as_table) end --- * Deprecated: Use `get_sky(as_table)` instead. --- * returns a table with the `sky_color` parameters as in `set_sky`. +--- @deprecated function Player:get_sky_color() end --- * Passing no arguments resets the sun to its default values. --- * `sun_parameters` is a table with the following optional fields: diff --git a/classes/Settings.lua b/classes/Settings.lua index ca76dcf..edf438d 100644 --- a/classes/Settings.lua +++ b/classes/Settings.lua @@ -1,3 +1,6 @@ +--- @diagnostic disable: missing-return + + --- An interface to read config files in the format of `minetest.conf`. --- --- `minetest.settings` is a `Settings` instance that can be used to access the diff --git a/classes/VoxelArea.lua b/classes/VoxelArea.lua index 09e8cbd..4135225 100644 --- a/classes/VoxelArea.lua +++ b/classes/VoxelArea.lua @@ -1,3 +1,6 @@ +--- @diagnostic disable: missing-return + + --- @class VoxelArea --- A helper class for voxel areas. --- It can be created via `VoxelArea(pmin, pmax)` or diff --git a/classes/VoxelManip.lua b/classes/VoxelManip.lua index 4317e8c..f47a89b 100644 --- a/classes/VoxelManip.lua +++ b/classes/VoxelManip.lua @@ -1,3 +1,5 @@ +--- @diagnostic disable: missing-return + --- @class VoxelManip --- [View in lua_api.txt](https://github.com/minetest/minetest/blob/5.7.0/doc/lua_api.txt#L4244) diff --git a/definitions/AuthenticationHandlerDefinition.lua b/definitions/AuthenticationHandlerDefinition.lua index 83759b9..0f8a43f 100644 --- a/definitions/AuthenticationHandlerDefinition.lua +++ b/definitions/AuthenticationHandlerDefinition.lua @@ -1,6 +1,9 @@ +--- @diagnostic disable: missing-return + + ---@class AuthenticationHandlerGetAuth ---@field password string ----@field priveleges table +---@field privileges table ---@field last_login number|nil -- Used by `minetest.register_authentication_handler`. diff --git a/definitions/ChatCommandDefinition.lua b/definitions/ChatCommandDefinition.lua index e0c193e..49d4cfe 100644 --- a/definitions/ChatCommandDefinition.lua +++ b/definitions/ChatCommandDefinition.lua @@ -1,4 +1,7 @@ --- Used by `minetest.register_chatcommand`. +--- @diagnostic disable: missing-return + + +--- Used by `minetest.register_chatcommand`. --- @class ChatCommandDefinition local ChatCommandDefinition = { --- Short parameter description. Example: `" "`. diff --git a/definitions/DetachedInventoryCallbacksDef.lua b/definitions/DetachedInventoryCallbacksDef.lua index 311d447..c3797d0 100644 --- a/definitions/DetachedInventoryCallbacksDef.lua +++ b/definitions/DetachedInventoryCallbacksDef.lua @@ -2,31 +2,31 @@ local DetachedInventoryCallbacksDef = { --- Called when a player wants to move items inside the inventory. --- Return value: number of items allowed to move. - --- @type fun(inv:InvRef, from_list:string, from_index:number, to_list:string, to_index:number, count:number, player:Player):number + --- @type nil|fun(inv:InvRef, from_list:string, from_index:number, to_list:string, to_index:number, count:number, player:Player):number allow_move = nil, --- Called when a player wants to put something into the inventory. --- Return value: number of items allowed to put. --- Return value -1: Allow and don't modify item count in inventory. - --- @type fun(inv:InvRef, list_name:string, index:number, stack:ItemStack, player:Player):number + --- @type nil|fun(inv:InvRef, list_name:string, index:number, stack:ItemStack, player:Player):number allow_put = nil, --- Called when a player wants to take something out of the inventory. --- Return value: number of items allowed to take. --- Return value -1: Allow and don't modify item count in inventory. - --- @type fun(inv:InvRef, list_name:string, index:number, stack:ItemStack, player:Player):number + --- @type nil|fun(inv:InvRef, list_name:string, index:number, stack:ItemStack, player:Player):number allow_take = nil, --- Called after the actual action has happened, according to what was allowed (see `allow_move()`). --- No return value. - --- @type fun(inv:InvRef, from_list:string, from_index:number, to_list:string, to_index:number, count:number, player:Player):void + --- @type nil|fun(inv:InvRef, from_list:string, from_index:number, to_list:string, to_index:number, count:number, player:Player):void on_move = nil, --- Called after the actual action has happened, according to what was allowed (see `allow_put()`). --- No return value. - --- @type fun(inv:InvRef, list_name:string, index:number, stack:ItemStack, player:Player) + --- @type nil|fun(inv:InvRef, list_name:string, index:number, stack:ItemStack, player:Player) on_put = nil, --- Called after the actual action has happened, according to what was allowed (see `allow_take()`). --- No return value. - --- @type fun(inv:InvRef, list_name:string, index:number, stack:ItemStack, player:Player) + --- @type nil|fun(inv:InvRef, list_name:string, index:number, stack:ItemStack, player:Player) on_take = nil, } diff --git a/definitions/EntityDefinition.lua b/definitions/EntityDefinition.lua index 2bdc3b2..a20adef 100644 --- a/definitions/EntityDefinition.lua +++ b/definitions/EntityDefinition.lua @@ -1,10 +1,16 @@ +--- @diagnostic disable: missing-return + + +--- Used by `core.register_entity`. +--- The entity definition table becomes a metatable of a newly created per-entity luaentity table, +--- meaning its fields (e.g. initial_properties) will be shared between all instances of an entity. --- @class EntityDefinition local EntityDefinition = { --- A table of object properties, see the `Object properties` section. --- The properties in this table are applied to the object --- once when it is spawned. - --- @type ObjectProperties - initial_properties = {}, + --- @type ObjectProperties? + initial_properties = nil, --- Called when the object is instantiated. diff --git a/definitions/HUDDefinition.lua b/definitions/HUDDefinition.lua index 02244bf..cbd0017 100644 --- a/definitions/HUDDefinition.lua +++ b/definitions/HUDDefinition.lua @@ -31,7 +31,7 @@ local HudDefinition = { --- To account for differing resolutions, the position coordinates are the percentage of the screen, --- ranging in value from `0` to `1`. --- - --- @type Position2d + --- @type Position2d? position = {x = 0, y = 0}, --- Offset in pixels from the position. @@ -40,13 +40,13 @@ local HudDefinition = { --- --- **Note:** offset will adapt to screen DPI as well as user defined scaling factor! --- - --- @type Position2d + --- @type Position2d? offset = {x = 0, y = 0}, --- Alignment anchor. Values: `{x = -1..1, y = -1..1}`. --- It is a table where `x` and `y` range from -1 to 1, with 0 being central. --- `-1` is moved to the left/up, and 1 is to the right/down. Fractional values can be used. - --- @type Position2d + --- @type Position2d? alignment = {x = 0, y = 0}, --- Direction: 0: left-right, 1: right-left, 2: top-bottom, 3: bottom-top. @@ -55,7 +55,7 @@ local HudDefinition = { --- `0` draws from left to right, `1` draws from right to left, `2` draws from top to bottom, --- and `3` draws from bottom to top. --- - --- @type number + --- @type number? direction = 0, --- * For `type` == `"image"`: @@ -80,7 +80,7 @@ local HudDefinition = { --- * * The size of this element. --- Negative values represent percentage of the screen; e.g. x=-100 means 100% (width). --- - --- @type Position2d + --- @type Position2d? scale = {x = 1, y = 1}, --- Name of the text or image to display. @@ -90,10 +90,14 @@ local HudDefinition = { --- * For "inventory": The name of the inventory list to be displayed. --- * For "waypoint": Distance suffix. Can be blank. --- - --- @type string + --- @type string? text = "", - --- @type string + --- * For "statbar": Optional texture name to enable a background / "off state" texture + --- (useful to visualize the maximal value). + --- Both textures must have the same size. + --- + --- @type string? text2 = "", --- * For "text": An integer containing the RGB value of the color used to draw the text. @@ -103,21 +107,14 @@ local HudDefinition = { --- * For "inventory": Number of items in the inventory to be displayed. --- * For "waypoint": An integer containing the RGB value of the color used to draw the text. --- - --- @type number + --- @type number? number = 0, --- * For "statbar": Same as `number` but for the "off state" texture. --- * For "inventory": Position of item that is selected. - --- @type number + --- @type number? item = 0, - --- * For "statbar": Optional texture name to enable a background / "off state" texture - --- (useful to visualize the maximal value). - --- Both textures must have the same size. - --- - --- @type string - text2 = "", - --- * For "text": size of the text. The player-set font size is multiplied by size.x (y value isn't used). --- * For "statbar": If used, will force full-image size to this value (override texture pack image size). --- * For "compass": The size of this element. @@ -128,7 +125,7 @@ local HudDefinition = { --- Example: On a 1920x1080 screen, {x = 0, y = -25} will result in a 270x270 minimap. --- * - Negative values are supported starting with protocol version 45. --- - --- @type Position2d + --- @type Position2d? size = {x=0, y=0}, --- Z index: lower z-index HUDs are displayed behind higher z-index HUDs @@ -150,12 +147,12 @@ local HudDefinition = { --- --- If your HUD element doesn't fit into any category, pick a number between the suggested values. --- - --- @type number + --- @type number? z_index = 0, --- * For "text": determines font style Bitfield with 1 = bold, 2 = italic, 4 = monospace. --- - --- @type number + --- @type number? style = 0, --- * For "waypoint": Waypoint precision, integer >= 0. Defaults to 10. @@ -165,11 +162,11 @@ local HudDefinition = { --- `precision = 2` will show multiples of `0.5`; --- `precision = 5` will show multiples of `0.2` and so on: precision = n will show multiples of `1/n`. --- - --- @type number + --- @type number? precision = 10, --- * For "waypoint"/"image_waypoint": World position of the waypoint. --- - --- @type Position + --- @type Position? world_pos = {x=0, y=0, z=0}, } diff --git a/definitions/ItemDefinition.lua b/definitions/ItemDefinition.lua index 0b9ec42..8b836aa 100644 --- a/definitions/ItemDefinition.lua +++ b/definitions/ItemDefinition.lua @@ -1,15 +1,15 @@ ---- @class ItemDefinition +--- @class ItemDefinition: table local ItemDefinition = { --- Can contain new lines. "\n" has to be used as new line character. --- See also: `get_description` in [`ItemStack`] - --- @type string + --- @type string? description = "", --- Must not contain new lines. --- Defaults to nil. --- Use an [`ItemStack`] to get the short description, e.g.: --- ItemStack(itemname):get_short_description() - --- @type string + --- @type string? short_description = "", --- key = name, value = rating; rating = . @@ -18,29 +18,29 @@ local ItemDefinition = { --- {soil = 2, outerspace = 1, crumbly = 1} --- {bendy = 2, snappy = 1}, --- {hard = 1, metal = 1, spikes = 1} - --- @type table + --- @type table? groups = {}, --- Texture shown in the inventory GUI --- Defaults to a 3D rendering of the node if left empty. - --- @type string + --- @type string? inventory_image = "", --- An overlay texture which is not affected by colorization - --- @type string + --- @type string? inventory_overlay = "", --- Texture shown when item is held in hand --- Defaults to a 3D rendering of the node if left empty. - --- @type string + --- @type string? wield_image = "", --- Like inventory_overlay but only used in the same situation as wield_image - --- @type string + --- @type string? wield_overlay = "", --- Scale for the item when held in hand - --- @type Position scale vector + --- @type Position? scale vector wield_scale = {x = 1, y = 1, z = 1}, --- An image file containing the palette of a node. @@ -48,25 +48,26 @@ local ItemDefinition = { --- the item stack metadata. --- The palette is always stretched to fit indices between 0 and 255, to --- ensure compatibility with "colorfacedir" (and similar) nodes. - --- @type string + --- @type string? palette = "", --- Color the item is colorized with. The palette overrides this. - --- @type string|ColorSpec + --- @type string|ColorSpec|nil + --- Examples: "#ff0000", "#ff0000ff", {r=255,g=0,b=0,a=255} color = "#ffffffff", --- Maximum amount of items that can be in a single stack. --- The default can be changed by the setting `default_stack_max` - --- @type number + --- @type number? stack_max = 99, --- Range of node and object pointing that is possible with this item held - --- @type number + --- @type number? range = 4.0, --- If true, item can point to all liquid nodes (`liquidtype ~= "none"`), --- even those for which `pointable = false` - --- @type boolean + --- @type boolean? liquids_pointable = false, --- When used for nodes: Defines amount of light emitted by node. @@ -74,20 +75,52 @@ local ItemDefinition = { --- To set the maximum (14), use the value 'minetest.LIGHT_MAX'. --- A value outside the range 0 to minetest.LIGHT_MAX causes undefined --- behavior. - --- @type number + --- @type number? light_source = 0, --- See "Tool Capabilities" section for an example including explanation + --- @type table? tool_capabilities = { + --- Time between two uses of the tool (in seconds). + --- For example, a value of 0.5 means the tool can be used twice per second. + --- @type number? full_punch_interval = 1.0, + --- Maximum level of items that can be dropped using this tool. + --- For example, if max_drop_level = 1, items with level 2 or 3 + --- will not be dropped when the node is dug with this tool. + --- @type number? max_drop_level = 0, + --- Capabilities of the tool against each group of nodes. + --- Each group has the following fields: + --- - `times`: table of times it takes to dig nodes of the group + --- for each level. The index is the level, the value is the time + --- in seconds. Level 1 is the lowest level. + --- - `uses`: number of uses the tool has against nodes of the group. + --- When this number is exhausted, the tool breaks. 0 means infinite + --- uses. + --- - `maxlevel`: maximum level of nodes in the group that this tool + --- can dig. For example, if maxlevel = 2, nodes of level 3 in + --- this group cannot be dug with this tool. --- For example: --- `choppy = {times = {2.50, 1.40, 1.00}, uses = 20, maxlevel = 2}`, + --- @type table> groupcaps = { --- For example: choppy = {times = {2.50, 1.40, 1.00}, uses = 20, maxlevel = 2}, }, + --- Damage dealt to players and entities when using the tool to punch + --- them. The damage is specified in the same way as for entities, + --- i.e. a table with damage groups as keys and damage values as values. --- Damage values must be between -32768 and 32767 (2^15) + --- Negative values heal the entity instead of damaging it. + --- If a damage group is not specified, the tool does no damage to that + --- group. + --- For example, to deal 7 damage to the "fleshy" group: + --- `damage_groups = {fleshy = 7}`, or for 3 damage to "fleshy" + --- and 1 damage to "crumbly": + --- `damage_groups = {fleshy = 3, crumbly = 1}` + --- If the tool should do no damage, use an empty table: + --- `damage_groups = {}` --- @type table damage_groups = {groupname = 7}, @@ -97,7 +130,7 @@ local ItemDefinition = { --- suitable groupcap using the formula "uses * 3^(maxlevel - 1)". --- It is recommend to set this explicitly instead of relying on the --- fallback behavior. - --- @type number + --- @type number? punch_attack_uses = nil, }, @@ -107,18 +140,20 @@ local ItemDefinition = { --- Otherwise should be name of node which the client immediately places --- on ground when the player places the item. Server will always update --- with actual result shortly. - --- @type string + --- @type string? node_placement_prediction = nil, --- if "", no prediction is made. --- if "air", node is removed. --- Otherwise should be name of node which the client immediately places --- upon digging. Server will always update with actual result shortly. - --- @type string + --- @type string? node_dig_prediction = "air", --- Definition of item sounds to be played at various events. --- All fields in this table are optional. + --- See also `minetest.registered_items[itemname].sound` + --- @type table? sound = { --- When tool breaks due to wear. Ignored for non-tools @@ -144,7 +179,7 @@ local ItemDefinition = { --- or nil to not modify the inventory. --- The placer may be any ObjectRef or nil. --- default: minetest.item_place - --- @type fun(itemstack:ItemStack, placer:Player|ObjectRef|nil, pointed_thing:pointed_thing) + --- @type fun(itemstack:ItemStack, placer:Player|ObjectRef|nil, pointed_thing:pointed_thing)? on_place = minetest.item_place, --- Same as on_place but called when not pointing at a node. @@ -152,13 +187,13 @@ local ItemDefinition = { --- or an itemstack to replace the original itemstack. --- The user may be any ObjectRef or nil. --- default: nil - --- @type fun(itemstack:ItemStack, user:Player|ObjectRef|nil, pointed_thing:pointed_thing) + --- @type fun(itemstack:ItemStack, user:Player|ObjectRef|nil, pointed_thing:pointed_thing)? on_secondary_use = nil, --- Shall drop item and return the leftover itemstack. --- The dropper may be any ObjectRef or nil. --- default: minetest.item_drop - --- @type fun(itemstack:ItemStack, dropper:Player|ObjectRef|nil, pos:Position) + --- @type fun(itemstack:ItemStack, dropper:Player|ObjectRef|nil, pos:Position)? on_drop = minetest.item_drop, --- Called when a dropped item is punched by a player. @@ -172,7 +207,7 @@ local ItemDefinition = { --- * `time_from_last_punch, ...` (optional): Other parameters from --- `luaentity:on_punch`. --- default: `minetest.item_pickup` - --- @type fun(itemstack:ItemStack, picker:Player|ObjectRef|nil, pointed_thing:pointed_thing, time_from_last_punch, ...) + --- @type fun(itemstack:ItemStack, picker:Player|ObjectRef|nil, pointed_thing:pointed_thing, time_from_last_punch, ...)? on_pickup = minetest.item_pickup, --- default: nil @@ -183,7 +218,7 @@ local ItemDefinition = { --- Otherwise, the function is free to do what it wants. --- The user may be any ObjectRef or nil. --- The default functions handle regular use cases. - --- @type fun(itemstack:ItemStack, user:Player|ObjectRef|nil, pointed_thing:pointed_thing):ItemStack|nil + --- @type (fun(itemstack:ItemStack, user:Player|ObjectRef|nil, pointed_thing:pointed_thing):ItemStack|nil)? on_use = nil, --- default: nil @@ -195,11 +230,12 @@ local ItemDefinition = { --- return itemstack --- end --- The user may be any ObjectRef or nil. - --- @type fun(itemstack:ItemStack, user:Player|ObjectRef|nil, node, digparams) + --- @type fun(itemstack:ItemStack, user:Player|ObjectRef|nil, node, digparams)? after_use = nil, --- Add your own custom fields. By convention, all custom field names --- should start with `_` to avoid naming collisions with future engine --- usage. + --- @type any? _custom_field = "< whatever >", } diff --git a/definitions/NodeDefinition.lua b/definitions/NodeDefinition.lua index 79f68a3..226bf1f 100644 --- a/definitions/NodeDefinition.lua +++ b/definitions/NodeDefinition.lua @@ -112,7 +112,7 @@ local NodeDefinition = { --- --- `*_optional` drawtypes need less rendering time if deactivated(always client-side). --- - --- @type string + --- @type string? drawtype = "normal", --- Supported for drawtypes "plantlike", "signlike", "torchlike", @@ -121,14 +121,14 @@ local NodeDefinition = { --- node. For torchlike, the image will start at the surface to which the --- node "attaches". For the other drawtypes the image will be centered --- on the node. - --- @type number + --- @type number? visual_scale = 1.0, --- {tile definition 1, def2, def3, def4, def5, def6} --- --- Textures of node; +Y, -Y, +X, -X, +Z, -Z --- List can be shortened to needed length. - --- @type table + --- @type table? tiles = nil, --- {tile definition 1, def2, def3, def4, def5, def6} @@ -138,20 +138,20 @@ local NodeDefinition = { --- texture. If the texture name is an empty string, that overlay is not --- drawn. Since such tiles are drawn twice, it is not recommended to use --- overlays on very common nodes. - --- @type table + --- @type table? overlay_tiles = nil, --- {tile definition 1, Tile definition 2}, --- Special textures of node; used rarely. --- List can be shortened to needed length. - --- @type table + --- @type table? special_tiles = nil, --- The node's original color will be multiplied with this color. --- If the node has a palette, then this setting only has an effect in --- the inventory and on the wield item. --- @see ColorSpec - --- @type string|ColorSpec + --- @type string|ColorSpec|nil color = '', --- Specifies how the texture's alpha channel will be used for rendering. @@ -165,7 +165,7 @@ local NodeDefinition = { --- "clip" otherwise. --- If set to a boolean value (deprecated): true either sets it to blend --- or clip, false sets it to clip or opaque mode depending on the drawtype. - --- @type string + --- @type string? use_texture_alpha = "opaque", --- The node's `param2` is used to select a pixel from the image. @@ -173,23 +173,23 @@ local NodeDefinition = { --- The node's color will be multiplied with the selected pixel's color. --- Tiles can override this behavior. --- Only when `paramtype2` supports palettes. - --- @type string + --- @type string? palette = "", --- Screen tint if player is inside node, see "ColorSpec" - --- @type string + --- @type string? post_effect_color = "#00000000", --- See "Nodes" - --- @type string + --- @type string? paramtype = "none", --- See "Nodes" - --- @type string + --- @type string? paramtype2 = "none", --- Value for param2 that is set when player places node - --- @type number + --- @type number? place_param2 = 0, --- If false, the cave generator and dungeon generator will not carve @@ -197,27 +197,27 @@ local NodeDefinition = { --- Specifically, this stops mod-added nodes being removed by caves and --- dungeons when those generate in a neighbor mapchunk and extend out --- beyond the edge of that mapchunk. - --- @type boolean + --- @type boolean? is_ground_content = true, --- If true, sunlight will go infinitely through this node - --- @type boolean + --- @type boolean? sunlight_propagates = false, --- If true, objects collide with node - --- @type boolean + --- @type boolean? walkable = true, --- If true, can be pointed at - --- @type boolean + --- @type boolean? pointable = true, --- If false, can never be dug - --- @type boolean + --- @type boolean? diggable = true, --- If true, can be climbed on like a ladder - --- @type boolean + --- @type boolean? climbable = false, --- Slows down movement of players through this node (max. 7). @@ -225,16 +225,16 @@ local NodeDefinition = { --- Note: If liquid movement physics apply to the node --- (see `liquid_move_physics`), the movement speed will also be --- affected by the `movement_liquid_*` settings. - --- @type number + --- @type number? move_resistance = 0, --- If true, placed nodes can replace this node - --- @type boolean + --- @type boolean? buildable_to = false, --- If true, liquids flow into and replace this node. --- Warning: making a liquid node 'floodable' will cause problems. - --- @type boolean + --- @type boolean? floodable = false, --- specifies liquid flowing physics @@ -247,7 +247,7 @@ local NodeDefinition = { --- recommended drawtype: "flowingliquid". --- If it's "source" or "flowing", then the --- `liquid_alternative_*` fields _must_ be specified - --- @type string + --- @type string? liquidtype = "none", --- These fields may contain node names that represent the @@ -270,7 +270,7 @@ local NodeDefinition = { --- Example: --- liquid_alternative_flowing = "example:water_flowing", --- liquid_alternative_source = "example:water_source", - --- @type string + --- @type string? liquid_alternative_flowing = "", --- These fields may contain node names that represent the @@ -293,19 +293,19 @@ local NodeDefinition = { --- Example: --- liquid_alternative_flowing = "example:water_flowing", --- liquid_alternative_source = "example:water_source", - --- @type string + --- @type string? liquid_alternative_source = "", --- Controls speed at which the liquid spreads/flows (max. 7). --- 0 is fastest, 7 is slowest. --- By default, this also slows down movement of players inside the node --- (can be overridden using `move_resistance`) - --- @type number + --- @type number? liquid_viscosity = 0, --- If true, a new liquid source can be created by placing two or more --- sources nearby - --- @type boolean + --- @type boolean? liquid_renewable = true, --- specifies movement physics if inside node @@ -323,64 +323,67 @@ local NodeDefinition = { --- Allows defining the nodebox height without using param2. --- The nodebox height is 'leveled' / 64 nodes. --- The maximum value of 'leveled' is `leveled_max`. - --- @type number + --- @type number? leveled = 0, --- Maximum value for `leveled` (0-127), enforced in --- `minetest.set_node_level` and `minetest.add_node_level`. --- Values above 124 might causes collision detection issues. - --- @type number + --- @type number? leveled_max = 127, --- Maximum distance that flowing liquid nodes can spread around --- source on flat land; --- maximum = 8; set to 0 to disable liquid flow - --- @type number + --- @type number? liquid_range = 8, --- Player will take this amount of damage if no bubbles are left - --- @type number + --- @type number? drowning = 0, --- If player is inside node, this damage is caused - --- @type number + --- @type number? damage_per_second = 0, --- See "Node boxes" + --- @type table? node_box = {type = "regular"}, --- Used for nodebox nodes with the type == "connected". --- Specifies to what neighboring nodes connections will be drawn. --- e.g. `{"group:fence", "default:wood"}` or `"default:stone"` - --- @type string[] + --- @type string[]? connects_to = {}, --- Tells connected nodebox nodes to connect only to these sides of this --- node. possible: "top", "bottom", "front", "left", "back", "right" - --- @type string[] + --- @type string[]? connect_sides = {}, --- File name of mesh when using "mesh" drawtype - --- @type string + --- @type string? mesh = "", --- Custom selection box definition. Multiple boxes can be defined. --- If "nodebox" drawtype is used and selection_box is nil, then node_box --- definition is used for the selection box. --- see [Node boxes] for possibilities + --- @type table? selection_box = {}, --- see [Node boxes] for possibilities --- Custom collision box definition. Multiple boxes can be defined. --- If "nodebox" drawtype is used and collision_box is nil, then node_box --- definition is used for the collision box. + --- @type table? collision_box = {}, --- Support maps made in and before January 2012 - --- @type boolean + --- @type boolean? legacy_facedir_simple = false, --- Support maps made in and before January 2012 - --- @type boolean + --- @type boolean? legacy_wallmounted = false, --- Valid for drawtypes: @@ -392,16 +395,17 @@ local NodeDefinition = { --- plantlike drawtype can only wave like plants. --- allfaces_optional drawtype can only wave like leaves. --- liquid, flowingliquid drawtypes can only wave like liquids. - --- @type number + --- @type number? waving = 0, --- Definition of node sounds to be played at various events. --- All fields in this table are optional. + --- @type nil|table sounds = { --- If walkable, played when object walks on it. If node is --- climbable or a liquid, played when object moves through it - --- @type SimpleSoundSpec + --- @type SimpleSoundSpec? footstep = nil, --- While digging node. @@ -411,32 +415,33 @@ local NodeDefinition = { --- In case of a tie, one of the sounds will be played (but we --- cannot predict which one) --- Default value: `"__group"` - --- @type SimpleSoundSpec|string + --- @type nil|SimpleSoundSpec|string dig = {} or "__group", --- Node was dug - --- @type SimpleSoundSpec + --- @type SimpleSoundSpec? dug = nil, --- Node was placed. Also played after falling - --- @type SimpleSoundSpec + --- @type SimpleSoundSpec? place = nil, --- When node placement failed. --- Note: This happens if the _built-in_ node placement failed. --- This sound will still be played if the node is placed in the --- `on_place` callback manually. - --- @type SimpleSoundSpec + --- @type SimpleSoundSpec? place_failed = nil, --- When node starts to fall or is detached - --- @type SimpleSoundSpec + --- @type SimpleSoundSpec? fall = nil, }, --- Name of dropped item when dug. --- Default dropped item is the node itself. --- Using a table allows multiple items, drop chances and item filtering: + --- @type table? drop = { --- Maximum number of item lists to drop. --- The entries in 'items' are processed in order. For each: @@ -447,7 +452,7 @@ local NodeDefinition = { --- Therefore, entries should progress from low to high drop chance. --- @type number max_items = 1, - ---- Examples: + --- Examples: --- ```lua --- { --- -- 1 in 1000 chance of dropping a diamond. @@ -496,19 +501,19 @@ local NodeDefinition = { --- infinite loop if it invokes the same callback. --- Consider using `minetest.swap_node()` instead. --- default: nil - --- @type fun(pos:Position) + --- @type fun(pos:Position)? on_construct = nil, --- Node destructor; called before removing node. --- Not called for bulk node placement. --- default: nil - --- @type fun(pos:Position) + --- @type fun(pos:Position)? on_destruct = nil, --- Node destructor; called after removing node. --- Not called for bulk node placement. --- default: nil - --- @type fun(pos:Position, old_node) + --- @type fun(pos:Position, old_node)? after_destruct = nil, --- Called when a liquid (new_node) is about to flood old_node, if it has @@ -518,7 +523,7 @@ local NodeDefinition = { --- over and over again every liquid update interval. --- Default: nil --- Warning: making a liquid node 'floodable' will cause problems. - --- @type fun(pos:Position, old_node, new_node) + --- @type fun(pos:Position, old_node, new_node)? on_flood = nil, @@ -531,7 +536,7 @@ local NodeDefinition = { --- be added directly to one or more of the dropped items. --- @see ItemStackMetaRef --- default: nil - --- @type fun(pos:Position, old_node, new_node, old_meta, drops:ItemStack[]) + --- @type fun(pos:Position, old_node, new_node, old_meta, drops:ItemStack[])? preserve_metadata = nil, --- Called after constructing node when node was placed using @@ -539,25 +544,25 @@ local NodeDefinition = { --- If return true no item is taken from itemstack. --- `placer` may be any valid ObjectRef or nil. --- default: nil - --- @type fun(pos:Position, placer:Player|ObjectRef|nil, itemstack:ItemStack, pointed_thing:pointed_thing) + --- @type fun(pos:Position, placer:Player|ObjectRef|nil, itemstack:ItemStack, pointed_thing:pointed_thing)? after_place_node = nil, --- oldmetadata is in table format. --- Called after destructing node when node was dug using --- minetest.node_dig / minetest.dig_node. --- default: nil - --- @type fun(pos:Player, oldnode, oldmetadata, digger:Player|ObjectRef|nil) + --- @type fun(pos:Player, oldnode, oldmetadata, digger:Player|ObjectRef|nil)? after_dig_node = nil, --- Returns true if node can be dug, or false if not. --- default: nil - --- @type fun(pos:Position, player:Player|ObjectRef|nil) + --- @type fun(pos:Position, player:Player|ObjectRef|nil)? can_dig = nil, --- default: minetest.node_punch --- Called when puncher (an ObjectRef) punches the node at pos. --- By default calls minetest.register_on_punchnode callbacks. - --- @type fun(pos:Position, node:NodeTable, puncher:Player|ObjectRef|nil, pointed_thing:pointed_thing) + --- @type fun(pos:Position, node:NodeTable, puncher:Player|ObjectRef|nil, pointed_thing:pointed_thing)? on_punch = nil, --- default: nil @@ -569,14 +574,14 @@ local NodeDefinition = { --- Note: pointed_thing can be nil, if a mod calls this function. --- This function does not get triggered by clients <=0.4.16 if the --- "formspec" node metadata field is set. - --- @type fun(pos:Position, node:NodeTable, clicker:Player|ObjectRef|nil, itemstack:ItemStack, pointed_thing:pointed_thing|nil) + --- @type fun(pos:Position, node:NodeTable, clicker:Player|ObjectRef|nil, itemstack:ItemStack, pointed_thing:pointed_thing|nil)? on_rightclick = nil, --- default: minetest.node_dig --- By default checks privileges, wears out item (if tool) and removes node. --- return true if the node was dug successfully, false otherwise. --- Deprecated: returning nil is the same as returning true. - --- @type fun(pos:Position, node:NodeTable, digger:Player): boolean + --- @type (fun(pos:Position, node:NodeTable, digger:Player): boolean)? on_dig = nil, --- default: nil @@ -584,53 +589,53 @@ local NodeDefinition = { --- elapsed is the total time passed since the timer was started. --- return true to run the timer for another cycle with the same timeout --- value. - --- @type fun(pos:Position, elapsed:number): boolean + --- @type (fun(pos:Position, elapsed:number): boolean)? on_timer = nil, --- fields = {name1 = value1, name2 = value2, ...} --- Called when an UI form (e.g. sign text input) returns data. --- See minetest.register_on_player_receive_fields for more info. --- default: nil - --- @type fun(pos:Position, formname:string, fields:table, sender:Player) + --- @type fun(pos:Position, formname:string, fields:table, sender:Player)? on_receive_fields = nil, --- Called when a player wants to move items inside the inventory. --- Return value: number of items allowed to move. - --- @type fun(pos:Position, from_list:string, from_index:number, to_list:string, to_index:number, count:number, player:Player): number + --- @type (fun(pos:Position, from_list:string, from_index:number, to_list:string, to_index:number, count:number, player:Player): number)? allow_metadata_inventory_move = nil, --- Called when a player wants to put something into the inventory. --- Return value: number of items allowed to put. --- Return value -1: Allow and don't modify item count in inventory. - --- @type fun(pos:Position, listname:string, index:number, stack:ItemStack, player:Player): number + --- @type (fun(pos:Position, listname:string, index:number, stack:ItemStack, player:Player): number)? allow_metadata_inventory_put = nil, --- Called when a player wants to take something out of the inventory. --- Return value: number of items allowed to take. --- Return value -1: Allow and don't modify item count in inventory. - --- @type fun(pos:Position, listname:string, index:number, stack:ItemStack, player:Player): number + --- @type (fun(pos:Position, listname:string, index:number, stack:ItemStack, player:Player): number)? allow_metadata_inventory_take = nil, --- Called after the actual action has happened, according to what was --- allowed. --- No return value. - --- @type fun(pos:Position, from_list:string, from_index:number, to_list:string, to_index:number, count:number, player:Player): void + --- @type (fun(pos:Position, from_list:string, from_index:number, to_list:string, to_index:number, count:number, player:Player): void)? on_metadata_inventory_move = nil, --- Called after the actual action has happened, according to what was --- allowed. --- No return value. - --- @type fun(pos:Position, listname:string, index:number, stack:ItemStack, player:Player): void + --- @type (fun(pos:Position, listname:string, index:number, stack:ItemStack, player:Player): void)? on_metadata_inventory_put = nil, --- Called after the actual action has happened, according to what was --- allowed. --- No return value. - --- @type fun(pos:Position, listname:string, index:number, stack:ItemStack, player:Player): void + --- @type (fun(pos:Position, listname:string, index:number, stack:ItemStack, player:Player): void)? on_metadata_inventory_take = nil, --- intensity: 1.0 = mid range of regular TNT. --- If defined, called when an explosion touches the node, instead of --- removing the node. - --- @type fun (pos:Position, intensity:number) + --- @type (fun(pos:Position, intensity:number): void)? on_blast = nil, --- stores which mod actually registered a node @@ -638,6 +643,6 @@ local NodeDefinition = { --- Useful for getting which mod truly registered something --- example: if a node is registered as ":othermodname:nodename", --- nodename will show "othermodname", but mod_origin will say "modname" - --- @type string + --- @type string? mod_origin = "modname", } diff --git a/definitions/PrivilegeDefinition.lua b/definitions/PrivilegeDefinition.lua index 9252d17..0e18b7d 100644 --- a/definitions/PrivilegeDefinition.lua +++ b/definitions/PrivilegeDefinition.lua @@ -1,14 +1,17 @@ +--- @diagnostic disable: missing-return + +--- Used by `core.register_privilege`. --- @class PrivilegeDefinition local PrivilegeDefinition = { - --- @type string Privilege description + --- @type string? Privilege description description = "", - --- @type string Whether to grant the privilege to singleplayer. + --- @type boolean? Whether to grant the privilege to singleplayer. give_to_singleplayer = true, --- Whether to grant the privilege to the server admin. --- Uses value of 'give_to_singleplayer' by default. - --- @type boolean + --- @type boolean? give_to_admin = true, --- Called when given to player 'name' by 'granter_name'. @@ -22,6 +25,7 @@ local PrivilegeDefinition = { --- @param name string for whom priv was granted --- @param granter_name string who gives the priv --- @return boolean + --- @type nil|fun(name:string, granter_name:string):boolean on_grant = function(name, granter_name) end, --- Called when taken from player 'name' by 'revoker_name'. @@ -35,5 +39,6 @@ local PrivilegeDefinition = { --- @param name string for whom priv was granted --- @param revoker_name string who gives the priv --- @return boolean + --- @type nil|fun(name:string, revoker_name:string):boolean on_revoke = function(name, revoker_name) end, } diff --git a/definitions/TileDefinition.lua b/definitions/TileDefinition.lua index 33278e6..3134e9a 100644 --- a/definitions/TileDefinition.lua +++ b/definitions/TileDefinition.lua @@ -3,11 +3,11 @@ local TileDefinition = { --- @type string name = "image.png", - --- @type TileAnimationDefinition + --- @type TileAnimationDefinition? animation = nil, --- Backface culling enabled by default for most nodes. - --- @type boolean + --- @type boolean? backface_culling = true, --- One of `{"node"|"world"|"user"}`. @@ -17,7 +17,7 @@ local TileDefinition = { --- `"user"` means that client setting will be used, similar to `glasslike_framed_optional`. --- --- **Note:** supported by solid nodes and nodeboxes only. - --- @type string + --- @type string? align_style = "none", --- `scale` is used to make texture span several (exactly scale) nodes, instead of just one, in each direction. @@ -26,11 +26,11 @@ local TileDefinition = { --- --- **Note** that as the effect is applied on per-mapblock basis, --- 16 should be equally divisible by scale or you may get wrong results. - --- @type number + --- @type number? scale = 1, --- - the texture's color will be multiplied with this color. --- - the tile's color overrides the owning node's color in all cases. - --- @type string|ColorSpec + --- @type string|ColorSpec|nil color = "" } diff --git a/minetest/utilities.lua b/minetest/utilities.lua index f9a7c13..b00fe76 100644 --- a/minetest/utilities.lua +++ b/minetest/utilities.lua @@ -1,4 +1,14 @@ +--- @diagnostic disable: missing-return +--- Returns the currently loading mod's name, when loading a mod. +--- - Returns nil if not loading a mod. +--- - Only works during mod loading (i.e. when a mod calls this function from +--- its top-level scope, or from a function called during mod loading). +--- - Useful for libraries to determine which mod is loading them, for +--- example to access that mod's mod storage. +--- @see minetest.get_modpath +--- @see minetest.get_modnames +--- @see minetest.get_worldpath --- @return string returns the currently loading mod's name, when loading a mod. function minetest.get_current_modname() end diff --git a/minetest_ns.lua b/minetest_ns.lua index 065b5c5..14bc372 100644 --- a/minetest_ns.lua +++ b/minetest_ns.lua @@ -136,8 +136,8 @@ function minetest.wrap_text(str, limit, as_table) end --- --- [View in lua_api.txt](https://github.com/minetest/minetest/blob/5.4.1/doc/lua_api.txt#L3252-L3256) --- ---- @param pos Position ---- @param decimal_places number +--- @param pos Position +--- @param decimal_places? number --- @return string function minetest.pos_to_string(pos, decimal_places) end --- returns a position or `nil` @@ -1520,9 +1520,9 @@ function minetest.strip_param2_color(param2, paramtype2) end function minetest.get_node_drops(node, toolname) end --- @class RecipeInput ---- @field method string `"normal"` or `"cooking"` or `"fuel"` ---- @field width number for example `3` ---- @field items ItemStack[] for example `{stack1, stack2, stack3, stack4, stack 5, stack 6, stack 7, stack 8, stack 9}` +--- @field method string `"normal"` or `"cooking"` or `"fuel"` +--- @field width number for example `3` +--- @field items ItemStack[]|table for example `{stack1, stack2, stack3, stack4, stack 5, stack 6, stack 7, stack 8, stack 9}` --- @class RecipeOutput --- @field item ItemStack diff --git a/specs/Color.lua b/specs/Color.lua new file mode 100644 index 0000000..1bf6f26 --- /dev/null +++ b/specs/Color.lua @@ -0,0 +1,20 @@ + +--- A ColorString is a string that represents a color. It can be one of the following: +--- * a named color, e.g. `"red"`, `"blue"`, `"green"`, etc. +--- (see [CSS Color Module Level 4](https://www.w3.org/TR/css-color-4/#named-colors) for a full list of named colors) +--- * a named color with alpha, e.g. `"red#08"`, `"blue#FF"`, `"green#F"`, etc. +--- * an RGB or RGBA hex color code, e.g. `"#RRGGBB"` or `"#RRGGBBAA"`, where `RR`, `GG`, `BB`, and `AA` are two-digit hexadecimal numbers representing the red, green, blue, and alpha (opacity) components of the color. +--- * e.g. `"#FF0000"` for red, `"#00FF00"` for green, `"#0000FF"` for blue, etc. +--- * a shorthand hex color code, e.g. `"#RGB"` or `"#RGBA"`, where `R`, `G`, `B`, and `A` are single-digit hexadecimal numbers representing the red, green, blue, and alpha (opacity) components of the color. +--- @class ColorString: string + + + +--- A ColorSpec specifies a 32-bit color. It can be written in any of the following forms: +--- * table form: Each element ranging from 0..255 (a, if absent, defaults to 255): +--- `colorspec = {a=255, r=0, g=255, b=0}` +--- * numerical form: The raw integer value of an ARGB8 quad: +--- `colorspec = 0xFF00FF00` +--- * string form: A ColorString (defined above): +--- `colorspec = "green"` +--- @class ColorSpec: {r:number, g:number, b:number, a:number}|ColorString|number diff --git a/specs/SimpleSoundSpec.lua b/specs/SimpleSoundSpec.lua index 1533042..5b9314a 100644 --- a/specs/SimpleSoundSpec.lua +++ b/specs/SimpleSoundSpec.lua @@ -1,15 +1,15 @@ --- @class SimpleSoundSpec local SimpleSoundSpec = { --- Scales the gain specified in `SimpleSoundSpec`. - --- @type number + --- @type number? gain = 1.0, --- Overwrites the pitch specified in `SimpleSoundSpec`. - --- @type number + --- @type number? pitch = 1.0, --- Overwrites the fade specified in `SimpleSoundSpec`. - --- @type number + --- @type number? fade = 0.0, --- Start with a time-offset into the sound. @@ -21,16 +21,16 @@ local SimpleSoundSpec = { --- --- Available since feature `sound_params_start_time`. --- - --- @type number + --- @type number? start_time = 0.0, --- If true, sound is played in a loop. - --- @type boolean + --- @type boolean? loop = false, --- Play sound at a position. --- Can't be used together with `object`. - --- @type Position + --- @type Position? pos = { x = 1, y = 2, z = 3 }, --- Attach the sound to an object. @@ -51,19 +51,19 @@ local SimpleSoundSpec = { --- the active object range; they should start playing again if objects --- come back into range (but due to a known bug, they don't yet). --- - --- @type ObjectRef + --- @type ObjectRef? object = nil, --- Only play for this player. --- Can't be used together with `exclude_player`. --- - --- @type string + --- @type string? to_player = '', --- Don't play sound for this player. --- Can't be used together with `to_player`. --- - --- @type string + --- @type string? exclude_player = '', --- Only play for players that are at most this far away when the sound @@ -71,6 +71,6 @@ local SimpleSoundSpec = { --- Needs `pos` or `object` to be set. --- `32` is the default. --- - --- @type number + --- @type number? max_hear_distance = 32, }