From 8bcf2ede4f0be2df8e4e15b46c1b860863d6b4d4 Mon Sep 17 00:00:00 2001 From: alek13 Date: Fri, 26 Sep 2025 01:06:10 +0300 Subject: [PATCH] Modern Lua Plugins: impromements & fixes in `ide-helper` for `ObjectRef` & `[Lua]Entity`. LG-1980 LG-1978 --- classes/LuaEntity.lua | 2 +- classes/ObjectRef.lua | 34 +++++++++++++++++++++++++--------- classes/ObjectRef/Entity.lua | 33 +++++++++++++++++++++++---------- 3 files changed, 49 insertions(+), 20 deletions(-) diff --git a/classes/LuaEntity.lua b/classes/LuaEntity.lua index bb22927..7fe381c 100644 --- a/classes/LuaEntity.lua +++ b/classes/LuaEntity.lua @@ -1,6 +1,6 @@ --- @class LuaEntity --- @field name string ---- @field object ObjectRef +--- @field object Entity LuaEntity = { } diff --git a/classes/ObjectRef.lua b/classes/ObjectRef.lua index 30cddf4..eb4f911 100644 --- a/classes/ObjectRef.lua +++ b/classes/ObjectRef.lua @@ -12,6 +12,7 @@ function ObjectRef:set_pos(pos) end --TODO: --- @return vector|Position returns the velocity, a 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. @@ -32,10 +33,16 @@ function ObjectRef:add_velocity(vel) end --- @param pos Position --- @param continuous boolean function ObjectRef:move_to(pos, continuous) end ---- 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 Position the direction from which the punch came, normalized vector + + +--- 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 function ObjectRef:punch(puncher, time_from_last_punch, tool_capabilities, direction) end --- @param clicker ObjectRef function ObjectRef:right_click(clicker) end @@ -92,12 +99,21 @@ function ObjectRef:get_attach() end --- @return ObjectRef[]|table a list of ObjectRefs that are attached to the object. function ObjectRef:get_children() end function ObjectRef:set_detach() end ---- @overload fun() ---- @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}` ---- @param rotation Position `{x=num, y=num, z=num}`, default `{x=0, y=0, z=0}` + +--- +--- @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}` +--- @param rotation? Position `{x=num, y=num, z=num}`, default `{x=0, y=0, z=0}` function ObjectRef:set_bone_position(bone, position, rotation) end ---- @return Position,Position position and rotation of the bone + +--- 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. +--- +--- @param bone string +--- @return Position,Position # position and rotation of the bone function ObjectRef:get_bone_position(bone) end --- @param object_property_table table function ObjectRef:set_properties(object_property_table) end diff --git a/classes/ObjectRef/Entity.lua b/classes/ObjectRef/Entity.lua index c422a6e..5b2d119 100644 --- a/classes/ObjectRef/Entity.lua +++ b/classes/ObjectRef/Entity.lua @@ -9,33 +9,43 @@ Entity = {} --- itself instantly becomes unusable with all further method calls having --- no effect and returning `nil`. function Entity:remove() end ---- @param vel vector e.g. `{x=0.0, y=2.3, z=1.0}` + +--- @param vel Position e.g. `{x=0.0, y=2.3, z=1.0}` or `vector.new(0.0, 2.3, 1.0)` function Entity:set_velocity(vel) end ---- @param acc vector + +--- @param acc Position e.g. `{x=0.0, y=2.3, z=1.0}` or `vector.new(0.0, 2.3, 1.0)` function Entity:set_acceleration(acc) end + --- Returns the acceleration, a vector. --- @return vector function Entity:get_acceleration() end + --- Remove & readd your objects to force a certain rotation. --- Does not reset rotation incurred through `automatic_rotate`. ---- @param rot vector (radians). X is pitch (elevation), Y is yaw (heading) and Z is roll (bank). +--- @param rot Position (radians). X is pitch (elevation), Y is yaw (heading) and Z is roll (bank). function Entity:set_rotation(rot) end + --- Returns the rotation, a vector (radians). --- @return vector function Entity:get_rotation() end + --- Sets the yaw in radians (heading). --- @param yaw number function Entity:set_yaw(yaw) end + --- Returns number in radians. --- @return number function Entity:get_yaw() end + --- Set a texture modifier to the base texture, for sprites and meshes. --- When calling `set_texture_mod` again, the previous one is discarded. --- @param mod string|TextureModifier the texture modifier. See [Texture modifiers]. function Entity:set_texture_mod(mod) end + --- Returns current texture modifier. --- @return string|TextureModifier function Entity:get_texture_mod() end + --- Specifies and starts a sprite animation. --- Only used by `sprite` and `upright_sprite` visuals. --- Animations iterate along the frame `y` position. @@ -43,16 +53,19 @@ function Entity:get_texture_mod() end --- @param num_frames number Total frames in the texture, default: `1` --- @param framelength number Time per animated frame in seconds, default: `0.2` --- @param select_x_by_camera boolean Only for visual = `sprite`. Changes the frame `x`position according to the view direction. default: `false`. ---- First column: subject facing the camera ---- Second column: subject looking to the left ---- Third column: subject backing the camera ---- Fourth column: subject looking to the right ---- Fifth column: subject viewed from above ---- Sixth column: subject viewed from below +--- - First column: subject facing the camera +--- - Second column: subject looking to the left +--- - Third column: subject backing the camera +--- - Fourth column: subject looking to the right +--- - Fifth column: subject viewed from above +--- - Sixth column: subject viewed from below function Entity:set_sprite(start_frame, num_frames, framelength, select_x_by_camera) end + --- (**Deprecated**: Will be removed in a future version, use the field `self.name` instead) --- @deprecated --- @return string function Entity:get_entity_name() end ---- @return LuaEntity + +--- @generic Lua_Entity: LuaEntity +--- @return Lua_Entity function Entity:get_luaentity() end