# Свойства блоков

## Вид

### Текстура - *texture*

Название текстуры блока (указывается только имя, без расширения или пути к файлу)

Файл текстуры должен находиться в `res/textures/blocks/` и иметь формат **png**

### Текстурирование сторон - *texture-faces*

>[!IMPORTANT]
> Не может использоваться одновременно с *texture*

Массив из 6 названий текстур, позволяющих указать их для каждой из сторон отдельно.

Пример: 
```json
"texture-faces": [
    "grass_side",
    "grass_side",
    "dirt",
    "grass_top",
    "grass_side",
    "grass_side"
]
```

### Модель - *model*

Модель блока из списка:
- "block" - используется по-умолчанию для всех обычных блоков
- "none" - невидимый блок (пример: воздух)
- "X" - модель травы (крест из двух спрайтов)
- "aabb" - модель, соответствующая хитбоксу блока (составной хитбокс будет объединен в один). Примеры: трубы, лампочки, панели.
- "custom" - используется при указании собственной модели через *model-name*

### Имя модели - *model-name*

Кроме встроенных типов моделей, можно использовать собственные, загружаемые из файлов.

В свойстве указывается имя модели без `точка_входа:models/` и расширения.

> [!WARNING]
> Текстуры (материалы), использующиеся в модели, должны находиться в атласе `blocks` и указываться в соответствующем формате:
> `blocks:имя_текстуры`

### Группа отрисовки - *draw-group*

Целое число определяющее номер группы отрисовки данного блока. 
Актуально для полупрозрачных блоков - решает проблемы невидимых сторон блоков за этим блоком.

### Полупрозрачность - *translucent*

Включает поддержку полупрозрачности в текстурах блока (примеры: вода, лёд).
Следует использовать только при надобности, так как влияет на производительность.
Не требуется для полной прозрачности (трава, цветы).

### Вращение - *rotation*

Профиль вращения (набор положений, в которые можно установить блок) из списка:

- "none" - вращение блока отключено (по-умолчанию)
- "pipe" - профиль "труба". Примеры блоков: бревно, труба, лампочка
- "pane" - профиль "панель". Примеры блоков: панель, дверь, табличка
- "stairs" - профиль "ступеньки" ("pane" + перевернутые варианты)

### Испускаемые частицы - *particles*

Частицы указываются в виде JSON объекта. Имена свойств можно найти [в разделе, посвященном частицам](particles.md).

При приближении к блоку движок создаст эмиттер, который будет работать 
до разрушения блока или отдаления камеры на некоторое расстояние.

## Варианты

Некоторые свойства могут варьироваться динамически, в зависимости от номера варианта, хранимого в пользовательских битах блока.

Параметры вариативности указываются в блоке `state-based`:

```json
{
    ...
    "state-based": {
        "offset": 0,
        "bits": 4,
        "variants": [
            {...},
            ...
        ]
    }
}
```

- `offset` определяет битового смещения, с которого начинается индекс варианта. (По-умолчанию - 0)
- `bits` определяет число бит, кодирующих индекс варианта. (По-умолчанию - 4).
На данный момент максимальное число вариантов - 16, поэтому указание более 4 бит не имеет практического смысла.

Доступные для вариативности свойства:
- model
- model-name
- texture
- texture-faces
- model-primitives (устарело)

Управление состоянием производится через `block.set_variant(x, y, z, index)`.

### Кастомные модели по вариантам (переключение геометрии)

Для custom-моделей можно переключать геометрию по варианту. Укажите отдельный `model-name` в нужных вариантах — рендерер кэширует геометрию по паре (id блока, вариант).

Базовая модель (из корня) становится вариантом 0. Массив variants соответствует индексам 1+.

Пример (база + два кастомных варианта):
```json
{
    "model": "custom",
    "model-name": "stairs_middle",
    "state-based": {
        "bits": 4,
        "variants": [
            { "model": "custom", "model-name": "stairs_left" },
            { "model": "custom", "model-name": "stairs_right" }
        ]
    }
}
```

В этом примере:
- Вариант 0 = `stairs_middle` (из корня)
- Вариант 1 = `stairs_left` (из variants[0])
- Вариант 2 = `stairs_right` (из variants[1])

## Освещение

### Излучение - *emission*:

Массив из трех целых чисел - R, G, B освещения от 0 до 15.

Примеры:

- `[15, 15, 15]` - самый яркий белый свет
- `[7, 0, 0]` - слабый красный свет
- `[0, 0, 0]` - блок не излучает свет (по-умолчанию)


### Светопроводимость - *light-passing*

При значении `true` блок проводит свет от излучающих блоков.

### Солнечная светопроводимость - *sky-light-passing*

При значении `true` блок не препятствует прохождению вертикального луча солнечного света.

### Без освещения - *shadeless*

Выключает освещение на модели блока.

### Вершинный Ambient-Occlusion - *ambient-occlusion*

Определяет наличие эффекта вершинного AO. Включен по-умолчанию.

### Отсечение - *culling*

Режим отсечения граней:
- **default** - обычное отсечение граней
- **optional** - отсечение граней среди блоков одной группы отрисовки можно отключить через настройку `graphics.dense-render` (Плотный рендер блоков).
- **disabled** - отсечение граней среди блоков одной группы отрисовки отключено.

В режиме `optional` при отключении `graphics.dense-render` будет использоваться `*_opaque` вариант текстуры (при наличии).

## Физика

### Препятствие - *obstacle*

Значение false отключает хитбокс у блока (позволяет игроку проходить сквозь блок)

### Хитбокс - *hitbox*

Массив из 6 чисел описывающих смещение и размер хитбокса блока.

