From b924170d10db8e7d4f9fd1cc2439c477ca8fece1 Mon Sep 17 00:00:00 2001 From: Vanic Date: Mon, 8 Jun 2026 21:14:34 +0300 Subject: [PATCH] `Player`: update annotations --- classes/ObjectRef/Player.lua | 515 +++++++++++++++++++++++------------ 1 file changed, 338 insertions(+), 177 deletions(-) diff --git a/classes/ObjectRef/Player.lua b/classes/ObjectRef/Player.lua index 3a9b9c1..e073f89 100644 --- a/classes/ObjectRef/Player.lua +++ b/classes/ObjectRef/Player.lua @@ -1,245 +1,331 @@ --- @meta - --- @class Player: ObjectRef Player = {} --- @return InvRef function Player:get_inventory() end ---- returns `""` if is not a player +--- Returns player name or `""` if is not a player. --- @return string function Player:get_player_name() end ---- **DEPRECATED**, use get_velocity() instead. ---- table {x, y, z} representing the player's instantaneous velocity in nodes/s +--- **DEPRECATED**, use `get_velocity()` instead. +--- table {x, y, z} representing the player's instantaneous velocity in nodes/s --- @deprecated function Player:get_player_velocity() end ---- **DEPRECATED**, use add_velocity(vel) instead. +--- **DEPRECATED**, use `add_velocity(vel)` instead. --- @deprecated function Player:add_player_velocity(vel) end ---- get camera direction as a unit vector +--- Get camera direction as a unit vector. +--- @return vector function Player:get_look_dir() end ---- pitch in radians ---- * Angle ranges between -pi/2 and pi/2, which are straight up and down ---- respectively. +--- Pitch in radians. +--- +--- Angle ranges between -pi/2 and pi/2, which are straight up and down respectively. +--- @return number function Player:get_look_vertical() end ---- yaw in radians ---- * Angle is counter-clockwise from the +z direction. +--- Yaw in radians. +--- +--- Angle is counter-clockwise from the +z direction. --- @return number function Player:get_look_horizontal() end ---- sets look pitch ---- * radians: Angle from looking forward, where positive is downwards. +--- Sets look pitch. +--- @param radians number Angle from looking forward, where positive is downwards. function Player:set_look_vertical(radians) end ---- sets look yaw ---- * radians: Angle from the +z direction, where positive is counter-clockwise. +--- Sets look yaw. +--- @param radians number Angle from the +z direction, where positive is counter-clockwise. function Player:set_look_horizontal(radians) end ---- pitch in radians - Deprecated as broken. Use ---- `get_look_vertical`. ---- * Angle ranges between -pi/2 and pi/2, which are straight down and up ---- respectively. +--- Pitch in radians - Deprecated as broken. Use `get_look_vertical`. +--- @deprecated function Player:get_look_pitch() end ---- yaw in radians - Deprecated as broken. Use ---- `get_look_horizontal`. ---- * Angle is counter-clockwise from the +x direction. +--- Yaw in radians - Deprecated as broken. Use `get_look_horizontal`. --- @deprecated function Player:get_look_yaw() end ---- sets look pitch - Deprecated. Use `set_look_vertical`. +--- Sets look pitch - Deprecated. Use `set_look_vertical`. +--- @deprecated function Player:set_look_pitch(radians) end ---- sets look yaw - Deprecated. Use ---- `set_look_horizontal`. +--- Sets look yaw - Deprecated. Use `set_look_horizontal`. +--- @deprecated function Player:set_look_yaw(radians) end ---- returns player's breath +--- Returns player's breath. +--- @return integer function Player:get_breath() end ---- sets player's breath ---- * values: ---- * `0`: player is drowning ---- * max: bubbles bar is not shown ---- * See [Object properties] for more information ---- * Is limited to range 0 ... 65535 (2^16 - 1) +--- Sets player's breath +--- +--- values: +--- * `0`: player is drowning +--- * max: bubbles bar is not shown +--- * See [Object properties](https://api.luanti.org/class-reference/#object-properties) for more information +--- +--- Is limited to range 0 ... 65535 (2^16 - 1) +--- @param value integer function Player:set_breath(value) end ---- Sets player's FOV ---- * `fov`: FOV value. ---- * `is_multiplier`: Set to `true` if the FOV value is a multiplier. ---- Defaults to `false`. ---- * `transition_time`: If defined, enables smooth FOV transition. ---- Interpreted as the time (in seconds) to reach target FOV. ---- If set to 0, FOV change is instantaneous. Defaults to 0. ---- * Set `fov` to 0 to clear FOV override. +--- Sets player's FOV. +--- +--- Set `fov` to 0 to clear FOV override. +--- @param fov integer FOV value. +--- @param is_multiplier boolean Set to `true` if the FOV value is a multiplier. Defaults to `false`. +--- @param transition_time number `transition_time`: If defined, enables smooth FOV transition. +--- Interpreted as the time (in seconds) to reach target FOV. +--- If set to 0, FOV change is instantaneous. Defaults to 0. function Player:set_fov(fov, is_multiplier, transition_time) end ---- Returns the following: ---- * Server-sent FOV value. Returns 0 if an FOV override doesn't exist. ---- * Boolean indicating whether the FOV value is a multiplier. ---- * Time (in seconds) taken for the FOV transition. Set by `set_fov`. +--- Returns the FOV. +--- @return integer fov Server-sent FOV value. Returns 0 if an FOV override doesn't exist. +--- @return boolean is_multiplier Boolean indicating whether the FOV value is a multiplier. +--- @return number transition_time Time (in seconds) taken for the FOV transition. Set by `set_fov`. function Player:get_fov() end ---- DEPRECATED, use get_meta() instead +--- DEPRECATED, use `get_meta()` instead --- * Sets an extra attribute with value on player. --- * `value` must be a string, or a number which will be converted to a --- string. --- * If `value` is `nil`, remove attribute from player. +--- @deprecated function Player:set_attribute(attribute, value) end ---- DEPRECATED, use get_meta() instead +--- DEPRECATED, use `get_meta()` instead --- * Returns value (a string) for extra attribute. --- * Returns `nil` if no attribute found. +--- @deprecated function Player:get_attribute(attribute) end ---- Returns a PlayerMetaRef. +--- Returns metadata associated with the player (a PlayerMetaRef). --- @return PlayerMetaRef function Player:get_meta() end ---- * Redefine player's inventory form ---- * Should usually be called in `on_joinplayer` ---- * If `formspec` is `""`, the player's inventory is disabled. +--- Redefines the player's inventory formspec. +--- +--- Should usually be called at least once in the `on_joinplayer` callback. +--- +--- If `formspec` is `""`, the player's inventory is disabled. +--- +--- If the inventory formspec is currently open on the client, it is updated immediately. +--- +--- See also: `core.register_on_player_receive_fields` +--- @param formspec string function Player:set_inventory_formspec(formspec) end ---- returns a formspec string +--- Returns a formspec string. +--- @return string function Player:get_inventory_formspec() end ---- * the formspec string will be added to every formspec shown to the user, ---- except for those with a no_prepend[] tag. ---- * This should be used to set style elements such as background[] and ---- bgcolor[], any non-style elements (eg: label) may result in weird behavior. ---- * Only affects formspecs shown after this is called. +--- The formspec string will be added to every formspec shown to the user, +--- except for those with a no_prepend[] tag. +--- +--- This should be used to set style elements such as background[] and +--- bgcolor[], any non-style elements (eg: label) may result in weird behavior. +--- +--- Only affects formspecs shown after this is called. +--- @param formspec string function Player:set_formspec_prepend(formspec) end ---- returns a formspec string. +--- Returns a formspec string. +--- @return string function Player:get_formspec_prepend(formspec) end ---- returns table with player pressed keys ---- * The table consists of fields with the following boolean values ---- representing the pressed keys: `up`, `down`, `left`, `right`, `jump`, ---- `aux1`, `sneak`, `dig`, `place`, `LMB`, `RMB`, and `zoom`. ---- * The fields `LMB` and `RMB` are equal to `dig` and `place` respectively, ---- and exist only to preserve backwards compatibility. ---- * Returns an empty table `{}` if the object is not a player. +--- @alias Player.controls_key 'up'|'down'|'left'|'right'|'jump'|'aux1'|'sneak'|'dig'|'place'|'LMB'|'RBM'|'zoom'|'movement_x'|'movement_y' + +--- Returns table with player pressed keys --- ---- @return table +--- The table consists of fields with the following boolean values +--- representing the pressed keys: `up`, `down`, `left`, `right`, `jump`, +--- `aux1`, `sneak`, `dig`, `place`, `LMB`, `RMB`, and `zoom`. +--- +--- The fields `LMB` and `RMB` are equal to `dig` and `place` respectively, +--- and exist only to preserve backwards compatibility. +--- +--- Returns an empty table `{}` if the object is not a player. +--- @return table function Player:get_player_control() end ---- returns integer with bit packed player pressed ---- keys. ---- * Bits: ---- * 0 - up ---- * 1 - down ---- * 2 - left ---- * 3 - right ---- * 4 - jump ---- * 5 - aux1 ---- * 6 - sneak ---- * 7 - dig ---- * 8 - place ---- * 9 - zoom ---- * Returns `0` (no bits set) if the object is not a player. +--- Returns integer with bit packed player pressed keys. +--- +--- Bits: +--- * 0 - up +--- * 1 - down +--- * 2 - left +--- * 3 - right +--- * 4 - jump +--- * 5 - aux1 +--- * 6 - sneak +--- * 7 - dig +--- * 8 - place +--- * 9 - zoom +--- +--- Returns `0` (no bits set) if the object is not a player. --- @return number function Player:get_player_control_bits() end ---- @class physics_override_table ---- @field speed? number multiplier to default walking speed value (default: `1`) ---- @field speed_walk? number multiplier to default walk speed value (default: `1`). Note: The actual walk speed is the product of `speed` and `speed_walk` ---- @field speed_climb? number multiplier to default climb speed value (default: `1`). Note: The actual climb speed is the product of `speed` and `speed_climb` ---- @field speed_crouch? number multiplier to default crouch speed value (default: `1`). Note: The actual crouch speed is the product of `speed` and `speed_crouch` ---- @field speed_fast? number multiplier to default fast (sprint) speed value (default: `1`). Note: The actual fast speed is the product of `speed` and `speed_fast` ---- @field jump? number multiplier to default jump value (default: `1`) ---- @field gravity? number multiplier to default gravity value (default: `1`) ---- @field liquid_fluidity? number multiplier to liquid movement resistance value (for nodes with `liquid_move_physics`); the higher this value, the lower the resistance to movement. At math.huge, the resistance is zero and you can move through any liquid like air. (default: `1`). Warning: Values below 1 are currently unsupported. ---- @field liquid_fluidity_smooth? number multiplier to default maximum liquid resistance value (for nodes with `liquid_move_physics`); controls deceleration when entering node at high speed. At higher values you come to a halt more quickly (default: `1`) ---- @field liquid_sink? number multiplier to default liquid sinking speed value; (for nodes with `liquid_move_physics`), (default: `1`) ---- @field acceleration_default? number multiplier to default acceleration value (default: `1`). Note: The actual acceleration is the product of `speed` and `acceleration_default` ---- @field acceleration_air? number multiplier to default air acceleration value (default: `1`). Note: The actual air acceleration is the product of `speed` and `acceleration_air` ---- @field acceleration_fast? number multiplier to default fast (sprint) acceleration (default: `1`). Note: The actual fast acceleration is the product of `speed` and `acceleration_fast` ---- @field sneak? boolean whether player can sneak (default: `true`) ---- @field sneak_glitch? boolean whether player can use the new move code replications of the old sneak side-effects: sneak ladders and 2 node sneak jump (default: `false`) ---- @field new_move? boolean use new move/sneak code. When `false` the exact old code is used for the specific old sneak behavior (default: `true`) +--- @class Player.physics_override_table +--- Multiplier to all movement speed (`speed_*`) +--- and acceleration (`acceleration_*`) values (default: `1`) +--- @field speed number? +--- +--- Multiplier to default walk speed value (default: `1`). +--- Note: The actual walk speed is the product of `speed` and `speed_walk` +--- @field speed_walk number? +--- +--- Multiplier to default climb speed value (default: `1`). +--- Note: The actual climb speed is the product of `speed` and `speed_climb` +--- @field speed_climb number? +--- +--- Multiplier to default crouch speed value (default: `1`). +--- Note: The actual crouch speed is the product of `speed` and `speed_crouch` +--- @field speed_crouch number? +--- +--- Multiplier to default fast (sprint) speed value (default: `1`). +--- Note: The actual fast speed is the product of `speed` and `speed_fast` +--- @field speed_fast number? +--- +--- Multiplier to default jump value (default: `1`) +--- @field jump number? +--- +--- Multiplier to default gravity value (default: `1`) +--- @field gravity number? +--- +--- Multiplier to liquid movement resistance value (for nodes with `liquid_move_physics`); +--- the higher this value, the lower the resistance to movement. +--- At `math.huge`, the resistance is zero and you can move through any liquid like air. (default: `1`). +--- Warning: Values below 1 are currently unsupported. +--- @field liquid_fluidity number? +--- +--- Multiplier to default maximum liquid resistance value (for nodes with `liquid_move_physics`); +--- controls deceleration when entering node at high speed. +--- At higher values you come to a halt more quickly (default: `1`) +--- @field liquid_fluidity_smooth number? +--- +--- Multiplier to default liquid sinking speed value; (for nodes with `liquid_move_physics`), (default: `1`) +--- @field liquid_sink number? +--- +--- Multiplier to default acceleration value (default: `1`). +--- Note: The actual acceleration is the product of `speed` and `acceleration_default` +--- @field acceleration_default number? +--- +--- Multiplier to default air acceleration value (default: `1`). +--- Note: The actual air acceleration is the product of `speed` and `acceleration_air` +--- @field acceleration_air number? +--- +--- Multiplier to default fast (sprint) acceleration (default: `1`). +--- Note: The actual fast acceleration is the product of `speed` and `acceleration_fast` +--- @field acceleration_fast number? +--- +--- Whether player can sneak (default: `true`) +--- @field sneak boolean? +--- +--- Whether player can use the new move code replications of the old sneak side-effects: sneak ladders and 2 node sneak jump (default: `false`) +--- @field sneak_glitch boolean? +--- +--- Use new move/sneak code. When `false` the exact old code is used for the specific old sneak behavior (default: `true`) +--- @field new_move boolean? ---- set physics override for player ---- * `override_table` is a table with the following fields: ---- * `speed`: multiplier to default walking speed value (default: `1`) ---- * `jump`: multiplier to default jump value (default: `1`) ---- * `gravity`: multiplier to default gravity value (default: `1`) ---- * `sneak`: whether player can sneak (default: `true`) ---- * `sneak_glitch`: whether player can use the new move code replications ---- of the old sneak side-effects: sneak ladders and 2 node sneak jump ---- (default: `false`) ---- * `new_move`: use new move/sneak code. When `false` the exact old code ---- is used for the specific old sneak behavior (default: `true`) ---- @param override_table physics_override_table +--- Overrides the physics attributes of the player +--- Note: All numeric fields above modify a corresponding movement_* setting. +--- @param override_table Player.physics_override_table function Player:set_physics_override(override_table) end ---- returns the table given to `set_physics_override` ---- @return physics_override_table +--- Returns the table given to `set_physics_override`. +--- @return Player.physics_override_table function Player:get_physics_override() end ---- add a HUD element described by HUD def, returns ID ---- number on success +--- Add a HUD element described by HUD def, returns ID number on success. +--- @param hud_definition HudDefinition +--- @return integer function Player:hud_add(hud_definition) end ---- remove the HUD element of the specified id +--- Remove the HUD element of the specified id. +--- @param id integer function Player:hud_remove(id) end ---- change a value of a previously added HUD ---- element. ---- * `stat` supports the same keys as in the hud definition table except for ---- `"hud_elem_type"`. +--- Change a value of a previously added HUD element. +--- @param id integer +--- @param stat string supports the same keys as in the hud definition table except for `"type"` (or the deprecated `"hud_elem_type"`). +--- @param value any function Player:hud_change(id, stat, value) end ---- gets the HUD element definition structure of the specified ID +--- Gets the HUD element definition structure of the specified ID. +--- @param id integer +--- @return HudDefinition function Player:hud_get(id) end ---- sets specified HUD flags of player. ---- * `flags`: A table with the following fields set to boolean values ---- * `hotbar` ---- * `healthbar` ---- * `crosshair` ---- * `wielditem` ---- * `breathbar` ---- * `minimap`: Modifies the client's permission to view the minimap. ---- The client may locally elect to not view the minimap. ---- * `minimap_radar`: is only usable when `minimap` is true ---- * `basic_debug`: Allow showing basic debug info that might give a gameplay advantage. ---- This includes map seed, player position, look direction, the pointed node and block bounds. ---- Does not affect players with the `debug` privilege. ---- * If a flag equals `nil`, the flag is not modified +--- @class Player.hud_flags +--- @field hotbar boolean? +--- @field healthbar boolean? +--- @field crosshair boolean? +--- @field wielditem boolean? +--- @field breathbar boolean? +--- +--- Modifies the client's permission to view the minimap. +--- The client may locally elect to not view the minimap +--- @field minimap boolean? +--- +--- Is only usable when `minimap` is true +--- @field minimap_radar boolean? +--- +--- Allow showing basic debug info that might give a gameplay advantage. +--- This includes map seed, player position, look direction, the pointed node and block bounds. +--- Does not affect players with the `debug` privilege. +--- @field basic_debug boolean? +--- +--- Modifies the client's permission to view chat on the HUD. +--- The client may locally elect to not view chat. Does not affect the console. +--- @field chat boolean? + +--- Sets specified HUD flags of player. +--- +--- If a flag equals `nil`, the flag is not modified +--- @param flags Player.hud_flags function Player:hud_set_flags(flags) end ---- returns a table of player HUD flags with boolean values. ---- * See `hud_set_flags` for a list of flags that can be toggled. +--- Returns a table of player HUD flags with boolean values. +--- @return Player.hud_flags function Player:hud_get_flags() end ---- sets number of items in builtin hotbar ----- * `count`: number of items, must be between `1` and `32` +--- Sets number of items in builtin hotbar. +--- +--- If count exceeds the `"main"` list size, the list size will be used instead. +--- @param count integer number of items, must be an integer in range [1, 32] function Player:hud_set_hotbar_itemcount(count) end ---- returns number of visible items +--- Returns number of visible items. +--- +--- This value is also clamped by the `"main"` list size. +--- @return integer function Player:hud_get_hotbar_itemcount() end ---- * sets background image for hotbar +--- Sets background image for hotbar. +--- @param string function Player:hud_set_hotbar_image(texturename) end ---- returns texturename +--- Returns texturename. +--- @return string function Player:hud_get_hotbar_image() end ---- * sets image for selected item of hotbar +--- Sets image for selected item of hotbar. +--- @param string function Player:hud_set_hotbar_selected_image(texturename) end ---- returns texturename +--- Returns texturename. +--- @return string function Player:hud_get_hotbar_selected_image() end +--- TODO +--- @class Player.minimap_mode + --- modes_list: {mode, mode, ...} --- * Overrides the available minimap modes (and toggle order), and changes the --- selected mode. @@ -259,10 +345,13 @@ function Player:hud_get_hotbar_selected_image() end --- * `scale`: Only for texture type, scale of the texture map in nodes per --- pixel (for example a `scale` of 2 means each pixel represents a 2x2 --- nodes square) ---- * `selected_mode` is the mode index to be selected after modes have been changed ---- (0 is the first mode). +--- @param modes_list Player.minimap_mode[] +--- @param selected_mode integer is the mode index to be selected after modes have been changed (0 is the first mode). function Player:set_minimap_modes(modes_list, selected_mode) end +--- TODO +--- @class Player.sky_parameters + --- * The presence of the function `set_sun`, `set_moon` or `set_stars` indicates --- whether `set_sky` accepts this format. Check the legacy format otherwise. --- * Passing no arguments resets the sky to its default values. @@ -323,10 +412,10 @@ function Player:set_minimap_modes(modes_list, selected_mode) end --- * `fog_color`: ColorSpec, override the color of the fog. --- Unlike `base_color` above this will apply regardless of the skybox type. --- (default: `"#00000000"`, which means no override) ---- @param sky_parameters table +--- @param sky_parameters Player.sky_parameters function Player:set_sky(sky_parameters) end ---- * Deprecated. Use `set_sky(sky_parameters)` +--- Deprecated. Use `set_sky(sky_parameters)` --- * `base_color`: ColorSpec, defaults to white --- * `type`: Available types: --- * `"regular"`: Uses 0 textures, `bgcolor` ignored @@ -334,20 +423,24 @@ function Player:set_sky(sky_parameters) end --- * `"plain"`: Uses 0 textures, `bgcolor` used --- * `clouds`: Boolean for whether clouds appear in front of `"skybox"` or --- `"plain"` custom skyboxes (default: `true`) +--- @deprecated function Player:set_sky(base_color, type, texture_names, clouds) end ---- * `as_table`: boolean that determines whether the deprecated version of this ---- function is being used. ---- * `true` returns a table containing sky parameters as defined in `set_sky(sky_parameters)`. ---- * Deprecated: `false` or `nil` returns base_color, type, table of textures, ---- clouds. +--- @param as_table boolean boolean that determines whether the deprecated version of this function is being used. +--- * `true` returns a table containing sky parameters as defined in `set_sky(sky_parameters)`. +--- * Deprecated: `false` or `nil` returns base_color, type, table of textures, clouds. +--- @return table Player.sky_parameters function Player:get_sky(as_table) end ---- * Deprecated: Use `get_sky(as_table)` instead. ---- * returns a table with the `sky_color` parameters as in `set_sky`. +--- Deprecated: Use `get_sky(as_table)` instead. +--- +--- Returns a table with the `sky_color` parameters as in `set_sky`. --- @deprecated function Player:get_sky_color() end +--- TODO +---@class Player.sun_parameters + --- * Passing no arguments resets the sun to its default values. --- * `sun_parameters` is a table with the following optional fields: --- * `visible`: Boolean for whether the sun is visible. @@ -365,12 +458,16 @@ function Player:get_sky_color() end --- * `scale`: Float controlling the overall size of the sun. (default: `1`) --- Note: For legacy reasons, the sun is bigger than the moon by a factor --- of about `1.57` for equal `scale` values. +--- @param sun_parameters Player.sun_parameters function Player:set_sun(sun_parameters) end ---- returns a table with the current sun parameters as in ---- `set_sun`. +--- Returns a table with the current sun parameters as in `set_sun`. +--- @return Player.sun_parameters function Player:get_sun() end +--- TODO +--- @class Player.moon_parameters + --- * Passing no arguments resets the moon to its default values. --- * `moon_parameters` is a table with the following optional fields: --- * `visible`: Boolean for whether the moon is visible. @@ -386,12 +483,16 @@ function Player:get_sun() end --- * `scale`: Float controlling the overall size of the moon (default: `1`) --- Note: For legacy reasons, the sun is bigger than the moon by a factor --- of about `1.57` for equal `scale` values. +--- @param moon_parameters Player.moon_parameters function Player:set_moon(moon_parameters) end ---- returns a table with the current moon parameters as in ---- `set_moon`. +--- Returns a table with the current moon parameters as in `set_moon`. +--- @return Player.moon_parameters function Player:get_moon() end +--- TODO +--- @class Player.star_parameters + --- * Passing no arguments resets stars to their default values. --- * `star_parameters` is a table with the following optional fields: --- * `visible`: Boolean for whether the stars are visible. @@ -406,12 +507,16 @@ function Player:get_moon() end --- alpha channel is used to set overall star brightness. --- (default: `#ebebff69`) --- * `scale`: Float controlling the overall size of the stars (default: `1`) +--- @param star_parameters Player.star_parameters function Player:set_stars(star_parameters) end ---- returns a table with the current stars parameters as in ---- `set_stars`. +--- Returns a table with the current stars parameters as in `set_stars`. +--- @return Player.star_parameters function Player:get_stars() end +--- TODO +--- @class Player.cloud_parameters + --- set cloud parameters --- * Passing no arguments resets clouds to their default values. --- * `cloud_parameters` is a table with the following optional fields: @@ -425,46 +530,80 @@ function Player:get_stars() end --- * `thickness`: cloud thickness in nodes (default `16`) --- * `speed`: 2D cloud speed + direction in nodes per second --- (default `{x=0, z=-2}`). +--- @param cloud_parameters Player.cloud_parameters function Player:set_clouds(cloud_parameters) end ---- returns a table with the current cloud parameters as in ---- `set_clouds`. +--- Returns a table with the current cloud parameters as in `set_clouds`. +--- @return Player.cloud_parameters function Player:get_clouds() end +--- @param ratio number? Value: --- * `0`...`1`: Overrides day-night ratio, controlling sunlight to a specific --- amount. --- * `nil`: Disables override, defaulting to sunlight based on day-night cycle function Player:override_day_night_ratio(ratio) end ---- returns the ratio or nil if it isn't overridden +--- Returns the ratio or nil if it isn't overridden. +--- @return number? function Player:get_day_night_ratio() end ---- set animation for player model in third person view. ---- * Every animation equals to a `{x=starting frame, y=ending frame}` table. ---- * `frame_speed` sets the animations frame speed. Default is 30. +--- @alias Player.local_animation {x:integer, y:integer} + +--- Set animation for player model in third person view. +--- @param idle Player.local_animation +--- @param walk Player.local_animation +--- @param dig Player.local_animation +--- @param walk_while_dig Player.local_animation +--- @param frame_speed integer sets the animations frame speed. Default is 30. function Player:set_local_animation(idle, walk, dig, walk_while_dig, frame_speed) end ---- returns idle, walk, dig, walk_while_dig tables and ---- `frame_speed`. +--- Returns idle, walk, dig, walk_while_dig tables and `frame_speed`. +--- @return Player.local_animation idle +--- @return Player.local_animation walk +--- @return Player.local_animation dig +--- @return Player.local_animation walk_while_dig +--- @return integer frame_speed function Player:get_local_animation() end ---- defines offset vectors for ---- camera per player. An argument defaults to `{x=0, y=0, z=0}` if unspecified. +--- Sets camera offset vectors. --- * in first person view --- * in third person view (max. values `{x=-10/10,y=-10,15,z=-5/5}`) --- v -- [firstperson, thirdperson] -function Player:set_eye_offset(v) end +--- @param firstperson vector? Offset in first person view. Defaults to vector.zero() if unspecified +--- @param thirdperson_back vector? Offset in third person back view. Clamped between `vector.new(-10, -10, -5)` and `vector.new(10, 15, 5)`. Defaults to `vector.zero()` if unspecified. +--- @param thirdperson_front vector? Offset in third person front view. Same limits as for `thirdperson_back` apply. Defaults to `thirdperson_back` if unspecified. +function Player:set_eye_offset(firstperson, thirdperson_back, thirdperson_front) end ---- returns first and third person offsets. +--- Returns first and third person offsets. +--- @return vector firstperson +--- @return vector thirdperson_back +--- @return vector thirdperson_front function Player:get_eye_offset() end ---- * Sends an already loaded mapblock to the player. ---- * Returns `false` if nothing was sent (note that this can also mean that ---- the client already has the block) ---- * Resource intensive - use sparsely +--- TODO +--- @class Player.camera_params + +--- Sets camera parameters. +--- @param params Player.camera_params +function Player:set_camera(params) end + +--- Returns the camera parameters. +--- @return Player.camera_params +function Player:get_camera() end + +--- Sends an already loaded mapblock to the player. +--- +--- Returns `false` if nothing was sent (note that this can also mean that +--- the client already has the block) +--- +--- Resource intensive - use sparsely +--- @return boolean function Player:send_mapblock(blockpos) end ---- sets lighting for the player +--- TODO +--- @class Player.light_definition + +--- Sets lighting for the player. --- * `light_definition` is a table with the following optional fields: --- * `saturation` sets the saturation (vividness). --- values > 1 increase the saturation @@ -473,12 +612,34 @@ function Player:send_mapblock(blockpos) end --- * `shadows` is a table that controls ambient shadows --- * `intensity` sets the intensity of the shadows from 0 (no shadows, default) to 1 (blackness) --- * This value has no effect on clients who have the "Dynamic Shadows" shader disabled. +--- @param light_definition Player.light_definition function Player:set_lighting(light_definition) end ---- returns the current state of lighting for the player. +--- Returns the current state of lighting for the player. --- * Result is a table with the same fields as `light_definition` in `set_lighting`. +--- @return Player.light_definition function Player:get_lighting() end --- Respawns the player using the same mechanism as the death screen, ---- including calling on_respawnplayer callbacks. +--- including calling `on_respawnplayer` callbacks. function Player:respawn() end + +--- @class Player.flags +--- Whether breathing (regaining air) is enabled, default `true`. +--- @field breathing boolean? +--- +--- Whether drowning (losing air) is enabled, default `true`. +--- @field drowning boolean? +--- +--- Whether the player takes damage from nodes, default true. +--- @field node_damage boolean? + +--- Sets player flags. +--- +--- Absent fields are left unchanged. +--- @param flags Player.flags +function Player:set_flags(flags) end + +--- Returns a table of player flags. +--- @return Player.flags +function Player:get_flags() end