This commit is contained in:
@clasher113
2024-06-13 23:55:33 +03:00
37 changed files with 1157 additions and 323 deletions
-16
View File
@@ -1,16 +0,0 @@
# Разделы
- [Рекомендации по использованию движка](1.Рекомендации-по-использованию-движка.md)
- [Контент‐паки](2.Контент‐паки.md)
- [Свойства блоков](3.Свойства-блоков.md)
- [Свойства предметов](4.Свойства-предметов.md)
- [XML разметка интерфейса](5.XML-разметка-интерфейса.md)
- [Предзагрузка ассетов](6.Предзагрузка-ассетов.md)
- [Аудио](7.Аудио.md)
- [Скриптинг](8.Скриптинг.md)
- [Модуль core:bit_converter](8.1.Модуль-Lua-core_bit_converter.md)
- [Модуль core:data_buffer](8.2.Модуль-Lua-core_data_buffer.md)
- [Пользовательский ввод](Пользовательский-ввод.md)
- [Файловая система и сериализация](Файловая-система-и-сериализация.md)
- [Консоль](Консоль.md)
- [Модели блоков](9.Модели-блоков.md)
@@ -1,12 +1,14 @@
# Вид
# Свойства блоков
## Текстура - `texture`
## Вид
### Текстура - `texture`
Название текстуры блока (указывается только имя, без расширения или пути к файлу)
Файл текстуры должен находиться в `res/textures/blocks/` и иметь формат **png**
## Текстурирование сторон - `texture-faces`
### Текстурирование сторон - `texture-faces`
>[!IMPORTANT]
> Не может использоваться одновременно с `texture`
@@ -25,7 +27,7 @@
]
```
## Модель - `model`
### Модель - `model`
Модель блока из списка:
- "block" - используется по-умолчанию для всех обычных блоков
@@ -33,12 +35,12 @@
- "X" - модель травы (крест из двух спрайтов)
- "aabb" - модель, соответствующая хитбоксу блока (составной хитбокс будет объединен в один). Примеры: трубы, лампочки, панели.
## Группа отрисовки - `draw-group`
### Группа отрисовки - `draw-group`
Целое число определяющее номер группы отрисовки данного блока.
Актуально для полупрозрачных блоков - решает проблемы невидимых сторон блоков за этим блоком.
## Вращение - `rotation`
### Вращение - `rotation`
Профиль вращения (набор положений, в которые можно установить блок) из списка:
@@ -46,9 +48,9 @@
- "pipe" - профиль "труба". Примеры блоков: бревно, труба, лампочка
- "pane" - профиль "панель". Примеры блоков: панель, дверь, табличка
# Освещение
## Освещение
## Излучение - `emission`
### Излучение - `emission`
Массив из трех целых чисел - R, G, B освещения от 0 до 15.
@@ -59,21 +61,21 @@
- `[0, 0, 0]` - блок не излучает свет (по-умолчанию)
## Светопроводимость - `light-passing`
### Светопроводимость - `light-passing`
При значении `true` блок проводит свет от излучающих блоков.
## Солнечная светопроводимость - `sky-light-passing`
### Солнечная светопроводимость - `sky-light-passing`
При значении `true` блок не препятствует прохождению вертикального луча солнечного света.
# Физика
## Физика
## Препятствие - `obstacle`:
### Препятствие - `obstacle`:
Значение false отключает хитбокс у блока (позволяет игроку проходить сквозь блок)
## Хитбокс - `hitbox`:
### Хитбокс - `hitbox`:
Массив из 6 чисел описывающих смещение и размер хитбокса блока.
@@ -87,45 +89,50 @@
- смещен на 0.0 м вверх
- смещен на 0.5 м на север
## Приземленность - `grounded`
### Приземленность - `grounded`
Блок может быть установлен только на полный блок.
Разрушается при разрушении блока под ним.
## Выделяемость - `selectable`
### Выделяемость - `selectable`
При значении в `false` курсор будет игнорировать блок, выделяя тот, что находится за ним.
## Заменяемость - `replaceable`
### Заменяемость - `replaceable`
При значении в `true` на месте блока можно установить любой другой блок. Пример: вода, трава, цветок.
## Разрушаемость - `breakable`
### Разрушаемость - `breakable`
При значении в `false` блок нельзя сломать.
# Инвентарь
## Инвентарь
## Скрытый блок - `hidden`
### Скрытый блок - `hidden`
При значении в `true` блок не появляется в инвентаре и для него не генерируется предмет, поэтому c 0.17 требуется указать свойство `picking-item`
## Подбираемый предмет - `picking-item`
### Подбираемый предмет - `picking-item`
Предмет, который будет выбран при нажатии средней кнопкой мыши на блок.
Пример: блок `door:door_open` скрыт (hidden) поэтому указывается `picking-item: "door:door.item"`
## Имя скрипта - `script-name`
### Имя скрипта - `script-name`
Позволяет указать название скрипта блока. Свойство обеспечивает возможность использования одного скрипта для нескольких блоков.
Название указывается без `пак:scripts/` и расширения.
## Имя макета UI - `ui-layout`
### Имя макета UI - `ui-layout`
Позволяет указать id XML-макета интерфейса блока. По-умолчанию используется строковый id блока.
## Размер инвентаря - `inventory-size`
### Размер инвентаря - `inventory-size`
Число слотов инвентаря блока. По-умолчанию - 0 (инвентарь отсутствует)
## Расширенные блоки
### Размер блока - `size`
Массив из трех целых чисел. Значение по-умолчанию - `[1, 1, 1]`.
@@ -1,6 +1,6 @@
# Консоль
Для работы с командным интерпретатором предоставляется библиотека **console**
Для работы с командным интерпретатором предоставляется библиотека **console**.
## Создание команд
@@ -83,7 +83,7 @@ eval name:str="World" {greeting:str='Hello'}
## Примеры схем команд
Схемы существующих команд можно найти в файле `res/script/stdcmd.lua`.
Схемы стандартных команд можно найти в файле `res/script/stdcmd.lua`.
Пример - команда **tp**:
+14
View File
@@ -0,0 +1,14 @@
# Документация
## Разделы
- [Рекомендации по использованию движка](engine-use-recommendations.md)
- [Контент‐паки](content-packs.md)
- [Свойства блоков](block-properties.md)
- [Свойства предметов](item-properties.md)
- [XML разметка интерфейса](xml-ui-layouts.md)
- [Предзагрузка ассетов](assets-preload.md)
- [Аудио](audio.md)
- [Скриптинг](scripting.md)
- [Консоль](console.md)
- [Модели блоков](block-models.md)
@@ -2,11 +2,20 @@
В качестве языка сценариев используется LuaJIT
Подразделы:
- [События движка](scripting/events.md)
- [Пользовательский ввод](scripting/user-input.md)
- [Файловая система и сериализация](scripting/filesystem.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)
```lua
require "контентпак:имя_модуля" -- загружает lua модуль из папки modules (расширение не указывается)
```
## Библиотека pack
## Библиотека *pack*
```python
pack.is_installed(packid: str) -> bool
@@ -29,10 +38,12 @@ file.write(pack.data_file(PACK_ID, "example.txt"), text)
```
Для пака *containermod* запишет текст в файл `world:data/containermod/example.txt`
## Библиотека player
## Библиотека *player*
```python
player.get_pos(playerid: int) -> number, number, number
```
Возвращает x, y, z координаты игрока
```python
@@ -79,7 +90,7 @@ player.get_selected_block(playerid: int) -> x,y,z
Возвращает координаты выделенного блока, либо nil
## Библиотека world
## Библиотека *world*
```python
world.get_list() -> массив таблиц {
@@ -120,13 +131,13 @@ world.exists() -> bool
Проверяет существование мира по имени.
## Библиотека pack
## Библиотека *pack*
```python
pack.get_folder(packid: str) -> str
```
Возвращает путь к папке установленного контент-пака
Возвращает путь к папке установленного контент-пака.
```python
pack.is_installed(packid: str) -> bool
@@ -138,13 +149,13 @@ pack.is_installed(packid: str) -> bool
pack.get_installed() -> массив строк
```
Возращает id всех установленных в мире контент-паков
Возращает id всех установленных в мире контент-паков.
```python
pack.get_available() -> массив строк
```
Возвращает id всех доступных, но не установленных в мире контент-паков
Возвращает id всех доступных, но не установленных в мире контент-паков.
```python
pack.get_base_packs() -> массив строк
@@ -172,13 +183,13 @@ pack.get_info(packid: str) -> {
- `~` - weak
например `!teal`
## Библиотека gui
## Библиотека *gui*
Библиотека содержит функции для доступа к свойствам UI элементов. Вместо gui следует использовать объектную обертку, предоставляющую доступ к свойствам через мета-методы __index, __newindex:
```lua
local inventory_doc = Document.new("id-макета")
print(inventory_doc.some_button.text)
indentory_doc.some_button.text = "new text"
print(document.some_button.text) -- где 'some_button' - id элемета
document.some_button.text = "новый текст"
```
В скрипте макета `layouts/файл_макета.xml` - `layouts/файл_макета.xml.lua` уже доступна переменная **document** содержащая объект класса Document
@@ -210,7 +221,8 @@ get_locales_info() -> таблица таблиц где
```
Возвращает информацию о всех загруженных локалях (res/texts/\*).
## Библиотека inventory
## Библиотека *inventory*
Библиотека функций для работы с инвентарем.
@@ -273,19 +285,19 @@ inventory.move(invA: int, slotA: int, invB: int, slotB: int)
invA и invB могут указывать на один инвентарь.
slotB будет выбран автоматически, если не указывать явно.
## Библиотека block
## Библиотека *block*
```python
block.name(blockid: int) -> str
```
Возвращает строковый id блока по его числовому id
Возвращает строковый id блока по его числовому id.
```python
block.index(name: str) -> int
```
Возвращает числовой id блока, принимая в качестве агрумента строковый
Возвращает числовой id блока, принимая в качестве агрумента строковый.
```python
block.material(blockid: int) -> str
@@ -373,6 +385,35 @@ block.set_rotation(x: int, y: int, z: int, rotation: int)
Устанавливает вращение блока по индексу в его профиле вращения.
### Расширенные блоки
Расширенные блоки - те, размер которых превышает 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 бит.
@@ -455,25 +496,25 @@ hud.open_permanent(layoutid: str)
hud.close(layoutid: str)
```
Удаляет элемент с экрана
Удаляет элемент с экрана.
```python
hud.get_block_inventory() -> int
```
Дает ID инвентаря открытого блока или 0
Дает ID инвентаря открытого блока или 0.
```python
hud.get_player() -> int
```
Дает ID игрока, к которому привязан пользовательский интерфейс
Дает ID игрока, к которому привязан пользовательский интерфейс.
```python
hud.pause()
```
Открывает меню паузы
Открывает меню паузы.
```python
hud.resume()
@@ -487,7 +528,7 @@ hud.resume()
time.uptime() -> float
```
Возвращает время с момента запуска движка в секундах
Возвращает время с момента запуска движка в секундах.
```python
time.delta() -> float
@@ -1,10 +1,12 @@
# Файловая система и сериализация
## Библиотека *file*
Библиотека функций для работы с файлами
```python
file.resolve(путь: str) -> str
```
```
Функция приводит запись `точка_входа:путь` (например `user:worlds/house1`) к обычному пути. (например `C://Users/user/.voxeng/worlds/house1`)
@@ -127,11 +129,10 @@ toml.parse(code: str) -> table
При сохранении данных пака в мире следует использовать функцию
```python
pack.data_file(packid: str, filename: str) -> str
pack.data_file(id_пака: str, имя_файла: str) -> str
```
Функция возвращает путь к файлу данных по типу: `world:data/packid/filename`
Функция возвращает путь к файлу данных по типу: `world:data/id_пака/имя_файла`
и создает недостающие директории в пути.
При использовании путей не соответствующим `data/{packid}/...` возможна потеря данных при перезаписи мира.
@@ -1,3 +1,5 @@
# Модуль core:bit_converter
## Конвертация значений в байты и обратно
```lua
@@ -23,27 +25,27 @@ function bit_converter.double_to_bytes(number: double) -> table
```lua
function bit_converter.uint16_to_bytes(integer: int) -> table
```
Конвертирует беззнаковое 2-х битное целое число в байты
Конвертирует беззнаковое 2-х байтовое целое число в байты
```lua
function bit_converter.uint32_to_bytes(integer: int) -> table
```
Конвертирует беззнаковое 4-х битное целое число в байты
Конвертирует беззнаковое 4-х байтовое целое число в байты
```lua
function bit_converter.int16_to_bytes(integer: int) -> table
```
Конвертирует знаковое 2-х битное целое число в байты
Конвертирует знаковое 2-х байтовое целое число в байты
```lua
function bit_converter.int32_to_bytes(integer: int) -> table
```
Конвертирует знаковое 4-х битное целое число в байты
Конвертирует знаковое 4-х байтовое целое число в байты
```lua
function bit_converter.int64_to_bytes(integer: int) -> table
```
Конвертирует знаковое 8-и битное целое число в байты
Конвертирует знаковое 8-и байтовое целое число в байты
```lua
function bit_converter.bytes_to_string(table: bytes) -> string
@@ -68,24 +70,24 @@ function bit_converter.bytes_to_double(table: bytes) -> number
```lua
function bit_converter.bytes_to_uint16(table: bytes) -> integer
```
Конвертирует массив байтов в 2-х битное беззнаковое число
Конвертирует массив байтов в 2-х байтовое беззнаковое число
```lua
function bit_converter.bytes_to_uint32(table: bytes) -> integer
```
Конвертирует массив байтов в 4-х битное беззнаковое число
Конвертирует массив байтов в 4-х байтовое беззнаковое число
```lua
function bit_converter.bytes_to_int16(table: bytes) -> integer
```
Конвертирует массив байтов в 2-х битное знаковое число
Конвертирует массив байтов в 2-х байтовое знаковое число
```lua
function bit_converter.bytes_to_int32(table: bytes) -> integer
```
Конвертирует массив байтов в 4-х битное знаковое число
Конвертирует массив байтов в 4-х байтовое знаковое число
```lua
function bit_converter.bytes_to_int64(table: bytes) -> integer
```
Конвертирует массив байтов в 8-х битное знаковое число
Конвертирует массив байтов в 8-х байтовое знаковое число
@@ -1,3 +1,5 @@
# Модуль core:data_buffer
## Буффер данных
### Хранит в себе массив байтов и позволяет легко получать или добавлять разные значения
@@ -39,27 +41,27 @@ function data_buffer:put_double(number: double)
```lua
function data_buffer:put_uint16(integer: int)
```
Конвертирует беззнаковое 2-х битное число в байты и записывает их в буффер
Конвертирует беззнаковое 2-х байтовое число в байты и записывает их в буффер
```lua
function data_buffer:put_uint32(integer: int)
```
Конвертирует беззнаковое 4-х битное число в байты и записывает их в буффер
Конвертирует беззнаковое 4-х байтовое число в байты и записывает их в буффер
```lua
function data_buffer:put_int16(integer: int)
```
Конвертирует знаковое 2-х битное число в байты и записывает их в буффер
Конвертирует знаковое 2-х байтовое число в байты и записывает их в буффер
```lua
function data_buffer:put_int32(integer: int)
```
Конвертирует знаковое 4-х битное число в байты и записывает их в буффер
Конвертирует знаковое 4-х байтовое число в байты и записывает их в буффер
```lua
function data_buffer:put_int64(integer: int)
```
Конвертирует знаковое 8-и битное число в байты и записывает их в буффер
Конвертирует знаковое 8-и байтовое число в байты и записывает их в буффер
```lua
function data_buffer:put_number(number: num)
@@ -110,27 +112,27 @@ function data_buffer:get_double() -> number
```lua
function data_buffer:get_uint16() -> integer
```
Читает следующее 2-х битное беззнаковое целое число из буффера
Читает следующее 2-х байтовое беззнаковое целое число из буффера
```lua
function data_buffer:get_uint32() -> integer
```
Читает следующее 4-х битное беззнаковое целое число из буффера
Читает следующее 4-х байтовое беззнаковое целое число из буффера
```lua
function data_buffer:get_int16() -> integer
```
Читает следующее 2-х битное знаковое целое число из буффера
Читает следующее 2-х байтовое знаковое целое число из буффера
```lua
function data_buffer:get_int32() -> integer
```
Читает следующее 4-х битное знаковое целое число из буффера
Читает следующее 4-х байтовое знаковое целое число из буффера
```lua
function data_buffer:get_int64() -> integer
```
Читает следующее 8-х битное знаковое целое число из буффера
Читает следующее 8-х байтовое знаковое целое число из буффера
```lua
function data_buffer:get_number() -> number
@@ -150,4 +152,4 @@ function data_buffer:set_position(integer: pos)
```lua
function data_buffer:set_bytes(table: bytes)
```
Устанавливает байты в буффер
Устанавливает байты в буффер
@@ -1,4 +1,5 @@
# Вектора
# Модули core:vector2, core:vector3
## Vector2
### Операции над векторами
@@ -7,6 +8,7 @@
function vector2:round(decimals: number) -> round[vec2]
```
Округление компонентов вектора
```lua
function vector2:len() -> number
```
@@ -68,7 +70,7 @@ function vector2:rot(
### Операции с векторами
```lua
local vec2 = require("res:vector2")
local vec2 = require("core:vector2")
local v1 = vec2(5, 10)
local v2 = vec2(10, 15)
@@ -170,7 +172,7 @@ function vector3:rot(
```lua
local vec3 = require("res:vector3")
local vec3 = require("core:vector3")
local v1 = vec3(1, 2, 3)
local v2 = vec3(4, 5, 6)