# Определение ресурсов (assets)

Документ описывает формат файлов ресурсов и правила их адресации на стороне сервера.
Описание основано на загрузчиках из `Src/Server/AssetsManager.hpp` и связанных структурах
подготовки (`PreparedNodeState`, `PreparedModel`, `PreparedGLTF`).

## Общая схема
- Ресурсы берутся из списка папок `AssetsRegister::Assets` (от последнего мода к первому).
  Первый найденный ресурс по пути имеет приоритет.
- Переопределения через `AssetsRegister::Custom` имеют более высокий приоритет.
- Адрес ресурса состоит из `domain` и `key`.
  `domain` — имя папки в assets, `key` — относительный путь внутри папки типа ресурса.
- Обработанные ресурсы сохраняются в `server_cache/assets`.

## Дерево папок
```
assets/
  <domain>/
    nodestate/   *.json
    model/       *.json | *.gltf | *.glb
    texture/     *.png | *.jpg (jpeg)
    particle/    (загрузка из файлов пока не реализована)
    animation/   (загрузка из файлов пока не реализована)
    sound/       (загрузка из файлов пока не реализована)
    font/        (загрузка из файлов пока не реализована)
```

Пример: `assets/core/nodestate/stone.json` имеет `domain=core`, `key=stone.json`.
При обращении к nodestate из логики нод используется ключ без суффикса `.json`
(сервер дописывает расширение автоматически).

## Nodestate (JSON)
Файл nodestate — это JSON-объект, где ключи — условия, а значения — описание модели
или список вариантов моделей.

### Условия
Условие — строковое выражение. Поддерживаются:
- числа, `true`, `false`
- переменные: `state` или `state:value` (двоеточие — часть имени)
- операторы: `+ - * / %`, `!`, `&`, `|`, `< <= > >= == !=`
- скобки

Пустая строка условия трактуется как `true`.

### Формат варианта модели
Объект варианта:
- `model`: строка `domain:key` **или** массив объектов моделей
- `weight`: число (вес при случайном выборе), по умолчанию `1`
- `uvlock`: bool (используется для векторных моделей; для одиночной модели игнорируется)
- `transformations`: массив строк `"key=value"` для трансформаций

Если `model` — строка, это одиночная модель.
Если `model` — массив, это векторная модель: набор объектов вида:
```
{ "model": "domain:key", "uvlock": false, "transformations": ["x=0", "ry=1.57"] }
```
Для векторной модели также могут задаваться `uvlock` и `transformations` на верхнем уровне
(они применяются к группе).

Трансформации поддерживают ключи:
`x`, `y`, `z`, `rx`, `ry`, `rz` (сдвиг и поворот).

Домен в строке `domain:key` можно опустить — тогда используется домен файла nodestate.

### Пример
```json
{
  "": { "model": "core:stone" },
  "variant == 1": [
    { "model": "core:stone_alt", "weight": 2 },
    { "model": "core:stone_alt_2", "weight": 1, "transformations": ["ry=1.57"] }
  ],
  "facing:north": {
    "model": [
      { "model": "core:stone", "transformations": ["ry=3.14"] },
      { "model": "core:stone_detail", "transformations": ["x=0.5"] }
    ],
    "uvlock": true
  }
}
```

## Model (JSON)
Формат описывает геометрию и текстуры.

### Верхний уровень
- `gui_light`: строка (сейчас используется только `default`)
- `ambient_occlusion`: bool
- `display`: объект с наборами `rotation`/`translation`/`scale` (все — массивы из 3 чисел)
- `textures`: объект `name -> string` (ссылка на текстуру или pipeline)
- `cuboids`: массив геометрических блоков
- `sub_models`: массив подмоделей

### Текстуры
В `textures` значение:
- либо строка `domain:key` (прямая ссылка на текстуру),
- либо pipeline-строка, начинающаяся с `tex` (компилируется `TexturePipelineProgram`).

Если домен не указан, используется домен файла модели.

### Cuboids
Элемент `cuboids`:
- `shade`: bool (по умолчанию `true`)
- `from`: `[x, y, z]`
- `to`: `[x, y, z]`
- `faces`: объект граней (`down|up|north|south|west|east`)
- `transformations`: массив `"key=value"` (ключи как у nodestate)

Грань (`faces.<name>`) может содержать:
- `uv`: `[u0, v0, u1, v1]`
- `texture`: строка (ключ из `textures`)
- `cullface`: `down|up|north|south|west|east`
- `tintindex`: int
- `rotation`: int16

### Sub-models
`sub_models` допускает:
- строку `domain:key`
- объект `{ "model": "domain:key", "scene": 0 }`
- объект `{ "path": "domain:key", "scene": 0 }`

Поле `scene` опционально.

### Пример
```json
{
  "ambient_occlusion": true,
  "textures": {
    "all": "core:stone"
  },
  "cuboids": [
    {
      "from": [0, 0, 0],
      "to": [16, 16, 16],
      "faces": {
        "north": { "uv": [0, 0, 16, 16], "texture": "#all" }
      }
    }
  ],
  "sub_models": [
    "core:stone_detail",
    { "model": "core:stone_variant", "scene": 1 }
  ]
}
```

## Model (glTF / GLB)
Файлы моделей могут быть:
- `.gltf` (JSON glTF)
- `.glb` (binary glTF)

Оба формата конвертируются в `PreparedGLTF`.

## Texture
Поддерживаются только PNG и JPEG.
Формат определяется по сигнатуре файла.

## Прочие типы ресурсов
Для `particle`, `animation`, `sound`, `font` загрузка из файловой системы
в серверном загрузчике пока не реализована (`std::unreachable()`), но возможна
регистрация из Lua через `path` (сырые бинарные данные).