Ресурспаки — кастомные предметы и звуки

На этой странице мы ответим на частые вопросы тех, кто хочет создавать визуально кастомные предметы и добавлять новые звуки в ресурспак. В сети полно туториалов по созданию собственного ресурспака, а вот инструкций по работе с custom model data и управлению звуками в нём куда меньше. Это руководство сосредоточено в основном на том, как правильно оформить ресурспак, а затем использовать его в Minecraft через скрипты Denizen.

Внутри корневой директории 

Если у вас ещё нет ресурспака: попасть в директорию resourcepacks можно через меню «Resource Packs» в клиенте Minecraft, нажав кнопку «Open Pack Folder». Внутри неё можно создать новую папку для вашего пака.

Путь: .minecraft/resourcepacks/MyResourcePack/

Главная директория вашего ресурспака должна содержать оба этих элемента:

Папку assets — здесь будут лежать все ваши файлы.
pack.mcmeta — это файл, по которому Minecraft понимает, в каком формате сделан ваш ресурспак. В идеале сюда же стоит положить pack.png — это 64x64 иконка вашего пака!

Пример файла: `pack.mcmeta`

Файл pack.mcmeta оформляется в формате json. В нём нужны две именованные строки: pack_format и description. Вот как он выглядит внутри:

{
   "pack": {
      "pack_format": 9,
      "description": "My Fancy Resource Pack"
   }
}

Ключ файла pack.mcmeta: `pack_format`

Это индикатор для Minecraft, под какую версию Minecraft сделан пак. Число немного условное — оно обновляется каждый раз, когда Minecraft меняет внутренний формат паков, иногда по несколько раз между релизами Minecraft.

6 соответствует версии 1.16.5,
7 соответствует версии 1.17,
8 соответствует версии 1.18,
9 соответствует версии 1.19,
13 соответствует версии 1.19.4
22 соответствует 1.20.4
34 соответствует 1.21
Другие значения для версий можно посмотреть на этой странице Minecraft Wiki

Ключ файла pack.mcmeta: `description`

Может быть пустым, но в идеале стоит вписать туда что-нибудь красивое. Символы Unicode нужно записывать в экранированном виде, например: \uКОД; два примера: \u2588 для █, и \u00A7 для § — знака параграфа, который парсит валидные цветовые коды, используемые для раскраски текста в чате Minecraft. Если хотите красный текст, ваша строка будет выглядеть примерно так: \u00A74Dark Red!. Замечание: сначала идёт цвет, потом форматирование; коды форматирования сохраняются после кода цвета, а не наоборот!

Спецсимволы можно найти в «Таблице символов». Если у вас Windows: Пуск > Стандартные — Windows. Если у вас Linux с GNOME или Unity: Gucharmap character map входит в GNOME desktop. Если вы используете GNOME, открыть таблицу символов можно одним из следующих способов:

Через меню в верхней части экрана: (язык) > Character Map.
Командой gucharmap в терминале.
Приложения > Стандартные > Character Map.

Также нужный символ Unicode всегда можно нагуглить.

Внутри директории Assets 

Путь: .minecraft/resourcepacks/MyResourcePack/assets/

В этой директории должна лежать ровно одна папка: minecraft. Больше здесь ничего не нужно.

Внутри директории minecraft 

Путь: .minecraft/resourcepacks/MyResourcePack/assets/minecraft/

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

blockstates — здесь хранятся состояния блоков (blockstates).
font — здесь хранятся данные шрифтов.
models — здесь хранятся данные и файлы моделей.
textures — здесь хранятся файлы текстур.
sounds — здесь хранятся ваши звуки.
optifine — здесь хранятся данные Optifine. Это руководство Optifine не покрывает.

Для поддержки Optifine рекомендуется зайти в их Discord и изучить их документацию в исходниках на GitHub.

Внутри директории sounds 

Путь: .minecraft/resourcepacks/MyResourcePack/assets/minecraft/sounds/. Звуки Minecraft используют формат .ogg. Бесплатные конвертеры можно найти в интернете, например Audio-Online-Convert.com. Для порядка, если вы добавляете новые звуки, рекомендуется класть их в папку с именем custom. В стандартных ресурсах Minecraft звуки разложены по категориям. Стандартный индекс звуков Minecraft лежит здесь: .minecraft/assets/indexes/1.21.json, где 1.21 — это версия Minecraft. Все ваши звуковые файлы (файлы .ogg) должны лежать в этой директории.

Пример файла: `sounds.json`

