add entities.raycast & update docs structure

2024-07-15 05:42:09 +03:00
parent 23cfe4a4cf
commit 9cdf3e29cc
9 changed files with 389 additions and 348 deletions
@@ -86,13 +86,13 @@

 Числа указываются в диапазоне [0.0, 1.0] - т.е в пределах блока.

-Массив `[0.25, 0.0, 0.5,  0.75, 0.4, 0.3]` описывает хитбокс: 
- шириной (с востока на запад) 0.75 м
- высотой 0.4 м
- длиной (с юга на север) 0.3 м
+Массив `[0.25, 0.0, 0.5,  0.75, 0.4, 0.3]` описывает хитбокс:
 - смещен на 0.25 м на запад
 - смещен на 0.0 м вверх
 - смещен на 0.5 м на север
+- шириной (с востока на запад) 0.75 м
+- высотой 0.4 м
+- длиной (с юга на север) 0.3 м

 ### Приземленность - *grounded*

@@ -9,7 +9,10 @@
 - [Свойства и методы UI элементов](scripting/ui.md)
 - [Сущности и компоненты](scripting/ecs.md)
 - [Библиотеки](#)
+    - [block](scripting/builtins/libblock.md)
+    - [entities](scripting/builtins/libentities.md)
    - [mat4](scripting/builtins/libmat4.md)
+    - [vec2, vec3, vec4](scripting/builtins/libvecn.md)
 - [Модуль core:bit_converter](scripting/modules/core_bit_converter.md)
 - [Модуль core:data_buffer](scripting/modules/core_data_buffer.md)
 - [Модули core:vector2, core:vector3](scripting/modules/core_vector2_vector3.md)
@@ -332,186 +335,6 @@ inventory.move(invA: int, slotA: int, invB: int, slotB: int)
 invA и invB могут указывать на один инвентарь.
 slotB будет выбран автоматически, если не указывать явно.

-## Библиотека *block*
-
-```python
-block.name(blockid: int) -> str
-```
-
-Возвращает строковый id блока по его числовому id.
-
-```python
-block.index(name: str) -> int
-```
-
-Возвращает числовой id блока, принимая в качестве агрумента строковый.
-
-```python
-block.material(blockid: int) -> str
-```
-
-Возвращает id материала блока.
-
-```python
-block.caption(blockid: int) -> str
-```
-
-Возвращает название блока, отображаемое в интерфейсе.
-
-```python
-block.get(x: int, y: int, z: int) -> int
-```
-
-Возвращает числовой id блока на указанных координатах. Если чанк на указанных координатах не загружен, возвращает -1.
-
-```python
-block.get_states(x: int, y: int, z: int) -> int
-```
-
-Возвращает состояние (поворот + доп. информация) в виде целого числа
-
-```python
-block.set(x: int, y: int, z: int, id: int, states: int)
-```
-
-Устанавливает блок с заданным числовым id и состоянием (0 - по-умолчанию) на заданных координатах.
-
-> [!WARNING]
-> `block.set` не вызывает событие on_placed.
-
-```python
-block.is_solid_at(x: int, y: int, z: int) -> bool
-```
-
-Проверяет, является ли блок на указанных координатах полным
-
-```python
-block.is_replaceable_at(x: int, y: int, z: int) -> bool
-```
-Проверяет, можно ли на заданных координатах поставить блок (примеры: воздух, трава, цветы, вода)
-
-```python
-block.defs_count() -> int
-```
-
-Возвращает количество id доступных в движке блоков
-
-```python
-block.get_picking_item(id: int) -> int
-```
-
-Возвращает числовой id предмета, указанного в свойстве *picking-item*.
-
-```lua
-block.raycast(start: vec3, dir: vec3, max_distance: number, [опционально] dest: table) -> {
-    block: int, -- id блока
-    endpoint: vec3, -- точка касания луча
-    iendpoint: vec3, -- позиция блока, которого касается луч
-    length: number, -- длина луча
-    normal: vec3 -- вектор нормали поверхности, которой касается луч
-} или nil
-```
-
-Бросает луч из точки start в направлении dir. Max_distance указывает максимальную длину луча.
-
-Функция возвращает таблицу с результатами или nil, если луч не касается блока.
-
-Для результата будет использоваться целевая (dest) таблица вместо создания новой, если указан опциональный аргумент.
-
-### Вращение
-
-Следующие функции используется для учёта вращения блока при обращении к соседним блокам или других целей, где направление блока имеет решающее значение.
-
-
-```lua
-- Возвращает целочисленный единичный вектор X блока на указанных координатах с учётом его вращения (три целых числа).
-- Если поворот отсутствует, возвращает 1, 0, 0
-block.get_X(x: int, y: int, z: int) -> int, int, int
-
-- То же, но для оси Y (по-умолчанию 0, 1, 0)
-block.get_Y(x: int, y: int, z: int) -> int, int, int
-
-- То же, но для оси Z (по-умолчанию 0, 0, 1)
-block.get_Z(x: int, y: int, z: int) -> int, int, int
-
-- Возвращает индекс поворота блока в его профиле вращения (не превышает 7).
-block.get_rotation(x: int, y: int, z: int) -> int
-
-- Устанавливает вращение блока по индексу в его профиле вращения.
-block.set_rotation(x: int, y: int, z: int, rotation: int)
-
-- Возвращает имя профиля вращения (none/pane/pipe)
-block.get_rotation_profile(id: int) -> str
-```
-
-### Расширенные блоки
-
-Расширенные блоки - те, размер которых превышает 1x1x1
-
-```python
-block.is_extended(id: int) -> bool
-```
-
-Проверяет, является ли блок расширенным.
-
-```python
-block.get_size(id: int) -> int, int, int
-```
-
-Возвращает размер блока.
-
-```python
-block.is_segment(x: int, y: int, z: int) -> bool
-```
-
-Проверяет является ли блок сегментом расширенного блока, не являющимся главным.
-
-```python
-block.seek_origin(x: int, y: int, z: int) -> int, int, int
-```
-
-Возвращает позицию главного сегмента расширенного блока или исходную позицию,
-если блок не являющийся расширенным.
-
-### Пользовательские биты
-
-Выделенная под использования в скриптах часть поля `voxel.states` хранящего доп-информацию о вокселе, такую как вращение блока. На данный момент выделенная часть составляет 8 бит.
-
-```python
-block.get_user_bits(x: int, y: int, z: int, offset: int, bits: int) -> int
-``` 
-
-Возвращает выбранное число бит с указанного смещения в виде целого беззнакового числа
-
-```python
-block.set_user_bits(x: int, y: int, z: int, offset: int, bits: int, value: int) -> int
-```
-Записывает указанное число бит значения value в user bits по выбранному смещению
-
-### Физика
-
-Информация свойствах блока, используемых физическим движком.
-
-```lua
-- Возвращает массив из двух векторов (массивов из 3 чисел):
-- 1. Минимальная точка хитбокса
-- 2. Размер хитбокса
-- rotation_index - индекс поворота блока
-block.get_hitbox(id: int, rotation_index: int) -> {vec3, vec3}
-```
-
-### Модель
-
-Информация о модели блока.
-
-```lua
-- возвращает тип модели блока (block/aabb/custom/...)
-block.get_model(id: int) -> str
-
-- возвращает массив из 6 текстур, назначенных на стороны блока
-block.get_textures(id: int) -> таблица строк
-```
-
 ## Библиотека item

 ```python
@@ -0,0 +1,143 @@
+# Библиотека *block*
+
+```lua
+-- Возвращает строковый id блока по его числовому id.
+block.name(blockid: int) -> str
+
+-- Возвращает числовой id блока, принимая в качестве агрумента строковый
+block.index(name: str) -> int
+
+-- Возвращает id материала блока.
+block.material(blockid: int) -> str
+
+-- Возвращает название блока, отображаемое в интерфейсе.
+block.caption(blockid: int) -> str
+
+-- Возвращает числовой id блока на указанных координатах.
+-- Если чанк на указанных координатах не загружен, возвращает -1.
+block.get(x: int, y: int, z: int) -> int
+
+-- Возвращает состояние (поворот + доп. информация) в виде целого числа
+block.get_states(x: int, y: int, z: int) -> int
+
+-- Устанавливает блок с заданным числовым id и состоянием (0 - по-умолчанию) на заданных координатах.
+block.set(x: int, y: int, z: int, id: int, states: int)
+```
+
+> [!WARNING]
+> `block.set` не вызывает событие on_placed.
+
+```lua
+-- Проверяет, является ли блок на указанных координатах полным
+block.is_solid_at(x: int, y: int, z: int) -> bool
+
+-- Проверяет, можно ли на заданных координатах поставить блок 
+-- (примеры: воздух, трава, цветы, вода)
+block.is_replaceable_at(x: int, y: int, z: int) -> bool
+
+-- Возвращает количество id доступных в загруженном контенте блоков
+block.defs_count() -> int
+
+-- Возвращает числовой id предмета, указанного в свойстве *picking-item*.
+block.get_picking_item(id: int) -> int
+```
+
+### Raycast
+
+```lua
+block.raycast(start: vec3, dir: vec3, max_distance: number, [опционально] dest: table) -> {
+    block: int, -- id блока
+    endpoint: vec3, -- точка касания луча
+    iendpoint: vec3, -- позиция блока, которого касается луч
+    length: number, -- длина луча
+    normal: vec3 -- вектор нормали поверхности, которой касается луч
+} или nil
+```
+
+Бросает луч из точки start в направлении dir. Max_distance указывает максимальную длину луча.
+
+Функция возвращает таблицу с результатами или nil, если луч не касается блока.
+
+Для результата будет использоваться целевая (dest) таблица вместо создания новой, если указан опциональный аргумент.
+
+## Вращение
+
+Следующие функции используется для учёта вращения блока при обращении к соседним блокам или других целей, где направление блока имеет решающее значение.
+
+
+```lua
+-- Возвращает целочисленный единичный вектор X блока на указанных координатах с учётом его вращения (три целых числа).
+-- Если поворот отсутствует, возвращает 1, 0, 0
+block.get_X(x: int, y: int, z: int) -> int, int, int
+
+-- То же, но для оси Y (по-умолчанию 0, 1, 0)
+block.get_Y(x: int, y: int, z: int) -> int, int, int
+
+-- То же, но для оси Z (по-умолчанию 0, 0, 1)
+block.get_Z(x: int, y: int, z: int) -> int, int, int
+
+-- Возвращает индекс поворота блока в его профиле вращения (не превышает 7).
+block.get_rotation(x: int, y: int, z: int) -> int
+
+-- Устанавливает вращение блока по индексу в его профиле вращения.
+block.set_rotation(x: int, y: int, z: int, rotation: int)
+
+-- Возвращает имя профиля вращения (none/pane/pipe)
+block.get_rotation_profile(id: int) -> str
+```
+
+## Расширенные блоки
+
+Расширенные блоки - те, размер которых превышает 1x1x1
+
+```lua
+-- Проверяет, является ли блок расширенным.
+block.is_extended(id: int) -> bool
+
+-- Возвращает размер блока.
+block.get_size(id: int) -> int, int, int
+
+-- Проверяет является ли блок сегментом расширенного блока, не являющимся главным.
+block.is_segment(x: int, y: int, z: int) -> bool
+
+-- Возвращает позицию главного сегмента расширенного блока или исходную позицию,
+-- если блок не является расширенным.
+block.seek_origin(x: int, y: int, z: int) -> int, int, int
+```
+
+## Пользовательские биты
+
+Выделенная под использования в скриптах часть поля `voxel.states` хранящего доп-информацию о вокселе, такую как вращение блока. На данный момент выделенная часть составляет 8 бит.
+
+```lua
+-- Возвращает выбранное число бит с указанного смещения в виде целого беззнакового числа
+block.get_user_bits(x: int, y: int, z: int, offset: int, bits: int) -> int
+
+-- Записывает указанное число бит значения value в user bits по выбранному смещению
+block.set_user_bits(x: int, y: int, z: int, offset: int, bits: int, value: int) -> int
+```
+
+
+## Физика
+
+Информация свойствах блока, используемых физическим движком.
+
+```lua
+-- Возвращает массив из двух векторов (массивов из 3 чисел):
+-- 1. Минимальная точка хитбокса
+-- 2. Размер хитбокса
+-- rotation_index - индекс поворота блока
+block.get_hitbox(id: int, rotation_index: int) -> {vec3, vec3}
+```
+
+## Модель
+
+Информация о модели блока.
+
+```lua
+-- возвращает тип модели блока (block/aabb/custom/...)
+block.get_model(id: int) -> str
+
+-- возвращает массив из 6 текстур, назначенных на стороны блока
+block.get_textures(id: int) -> таблица строк
+```
@@ -0,0 +1,26 @@
+# Библиотека *entities*
+
+Библиотека предназначена для работы с реестром сущностей.
+
+```lua
+-- Возвращает сущность по уникальному идентификатору
+-- Возвращаемая таблица - та же, что доступна в компонентах сущности.
+entities.get(uid: int) -> table
+
+-- Создает указанную сущность.
+-- args - таблица таблиц параметров компонентов (переменная ARGS)
+-- args не является обязательным
+entities.spawn(name: str, pos: vec3, [optional] args: table)
+
+-- Проверяет наличие сущности по уникальному идентификатору.
+entities.exists(uid: int) -> bool
+```
+
+```lua
+entities.raycast(start: vec3, dir: vec3, max_distance: number,
+                 ignore: int, [optional] destination: table) -> table или nil
+```
+
+Функция является расширенным вариантом [block.raycast](libblock.md#raycast). Возвращает таблицу с результатами если луч касается блока, либо сущности.
+
+Соответственно это повлияет на наличие полей *entity* и *block*.