studio/docs/TUTORIAL_ADD_BLOCK.md

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

Делаем новый воксельный блок (по аналогии с 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 добавь:

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

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

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

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.