Этот файл индексирует, где Minecraft должен искать ваши звуки. Ниже — пример настройки для двух кастомных звуков: defense_levelup0 и defense_levelup1.

{
  "entity.player.defense.level": {
    "sounds": [
      {
        "name": "custom/defense_levelup0"
      },
      {
        "name": "custom/defense_levelup1"
      }
    ],
    "subtitle": "Excited Trumpet Noises"
  }
}

Первый ключ — это имя звука; в нашем примере это entity.player.defense.level. Из обязательных полей внутри команды нужно указать только sounds. По желанию можно задать субтитры, которые будут отображаться, если в игре включены субтитры. Если в массиве "sounds":[] указано несколько звуков, при воспроизведении между ними будет случайно выбираться с учётом их веса. Расширение файла — .ogg; другие форматы не поддерживаются.

Для каждого файла нужно указать данные: "name":"ПУТЬ/ИМЯ_ФАЙЛА", без расширения файла. По желанию можно вручную задать следующие валидные параметры звука:

volume — громкость воспроизведения звука.
- По умолчанию 1.0; допустимый диапазон — от 0.0 до 1.0; 1.0 — это максимальная громкость.
- Значение volume в Denizen PlaySound может быть и больше — но это не увеличивает громкость, а увеличивает дальность, на которой звук слышно.
- Например, volume 5 — звук слышно с расстояния в пять чанков.
pitch — высота звука, отличающаяся от исходного .ogg.
- По умолчанию 1.0; допустимый диапазон — от 0.0 до 2.0; 1.0 — высокий звук, 0.0 — низкий.
weight — шанс, с которым этот звук будет выбран при случайном выборе. Чем больше число, тем чаще используется.
stream — определяет, нужно ли стримить звук из файла.
- По умолчанию false.
- Рекомендуется ставить true, если звук длиннее двух секунд — иначе могут быть лаги.
- Используйте это умеренно; не стоит ставить true всему подряд.
- Применяется ко всем музыкальным дискам.
preload — определяет, нужно ли загрузить звук при загрузке пака, а не в момент проигрывания.
- По умолчанию false.
- Используется для фоновых звуков.
attenuation_distance — определяет скорость затухания звука в зависимости от расстояния.
- По умолчанию 1.0.
- Используется для порталов, маяков, кондуитов.
type — определяет, какое предопределённое событие запускает этот звук.
- По умолчанию sound, второй вариант — event.
- sound — значение name воспринимается как имя файла.
- event — значение name воспринимается как имя уже определённого события.
- Используется для случаев вроде «находится под водой», «в пещере», «рядом с маяком», «рядом с ульем».

Использование кастомных звуков 

Воспроизведение вашего звука опирается на уникальное кастомное имя, которое вы ему дали. В нашем примере мы задали имя звука как entity.player.defense.level. Проиграть этот звук можно командой playsound так: /ex playsound <player> entity.player.defense.level custom. В скрипте это будет выглядеть примерно так:

MyCustomSound:
    type: task
    script:
        - playsound <player> sound:entity.player.defense.level custom

Внутри директории blockstates 

Путь: .minecraft/resourcepacks/MyResourcePack/assets/minecraft/blockstates/

Чтобы менять конкретные состояния блоков, нужно указывать каждое состояние по отдельности. Дополнительные состояния блоков добавлять нельзя. При указании моделей для состояний блоков путь ведёт в директорию models по адресу /assets/minecraft/models/. Настройка этого в руководстве не рассматривается.

Внутри директории models 

Путь: .minecraft/resourcepacks/MyResourcePack/assets/minecraft/models/

Чтобы «создать» новые предметы, нужно модифицировать уже существующие предметы Minecraft. Раньше это делалось через Durability, но идеальный инструмент для этого — custom_model_data, появившийся в Minecraft 1.14. Три типа моделей для model data: block states, block models и item models. Block States и Block Model data в этом руководстве не рассматриваются.

Пример файла: `wooden_sword.json`

Существующие файлы, такие как wooden_sword, должны выглядеть примерно так:

{
    "parent": "item/handheld",
    "textures": {
        "layer0": "item/wooden_sword"
    }
}

Это пример wooden_sword.json, который лежит по пути /assets/minecraft/models/item/wooden_sword.json. Ключ parent указывает на модель, в которую этот файл инжектит данные. Значение parent — это ПУТЬ/ИМЯ_ФАЙЛА из директории models, если указывается файл модели, и путь в директории textures, если указывается текстура.

