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

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

WARNING

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

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

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

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

Буквені текстові компоненти

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

Вони створюються за допомогою методів Component.nullToEmpty або Component.literal, які обидва діють трохи по різному. Component.nullToEmptyприймає нульові значення як вхідні дані та повертає екземплярComponent. На відміну від цього, Component.literalне повинен мати нульовий вхід, але повертаєMutableComponent, це підклас Component`, який можна легко стилізувати та об’єднувати. Про це пізніше.

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

Перекладувані текстові компоненти

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

Component translatable = Component.translatable("example-mod.text.hello");

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

Мовний файл en_us.json, виглядає так:

{
  "example-mod.text.hello": "Hello!",
  "example-mod.text.bye": "Goodbye :("
}

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

Component translatable = Component.translatable("example-mod.text.hello", player.getDisplayName());

Ви можете посилатися на ці змінні в перекладі так:

{
  "example-mod.text.hello": "%1$s said hello!"
}

У грі %1$s буде замінено іменем гравця, якого ви згадали в коді. Використання player.getDisplayName() зробить так, що додаткова інформація про сутність з’явиться у спливній підказці під час наведення курсора на ім’я в повідомленні чату, на відміну від використання player.getName(), який все одно отримає назву; однак він не показуватиме додаткових деталей. Подібне можна зробити з itemStacks, використовуючи stack.getDisplayName().

Щодо того, що взагалі означає %1$s, все, що вам справді потрібно знати, це те, що число відповідає змінній, яку ви намагаєтеся використати. Припустімо, у вас є три змінні, які ви використовуєте.

Component translatable = Component.translatable("example-mod.text.whack.item", victim.getDisplayName(), attacker.getDisplayName(), itemStack.toHoverableText());

Якщо ви хочете вказати, хто в нашому випадку є зловмисником, ви б використовували %2$s, оскільки це друга змінна, яку ми передали. Так само %3$s посилається на itemStack. Переклад із такою кількістю додаткових параметрів може виглядати так:

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

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

Як згадувалося раніше, ви можете серіалізувати текст у JSON за допомогою текстового кодека. Додаткову інформацію про кодеки див. сторінку кодеків.

Gson gson = new Gson();
MutableComponent mutable = Component.translatable("example-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-код
	Чорний<0/>black	§0	\u00A70	#000000
	Темно-синій<0/>dark_blue	§1	\u00A71	#0000AA
	Темно-зелений dark_green	§2	\u00A72	#00AA00
	Темно-водянистий	§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