# Туториал: добавить новый тип блока

Делаем новый воксельный блок (по аналогии с grass-snow, greystone и др.). Время: ~30 минут.

## Что у нас есть

Существующие типы блоков описаны в `src/editor/engine/CONST/blockTypes.js`. У каждого блока:
- `id` (uint16 — компактное хранение в чанках)
- `name` (показывается в инспекторе)
- `texture` (имя файла из `public/kubikon-assets/blocks/`)
- `solid` (true/false — игрок проходит сквозь?)
- `transparent` (для стекла — рендер с alpha)
- доп. свойства: `breakable`, `gravity`, `gluon` и т.д.

## Шаг 1: Текстура

Текстуры блоков — PNG 256x256, лежат в `public/kubikon-assets/blocks/`.

Возьми готовую (Kenney воксельные тайлсеты — CC0) или нарисуй сам. Положи как `<имя>.png`, например `my_cool_brick.png`.

## Шаг 2: Регистрация типа

В `src/editor/engine/CONST/blockTypes.js` добавь:

```javascript
export const BLOCK_TYPES = [
  // ...существующие...
  {
    id: 42,                          // следующий свободный uint16
    name: 'Мой кирпич',
    texture: 'my_cool_brick.png',
    solid: true,
    breakable: true,
    breakTime: 2.0,                  // сек. чтобы сломать киркой
    category: 'материалы',
  },
];
```

## Шаг 3: Проверь в редакторе

```bash
npm run dev
# открой http://localhost:5174/edit/sample (standalone-режим)
```

В сайдбаре «Блоки» → категория «материалы» → твой кирпич должен появиться. Клик → выбор → ставь на ландшафт.

## Шаг 4: Тонкая настройка

Самое частое — текстура повёрнута/растянута. Открой `src/editor/engine/BlockManager.js`, найди `_buildFace()`. По умолчанию UV-маппинг 1 текстура на грань 1м×1м. Если нужно повторение — поменяй `uvScale`.

Для не-кубических блоков (ступени, плиты) — см. `BlockShape.js`.

## Шаг 5: Скрипты могут спавнить твой блок

Если блок должен быть доступен в `game.scene.placeBlock(type, x, y, z)` — добавь его id в whitelist `src/editor/engine/scripts/ScriptSandboxAPI.js:ALLOWED_BLOCK_IDS`.

## Шаг 6: PR

```bash
git checkout -b feature/cool-brick-block
git add public/kubikon-assets/blocks/my_cool_brick.png \
        src/editor/engine/CONST/blockTypes.js
git commit -m "feat: добавить блок 'Мой кирпич' (id=42)"
git push origin feature/cool-brick-block
```

Открой PR на https://git.rublox.pro/rublox/studio/pulls.

## Подсказки

- **Не используй id уже занятые** — `grep -c 'id:' blockTypes.js` покажет сколько типов есть.
- **Не помещай большие текстуры** — 256x256 максимум. Иначе текстурный атлас не влезет в GPU.
- **`solid: false` для жидкостей** — игрок проходит сквозь, но рендерится с прозрачностью.
- **`gravity: true` для песка** — блок падает если под ним пусто.

## Что делать если блок не появляется

1. Проверь Console (F12) — есть ли ошибка про parsing JSON или texture not found.
2. Проверь что `texture` совпадает по имени с файлом в `public/kubikon-assets/blocks/`.
3. Проверь что `id` уникальный — два блока с одним id ломают map.
4. Очисти localStorage браузера (там кешируется состояние редактора): `localStorage.clear()` в Console.