Improve object documentation in lua_api.md (#13239)

Co-authored-by: DS <ds.desour@proton.me>
This commit is contained in:
Wuzzy 2023-07-30 15:54:01 +02:00 committed by GitHub
parent 3f2a10bb4b
commit 20e9969313
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23

@ -7411,15 +7411,19 @@ child will follow movement and rotation of that bone.
### Methods ### Methods
* `get_pos()`: returns `{x=num, y=num, z=num}` * `get_pos()`: returns position as vector `{x=num, y=num, z=num}`
* `set_pos(pos)`: `pos`=`{x=num, y=num, z=num}` * `set_pos(pos)`:
* Sets the position of the object.
* No-op if object is attached.
* `pos` is a vector `{x=num, y=num, z=num}`
* `get_velocity()`: returns the velocity, a vector. * `get_velocity()`: returns the velocity, a vector.
* `add_velocity(vel)` * `add_velocity(vel)`
* Changes velocity by adding to the current velocity.
* `vel` is a vector, e.g. `{x=0.0, y=2.3, z=1.0}` * `vel` is a vector, e.g. `{x=0.0, y=2.3, z=1.0}`
* In comparison to using get_velocity, adding the velocity and then using * In comparison to using get_velocity, adding the velocity and then using
set_velocity, add_velocity is supposed to avoid synchronization problems. set_velocity, add_velocity is supposed to avoid synchronization problems.
Additionally, players also do not support set_velocity. Additionally, players also do not support set_velocity.
* If a player: * If object is a player:
* Does not apply during free_move. * Does not apply during free_move.
* Note that since the player speed is normalized at each move step, * Note that since the player speed is normalized at each move step,
increasing e.g. Y velocity beyond what would usually be achieved increasing e.g. Y velocity beyond what would usually be achieved
@ -7431,11 +7435,19 @@ child will follow movement and rotation of that bone.
* If `continuous` is true, the Lua entity will not be moved to the current * If `continuous` is true, the Lua entity will not be moved to the current
position before starting the interpolated move. position before starting the interpolated move.
* For players this does the same as `set_pos`,`continuous` is ignored. * For players this does the same as `set_pos`,`continuous` is ignored.
* `punch(puncher, time_from_last_punch, tool_capabilities, direction)` * no-op if object is attached
* `puncher` = another `ObjectRef`, * `punch(puncher, time_from_last_punch, tool_capabilities, dir)`
* `time_from_last_punch` = time since last punch action of the puncher * punches the object, triggering all consequences a normal punch would have
* `direction`: can be `nil` * `puncher`: another `ObjectRef` which punched the object
* `right_click(clicker)`; `clicker` is another `ObjectRef` * `dir`: direction vector of punch
* Other arguments: See `on_punch` for entities
* All arguments except `puncher` can be `nil`, in which case a default
value will be used
* `right_click(clicker)`:
* simulates using the 'place/use' key on the object
* triggers all consequences as if a real player had done this
* `clicker` is another `ObjectRef` which has clicked
* note: this is called `right_click` for historical reasons only
* `get_hp()`: returns number of health points * `get_hp()`: returns number of health points
* `set_hp(hp, reason)`: set number of health points * `set_hp(hp, reason)`: set number of health points
* See reason in register_on_player_hpchange * See reason in register_on_player_hpchange
@ -7444,46 +7456,74 @@ child will follow movement and rotation of that bone.
* `get_inventory()`: returns an `InvRef` for players, otherwise returns `nil` * `get_inventory()`: returns an `InvRef` for players, otherwise returns `nil`
* `get_wield_list()`: returns the name of the inventory list the wielded item * `get_wield_list()`: returns the name of the inventory list the wielded item
is in. is in.
* `get_wield_index()`: returns the index of the wielded item * `get_wield_index()`: returns the wield list index of the wielded item (starting with 1)
* `get_wielded_item()`: returns an `ItemStack` * `get_wielded_item()`: returns the wielded item as an `ItemStack`
* `set_wielded_item(item)`: replaces the wielded item, returns `true` if * `set_wielded_item(item)`: replaces the wielded item, returns `true` if
successful. successful.
* `get_armor_groups()`:
* 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' for details
* `set_armor_groups({group1=rating, group2=rating, ...})` * `set_armor_groups({group1=rating, group2=rating, ...})`
* `get_armor_groups()`: returns a table with the armor group ratings * 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
* `set_animation(frame_range, frame_speed, frame_blend, frame_loop)` * `set_animation(frame_range, frame_speed, frame_blend, frame_loop)`
* `frame_range`: table {x=num, y=num}, default: `{x=1, y=1}` * Sets the object animation parameters and (re)starts the animation
* `frame_speed`: number, default: `15.0` * Animations only work with a `"mesh"` visual
* `frame_range`: Beginning and end frame (as specified in the mesh file).
* Syntax: `{x=start_frame, y=end_frame}`
* 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
* Only integer numbers are supported
* default: `{x=1, y=1}`
* `frame_speed`: How fast the animation plays, in frames per second (number)
* default: `15.0`
* `frame_blend`: number, default: `0.0` * `frame_blend`: number, default: `0.0`
* `frame_loop`: boolean, default: `true` * `frame_loop`: If `true`, animation will loop. If false, it will play once
* `get_animation()`: returns `range`, `frame_speed`, `frame_blend` and * default: `true`
`frame_loop`. * `get_animation()`: returns current animation parameters set by `set_animaition`:
* `range`, `frame_speed`, `frame_blend`, `frame_loop`.
* `set_animation_frame_speed(frame_speed)` * `set_animation_frame_speed(frame_speed)`
* `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`
* `set_attach(parent[, bone, position, rotation, forced_visible])` * `set_attach(parent[, bone, position, rotation, forced_visible])`
* Attaches object to `parent`
* See 'Attachments' section for details
* `parent`: `ObjectRef` to attach to * `parent`: `ObjectRef` to attach to
* `bone`: default `""` (the root bone) * `bone`: Bone to attach to. Default is `""` (the root bone)
* `position`: relative position, default `{x=0, y=0, z=0}` * `position`: relative position, default `{x=0, y=0, z=0}`
* `rotation`: relative rotation in degrees, default `{x=0, y=0, z=0}` * `rotation`: relative rotation in degrees, default `{x=0, y=0, z=0}`
* `forced_visible`: Boolean to control whether the attached entity * `forced_visible`: Boolean to control whether the attached entity
should appear in first person, default `false`. 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 * This command may fail silently (do nothing) when it would result
in circular attachments. in circular attachments.
* `get_attach()`: returns parent, bone, position, rotation, forced_visible, * `get_attach()`:
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`
* `get_children()`: returns a list of ObjectRefs that are attached to the * `get_children()`: returns a list of ObjectRefs that are attached to the
object. object.
* `set_detach()` * `set_detach()`: Detaches object. No-op if object was not attached.
* `set_bone_position([bone, position, rotation])` * `set_bone_position([bone, position, rotation])`
* `bone`: string. Default is `""`, the root bone * `bone`: string. Default is `""`, the root bone
* `position`: `{x=num, y=num, z=num}`, relative, `default {x=0, y=0, z=0}` * `position`: `{x=num, y=num, z=num}`, relative, `default {x=0, y=0, z=0}`
* `rotation`: `{x=num, y=num, z=num}`, default `{x=0, y=0, z=0}` * `rotation`: `{x=num, y=num, z=num}`, default `{x=0, y=0, z=0}`
* `get_bone_position(bone)`: returns position and rotation of the bone * `get_bone_position(bone)`:
* `set_properties(object property table)` * returns bone parameters previously set by `set_bone_position`
* `get_properties()`: returns object property table * returns `position, rotation` of the specified bone (as vectors)
* note: position is relative to the object
* `set_properties(object property table)`:
* set a number of object properties in the given table
* only properties listed in the table will be changed
* see the 'Object properties' section for details
* `get_properties()`: returns a table of all object properties
* `is_player()`: returns true for players, false otherwise * `is_player()`: returns true for players, false otherwise
* `get_nametag_attributes()` * `get_nametag_attributes()`
* returns a table with the attributes of the nametag of an object * returns a table with the attributes of the nametag of an object
* a nametag is a HUD text rendered above the object
* ```lua * ```lua
{ {
text = "", text = "",
@ -7513,11 +7553,14 @@ child will follow movement and rotation of that bone.
itself instantly becomes unusable with all further method calls having itself instantly becomes unusable with all further method calls having
no effect and returning `nil`. no effect and returning `nil`.
* `set_velocity(vel)` * `set_velocity(vel)`
* Sets the velocity
* `vel` is a vector, e.g. `{x=0.0, y=2.3, z=1.0}` * `vel` is a vector, e.g. `{x=0.0, y=2.3, z=1.0}`
* `set_acceleration(acc)` * `set_acceleration(acc)`
* Sets the acceleration
* `acc` is a vector * `acc` is a vector
* `get_acceleration()`: returns the acceleration, a vector * `get_acceleration()`: returns the acceleration, a vector
* `set_rotation(rot)` * `set_rotation(rot)`
* Sets the rotation
* `rot` is a vector (radians). X is pitch (elevation), Y is yaw (heading) * `rot` is a vector (radians). X is pitch (elevation), Y is yaw (heading)
and Z is roll (bank). and Z is roll (bank).
* Does not reset rotation incurred through `automatic_rotate`. * Does not reset rotation incurred through `automatic_rotate`.
@ -7532,6 +7575,7 @@ child will follow movement and rotation of that bone.
* `get_texture_mod()` returns current texture modifier * `get_texture_mod()` returns current texture modifier
* `set_sprite(start_frame, num_frames, framelength, select_x_by_camera)` * `set_sprite(start_frame, num_frames, framelength, select_x_by_camera)`
* Specifies and starts a sprite animation * Specifies and starts a sprite animation
* Only used by `sprite` and `upright_sprite` visuals
* Animations iterate along the frame `y` position. * Animations iterate along the frame `y` position.
* `start_frame`: {x=column number, y=row number}, the coordinate of the * `start_frame`: {x=column number, y=row number}, the coordinate of the
first frame, default: `{x=0, y=0}` first frame, default: `{x=0, y=0}`
@ -7546,11 +7590,11 @@ child will follow movement and rotation of that bone.
* Fifth column: subject viewed from above * Fifth column: subject viewed from above
* Sixth column: subject viewed from below * Sixth column: subject viewed from below
* `get_entity_name()` (**Deprecated**: Will be removed in a future version, use the field `self.name` instead) * `get_entity_name()` (**Deprecated**: Will be removed in a future version, use the field `self.name` instead)
* `get_luaentity()` * `get_luaentity()`: returns the object's associated luaentity table
#### Player only (no-op for other objects) #### Player only (no-op for other objects)
* `get_player_name()`: returns `""` if is not a player * `get_player_name()`: Returns player name or `""` if is not a player
* `get_player_velocity()`: **DEPRECATED**, use get_velocity() instead. * `get_player_velocity()`: **DEPRECATED**, use get_velocity() instead.
table {x, y, z} representing the player's instantaneous velocity in nodes/s table {x, y, z} representing the player's instantaneous velocity in nodes/s
* `add_player_velocity(vel)`: **DEPRECATED**, use add_velocity(vel) instead. * `add_player_velocity(vel)`: **DEPRECATED**, use add_velocity(vel) instead.
@ -7583,7 +7627,7 @@ child will follow movement and rotation of that bone.
* See [Object properties] for more information * See [Object properties] for more information
* Is limited to range 0 ... 65535 (2^16 - 1) * Is limited to range 0 ... 65535 (2^16 - 1)
* `set_fov(fov, is_multiplier, transition_time)`: Sets player's FOV * `set_fov(fov, is_multiplier, transition_time)`: Sets player's FOV
* `fov`: FOV value. * `fov`: Field of View (FOV) value.
* `is_multiplier`: Set to `true` if the FOV value is a multiplier. * `is_multiplier`: Set to `true` if the FOV value is a multiplier.
Defaults to `false`. Defaults to `false`.
* `transition_time`: If defined, enables smooth FOV transition. * `transition_time`: If defined, enables smooth FOV transition.
@ -7602,7 +7646,7 @@ child will follow movement and rotation of that bone.
* `get_attribute(attribute)`: DEPRECATED, use get_meta() instead * `get_attribute(attribute)`: DEPRECATED, use get_meta() instead
* Returns value (a string) for extra attribute. * Returns value (a string) for extra attribute.
* Returns `nil` if no attribute found. * Returns `nil` if no attribute found.
* `get_meta()`: Returns a PlayerMetaRef. * `get_meta()`: Returns metadata associated with the player (a PlayerMetaRef).
* `set_inventory_formspec(formspec)` * `set_inventory_formspec(formspec)`
* Redefine player's inventory form * Redefine player's inventory form
* Should usually be called in `on_joinplayer` * Should usually be called in `on_joinplayer`