В примере выше wooden_sword использует родительскую модель по пути: /assets/minecraft/textures/item/handheld.json. А ещё wooden_sword использует текстуру-картинку по пути: /assets/minecraft/textures/item/wooden_sword.png.

Заметьте: если убрать ключи parent, не указав при этом все параметры отображения предмета, результат будет непредсказуемым. Например, wooden_sword опирается на родительский файл /assets/minecraft/textures/item/generated.json; тот, в свою очередь, опирается на родительский файл /assets/minecraft/textures/builtin/generated.json. Если эти файлы не переопределены в вашем паке, используются соответствующие стандартные файлы из ресурсов Minecraft. Чтобы добавить условие custom_model_data, его указывают в ключе overrides. Вот пример override'а с заданным custom_model_data:

{
    "parent": "item/handheld",
    "textures": {
        "layer0": "item/wooden_sword"
    },
    "overrides": [
        { "predicate": { "custom_model_data": 1 }, "model": "item/custom/dserver_ubersword" }
    ]
}

Замечание: не забывайте, что объекты и массивы разделяются запятыми. В примере выше предмет wooden_sword расширяется дополнительной моделью, которая применяется, когда у предмета в игре выставлен соответствующий механизм. Этот файл лежит по пути: /assets/minecraft/models/item/custom/dserver_ubersword.json. Допустимые значения custom_model_data — целые числа (в том числе большие, в отличие от более ограниченного durability). Пример файла с несколькими значениями custom_model_data выглядит так:

{
    "parent": "item/handheld",
    "textures": {
        "layer0": "item/wooden_sword"
    },
    "overrides": [
        { "predicate": { "custom_model_data": 1 }, "model": "item/custom/dserver_ubersword" },
        { "predicate": { "custom_model_data": 2 }, "model": "item/custom/dserver_prosword" },
        { "predicate": { "custom_model_data": 3 }, "model": "item/custom/dserver_greatsword" },
        { "predicate": { "custom_model_data": 4 }, "model": "item/custom/dserver_decentsword" }
    ]
}

Пример файла: `custom_item.json`

Файл с данными модели вашего кастомного предмета — это то, что вы, возможно, и сами будете править. Существует немало программ для 3D-моделирования, самая рекомендуемая — бесплатный и очень способный BlockBench, либо платный Cubik Pro, который, по отзывам, очень мощный. Важно, чтобы выбранная вами программа умела экспортировать модель в формат .json. Cubik Pro, в частности, сам сохраняет модель и связанный с ней файл изображения в нужные места и корректно оформляет файл модели. Когда вы кладёте файл модели кастомного предмета туда, куда указано в примере выше, начало файла модели должно выглядеть примерно так:

