84 lines
4.1 KiB
Markdown
84 lines
4.1 KiB
Markdown
# Туториал: добавить новый тип блока
|
||
|
||
Делаем новый воксельный блок (по аналогии с 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.
|