Вырашэнне праблем з усталёўкай і запускам

Калі вы сутыкнуліся з цяжкасцямі пры ўсталёўцы Minecraft, загрузчыкаў модаў (Forge/Fabric/NeoForge/Quilt), модаў, модпакаў, шэйдараў або падчас запуску гульні, гэтае кіраўніцтва дапаможа вам знайсці і вырашыць праблему крок за крокам.

---

🌐 1. Спампоўванне не атрымоўваецца або спыняецца (Праблемы з сеткай)

Симптом

• Загрузка файлаў гульні, рэсурсаў або загрузчыкаў спыняецца на 0%.
• Лаўнчар паказвае памылкі злучэння (CONNECTION_TIMED_OUT, NAME_NOT_RESOLVED, HTTP_STATUS 504).

Вырашэнне

Выкарыстоўвайце люстэрка (Mirror)

Калі афіцыйныя серверы Mojang або Forge перагружаны ці недаступныя ў вашым рэгіёне, вы можаце пераключыцца на бачнае люстэрка:

1. Перайдзіце ў Налады (іконка шасцярэнькі ў левай панэлі).
2. Пракруціце ўніз да раздзела Налады сеткі.
3. Знайдзіце пункт Крыніца загрузкі / Люстэрка (Download Source / Mirror).
4. Змяніце параметр з Па змаўчанні на BMCLAPI або MCBBS (гэта надзейныя люстэркі, якія цалкам дублююць афіцыйныя файлы).

Налады проксі

Калі доступ да пэўных сервераў абмежаваны ў вашай сетцы, вы можаце наладзіць проксі непасрэдна ў лаўнчары:

1. Перайдзіце ў Налады -> Налады сеткі і знайдзіце раздзел проксі.
2. Увядзіце адрас вашага SOCKS5 ці HTTP проксі-сервера.
3. Праверце злучэнне.

---

📦 2. Памылка спампоўвання мода / модпака (Абмежаванне CurseForge API)

Симптом

• Пры спампоўванні модпака ці мода з CurseForge загрузка перарываецца з папярэджаннем аб памылцы.
• З'яўляецца паведамленне аб абмежаванні іншых лаўнчараў ("Restricted third-party downloads").

Прычына

Некаторыя аўтары модаў на CurseForge адключаюць магчымасць спампоўвання праз API для іншых лаўнчараў, каб прымусіць гульцоў наведваць іх афіцыйны сайт для прагляду рэкламы.

Вырашэнне

XMCL дазваляе спампаваць такія файлы ўручную і аўтаматычна працягнуць усталёўку:

1. Адкрыйце падрабязнасці працы ў мэнэджары задач (уверсе справа).
2. Націсніце на спасылку побач з модам, які не ўдалося спампаваць, каб адкрыць яго старонку ў браўзеры.
3. Спампуйце .jar файл уручную праз браўзер.
4. Перацягніце спампаваны файл .jar прама ў акно лаўнчара (або пакладзіце яго ў папку mods гэтага профілю).
5. XMCL аўтаматычна выявіць файл і завершыць усталёўку.

---

🔍 3. Мод ёсць на сайце CurseForge, але яго няма ў пошуку лаўнчара

Симптом

• Вы шукаеце мод у пошуку лаўнчара, але ён піша "Вынікі не знойдзены", хоць на сайце CurseForge мод ёсць.

Прычына

Платформа CurseForge дазваляе аўтарам модаў адключаць доступ іншых праграм праз API. Калі аўтар робіць гэта, API CurseForge (якое XMCL выкарыстоўвае для пошуку) больш не вяртае гэты мод у пошукавых запытах.

Вырашэнне

1. Адкрыйце браўзер і знайдзіце старонку мода на сайце CurseForge.
2. Націсніце Download, каб захаваць .jar файл на кампутар.
3. Адкрыйце XMCL і абярыце патрэбны профіль гульні.
4. Перацягніце спампаваны .jar файл прама ў акно лаўнчара. XMCL аўтаматычна ўсталюе яго ў папку mods гэтага профілю.

---

📦 4. Імпартаваныя модпакі "зыходзяць" ці выглядаюць пустымі

Симптом

• Вы перацягнулі файл модпака .zip ці .mrpack у лаўнчар, але не бачыце яго ў бягучым профілі, або спіс модаў выглядае пустым.

Прычына

1. Стварэнне новага профілю: XMCL не змешвае модпакі з вашым актыўным профілем. Замест гэтага ён стварае абсалютна новы профіль (інстанс) спецыяльна для гэтага модпака.
2. Фон спампоўвання: Файлы модпакаў у мэтах эканоміі месца не ўтрымліваюць самі .jar файлы модаў, а толькі іх спіс. Пасля імпарту XMCL запускае фонавую задачу для загрузкі ўсіх модаў. Пакуль яна не завершыцца, спіс модаў можа быць пустым.

