Player

## Описание

Сущность, изображающая игроков в игровом мире.

Объекты этого типа создаются при подключении игрока к серверу и могут быть получены из списка, возвращаемого функцией get\_connected\_players(), либо по имени игрока функцией get\_player\_by\_name().

## Методы

Наследует все методы ObjectRef, кроме того имеет собственные:

```
string = object:get_player_name()

```

Возвращает имя (логин) игрока; если объект не является **Player** — возвращает пустую строку.

```
Position = object:get_player_velocity()

```

Возвращает вектор скорости игрока.

```
Position = object:get_look_dir()

```

Возвращает направление взгляда игрока (в виде единичного вектора).

```
number = object:get_look_vertical()

```

Возвращает угол между направлением взгляда игрока и горизонталью (в радианах).

-pi/2 — зенит, pi/2 — надир.

```
number = object:get_look_horizontal()

```

Возвращает отклонение взгляда игрока в горизонтальной плоскости (в радианах).

0 — север, pi/2 — запад.

```
number = object:set_look_vertical(number angle)

```

Задаёт отклонение взгляда игрока от горизонтали (в радианах).

-pi/2 и меньше — зенит, pi/2 и больше — надир.

```
number = object:set_look_horizontal(number angle)

```

Задаёт отклонение взгляда игрока в горизонтальной плоскости (в радианах).

0 — север, pi/2 — запад.

```
number = object:get_breath()

```

Возвращает количество воздуха у игрока.

```
nil = object:set_breath(number breath)

```

Задаёт количество воздуха у игрока.

Дробные значения `breath` округляются до целых, отрицательные — увеличиваются на 65536.

По умолчанию интерпретируются следующим образом:

* `breath == 0` -- игрок «задыхается», теряя HP;
* `breath > 0 and breath < 11` -- отображается соответствующий HUD, в любой ноде, для которой не указано иное, значение растёт;
* `breath >= 11` -- HUD не отображается, значение больше не растёт.

```
PlayerMetaRef = object:get_meta()

```

Возвращает метаданные игрока.

```
FormString = object:get_inventory_formspec()

```

Возвращает строку, описывающую меню инвентаря игрока.

```
boolean = object:set_inventory_formspec(FormString form)

```

Задаёт строку, описывающую меню инвентаря игрока; обычно возвращает `true`.

```
FormString = object:get_formspec_prepend()

```

Возвращает строку-префикс для форм, показываемых игроку.

```
boolean = object:set_formspec_prepend(FormString form)

```

Задаёт строку-префикс для форм, показываемых игроку.

```
table | string = object:get_player_control()

```

Возвращает таблицу, описывающую состояние управляющих клавиш у игрока.

Возвращаемая таблица содержит следующие поля (значение `true` соответствует нажатой клавише):

* `boolean right` -- вправо (по умолчанию - D);
* `boolean left` -- влево (по умолчанию - A);
* `boolean down` -- назад (по умолчанию - S);
* `boolean up` -- вперёд (по умолчанию - W);
* `boolean LMB` -- ударить (по умолчанию - левая кнопка мыши);
* `boolean RMB` -- поставить (по умолчанию - правая кнопка мыши);
* `boolean jump` -- прыжок (по умолчанию - пробел);
* `boolean sneak` -- ползти (по умолчанию - левый shift);
* `boolean aux1` -- использовать (по умолчанию - E).

Если `object` не является **Player**, то возвращает пустую строку.

```
number | string = object:get_player_control_bits()

```

Возвращает состояние управляющих клавиш у игрока в виде целого числа.

Возвращаемое число является суммой вида `2*(k1 + k2 + ...)`, где `kn` в зависимости от нажатых клавиш равны:

* up - 0;
* down - 1;
* left - 2;
* right - 3;
* jump - 4;
* aux1 - 5;
* sneak - 6;
* LMB - 7;
* RMB - 8.

Если `object` не является **Player**, то возвращает пустую строку.

Описание клавиш см. `object:get_player_control`.

```
table = object:get_physics_override()

```

Возвращает таблицу, описывающую настройки физики для игрока (см. `object:set_physics_override`).

Аналогичную таблицу возвращает, даже если `object` не является **Player**.

```
nil = object:set_physics_override(table override_table)

```

Задаёт таблицу, описывающую настройки физики для игрока.

Таблица `override_table` содержит следующие поля:

* `number speed = 1` -- коэффициент к скорости игрока;
* `number jump = 1` -- коэффициент к прыжку игрока;
* `number gravity = 1` -- коэффициент к гравитации, действующей на игрока;
* `boolean sneak = true` -- возможность «ползти», «красться»;
* `boolean sneak_glitch = true` -- возможность «подтягиваться»;
* `boolean new_move = true` -- использовать новый код для обработки `sneak`.