{
	"textures": {
		"particle": "item/custom/handheld/dserver_ubersword",
		"texture": "item/custom/handheld/dserver_ubersword"
	},

Заметьте, что вам по-прежнему нужны и остальные части JSON-файла, например ключ "parent".

В примере выше ключи particle и texture указывают на файлы картинок, которые мы будем хранить по пути: /assets/minecraft/textures/item/custom/handheld/dserver_ubersword.png.

Использование кастомных предметов 

Выдать себе предмет просто. Если вам нужна штука разово или вы просто тестируете, воспользуйтесь командой /ex: /ex give wooden_sword[custom_model_data=1]. Скрипт предмета выглядит примерно так:

UberSword:
    type: item
    material: wooden_sword
    mechanisms:
        custom_model_data: 1

Механизм custom_model_data указывается наряду с любыми другими механизмами кастомного предмета. Выдать себе кастомный предмет можно так же, как и любой другой предмет-скрипт — /ex give dserver_ubersword или из скрипта командой give / inventory.

Внутри директории textures 

Путь: .minecraft/resourcepacks/MyResourcePack/assets/minecraft/textures/. Здесь хранятся ваши файлы картинок. Эти файлы должны лежать по относительным путям, указанным в соответствующих им файлах моделей.

Создание кастомных шрифтов 

Один из многих полезных инструментов ресурспака — кастомные шрифты! В самом базовом случае они позволяют менять шрифт текста, а в более продвинутом — добавлять эмодзи и целые кастомные картинки! Шрифт с кастомной картинкой размером с инвентарь, размещённый в заголовке инвентаря, даёт возможность сделать полностью кастомный экран GUI инвентаря!

Как сделать кастомный шрифт?

Просто!

Шаг 1. В вашем ресурспаке заведите отдельную папку, специфичную для пака. Для многих других фич нужно переопределять папку minecraft, но здесь можно завести свою. То есть вместо assets/minecraft/font у вас будет assets/examplepack/font (но замените examplepack на имя вашего пака… или любое простое обозначение, как вам удобнее). Шаг 2. Внутри assets/examplepack/font создайте файл с именем, например, examplefont.json (но опять же, как угодно — например, gui.json или particles.json). Шаг 3. Внутри этого json-файла добавьте следующее:

{
  "providers": [
      {
          "type": "bitmap",
          "file": "examplepack:samplefolder/sampleimage.png",
          "ascent": 8,
          "height": 8,
          "chars": [
              "a"
          ]
      },
      {
          "type": "bitmap",
          "file": "examplepack:samplefolder/sampleimage2.png",
          "ascent": 8,
          "height": 8,
          "chars": [
              "b"
          ]
      }
  ]
}

Обратите внимание, что samplefolder и sampleimage — это места, куда нужно подставить собственные имена.

Шаг 4. По пути assets/examplepack/textures/samplefolder/ положите sampleimage.png — любую валидную картинку любого валидного размера (8x8, 32x32, 128x128 и т. п.).

Имена папок и файлов могут быть любыми, главное — ASCII (a-z, 0-9), всё в нижнем регистре, и короткие/простые. В общем, не провоцируйте баги сложными и грязными именами.

Важно, чтобы имена в JSON-файле совпадали с реальными путями к файлам.

Если нужны картинки для теста, вот пара валидных примеров: sampleimage.png, sampleimage2.png

Шаг 5. Загрузите пак в игре.

Шаг 6. В игре попробуйте выполнить /ex narrate <&font[examplepack:examplefont]>ab

Обратите внимание, что используется имя папки examplepack и имя JSON-файла examplefont. Подставьте сюда свои имена.

Также обратите внимание, что текст ab соответствует строкам "a" и "b" в JSON.

Вы должны увидеть свои картинки:

../../_images/custom_font_demo.png

Если хотите вставить кастомный шрифт в обычную строку, можно сделать и так: /ex narrate "Hi there <element[ab].font[examplepack:examplefont]> how's it going?", либо в любой момент переключиться обратно на стандартный шрифт через <&font[minecraft:default]>.

Как добавить в шрифт новые картинки?

Просто скопируйте блок, начинающийся с { и заканчивающийся }, и обязательно добавьте , между блоками (но не после последнего). Затем поменяйте chars на новую букву или цифру, которую вы ещё не использовали, и обновите file на путь к новой картинке.

Некоторые предпочитают в chars писать \uF801 в JSON, а в скриптах использовать <&chr[f801]>, увеличивая число на 1 для каждого нового значения. Иногда это удобно для организации, но по большей части это просто наследие старого стандарта, когда переопределяли стандартный шрифт Minecraft, а не делали свой.

Как сделать картинки больше или меньше?

Менять размер самого .png файла бесполезно — чтобы изменить размер картинки, отредактируйте значения height и ascent в JSON-файле.

Параметр height отвечает за размер картинки, а ascent — за её смещение вверх или вниз относительно строки текста, в которой она находится.

Стандартный размер текста — 8 и для height, и для ascent.

Учтите, что текст крупнее 8 в чате будет наезжать на соседние строки.

Как сделать кастомный GUI инвентаря?

Вот пример пака для кастомных GUI инвентаря:

Можно добавить этот json, например, по пути assets/examplepack/font/gui.json

{
  "providers": [
      {
          "type": "bitmap",
          "file": "examplepack:gui/vanilla_inventory_reference.png",
          "ascent": 13,
          "height": 127,
          "chars": [
              "a"
          ]
      },
      {
          "type": "bitmap",
          "file": "examplepack:gui/custom_inventory.png",
          "ascent": 13,
          "height": 127,
          "chars": [
              "b"
          ]
      },
      {
          "type": "bitmap",
          "file": "examplepack:gui/space.png",
          "ascent": -32768,
          "height": -10,
          "chars": [
              "-"
          ]
      },
      {
          "type": "bitmap",
          "file": "examplepack:gui/space.png",
          "ascent": -32768,
          "height": -170,
          "chars": [
              "="
          ]
      }
  ]
}

В этом паке символ - использует «space» — картинку 1x1 с особыми значениями ascent и height, которые сдвигают картинку на нужное место из заголовка инвентаря, чтобы она легла поверх всего GUI, а = возвращает текст в нормальное место. Вот картинка space, которую можно использовать.

Символ a, vanilla_inventory_reference — это картинка ванильного инвентаря, которую можно использовать как шаблон. Скачать референс можно здесь. Если у вас кастомный текстурпак, возможно, вы предпочтёте взять в качестве референса картинку инвентаря именно из вашего пака, а не ванильную.

Символ b, custom_inventory — это отредактированная ванильная картинка для демонстрации. Можно скачать мой демо-пример, если нужно.

Примените его в скрипте инвентаря так:

example_gui:
    type: inventory
    debug: false
    gui: true
    inventory: chest
    title: <&f><&font[examplepack:gui]>-b=<&font[minecraft:default]><&0>Hello there!
    slots:
    - [] [] [] [] [] [] [] [] []
    - [] [] [] [] [stick] [] [] [] []
    - [] [stone] [] [] [] [] [] [] []
    - [] [] [] [] [] [] [] [] []
    - [] [] [] [] [] [] [] [] []
    - [] [] [] [] [] [] [] [] []

Обратите внимание: <&f> задаёт белый цвет (чтобы цвет не испортил картинку), - сдвигает позицию, b добавляет картинку, = возвращает позицию к стандартной, <&font[minecraft:default]> переключает обратно на стандартный шрифт, затем <&0> возвращает стандартный чёрный цвет, и наконец — обычное название инвентаря.

Откройте этот скрипт командой /ex inventory open d:example_gui, чтобы увидеть результат в игре.

../../_images/example_inv_demo.png

В реальном использовании вам не нужно повторять структуру GUI инвентаря один в один — можно полностью закрыть пустые слоты или нарисовать что угодно. Референс в основном нужен для того, чтобы понимать, где окажутся предметы, если вы их добавите.

Возможно, вы захотите сделать некоторые части картинки прозрачными — тогда при наведении на предмет фон-подсветка будет показываться корректно.

Вот пример GUI инвентаря, чуть ближе к боевым условиям: (нажмите, чтобы скачать)

../../_images/masterpiece_inv.png

Эта картинка служит напоминанием о том, что даже после того, как вы освоите код, не стоит пренебрегать помощью художника для ресурспака — попытка сделать всё самому обычно не стоит того.

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

`Итог по шрифтам`


Если вы в точности следовали этой инструкции по шрифтам и ничего не переименовывали, структура файлов вашего пака должна совпадать с этой:



Советы и заметки на ходу работы
Очень удобный приём для отладки ресурспаков «методом тыка» — пак можно активно править и сразу видеть изменения в игре.
Одно из самых частых заблуждений насчёт ресурспаков — что их обязательно нужно сохранять в виде .zip.
ЭТО НЕ ТАК! Можно хранить пак прямо в папке resourcepacks — править и просто перезагружать!
Стандартная горячая клавиша для перезагрузки ресурспаков — F3 + T.
Если вы видите плоский фиолетово-чёрный квадрат — это стандартная Minecraft-заглушка для отсутствующей текстуры.

если у предмета плоская фиолетово-чёрная текстура — путь к файлу модели предмета указан неверно или файл отсутствует;
если у предмета есть форма, но нет текстуры — путь к картинке в файле модели указан неверно или файл картинки отсутствует;
если предмет выглядит нормально — ваш ресурспак не регистрирует изменения этого предмета.

Есть очень удобный JSON-форматтер и валидатор — вот он. Minecraft не покажет никаких ошибок при битом JSON, кроме сломанных текстур и моделей.
Кастомные текстуры, модели и звуки можно класть в любые вложенные подпапки. Не забывайте, что все имена файлов и папок должны быть в нижнем регистре, иначе будут проблемы с чувствительностью к регистру.
Стандартная папка с ресурспаками находится в вашей основной директории Minecraft и выглядит примерно так:
C:/Users/[имя_пользователя]/AppData/Roaming/.minecraft/resourcepacks (в Windows можно быстро перейти через %appdata%/.minecraft/resourcepacks), или /home/[имя_пользователя]/.minecraft/resourcepacks в Linux.
Можно просто открыть папку кнопкой Open Resource Pack Folder в разделе Resource Packs... игрового меню.
Лучший шаблон для модификации стандартных моделей и текстур Minecraft — это дефолтный ресурс, который лежит прямо в jar-файле версии по пути: /.minecraft/versions/.
Его можно распаковать и найти внутри папку assets.
Учтите, что при копировании всей папки assets в качестве шаблона стоит удалить материалы, которые вы не меняете, — это лишний вес вашего ресурспака.


Полезные технические доки и ссылки

Мета-документация по команде Playsound
Форматтер и валидатор JSON
Online-Convert.com | Конвертация аудио в OGG