From a8dfcb767b725352383882e5e6f7fabe0d5ec606 Mon Sep 17 00:00:00 2001 From: Vanic Date: Mon, 16 Feb 2026 21:26:51 +0300 Subject: [PATCH] Update annotations `ObjectRef`: Fixing annotations, adding missing methods, fixing return type (position -> vector) #8 --- classes/ObjectRef.lua | 338 ++++++++++++++++++++++++++++++++---------- 1 file changed, 259 insertions(+), 79 deletions(-) diff --git a/classes/ObjectRef.lua b/classes/ObjectRef.lua index 2562f42..33c8172 100644 --- a/classes/ObjectRef.lua +++ b/classes/ObjectRef.lua @@ -1,106 +1,200 @@ --- @meta - +--- Moving things in the game are generally these. +--- This is basically a reference to a C++ ServerActiveObject. --- @class ObjectRef ObjectRef = {} ---- @return Position +--- Returns whether the object is valid. +function ObjectRef:is_valid() end + +--- Returns position as vector `{x=num, y=num, z=num}` +--- @return vector function ObjectRef:get_pos() end ---- @param pos Position + +--- Sets the position of the object. +--- +--- No-op if object is attached +--- @param pos Position is a vector `{x=num, y=num, z=num}` function ObjectRef:set_pos(pos) end ---TODO: ---- @return vector|Position returns the velocity, a vector. +--- Changes position by adding to the current position. +--- +--- No-op if object is attached. +--- +--- In comparison to using `set_pos`, `add_pos` will avoid synchronization problems. +--- @param pos Position is a vector `{x=num, y=num, z=num}`. +function ObjectRef:add_pos(pos) end + +--- Returns the velocity, a vector. +--- @return vector function ObjectRef:get_velocity() end ---- @param vel vector|Position e.g. `{x=0.0, y=2.3, z=1.0}` ---- * In comparison to using get_velocity, adding the velocity and then using ---- set_velocity, add_velocity is supposed to avoid synchronization problems. ---- Additionally, players also do not support set_velocity. ---- * If a player: ---- * Does not apply during free_move. ---- * Note that since the player speed is normalized at each move step, ---- increasing e.g. Y velocity beyond what would usually be achieved ---- (see: physics overrides) will cause existing X/Z velocity to be reduced. ---- * Example: `add_velocity({x=0, y=6.5, z=0})` is equivalent to ---- pressing the jump key (assuming default settings) +--- Changes velocity by adding to the current velocity. +--- +--- In comparison to using `get_velocity`, adding the velocity and then using +--- `set_velocity`, `add_velocity` is supposed to avoid synchronization problems. +--- +--- Additionally, players also do not support set_velocity. +--- +--- If a player: +--- * Does not apply during `free_move`. +--- * Note that since the player speed is normalized at each move step, +--- increasing e.g. Y velocity beyond what would usually be achieved +--- (see: physics overrides) will cause existing X/Z velocity to be reduced. +--- * Example: `add_velocity({x=0, y=6.5, z=0})` is equivalent to +--- pressing the jump key (assuming default settings) +--- @param vel Position is a vector e.g. `{x=0.0, y=2.3, z=1.0}` function ObjectRef:add_velocity(vel) end + +--- Does an interpolated move for Lua entities for visually smooth transitions. +--- +--- If `continuous` is true (default: false), the Lua entity will not be moved to the current +--- position before starting the interpolated move. +--- +--- For players this does the same as `set_pos`,`continuous` is ignored. +--- +--- No-op if object is attached. --- @overload fun(pos) ---- * Does an interpolated move for Lua entities for visually smooth transitions. ---- * If `continuous` is true (default: false), the Lua entity will not be moved to the current ---- position before starting the interpolated move. ---- * For players this does the same as `set_pos`,`continuous` is ignored. ---- @param pos Position +--- @param pos Position --- @param continuous boolean function ObjectRef:move_to(pos, continuous) end - --- Punches the object, triggering all consequences a normal punch would have. ---- - Arguments `time_from_last_punch`, `tool_capabilities`, and `direction` will be replaced with a default value when the caller sets them to `nil`. ---- - Other arguments: See on_punch for entities --- ---- @param puncher? ObjectRef|Entity|Player|nil another `ObjectRef` which punched the object or `nil` ---- @param time_from_last_punch? number time since last punch action of the puncher ---- @param tool_capabilities? table the tool capabilities of the puncher. See [Tool Capabilities](https://api.luanti.org/tool-capabilities/) ---- @param direction? Position the direction from which the punch came, normalized vector +--- Arguments `time_from_last_punch`, `tool_capabilities`, and `direction` will be replaced +--- with a default value when the caller sets them to `nil`. +--- +--- Other arguments: See on_punch for entities +--- @param puncher? ObjectRef|Entity|Player|nil another `ObjectRef` which punched the object (can be `nil`) +--- @param time_from_last_punch? number Meant for disallowing spamming of clicks (can be `nil`) +--- @param tool_capabilities? table capability table of used item. See [Tool Capabilities](https://api.luanti.org/tool-capabilities/) +--- @param direction? Position direction vector. Points from the puncher to the punched (can be nil) function ObjectRef:punch(puncher, time_from_last_punch, tool_capabilities, direction) end ---- @param clicker ObjectRef + +--- Simulates using the 'place/use' key on the object +--- +--- Triggers all consequences as if a real player had done this +--- +--- Note: this is called `right_click`` for historical reasons only +--- @param clicker ObjectRef is another `ObjectRef` which has clicked function ObjectRef:right_click(clicker) end ---- returns number of health points + +--- Returns number of health points --- @return number function ObjectRef:get_hp() end ---- set number of health points ---- * See reason in register_on_player_hpchange + +--- Set number of health points +--- * See reason in `register_on_player_hpchange` --- * Is limited to the range of 0 ... 65535 (2^16 - 1) --- * For players: HP are also limited by `hp_max` specified in object properties ---- @param hp number +--- @param hp number --- @param reason PlayerHPChangeReason function ObjectRef:set_hp(hp, reason) end ---- @return InvRef|nil for players, otherwise returns `nil` + +--- Returns an `InvRef` for players, otherwise returns `nil` +--- @return InvRef|nil function ObjectRef:get_inventory() end ---- @return string the name of the inventory list the wielded item is in. + +--- Returns the name of the inventory list the wielded item is in. +--- @return string function ObjectRef:get_wield_list() end ---- @return number the index of the wielded item + +--- returns the wield list index of the wielded item (starting with 1) +--- @return number function ObjectRef:get_wield_index() end + +--- Returns a copy of the wielded item as an `ItemStack` --- @return ItemStack function ObjectRef:get_wielded_item() end ---- replaces the wielded item, returns `true` if successful. + +--- Replaces the wielded item, returns `true` if successful. --- @param item ItemStack --- @return boolean function ObjectRef:set_wielded_item(item) end ---- @param groups table {group1=rating, group2=rating, ...} -function ObjectRef:set_armor_groups(groups) end ---- @return table with the armor group ratings + +--- Returns a table with all of the object's armor group ratings +--- +--- Syntax: the table keys are the armor group names, +--- the table values are the corresponding group ratings +--- +--- See section [ObjectRef armor groups](https://api.luanti.org/groups/#objectref-armor-groups) for details +--- @return table function ObjectRef:get_armor_groups() end ---- @param frame_range table {x=num, y=num}, default: `{x=1, y=1}` ---- @param frame_speed number default: `15.0` ---- @param frame_blend number default: `0.0` ---- @param frame_loop boolean default: `true` + +--- Sets the object's full list of armor groups +--- +--- Same table syntax as for `get_armor_groups` +--- +--- Note: all armor groups not in the table will be removed +--- @param groups table `{group1=rating, group2=rating, ...}` +function ObjectRef:set_armor_groups(groups) end + +--- Sets the object animation parameters and (re)starts the animation +--- +--- Animations only work with a `"mesh"` visual +--- +--- Animation interpolates towards the end frame but stops when it is reached +--- * If looped, there is no interpolation back to the start frame +--- * If looped, the model should look identical at start and end +--- @param frame_range table Beginning and end frame (as specified in the mesh file). Syntax: `{x=start_frame, y=end_frame}`. Default: `{x=1.0, y=1.0}` +--- @param frame_speed number How fast the animation plays, in frames per second (number). Default: `15.0` +--- @param frame_blend number Default: `0.0` +--- @param frame_loop boolean If true, animation will loop. If false, it will play once. Default: `true` function ObjectRef:set_animation(frame_range, frame_speed, frame_blend, frame_loop) end ---- @return table,number,number,boolean `range`, `frame_speed`, `frame_blend` and `frame_loop`. + +--- Returns current animation parameters set by `set_animation`: +--- * `frame_range` +--- * `frame_speed` +--- * `frame_blend` +--- * `frame_loop` +--- @return table,number,number,boolean function ObjectRef:get_animation() end ---- @param frame_speed number default: `15.0` + +--- Sets the frame speed of the object's animation +--- +--- Unlike `set_animation`, this will not restart the animation +--- +--- `frame_speed`: See `set_animation`. +--- @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`. +--- @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`. function ObjectRef:set_attach(parent, bone, position, rotation, forced_visible) end + --- 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. + +--- Returns a list of ObjectRefs that are attached to the object. +--- @return ObjectRef[] function ObjectRef:get_children() end + +--- Detaches object. No-op if object was not attached. function ObjectRef:set_detach() end +--- Sets absolute bone overrides, e.g. it is equivalent to +--- ``` +--- obj:set_bone_override(bone, { +--- position = {vec = position, absolute = true}, +--- rotation = {vec = rotation:apply(math.rad), absolute = true} +--- }) +--- ``` +--- **Note**: Rotation is in degrees, not radians. --- +--- **Deprecated**: Use `set_bone_override` instead. --- @deprecated --- @param bone? string Default is `""`, the root bone --- @param position? Position `{x=num, y=num, z=num}`, relative, `default {x=0, y=0, z=0}` @@ -108,49 +202,135 @@ function ObjectRef:set_detach() end function ObjectRef:set_bone_position(bone, position, rotation) end --- Returns the previously set position and rotation of the bone. ---- - Shorthand for `get_bone_override(bone).position.vec, get_bone_override(bone).rotation.vec:apply(math.deg)`. ---- - **Note:** Returned rotation is in degrees, not radians. ---- - **Deprecated:** Use `get_bone_override` instead. --- +--- Shorthand for `get_bone_override(bone).position.vec, get_bone_override(bone).rotation.vec:apply(math.deg)`. +--- +--- **Note:** Returned rotation is in degrees, not radians. +--- +--- **Deprecated:** Use `get_bone_override` instead. +--- @deprecated --- @param bone string ---- @return Position,Position # position and rotation of the bone +--- @return Position,Position function ObjectRef:get_bone_position(bone) end ---- @param object_property_table table + +---@alias property { vec:vector, interpolation:number, absolute:boolean } + +--- `override = nil` (including omission) is shorthand for `override = {}` which clears the override. +--- +--- Each `property` is a table of the form `{ vec = vector, interpolation = 0, absolute = false }` or `nil` +--- * `vec` is in the same coordinate system as the model, and in radians for rotation. +--- It defaults to `vector.zero()` for translation and rotation and `vector.new(1, 1, 1)` for scale. +--- * `interpolation`: The old and new overrides are interpolated over this timeframe (in seconds). +--- * `absolute`: If set to `false` (which is the default), the override will be relative to the animated property: +--- * Translation in the case of `position`; +--- * Composition in the case of `rotation`; +--- * Per-axis multiplication in the case of `scale` +--- +--- `property = nil` is equivalent to no override on that property. +--- +--- **Note**: Unlike set_bone_position, the rotation is in radians, not degrees. +--- +--- Compatibility note: Clients prior to 5.9.0 only support absolute position and rotation. +--- +--- All values are treated as absolute and are set immediately (no interpolation). +--- @param bone string +--- @param override { position:property?, rotation:property?, scale:property? }? +function ObjectRef:set_bone_override(bone, override) end + +--- Returns `override` in the above format +--- +--- **Note**: Unlike get_bone_position, the returned rotation is in radians, not degrees. +--- @return {position:property, rotation:property, scale:property} +function ObjectRef:get_bone_override(bone) end + +--- Returns all bone overrides as table `{[bonename] = override, ...}`. +--- @return table +function ObjectRef:get_bone_overrides() end + +--- @param object_property_table ObjectProperties function ObjectRef:set_properties(object_property_table) end ---- @return table object property table + +--- Returns a table of all object properties +--- @return ObjectProperties function ObjectRef:get_properties() end ---- @return boolean true for players, false otherwise + +--- Sets observers (players this object is sent to) +--- +--- If observers is nil, the object's observers are "unmanaged": +--- The object is sent to all players as governed by server settings. This is the default. +--- +--- Attachments: The effective observers of an object are made up of all players who can observe the object +--- and are also effective observers of its parent object (if there is one). +--- +--- Players are automatically added to their own observer sets. Players must effectively observe themselves. +--- +--- Object activation and deactivation are unaffected by observability. +--- +--- Attached sounds do not work correctly and thus should not be used on objects with managed observers yet. +--- @param observers table is a "set" of player names: `{name1 = true, name2 = true, ...}`. +--- A set is a table where the keys are the elements of the set (in this case, valid player names) and the values are all true. +function ObjectRef:set_observers(observers) end + +--- Throws an error if the object is invalid +--- * returns nil if the observers are unmanaged +--- * returns a table with all observer names as keys and true values (a "set") otherwise +--- @return table +function ObjectRef:get_observers() end + +--- Like `get_observers()`, but returns the "effective" observers, taking into account attachments +--- +--- Time complexity: O(nm) +--- * n: number of observers of the involved entities +--- * m: number of ancestors along the attachment chain +--- @return table +function ObjectRef:get_effective_observers() end + +--- Returns `true` for players, `false` otherwise +--- @return boolean function ObjectRef:is_player() end + +--- Returns a table with the attributes of the nametag of an object +--- +--- A nametag is a HUD text rendered above the object +--- --- Example: --- ``` ---- { ---- text = "", ---- color = {a=0..255, r=0..255, g=0..255, b=0..255}, ---- bgcolor = {a=0..255, r=0..255, g=0..255, b=0..255}, ---- } +--- { +--- text = "", +--- color = {a=0..255, r=0..255, g=0..255, b=0..255}, +--- bgcolor = {a=0..255, r=0..255, g=0..255, b=0..255}, +--- } --- ``` ---- @return table a table with the attributes of the nametag of an object +--- @return {text:string, color:colorSpec, bgcolor:ColorSpec} function ObjectRef:get_nametag_attributes() end ---- sets the attributes of the nametag of an object. + +--- Sets the attributes of the nametag of an object. +--- +--- `attributes`: +--- ```{ +--- text = "My Nametag", +--- color = ColorSpec, +--- -- ^ Text color +--- bgcolor = ColorSpec or false, +--- -- ^ Sets background color of nametag +--- -- `false` will cause the background to be set +--- -- automatically based on user settings +--- -- Default: false +--- } +--- ``` --- @param attributes table ---- ``` ---- { ---- text = "My Nametag", ---- color = ColorSpec, ---- -- ^ Text color ---- bgcolor = ColorSpec or false, ---- -- ^ Sets background color of nametag ---- -- `false` will cause the background to be set automatically based on user settings ---- -- Default: false ---- } ---- ``` function ObjectRef:set_nametag_attributes(attributes) end + --- Returns a global unique identifier (a string) ---- For players, this is a player name. ---- For Lua entities, this is a uniquely generated string, guaranteed not to collide with player names. +--- +--- * For players, this is a player name. +--- * For Lua entities, this is a uniquely generated string, guaranteed not to collide with player names. +--- --- example: `@bGh3p2AbRE29Mb4biqX6OA` +--- --- GUIDs only use printable ASCII characters. --- GUIDs persist between object reloads, and their format is guaranteed not to change. +--- --- Thus you can use the GUID to identify an object in a particular world online and offline. --- @return string function ObjectRef:get_guid()