```
number = object:hud_add(table hud_definition)

```

Добавляет HUD для игрока, возвращая его id.

Таблица `hud_definition` может содержать следующие поля:

* `string hud_elem_type` -- тип элемента;

* `"image"` -- ;
* `"text"` -- ;
* `"statbar"` -- ;
* `"inventory"` -- ;
* `"waypoint"` -- ;

* `string name` -- наименование элемента, на данный момент не используется напрямую, однако может играть роль описания или параметра поиска;
* `string text` -- ;
* `number item` -- ;
* `number number` -- ;
* `table position` -- {x=,y=} в % от экрана;
* `table size` -- ;
* `table scale` -- ;
* `number direction` -- ;
* `number dir` -- ;
* `table alignment` -- ;
* `table offset` -- ;
* `Position world_pos` -- .

```
boolean | nil = object:hud_remove(number id)

```

Удаляет у игрока HUD под номером `id`; в случае успеха возвращает `true`, если HUD'а с таким номером у игрока нет, возвращает `nil`.

```
boolean | nil = object:hud_change(number id, string stat, any value)

```

Заменяет у игрока значение поля `stat` HUD'а под номером `id` на `value` (см. `object:hud_add`).

В случае успеха возвращает `true`, если HUD'а с таким номером у игрока нет, возвращает `nil`.

```
table | nil = object:hud_get(number id)

```

Возвращает для игрока таблицу с описанием HUD'а под номером `id` (см. `object:hud_add`); если HUD'а с таким номером у игрока нет, возвращает `nil`.

```
table = object:hud_get_flags()

```

Возвращает таблицу, содержащую параметры HUD'а игрока (см. `object:hud_set_flags`).

```
boolean = object:hud_set_flags(table flags)

```

Задаёт таблицу, содержащую параметры HUD'а игрока.

Таблица `flags` может содержать следующие поля:

* `boolean hotbar` -- отображение хотбара;
* `boolean crosshair` -- отображение перекрестия посреди экрана;
* `boolean wielditem` -- отображение «руки» и предмета в ней;
* `boolean healthbar` -- отображение индикатора HP;
* `boolean breathbar` -- отображение индикатора дыхания;
* `boolean minimap` -- возможность использовать миникарту.

Значение `true` или `false` переключит флаг соответствующие положение, `nil` оставит значение без изменений.

Возвращает `true` в случае успеха

```
number = object:hud_get_hotbar_itemcount()

```

Возвращает количество слотов в хотбаре игрока.

```
boolean | nil = object:hud_set_hotbar_itemcount(number count)

```

Задаёт количество слотов в хотбаре игрока; дробные числа округляются в меньшую сторону.

Значение `count` должно быть от 1 до 23 включительно, в противном случае возвращает `nil` (в остальных случаях возвращает `true`).

```
string = object:hud_get_hotbar_image()

```

Возвращает имя файла-текстуры для хотбара игрока.

```
string = object:hud_set_hotbar_image(string texture_name)

```

Задаёт имя файла-текстуры для хотбара игрока; возвращает его же.

```
string = object:hud_get_hotbar_selected_image()

```

Возвращает имя файла-текстуры для выбранного слота в хотбаре игрока.

```
string = object:hud_set_hotbar_selected_image(string texture_name)

```

Задаёт имя файла-текстуры для выбранного слота в хотбаре игрока; возвращает его же.

```
ColorSpec, string, table  = object:get_sky()

```

Возвращает цвет скайбокса, его тип и таблицу с текстурами (см. `object:set_sky`).

```
boolean = object:set_sky(ColorSpec bgcolor, string type, table textures)

```

Задаёт параметры скайбокса для игрока.

* `bgcolor` -- цвет глобального освещения;

* `type` тип скайбокса;

* `regular` -- скайбокс по умолчанию, `bgcolor` и `textures` игнорируются;
* `skybox` -- используются и `textures`, и `bgcolor`;
* `plain` -- используется только `bgcolor`;

* `textures` - список, элементами которой должны быть шесть текстур в виде ImageString.

```
table = object:get_clouds()

```

Возвращает параметры облаков для игрока (см. `object:set_clouds`).

```
unknoun = object:set_clouds(table parameters)

```

Задаёт параметры облаков для игрока.

Таблица `parameters` может содержать следующие поля:

* `number density = 0.4` -- плотность (от 0 до 1);
* `ColorSpec color = "#fff0f0e5"` -- базовый цвет;
* `ColorSpec ambient = "#000000"` -- нижний предел цвета (используется для светимости ночью);
* `number height = 120` -- высота (по умолчанию берётся из настроек);
* `number thickness = 16` -- толщина (в нодах);
* `table speed = {x = 0, z = -2}` -- 2D-вектор скорости (в нодах в секунду).