Числа указываются в диапазоне [0.0, 1.0] - т.е в пределах блока (в случае расширенного блока хитбокс может быть больше единицы, но не должен выходить за пределы size).

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

Для составных хитбоксов используется свойство *hitboxes* - массив хитбоксов, например:

```json
"hitboxes": [
  [0, 0, 0, 1, 0.625, 1],
  [0, 0.6875, 0, 1, 0.3125, 1]
]
```

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

Блок может быть установлен только на полный блок.
Разрушается при разрушении блока под ним.

### Выделяемость - *selectable*

При значении в `false` курсор будет игнорировать блок, выделяя тот, что находится за ним.

### Заменяемость - *replaceable*

При значении в `true` на месте блока можно установить любой другой блок. Пример: вода, трава, цветок.

### Разрушаемость - *breakable*

При значении в `false` блок нельзя сломать.

## Инвентарь

### Скрытый блок - *hidden*

При значении в `true` блок не появляется в инвентаре и для него не генерируется предмет, поэтому c 0.17 требуется указать свойство *picking-item*

### Подбираемый предмет - *picking-item*

Предмет, который будет выбран при нажатии средней кнопкой мыши на блок.

Пример: блок `door:door_open` скрыт (hidden) поэтому указывается `picking-item: "door:door.item"`

### Имя макета UI - *ui-layout*

Позволяет указать id XML-макета интерфейса блока. По-умолчанию используется строковый id блока.

### Размер инвентаря - *inventory-size*

Число слотов инвентаря блока. По-умолчанию - 0 (инвентарь отсутствует)

## Расширенные блоки

### Размер блока - *size*

Массив из трех целых чисел. Значение по-умолчанию - `[1, 1, 1]`.

## Поля блока

Поля блоков позволяет записывать больше уникальных для конкретного блока данных, чем это позволяют пользовательские биты.

Поля блока объявляются в следующем формате:

```json
"fields": {
    "имя": {"type": "тип_данных"},
    "имя_массива": {"type": "тип_данных", "length": "длина_массива"}
}
```

Кроме `type` и `length` доступен параметр `convert-strategy` определяющий
стратегию конвертации значения при сужении типа данных.

Параметр принимает одно из двух значений:
- `reset` - значение, не попадающее в новый диапазон, будет сброшено до 0
- `clamp` - значение будет сведено к ближайшему в новом диапазоне

Пример: число 231 при изменении типа поля с int16 до int8:
- в режиме `reset` превратится в 0
- в режиме `clamp` превратится в 127


Доступные типы данных:

| Тип     | Размер   | Описание                      |
| ------- | -------- | ----------------------------- |
| int8    | 1 байт   | целочисленный знаковый 8 бит  |
| int16   | 2 байта  | целочисленный знаковый 16 бит |
| int32   | 4 байта  | целочисленный знаковый 32 бит |
| int64   | 8 байт   | целочисленный знаковый 64 бит |
| float32 | 4 байта  | вещественный 32 бит           |
| float64 | 8 байт   | вещественный 64 бит           |
| char    | 1 байт   | символьный                    |

- На данный момент общая сумма размеров полей не может превышать 240 байт.
- Поле без указания длины массива эквивалентно массиву из 1 элемента.
- Массив символьного типа может использоваться для хранения UTF-8 строк.

## Пользовательские свойства

Доступ к пользовательским свойствам производится через таблицу `block.properties[id]["свойство"]` где id - числовой id (индекс) блока.

Пользовательские свойства должны быть объявляены в файле `пак:config/user-props.toml`:
```toml
"пак:имя_свойства" = {}
```

Пример: [пользовательские свойства пака **base**](../../res/content/base/config/user-props.toml).

## Свойства, вводимые паком `base`

### Прочность - *base:durability*

Время разрушения блока без инструментов и эффектов в секундах.

### Лут - *base:loot*

Список таблиц со свойствами:

```json
{
    "item": "пак:предмет",
    "min": 1,
    "max": 3,
    "chance": 0.5
}
```

- count равен 1 по-умолчанию. Не нужно указывать если указаны `min` и `max`.
- min, max - минимальное и максимальное количество предмета.
- chance - вероятность выпадения предмета. По-умолчанию: 1.0.

Следует учитывать, что в item указывается именно предмет. Т.е. чтобы указать предмет блока, нужно добавить `.item` после имени блока.
Пример: `base:dirt.item`.

Для генерации лута следует использовать функцию `block_loot(block_id: int)` в модуле `base:util`.

## Другое

### Имя скрипта - *script-name*

Позволяет указать название скрипта блока. Свойство обеспечивает возможность использования одного скрипта для нескольких блоков.
Название указывается без `пак:scripts/` и расширения.

### Интервал тактов - *tick-interval*

Интервал в тактах мира (1/20 секуды). Значение 20 приводит к интервалу вызова on_block_tick равному одной секунде.

## Методы

Методы используются для управлением перезаписью свойств при расширении блока другими паками.

### `имя_свойства@append`

Добавляет элементы в конец списка, вместо его полной перезаписи.

## Теги - *tags*

Теги позволяют обозначать обобщённые свойства блоков. Названия следует формировать как `префикс:имя_тега`.
Префикс не является обязательным, но позволяет избегать нежелательных логических коллизий. Пример:

```json
{
    "tags": [
        "core:ore",
        "base_survival:food",
    ]
}
```

Теги блокам можно добавлять и из других паков, с помощью файла `ваш_пак:tags.toml`. Пример

```toml
"префикс:имя_тега" = [
    "рандомный_пак:какой_то_блок",
    "ещё_один_пак:предмет",
]
"другой_префикс:другое_имя_тега" = [
    # ...
]
```