StackDeobfuscator

Что делает StackDeobfuscator

StackDeobfuscator - технический Fabric-мод для Minecraft Java Edition, предназначенный для разработчиков модов и владельцев тестовых серверов. Он автоматически заменяет обфусцированные имена классов и методов в логах, ошибках и crash report на читаемые названия из Yarn, Quilt или Mojang mappings.

Без такого инструмента Minecraft часто показывает что-то вроде net.minecraft.class_310. По этой строке сложно понять, какой именно участок игры вызвал сбой. StackDeobfuscator превращает ее в понятное имя, например net.minecraft.client.MinecraftClient, поэтому причину ошибки можно искать намного быстрее.

Геймплей мод не меняет. Новые блоки, предметы, мобы или механики он не добавляет. Его задача уже и практичнее: сделать диагностику Minecraft понятной за пределами среды разработки. Это особенно полезно при тестировании сборки модов, запуске клиента с большим количеством дополнений и поиске причины падения на сервере.

Зачем нужен этот мод

В production-сборке Minecraft имена классов и методов обычно обфусцированы. В результате обычный crash report выглядит как длинный список class_ и method_, а разработчику приходится вручную сопоставлять их с mappings.

StackDeobfuscator выполняет это преобразование автоматически:

• заменяет нечитаемые имена классов на понятные названия;
• расшифровывает имена методов в stack trace;
• обрабатывает ошибки, выведенные в консоль;
• изменяет crash report, чтобы его было проще анализировать;
• использует выбранные Yarn, Quilt или Mojang mappings;
• загружает и разбирает mappings асинхронно, не блокируя запуск игры.

На практике это экономит время при разборе конфликтов между модами. Вместо поиска по условному class_309.method_1474 можно сразу увидеть, что ошибка связана с обработчиком клавиатуры или другим конкретным компонентом Minecraft.

Как выглядит результат

Ниже показана разница между обычным обфусцированным stack trace и отчетом после обработки StackDeobfuscator.

До установки

[23:13:08] [Render thread/ERROR]: Reported exception thrown!
net.minecraft.class_148: Manually triggered debug crash
         at net.minecraft.class_309.method_1474(class_309.java:509) ~[client-intermediary.jar:?]
         at net.minecraft.class_310.method_1574(class_310.java:1955) ~[client-intermediary.jar:?]
         at net.minecraft.class_310.method_1523(class_310.java:1180) ~[client-intermediary.jar:?]
         at net.minecraft.class_310.method_1514(class_310.java:801) ~[client-intermediary.jar:?]
         at net.minecraft.client.main.Main.main(Main.java:237) ~[minecraft-1.19.4-client.jar:?]
         at net.fabricmc.loader.impl.game.minecraft.MinecraftGameProvider.launch(MinecraftGameProvider.java:462) ~[fabric-loader-0.14.18.jar:?]
         at net.fabricmc.loader.impl.launch.knot.Knot.launch(Knot.java:74) ~[fabric-loader-0.14.18.jar:?]
         at net.fabricmc.loader.impl.launch.knot.KnotClient.main(KnotClient.java:23) ~[fabric-loader-0.14.18.jar:?]
         at org.prismlauncher.launcher.impl.StandardLauncher.launch(StandardLauncher.java:88) ~[NewLaunch.jar:?]
         at org.prismlauncher.EntryPoint.listen(EntryPoint.java:126) ~[NewLaunch.jar:?]
         at org.prismlauncher.EntryPoint.main(EntryPoint.java:71) ~[NewLaunch.jar:?]
Caused by: java.lang.Throwable: Manually triggered debug crash
         at net.minecraft.class_309.method_1474(class_309.java:506) ~[client-intermediary.jar:?]
         ... 10 more

После обработки через Yarn или Quilt mappings