```
number | nil = object:get_day_night_ratio()

```

Возвращает текущий коэффициент глобального освещения для игрока или `nil`, если выставленно освещение по умолчанию (см. `object:override_day_night_ratio`).

```
boolean = object:override_day_night_ratio(number ratio | nil nil)

```

Задаёт коэффициент глобального освещения для игрока (0 - минимум, 1 - максимум); для возврата к освещению по умолчанию следует явно передать аргумент `nil`; в случае успеха возвращает `true`.

```
table, table, table, table, number = object:get_local_animation()

```

Возвращает таблицы, описывающие анимации stand, walk, dig, dig+walk и скорость анимации для игрока (см. `object:set_local_animation`).

```
nil = object:set_local_animation(table stand, table walk, table dig, table walk_dig, number frame_speed)

```

Задаёт параметры стандартных анимаций для игрока.

Каждый аргумент-таблица содержит поля x и y, числовые значения которых интерпретируются как начальный и конечный кадр анимации в общей анимации 3D-модели.

* `stand` -- проигрывается, когда игрок стоит;
* `walk` -- проигрывается, когда игрок бежит/идёт;
* `dig` -- проигрывается, когда игрок копаёт/ударяет;
* `walk_dig` -- проигрывается, когда игрок копаёт/ударяет на ходу.

Аргумент `frame_speed` задаёт скорость анимации (в кадрах в секунду).

```
Position, Position = object:get_eye_offset()

```

Возвращает смещения относительно игрока камеры от первого лица и камеры от третьего лица.

```
nil = object:set_eye_offset(Position first_offset, Position third_offset)

```

Задаёт смещения относительно игрока камеры от первого лица и камеры от третьего лица.

## Устаревшие методы

Следующие методы устарели и не должны использоваться (но могут встретиться в старых модах):

```
number = object:get_look_pitch()

```

Аналог `object:get_look_vertical` с точностью до наоборот (-pi/2 — надир, pi/2 — зенит).

```
number = object:set_look_pitch(number angle)

```

Аналог `object:set_look_vertical`.

```
number = object:get_look_yaw()

```

Аналог `object:get_look_horizontal` со смещением на pi/2 (0 - восток, pi/2 - север).

```
number = object:set_look_yaw(number radians)

```

Аналог `object:set_look_horizontal`.

```
string | nil = object:get_attribute(string attribute)

```

Возвращает значение атрибута `attribute`, либо `nil` — если атрибут не найден.

Вместо этого работать с объектом, возвращённым `get_meta()`.

```
string = object:set_attribute(string attribute, string value)

```

Задаёт значение атрибута `attribute` равным `value`.

Вместо этого работать с объектом, возвращённым `get_meta()`.

## Примечания

1. ↑ TODO: ранее вызов этих методов применительно к LuaEntitySAO не порождал ошибки, а просто игнорировался, возвращая при этом `nil` (если в описании не указано иное), нужно перепроверить.
2. ↑ 2,0 2,1 2,2 2,3 TODO: соотнести стороны света и оси координат или дать ссылку на соответствующую статью.
3. ↑ 3,0 3,1 TODO: раньше для чего-то возвращало аргумент `angle`, нужно перепроверить.
4. ↑ 4,0 4,1 4,2 4,3 4,4 4,5 TODO: не ясно, когда может появиться `false`, необходимо уточнить.
5. ↑ TODO: дать описание назначения префикса либо ссылку на основную статью.
6. ↑ TODO: старые данные, нуждаются в перепроверке.
7. ↑ TODO: здесь только список, необходимо добавить описания полей таблицы `hud_definition`.
8. ↑ TODO: судя по документации, возможна замена только для следующих значений `stat`: `position`, `name`, `scale`, `text`, `number`, `item`, `dir`; необходимо проверить.
9. ↑ 9,0 9,1 9,2 9,3 TODO: по логике вещей здесь должен использоваться тип ImageString, однако раньше наименование файла без расширения не срабатывали, да и модификаторы модификаторы работали не все и через раз; перепроверить.
10. ↑ TODO: необходимо уточнить количество и соответствие текстур сторонам света.
11. ↑ TODO: учточнить возврат.
12. ↑ TODO: описание полей — перевод документации, нужно проверять.
13. ↑ TODO: возможно, нужно будет подробнее описать этот механизм.
14. ↑ TODO: в документации сказано, что для камеры от третьего лица максимальное значение `{x=-10/10,y=-10,15,z=-5/5}`; необходимо проверить.