From f248f348179eda2cbfcc62ea4d0e7b06fe0a0855 Mon Sep 17 00:00:00 2001 From: alek13 Date: Wed, 17 Jul 2024 16:30:23 +0300 Subject: [PATCH] IDE Helper: reformat `ItemDefinition`, add `SimpleSoundSpec`. --- definitions/ItemDefinition.lua | 92 +++++++++++++++++----------------- minetest_types.lua | 4 ++ specs/SimpleSoundSpec.lua | 76 ++++++++++++++++++++++++++++ 3 files changed, 126 insertions(+), 46 deletions(-) create mode 100644 specs/SimpleSoundSpec.lua diff --git a/definitions/ItemDefinition.lua b/definitions/ItemDefinition.lua index 810f5a1..65af490 100644 --- a/definitions/ItemDefinition.lua +++ b/definitions/ItemDefinition.lua @@ -118,68 +118,68 @@ local ItemDefinition = { -- When item is used with the 'punch/mine' key pointing at nothing (air) }, + --- When the 'place' key was pressed with the item in hand + --- and a node was pointed at. + --- Shall place item and return the leftover itemstack + --- 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) on_place = minetest.item_place, - -- When the 'place' key was pressed with the item in hand - -- and a node was pointed at. - -- Shall place item and return the leftover itemstack - -- or nil to not modify the inventory. - -- The placer may be any ObjectRef or nil. - -- default: minetest.item_place + --- Same as on_place but called when not pointing at a node. + --- Function must return either nil if inventory shall not be modified, + --- 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) on_secondary_use = nil, - -- Same as on_place but called when not pointing at a node. - -- Function must return either nil if inventory shall not be modified, - -- or an itemstack to replace the original itemstack. - -- The user may be any ObjectRef or nil. - -- default: 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) on_drop = minetest.item_drop, - -- Shall drop item and return the leftover itemstack. - -- The dropper may be any ObjectRef or nil. - -- default: minetest.item_drop + --- Called when a dropped item is punched by a player. + --- Shall pick-up the item and return the leftover itemstack or nil to not + --- modify the dropped item. + --- Parameters: + --- * `itemstack`: The `ItemStack` to be picked up. + --- * `picker`: Any `ObjectRef` or `nil`. + --- * `pointed_thing` (optional): The dropped item (a `"__builtin:item"` + --- luaentity) as `type="object"` `pointed_thing`. + --- * `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, ...) on_pickup = minetest.item_pickup, - -- Called when a dropped item is punched by a player. - -- Shall pick-up the item and return the leftover itemstack or nil to not - -- modify the dropped item. - -- Parameters: - -- * `itemstack`: The `ItemStack` to be picked up. - -- * `picker`: Any `ObjectRef` or `nil`. - -- * `pointed_thing` (optional): The dropped item (a `"__builtin:item"` - -- luaentity) as `type="object"` `pointed_thing`. - -- * `time_from_last_punch, ...` (optional): Other parameters from - -- `luaentity:on_punch`. - -- default: `minetest.item_pickup` + --- default: nil + --- When user pressed the 'punch/mine' key with the item in hand. + --- Function must return either nil if inventory shall not be modified, + --- or an itemstack to replace the original itemstack. + --- e.g. itemstack:take_item(); return itemstack + --- 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) on_use = nil, - -- default: nil - -- When user pressed the 'punch/mine' key with the item in hand. - -- Function must return either nil if inventory shall not be modified, - -- or an itemstack to replace the original itemstack. - -- e.g. itemstack:take_item(); return itemstack - -- 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. + --- default: nil + --- If defined, should return an itemstack and will be called instead of + --- wearing out the item (if tool). If returns nil, does nothing. + --- If after_use doesn't exist, it is the same as: + --- function(itemstack, user, node, digparams) + --- itemstack:add_wear(digparams.wear) + --- return itemstack + --- end + --- The user may be any ObjectRef or nil. --- @type fun(itemstack:ItemStack, user:Player|ObjectRef|nil, node, digparams) after_use = nil, - -- default: nil - -- If defined, should return an itemstack and will be called instead of - -- wearing out the item (if tool). If returns nil, does nothing. - -- If after_use doesn't exist, it is the same as: - -- function(itemstack, user, node, digparams) - -- itemstack:add_wear(digparams.wear) - -- return itemstack - -- end - -- The user may be any ObjectRef or nil. - _custom_field = whatever, - -- Add your own custom fields. By convention, all custom field names - -- should start with `_` to avoid naming collisions with future engine - -- usage. + --- Add your own custom fields. By convention, all custom field names + --- should start with `_` to avoid naming collisions with future engine + --- usage. + _custom_field = "< whatever >", } diff --git a/minetest_types.lua b/minetest_types.lua index 3e5de78..1e5c19c 100644 --- a/minetest_types.lua +++ b/minetest_types.lua @@ -361,6 +361,8 @@ function minetest.register_node(name, node_definition) end --- [View in lua_api.txt](https://github.com/minetest/minetest/blob/5.4.1/doc/lua_api.txt#L4472-L4472) function minetest.register_craftitem(name, item_definition) end --- [View in lua_api.txt](https://github.com/minetest/minetest/blob/5.4.1/doc/lua_api.txt#L4473-L4473) +--- @param name string +--- @param item_definition ItemDefinition function minetest.register_tool(name, item_definition) end --- * Overrides fields of an item registered with register_node/tool/craftitem. --- * Note: Item must already be defined, (opt)depend on the mod defining it. @@ -368,6 +370,8 @@ function minetest.register_tool(name, item_definition) end --- {light_source=minetest.LIGHT_MAX})` --- --- [View in lua_api.txt](https://github.com/minetest/minetest/blob/5.4.1/doc/lua_api.txt#L4474-L4478) +--- @param name string +--- @param redefinition ItemDefinition function minetest.override_item(name, redefinition) end --- * Unregisters the item from the engine, and deletes the entry with key --- `name` from `minetest.registered_items` and from the associated item table diff --git a/specs/SimpleSoundSpec.lua b/specs/SimpleSoundSpec.lua new file mode 100644 index 0000000..1533042 --- /dev/null +++ b/specs/SimpleSoundSpec.lua @@ -0,0 +1,76 @@ +--- @class SimpleSoundSpec +local SimpleSoundSpec = { + --- Scales the gain specified in `SimpleSoundSpec`. + --- @type number + gain = 1.0, + + --- Overwrites the pitch specified in `SimpleSoundSpec`. + --- @type number + pitch = 1.0, + + --- Overwrites the fade specified in `SimpleSoundSpec`. + --- @type number + fade = 0.0, + + --- Start with a time-offset into the sound. + --- The behavior is as if the sound was already playing for this many seconds. + --- Negative values are relative to the sound's length, so the sound reaches + --- its end in `-start_time` seconds. + --- It is unspecified what happens if `loop` is false and `start_time` is + --- smaller than minus the sound's length. + --- + --- Available since feature `sound_params_start_time`. + --- + --- @type number + start_time = 0.0, + + --- If true, sound is played in a loop. + --- @type boolean + loop = false, + + --- Play sound at a position. + --- Can't be used together with `object`. + --- @type Position + pos = { x = 1, y = 2, z = 3 }, + + --- Attach the sound to an object. + --- Can't be used together with `pos`. + --- + --- For backward compatibility, sounds continue playing at the last location + --- of the object if an object is removed (for example if an entity dies). + --- It is not recommended to rely on this. + --- For death sounds, prefer playing a positional sound instead. + --- + --- If you want to stop a sound when an entity dies or is deactivated, + --- store the handle and call `minetest.sound_stop` in `on_die` / `on_deactivate`. + --- + --- Ephemeral sounds are entirely unaffected by the object being removed + --- or leaving the active object range. + --- + --- Non-ephemeral sounds stop playing on clients if objects leave + --- 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 + object = nil, + + --- Only play for this player. + --- Can't be used together with `exclude_player`. + --- + --- @type string + to_player = '', + + --- Don't play sound for this player. + --- Can't be used together with `to_player`. + --- + --- @type string + exclude_player = '', + + --- Only play for players that are at most this far away when the sound + --- starts playing. + --- Needs `pos` or `object` to be set. + --- `32` is the default. + --- + --- @type number + max_hear_distance = 32, +}