[23:11:25] [Render thread/ERROR]: Reported exception thrown!
net.minecraft.util.crash.CrashException: Manually triggered debug crash
         at net.minecraft.client.Keyboard.pollDebugCrash(Keyboard.java:509) ~[client-intermediary.jar:?]
         at net.minecraft.client.MinecraftClient.tick(MinecraftClient.java:1955) ~[client-intermediary.jar:?]
         at net.minecraft.client.MinecraftClient.render(MinecraftClient.java:1180) ~[client-intermediary.jar:?]
         at net.minecraft.client.MinecraftClient.run(MinecraftClient.java:801) ~[client-intermediary.jar:?]
         at net.minecraft.client.main.Main.main(Main.java:237) ~[minecraft-1.19.4-client.jar:?]
         at net.fabricmc.loader.impl.game.minecraft.MinecraftGameProvider.launch(MinecraftGameProvider.java:462) ~[fabric-loader-0.14.18.jar:?]
         at net.fabricmc.loader.impl.launch.knot.Knot.launch(Knot.java:74) ~[fabric-loader-0.14.18.jar:?]
         at net.fabricmc.loader.impl.launch.knot.KnotClient.main(KnotClient.java:23) ~[fabric-loader-0.14.18.jar:?]
         at org.prismlauncher.launcher.impl.StandardLauncher.launch(StandardLauncher.java:88) ~[NewLaunch.jar:?]
         at net.prismlauncher.EntryPoint.listen(EntryPoint.java:126) ~[NewLaunch.jar:?]
         at net.prismlauncher.EntryPoint.main(EntryPoint.java:71) ~[NewLaunch.jar:?]
Caused by: java.lang.Throwable: Manually triggered debug crash
         at net.minecraft.client.Keyboard.pollDebugCrash(Keyboard.java:506) ~[client-intermediary.jar:?]
         ... 10 more

После обработки через Mojang mappings

[23:04:12] [Render thread/ERROR]: Reported exception thrown!
net.minecraft.ReportedException: Manually triggered debug crash
         at net.minecraft.client.KeyboardHandler.tick(KeyboardHandler.java:509) ~[client-intermediary.jar:?]
         at net.minecraft.client.Minecraft.tick(Minecraft.java:1955) ~[client-intermediary.jar:?]
         at net.minecraft.client.Minecraft.runTick(Minecraft.java:1180) ~[client-intermediary.jar:?]
         at net.minecraft.client.Minecraft.run(Minecraft.java:801) ~[client-intermediary.jar:?]
         at net.minecraft.client.main.Main.main(Main.java:237) ~[minecraft-1.19.4-client.jar:?]
         at net.fabricmc.loader.impl.game.minecraft.MinecraftGameProvider.launch(MinecraftGameProvider.java:462) ~[fabric-loader-0.14.18.jar:?]
         at net.fabricmc.loader.impl.launch.knot.Knot.launch(Knot.java:74) ~[fabric-loader-0.14.18.jar:?]
         at net.fabricmc.loader.impl.launch.knot.KnotClient.main(KnotClient.java:23) ~[fabric-loader-0.14.18.jar:?]
         at org.prismlauncher.launcher.impl.StandardLauncher.launch(StandardLauncher.java:88) ~[NewLaunch.jar:?]
         at net.prismlauncher.EntryPoint.listen(EntryPoint.java:126) ~[NewLaunch.jar:?]
         at net.prismlauncher.EntryPoint.main(EntryPoint.java:71) ~[NewLaunch.jar:?]
Caused by: java.lang.Throwable: Manually triggered debug crash
         at net.minecraft.client.KeyboardHandler.tick(KeyboardHandler.java:506) ~[client-intermediary.jar:?]
         ... 10 more

Разница заметна сразу. class_310 превращается в MinecraftClient или Minecraft, а method_1574 получает имя tick. Такой отчет проще читать человеку, который не держит в голове таблицы соответствий Minecraft mappings.

Поддерживаемые mappings

StackDeobfuscator может работать с несколькими наборами mappings. Выбор зависит от того, какие названия удобнее использовать в конкретном проекте.

Набор mappings	Совместимые версии Minecraft	Размер загрузки	Размер кэша
Yarn	18w49a, снапшот Minecraft 1.14, и новее	1.4 MiB	1.4 MiB
Quilt	Minecraft 1.18.2 и новее	1.4 MiB плюс 1.1 MiB для версий ниже 1.19.2	1.4 MiB плюс 1.1 MiB для версий ниже 1.19.2
Mojang	Minecraft 1.14.4, 19w36a, снапшот 1.15, и новее	9.0 MiB без сжатия плюс 559.1 KiB	1.3 MiB плюс 558.6 KiB

Размеры приведены по состоянию на 12 мая 2024 года, когда актуальной версией была Minecraft 1.20.6. Mojang mappings занимают больше места, потому что исходные данные не сжимаются так же, как другие наборы.