Вырашэнне

1. Змяніце профіль: Націсніце на меню выбару профілю ў левай частцы лаўнчара і абярыце новы профіль, названы ў гонар імпартаванага модпака.
2. Праверце менеджэр задач: Націсніце на іконку загрузкі ўверсе справа лаўнчара, каб пераканацца, што працэс загрузкі файлаў завершаны, перш чым запускаць гульню.

---

🔄 5. Бясконцая загрузка пашкоджаных файлаў (Памылка кантрольнай сумы)

Симптом

• Лаўнчар пастаянна спампоўвае адзін і той жа файл бібліятэкі ці рэсурсу, пазначаючы яго як пашкоджаны.
• Гульня не запускаецца з-за пастаянных памылак валідацыі файлаў.

Прычына

Спампоўванне файла было перапынена, і часткова загружаны пашкоджаны файл заблакаваўся ў лакальным кэшы, не даючы лаўнчару замяніць яго правільным.

Вырашэнне

1. Знайдзіце шлях да пашкоджанага файла ў паведамленні аб памылцы ці файле лога (напрыклад, libraries/org/lwjgl/...).
2. Адкрыйце папку даных вашага профілю (націсніце на іконку папкі ўверсе справа на галоўнай старонцы профілю).
3. Перайдзіце па паказаным шляху і выдаліце папку з пашкоджаным файлам.
4. Націсніце «Рамонт» (Repair) ці зноў запусціце гульню. Лаўнчар спампуе новую чыстую копію файла.

---

☕ 6. Гульня вылятае адразу пасля запуску (Няправільная версія Java)

Симптом

• Гульня пачынае запускацца, але адразу зачыняецца з кодам памылкі 1 ці -1.
• У файлах журналаў (логаў) прысутнічае памылка UnsupportedClassVersionError ці паведамленне "Java не знойдзена".

Прычына

Кожная версія Minecraft патрабуе сваю версію Java (JDK). Выкарыстанне няправільнай версіі прывядзе да вылету гульні.

Вырашэнне

XMCL мае аўтаматычны менеджэр Java, які самастойна загружае неабходныя версіі JDK.

Сумяшчальнасць Java

Пераканайцеся, што ваш профіль выкарыстоўвае правільную версію Java:

• Minecraft 1.12.2 і старэйшыя: Java 8
• Minecraft 1.16 - 1.17: Java 16 / 17
• Minecraft 1.18 - 1.20.4: Java 17
• Minecraft 1.20.5+: Java 21

Як выбраць версію Java ў XMCL:

1. Адкрыйце налады профілю (іконка шасцярэнькі побач з кнопкай "Гуляць").
2. Знайдзіце раздзел Java.
3. Націсніце на поле выбару. XMCL пакажа ўсе версіі Java, усталяваныя ў сістэме, і вылучыць сумяшчальныя зялёным колерам.
4. Калі патрэбнай версіі няма, націсніце Усталяваць Java, каб лаўнчар аўтаматычна спампаваў лепшую версію.

---

📑 7. Лаўнчар не адкрываецца або паказвае чорны экран

Симптом

• Пасля падвойнага кліку па іконцы лаўнчара нічога не адбываецца.
• Акно лаўнчара адкрываецца, але застаецца цалкам чорным.

Вырашэнне

Вы можаце праверыць файлы логаў, каб зразумець прычыну:

1. Перайдзіце ў папку даных XMCL у вашай сістэме:
   • Windows: %appdata%\xmcl
   • macOS: ~/Library/Application Support/xmcl
   • Linux: ~/.config/xmcl
2. Адкрыйце папку logs і знайдзіце самы свежы файл main.log.

---

📋 8. Стварыць дыягнастычную справаздачу (Рэкамендаваны першы крок)

Перш чым шукаць логі ўручную, мы настойліва рэкамендуем стварыць дыягнастычную справаздачу ў лаўнчары. Гэта збярэ ўсе журналы лаўнчара, гульні і сістэмную інфармацыю ў адзін файл, што дапаможа распрацоўшчыкам або супольнасці хутчэй знайсці прычыну памылкі.

Як стварыць справаздачу:

1. Націсніце меню Дапамога і водгукі (Help & Feedback) у верхняй панэлі лаўнчара.

2. Націсніце Стварыць справаздачу (Generate Report) для збору ўсіх логаў.

   

---

📑 9. Як аналізаваць логі (журналы) лаўнчара і гульні

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

🔍 Як знайсці файлы журналаў (логаў)

У залежнасці ад таго, адбылася памылка ў лаўнчары ці ў гульні, вам патрэбны розныя логі:

А. Логі лаўнчара (main.log)

Пры вылетах лаўнчара, памылках сеткі ці праблемах з аўтарызацыяй:

• Windows: Націсніце Win + R, увядзіце %appdata%\xmcl\logs і націсніце Enter.
• macOS: Перайдзіце ў ~/Library/Application Support/xmcl/logs.
• Linux: Перайдзіце ў ~/.config/xmcl/logs.
• Знайдзіце апошні файл з назвай main.log.

Б. Логі гульні (latest.log і справаздачы аб вылетах)

Пры вылетах Minecraft, памылках модаў або праблемах з прадукцыйнасцю:

• Адкрыйце старонку профілю ў лаўнчары.
• Націсніце на іконку Папкі ўверсе справа, каб адкрыць яе рабочую дырэкторыю.
• Перайдзіце ў папку logs і адкрыйце файл latest.log.
• Калі гульня вылецела і зачынілася, перайдзіце ў папку crash-reports і знайдзіце апошні .txt файл (фармат назвы crash-YYYY-MM-DD_HH.MM.SS-client.txt).

---

🛠 Аналіз логаў і выпраўленне частых памылак

Адкрыйце файл лога ў любым тэкставым рэдактары (напрыклад, у Блакноце) і выкарыстоўвайце пошук (Ctrl + F) для знаходжання наступных памылак:

🔴 Выпадак 1: Недахоп аператыўнай памяці (Out of Memory)

• Што шукаць: java.lang.OutOfMemoryError: Java heap space або код выхаду -805306369.
• Тлумачэнне: Вы выдзелілі занадта мала RAM для загрузкі ўсіх усталяваных модаў.
• Як выправіць:
  1. Адкрыйце налады профілю (шасцярэнька побач з кнопкай "Гуляць").
  2. Пракруціце да раздзела Java.
  3. Павялічце значэнні Мін. памяць і Макс. памяць (напрыклад, усталюйце максімальную памяць на 4096 ці 6144 МБ).

🔴 Выпадак 2: Канфлікт модаў ці адсутнасць залежнасцяў

• Што шукаць: Mixin transformation failed, DependencyResolutionException або радкі накшталт Requires mod 'fabric' (version X or later), but only version Y is installed.
• Тлумачэнне: Аднаму з вашых модаў патрабуецца іншы дапаможны мод, які адсутнічае, альбо два моды несумяшчальныя.
• Як выправіць: Уважліва прачытайце радок памылкі — там звычайна напісана назва патрэбнага мода. Спампуйце яго і пакладзіце ў папку mods альбо выдаліце канфліктуючы мод.

🔴 Выпадак 3: Несумяшчальнасць Java

• Што шукаць: java.lang.UnsupportedClassVersionError: ... has been compiled by a more recent version of the Java Runtime.
• Тлумачэнне: Вы запускаеце Minecraft або модпак з несумяшчальнай версіяй Java (напрыклад, Java 8 для Minecraft 1.20).
• Як выправіць: Адкрыйце налады профілю, перайдзіце ў раздзела Java, і націсніце Усталяваць Java, каб аўтаматычна спампаваць сумяшчальную версію.

🔴 Выпадак 4: Збой драйвера відэакарты (OpenGL)

• Што шукаць: GLFW error 65542: WGL: The driver does not seem to support OpenGL або Pixel format not accelerated.
• Тлумачэнне: Вашы драйверы відэакарты састарэлі, альбо гульня запускаецца на ўбудаванай графіцы працэсара замест дыскрэтнай відэакарты.
• Як выправіць: Абнавіце драйверы відэакарты з афіцыйнага сайта вытворцы (NVIDIA, AMD ці Intel). На ноўтбуках прымусова наладзьце запуск Java з выкарыстаннем высокапрадукцыйнай відэакарты ў наладах сістэмы.

---

❓ Што рабіць, калі вы не разумееце логі?

Калі вы праглядзелі логі і ўсё роўна не можаце зразумець прычыну збою — гэта не праблема! Супольнасць XMCL заўсёды гатова дапамагчы:

1. Далучайцеся да нашага афіцыйнага Discord-сервера

• Атрымайце хуткую дапамогу ад распрацоўшчыкаў і вопытных гульцоў.

• Запрашэнне: Афіцыйны Discord

• Як папрасіць дапамогі: Перайдзіце ў канал #feedback-and-idea і загрузіце туды вашу дыягнастычную справаздачу або тэкставы файл лога.

• Вось як выглядае наш канал водгукаў і дапамогі:

  

2. Запытайце на Reddit

• Вы можаце задаць пытанні на форуме супольнасці:
• Наведаць: Subreddit r/XMCL

3. Стварыце Issue на GitHub

• Калі вы сутыкнуліся з багам у самой праграме лаўнчара:
• Стварыць справаздачу: XMCL GitHub Issues
• Скапіруйце змесціва вашай дыягнастычнай справаздачы ў апісанне, каб распрацоўшчыкі змаглі выправіць памылку.