Текст і переклади 1.21.1

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

WARNING

Ця сторінка написана для версії 1.21.1. Документація для старіших версій може бути неповною.

Щоразу, коли Minecraft промальовує текст у грі, він, ймовірно, визначається за допомогою об'єкта Component. Цей власний тип використовується замість String для більш розширеного форматування, включаючи кольори, жирний, зашифрований і події натискання. Вони також забезпечують легкий доступ до системи перекладу, що полегшує переклад будь-якого елемента інтерфейсу різними мовами.

Якщо ви раніше працювали з пакетами даних або функціями, ви можете побачити паралелі з текстовим форматом json, який використовується для показу імен, книг та табличок, і не тільки. Як ти мабуть, можна здогадатися, це просто представлення json об'єкта Component, і його можна конвертувати в і з використанням Component.Serializer.

Коли створюєте мод, зазвичай краще створювати об'єкти Текст безпосередньо у коді, використовуючи переклади, коли це можливо.

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

Найпростіший спосіб створити об'єкт Текст — створити літерал. Це просто рядок який промальовуватиме як є, за замовчуванням без жодного форматування.

Вони створюються за допомогою методів Component.nullToEmpty або Component.literal, які обидва діють трохи інакше. Component.nullToEmpty приймає нульові значення як вхідні дані та повертає екземпляр 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(для української треба uk_ua.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 замість літерального або перекладаного тексту.

Десеріалізація тексту

Крім того, щоб десеріалізувати текстовий об'єкт 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
	<0>Курсив	§o
	Зашифрований	§k