Yarn и Quilt проверяют наличие обновлений версии раз в 48 часов. Для каждой версии Minecraft mappings скачиваются и разбираются один раз, после чего используются из локального кэша. Повторно загружать одни и те же данные при каждом запуске не требуется.

Где StackDeobfuscator особенно полезен

В одиночной игре обычному игроку этот мод почти не нужен, если только он не помогает тестировать собственную сборку. Зато при разработке Fabric-модов польза заметна сразу: crash report становится пригодным для чтения, а поиск конфликтующего мода занимает меньше времени.

На сервере StackDeobfuscator помогает администраторам и разработчикам разбирать ошибки в консоли. Если сервер падает во время загрузки мира, обработки тика или выполнения конкретного действия игрока, читаемые названия методов дают гораздо больше зацепок, чем набор числовых идентификаторов.

Особенно хорошо мод подходит для:

• тестовых серверов Minecraft;
• крупных сборок модов на Fabric;
• проверки новых версий модов;
• анализа клиентских и серверных crash report;
• подготовки понятных отчетов об ошибках;
• разработки модов без постоянного запуска полноценной среды разработки.

Важно понимать ограничение: StackDeobfuscator не исправляет саму ошибку и не определяет виноватый мод автоматически. Он делает stack trace понятнее. Причину сбоя все равно нужно искать по контексту, версии Minecraft, установленным модам и строкам вокруг исключения.

Совместимость и версии

StackDeobfuscator рассчитан на Fabric и поддерживает версии Minecraft от ранних снапшотов 1.14 до линейки 1.21.x. Проект распространяется именно как Fabric-мод, поэтому для его работы нужен Fabric Loader. Поддержка Forge или NeoForge в описании проекта не заявлена.

Есть важный нюанс по новым версиям. Для Minecraft новее 1.21.11 мод считается устаревшим, потому что в этих версиях обфускация больше не требует такого инструмента. На старых версиях он по-прежнему поддерживается и сохраняет смысл, особенно в разработке и тестировании модов.

Последний релиз StackDeobfuscator - версия 1.4.3. В ней добавлены данные версий для веб-просмотрщика mappings и обновлена библиотека, чтобы снизить вероятность конфликтов с другими модами.

Что изменится после установки

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

• сообщения об ошибках становятся читаемее;
• названия классов и методов отображаются в выбранной системе mappings;
• crash report проще передавать разработчику для анализа;
• диагностика проблем в сборке модов становится быстрее;
• mappings загружаются в фоне и сохраняются для повторного использования.

Поэтому StackDeobfuscator не стоит воспринимать как мод для улучшения FPS или добавления контента. Это небольшая утилита для диагностики, которая раскрывает техническую часть Minecraft там, где ванильный отчет обычно выглядит слишком запутанно.

Практические нюансы

Если вы устанавливаете StackDeobfuscator ради конкретного crash report, сначала проверьте версию Minecraft и загрузчик. Набор mappings должен соответствовать версии игры, иначе часть названий может остаться без расшифровки или отображаться не так, как ожидается.

Для разработчиков Fabric-модов Yarn часто удобнее благодаря привычным именам из экосистемы Fabric. Quilt mappings подходят для проектов, ориентированных на Quilt, а Mojang mappings могут быть полезнее тем, кто работает с официальной системой именования Minecraft.

На производительность во время игры мод не должен заметно влиять: основная работа связана с обработкой сообщений об ошибках и загрузкой mappings. Первая загрузка данных может занять больше времени, особенно при выборе Mojang mappings, но после кэширования повторная обработка выполняется без повторного скачивания полного набора.

StackDeobfuscator также известен отдельным веб-инструментом для преобразования stack trace. Он полезен, когда нужно быстро разобрать уже существующий отчет без установки дополнительного мода в игру.

Итог

StackDeobfuscator - специализированный Fabric-мод для Minecraft, который переводит обфусцированные stack trace на язык, понятный разработчикам и администраторам. Он поддерживает Yarn, Quilt и Mojang mappings, работает с клиентскими и серверными ошибками, а данные загружает асинхронно и хранит в кэше.

Если вы регулярно собираете моды, тестируете Fabric-проекты или разбираете падения Minecraft на сервере, такая утилита заметно упрощает диагностику. Для новых версий после 1.21.11 она уже не требуется, но на совместимых старых версиях остается удобным способом быстро понять, где именно возникла проблема.