Базовый гайд по созданию модификаций

Модификации Туториалы по разработке
1 
# [Гайд] Создание первой модификации для Hytale: от идеи до добавления предметов и блоков

В отличие от серверных плагинов, которые управляют системной логикой и сетевыми событиями, **модификации (моды)** в Hytale отвечают за наполнение игры новым контентом: кастомными предметами, блоками, мобами, рецептами крафта, 3D-моделями и текстурами.

Hytale использует **data-driven архитектуру**: большая часть игровых сущностей объявляется через декларативные конфигурации (JSON) и связывается с ассетами моделей и текстур.

В этом руководстве мы разберем базовую структуру мода, напишем манифест, создадим кастомный предмет и блок с рецептом крафта.

---

### Необходимые инструменты

1. **Редактор кода / текста:** [VS Code](https://code.visualstudio.com/) (рекомендуется с расширениями *JSON Language Features* и *Even Better TOML*) или любая IDE от JetBrains.
2. **Инструмент для 3D-моделирования:** **Hytale Model Maker (HMM)** (встроен в экосистему Hytale) или [Blockbench](https://www.blockbench.net/) для создания воксельных моделей и анимаций.
3. **Графический редактор:** Aseprite, Photoshop, Paint.NET или GIMP для отрисовки текстур и иконок.

---

### Шаг 1. Анатомия и структура каталогов мода

Каждая модификация Hytale представляет собой отдельный каталог (или zip-архив), содержащий манифест, директории данных и мультимедиа-ресурсов.

Создайте папку для вашего мода (например, `RubyExpansion`) со следующей иерархией:

```text
RubyExpansion/
├── mod.json                     # Манифест с метаданными мода
├── assets/                      # Графика, модели, аудио
│   ├── models/                  # Файлы 3D-моделей (.bbmodel / .hytale)
│   │   └── items/
│   │       └── ruby_sword.geo.json
│   ├── textures/                # Растровые текстуры
│   │   ├── items/
│   │   │   ├── ruby_gem.png
│   │   │   └── ruby_sword.png
│   │   └── blocks/
│   │       └── ruby_ore.png
│   └── sounds/                  # Кастомные звуковые эффекты
└── data/                        # Логика и свойства игровых объектов (JSON)
    ├── items/                   # Определение предметов
    │   ├── ruby_gem.json
    │   └── ruby_sword.json
    ├── blocks/                  # Определение блоков
    │   └── ruby_ore.json
    └── recipes/                 # Рецепты крафта и плавки
        └── ruby_sword_craft.json

Шаг 2. Создание манифеста (mod.json)

В корне мода создайте файл mod.json. Игра считывает этот файл при инициализации для разрешения зависимостей и версионности:

JSON

{
  "id": "hytalify:ruby_expansion",
  "name": "Ruby Expansion",
  "version": "1.0.0",
  "description": "Добавляет в игру рубиновую руду, самоцветы и рубиновое оружие.",
  "authors": [
    "ВашНик"
  ],
  "website": "[https://hytalify.online](https://hytalify.online)",
  "minEngineVersion": "1.0.0",
  "dependencies": []
}

  • id — уникальный идентификатор мода в формате namespace:mod_id (используйте строчные буквы и знак подчеркивания).

  • minEngineVersion — минимально совместимая версия клиента/сервера игры.

Шаг 3. Создание кастомного предмета (data/items/ruby_sword.json)

Создадим файл data/items/ruby_sword.json, описывающий боевой меч:

JSON

{
  "id": "hytalify:ruby_sword",
  "name": "Рубиновый меч",
  "category": "weapon",
  "rarity": "rare",
  "max_stack": 1,
  "durability": 750,
  "render": {
    "model": "hytalify:models/items/ruby_sword",
    "texture": "hytalify:textures/items/ruby_sword",
    "icon": "hytalify:textures/items/ruby_sword"
  },
  "combat": {
    "damage_type": "slashing",
    "base_damage": 32.0,
    "attack_speed": 1.4,
    "crit_chance": 0.15,
    "crit_multiplier": 1.5
  },
  "behavior": {
    "swing_animation": "two_handed_slash",
    "can_block": true,
    "block_reduction": 0.6
  }
}

Совет по путям: всегда используйте пространство имен (namespace) вашего мода в ссылках на ассеты (hytalify:textures/...), чтобы избежать конфликтов с другими модификациями.

Шаг 4. Создание кастомного блока (data/blocks/ruby_ore.json)

Теперь создадим рубиновую руду, которая будет добываться в подземных пещерах:

JSON

{
  "id": "hytalify:ruby_ore",
  "name": "Рубиновая руда",
  "material": "stone",
  "hardness": 4.5,
  "resistance": 6.0,
  "required_tool": "pickaxe",
  "min_tool_tier": "iron",
  "textures": {
    "all": "hytalify:textures/blocks/ruby_ore"
  },
  "drops": [
    {
      "item": "hytalify:ruby_gem",
      "count": {
        "min": 1,
        "max": 3
      },
      "chance": 1.0
    }
  ],
  "light_emission": 2
}

Здесь мы указали, что блок требует железную кирку или выше, имеет легкое свечение в темноте (light_emission: 2) и при разрушении с вероятностью 100% дропает от 1 до 3 рубинов (hytalify:ruby_gem).

Шаг 5. Регистрация рецепта крафта (data/recipes/ruby_sword_craft.json)

Чтобы игроки могли выковать меч на верстаке:

JSON

{
  "type": "crafting_table",
  "result": {
    "item": "hytalify:ruby_sword",
    "count": 1
  },
  "pattern": [
    " R ",
    " R ",
    " S "
  ],
  "ingredients": {
    "R": {
      "item": "hytalify:ruby_gem"
    },
    "S": {
      "item": "base:stick"
    }
  }
}

Шаг 6. Создание и привязка 3D-модели

  1. Откройте Blockbench или Hytale Model Maker.

  2. Создайте геометрию меча, используя низкополигональные воксели (кубы).

  3. Нанесите текстуру разрешением 32x32 или 64x64 пикселя.

  4. Экспортируйте файл геометрии в папку assets/models/items/ruby_sword.geo.json, а сохраненную текстуру — в assets/textures/items/ruby_sword.png.

Шаг 7. Установка и проверка в игре

  1. Перенесите всю папку RubyExpansion (или запакованный .zip) в каталог:

    • Клиент: %appdata%/Hytale/mods/ (Windows) или ~/.local/share/Hytale/mods/ (Linux).

    • Выделенный сервер: в директорию mods/ в корне сервера.

  2. Запустите игру или сервер.

  3. Откройте чат или консоль и выдайте себе предмет командой:

    Plaintext

    /give @s hytalify:ruby_sword 1

  4. Если предмет появился в инвентаре, отображает правильную 3D-модель и наносит урон — ваша модификация работает штатно.

:hammer_and_wrench: Есть вопросы по синтаксису или моделям?

Если игра не видит текстуры или выдает ошибку парсинга JSON — прикрепляйте фрагмент конфига и лог в комментариях, поможем разобраться!