Update annotations ObjectRef: Fixing annotations, adding missing methods, fixing return type (position -> vector) #8

This commit is contained in:
Van
2026-02-16 21:26:51 +03:00
parent 6c9b96dc00
commit a8dfcb767b

View File

@@ -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<string,number>
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<number,ObjectRef> 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<string,any>
---@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<string,{position:property, rotation:property, scale:property}>
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<string,boolean> 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<string, boolean>
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<string, boolean>
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()