Текст и переводы 1.21.4

Подробная документация по работе Minecraft с форматированным текстом и переводами.

WARNING

Эта страница написана для версии 1.21.4.
Документация для старых версий может быть неполной.

Всякий раз, когда Minecraft отображает текст в игре, он, вероятно, определяется с помощью объекта Component. Этот пользовательский тип используется вместо String для обеспечения более сложного форматирования, включая цвета, выделение жирным шрифтом, обфускации и событий нажатия (click). Они также обеспечивают легкий доступ в систему перевода, что упрощает перевод любого элемента пользовательского интерфейса в разные языки.

Если вы раньше работали с пакетами данных (датапаками) или функциями, вы можете увидеть параллели с текстовым форматом json, используемым для отображения названий, книг, табличек и другого. Как вы, возможно, догадываетесь, это на самом деле json-представление объекта Component, и его можно преобразовать в Component.Serializer и обратно с помощью Component.Serializer\`.

При создании мода, предпочтительнее создавать свои Component объекты непосредственно в коде, используя перевод, когда это возможно.

Текстовые литералы

Самый простой способ создать объект Component это использовать литерал. По сути это строка которая будет отображена как есть, без форматирования по умолчанию.

Они создаются с помощью методов Component.nullToEmpty и Component.literal, которые действуют немного по-разному. Component.nullToEmpty принимает значения null в себя и возвращает экземпляр класса Component. Component.literal же наоборот не сможет принять значение null, и вернётMutableComponent являющийся наследуемым классом от Component, который можно легко стилизовать и конкатенировать. Подробнее об этом будет сказано позже.

Text literal = Component.nullToEmpty("Hello, world!");
MutableComponent mutable = Component.literal("Hello, world!");
// Keep in mind that a MutableComponent can be used as a Text, making this valid:
Text mutableAsText = mutable;

Переводимый Текст

Когда вы хотите предоставить несколько переводов для одной и той же строчки текста, вы можете использовать метод Component.translatable для ссылки на ключ перевода в любом языковом файле. Если ключ не существует, ключ перевода конвертируется в литерал.

Text translatable = Component.translatable("my_mod.text.hello");

// Similarly to literals, translatable text can be easily made mutable.
MutableComponent mutable = Component.translatable("my_mod.text.bye");

Файл языка, en_us.json, выглядит как то так:

{
  "my_mod.text.hello": "Hello!",
  "my_mod.text.bye": "Goodbye :("
}

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

Text translatable = Component.translatable("my_mod.text.hello", player.getDisplayName());

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

{
  "my_mod.text.hello": "%1$s said hello!"
}

В игре %1$s будет заменено именем игрока, на которого вы ссылаетесь в коде. Использование player.getDisplayName() приведет к тому, что дополнительная информация об объекте появится во всплывающей подсказке при наведении курсора на имя в сообщении чата, в отличие от использования player.getName(), которое все равно получит имя; однако дополнительные детали не отображаются. Аналогичное можно сделать с itemStacks, используя stack.toHoverableText().

Что касается того, что вообще означает %1$s, все, что вам действительно нужно знать, это то, что это число соответствует переменной, которую вы пытаетесь использовать. Допустим, у вас есть три переменные, которые вы используете.

Text translatable = Component.translatable("my_mod.text.whack.item", victim.getDisplayName(), attacker.getDisplayName(), itemStack.toHoverableText());

Если вы хотите указать, кто в нашем случае является злоумышленником, вы должны использовать %2$s, потому что это вторая переменная, которую мы передали. Аналогично, %3$s относится к itemStack. Перевод с таким количеством дополнительных параметров может выглядеть так:

{
  "my_mod.text.whack.item": "%1$s was whacked by %2$s using %3$s"
}

Десериализация Текста

Как было упомянуто выше, вы можете сериализовать текст в JSON используя текстовый кодек. Для большей информации об кодеках, посмотрите страницу Codec.

Gson gson = new Gson();
MutableComponent mutable = Component.translatable("my_mod.text.bye");
String json = gson.toJson(ComponentSerialization.CODEC.encodeStart(JsonOps.INSTANCE, mutable).getOrThrow());

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

Сериализация Текста

Кроме того, чтобы десериализовать текстовый объект в реальный класс Component, опять же, используйте кодек.

String jsonString = "...";
Component deserialized = ComponentSerialization.CODEC
		.decode(JsonOps.INSTANCE, gson.fromJson(jsonString, JsonElement.class))
		.getOrThrow()
		.getFirst();

Форматирование Текста

Вы можете быть знакомы со стандартом форматирования в Minecraft:

Вы можете применить эти стили форматирования, используя перечисление ChatFormatting в классе MutableComponent:

MutableComponent result = Component.literal("Hello World!")
  .withStyle(ChatFormatting.AQUA, ChatFormatting.BOLD, ChatFormatting.UNDERLINE);

Цвет	Название	Код в чате	Код для MOTD	HEX-код
	Чёрный (black)	§0	\u00A70	#000000
	Тёмно-синий (dark_blue)	§1	\u00A71	#0000AA
	Тёмно-зелёный (dark_green)	§2	\u00A72	#00AA00
	Тёмно-голубой (dark_aqua)	§3	\u00A73	#00AAAA
	Тёмно-красный (dark_red)	§4	\u00A74	#AA0000
	Тёмно-фиолетовый (dark_purple)	§5	\u00A75	#AA00AA
	Золотой (gold)	§6	\u00A76	#FFAA00
	Серый (gray)	§7	\u00A77	#AAAAAA
	Тёмно-серый (dark_gray)	§8	\u00A78	#555555
	Синий (blue)	§9	\u00A79	#5555FF
	Зелёный (green)	§a	\u00A7a	#55FF55
	Голубой (aqua)	§b	\u00A7b	#55FFFF
	Красный (red)	§c	\u00A7c	#FF5555
	Фиолетовый (light_purple)	§d	\u00A7d	#FF55FF
	Жёлтый (yellow)	§e	\u00A7e	#FFFF55
	Белый (white)	§f	\u00A7f	#FFFFFF
	Сброс форматирования	§r
	Жирный	§l
	Зачёркнутый	§m
	Подчёркнутый	§n
	Курсив	§o
	Зашифрованный	§k