Вирішення проблем із встановленням та запуском

Якщо у вас виникають проблеми під час встановлення Minecraft, завантажувачів модів (Forge/Fabric/NeoForge/Quilt), модів, модпаків чи шейдерів, або якщо гра не запускається, цей посібник допоможе вам крок за кроком знайти та усунути несправність.

---

🌐 1. Помилка або зависання завантаження (Проблеми з мережею)

Симптоми

• Завантаження Minecraft, ресурсів, бібліотек чи Forge/Fabric зупиняється на позначці 0%.
• Лаунчер видає помилки тайм-ауту або з'єднання (CONNECTION_TIMED_OUT, NAME_NOT_RESOLVED, HTTP_STATUS 504).

Рішення

Використовуйте дзеркало завантаження

Якщо офіційні сервери Mojang або Forge працюють повільно чи заблоковані вашим інтернет-провайдером, ви можете перемкнутися на альтернативне дзеркало:

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

Налаштування проксі

Якщо у вашому регіоні обмежено доступ до деяких ресурсів, ви можете налаштувати проксі прямо в лаунчері:

1. У розділі Налаштування -> Налаштування мережі знайдіть параметри проксі.
2. Вкажіть адресу вашого SOCKS5 або HTTP проксі-сервера.
3. Перевірте з'єднання.

---

📦 2. Не завантажується мод або модпак (Обмеження CurseForge API)

Симптоми

• Під час завантаження модпаку або окремого моду з CurseForge деякі моди не завантажуються і біля них з'являється попереджувальний знак.
• Повідомлення попереджає про "Обмеження завантаження для сторонніх лаунчерів".

Причина

Деякі автори модів на CurseForge вимикають можливість завантаження через API для сторонніх лаунчерів, щоб змусити гравців заходити на їхні офіційні веб-сторінки.

Рішення

XMCL вирішує це, дозволяючи вам завантажити відсутні файли вручну:

1. Подивіться деталі завантаження в диспетчері завдань лаунчера (у верхньому правому кутку).
2. Натисніть на посилання поруч із модом, завантаження якого завершилося помилкою, щоб відкрити його сторінку в браузері.
3. Завантажте файл .jar вручну через браузер.
4. Перетягніть (Drag-and-Drop) завантажений файл .jar безпосередньо у вікно лаунчера (або покладіть його в папку mods вашої збірки).
5. XMCL автоматично розпізнає його та завершить встановлення збірки.

---

🔍 3. Мод є на сайті CurseForge, але відсутній у пошуку лаунчера

Симптоми

• Ви шукаєте мод у лаунчері, але бачите повідомлення «Нічого не знайдено», хоча цей мод точно є на офіційному сайті CurseForge.

Причина

Платформа CurseForge дозволяє авторам модів вимикати доступ сторонніх додатків (API) до їхніх робіт. Якщо цей доступ вимкнено, API CurseForge (яке XMCL використовує для пошуку) не повертає цей мод у результатах пошуку лаунчера.

Рішення

1. Відкрийте браузер і перейдіть на сторінку моду на CurseForge.
2. Натисніть кнопку Download, щоб завантажити файл .jar на свій комп'ютер.
3. Відкрийте XMCL та виберіть потрібний профіль гри (інстанс).
4. Перетягніть (Drag-and-drop) завантажений файл .jar прямо у вікно лаунчера. XMCL автоматично встановить його в папку mods вибраного профілю.

---

📦 4. Імпортовані збірки «зникають» або здаються порожніми

Симптоми

• Ви перетягнули файл збірки .zip або .mrpack в лаунчер, але не можете знайти її в поточному профілі гри, або список модів порожній.

Причина

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

Рішення

1. Перемкніть профіль (інстанс): Натисніть на бічну панель або перемикач профілів, щоб переглянути всі доступні інстанси. Знайдіть там новий профіль із назвою вашої збірки та виберіть його.
2. Перевірте Диспетчер завдань: Натисніть на іконку завдань (у верхньому правому кутку лаунчера), щоб перевірити, чи не триває завантаження файлів збірки. Зачекайте завершення завантаження перед запуском гри.

---

🔄 5. Нескінченне завантаження через помилку контрольної суми (Checksum Mismatch)

Симптоми

• Лаунчер постійно завантажує один і той самий файл бібліотеки або ресурсу, стверджуючи, що він пошкоджений.
• Гра не запускається, оскільки перевірка файлів завершується помилкою раз за разом.

Причина

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

Рішення

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. Перейдіть до папки даних лаунчера на вашому комп'ютері:
   • Windows: %appdata%\xmcl
   • macOS: ~/Library/Application Support/xmcl
   • Linux: ~/.config/xmcl
2. Відкрийте папку logs та знайдіть найсвіжіший файл main.log.

---

📋 8. Створення діагностичного звіту (Рекомендовано в першу чергу)

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

Як створити звіт:

1. Натисніть кнопку Допомога (Help) або Зворотний зв'язок у верхній панелі лаунчера.

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, проблем із продуктивністю або Java:

• Відкрийте картку профілю гри (інстансу) в лаунчері.
• Натисніть іконку Папки у верхньому правому кутку робочої панелі інстансу, щоб відкрити його директорію.
• Перейдіть у папку logs та відкрийте файл latest.log.
• Якщо гра раптово закрилася (крашнулась), перейдіть у папку crash-reports та знайдіть найновіший текстовий файл (назва формату crash-YYYY-MM-DD_HH.MM.SS-client.txt).

---

🛠 Як аналізувати логи та вирішувати поширені проблеми

Відкрийте файл логів у будь-кому текстовому редакторі (наприклад, Блокноті) та скористайтеся пошуком (Ctrl + F), щоб знайти ключові помилки:

🔴 Випадок 1: Нестача оперативної пам'яті (Out of Memory)

• Що шукати: java.lang.OutOfMemoryError: Java heap space або код виходу Exit code: -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.
• Причина: Ви використовуєте версію Java, яка не підходить для запуску вибраної версії Minecraft чи збірки (наприклад, Java 8 для Minecraft 1.20).
• Як виправити: У налаштуваннях профілю перейдіть до розділу Java та натисніть кнопку Встановити 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-сервер XMCL

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

• Ознайомтеся з ілюстрацією нашого каналу відгуків:

  

2. Запитуйте на Reddit

• Ви також можете опублікувати питання в нашій спільноті на Reddit:
• Посилання: Спільнота r/XMCL на Reddit

3. Створіть Issue на GitHub

• Якщо ви вважаєте, що знайшли помилку в самому лаунчері, ви можете створити звіт про баг.
• Створити тут: XMCL GitHub Issues
• Скопіюйте опис проблеми та додайте вміст діагностичного звіту або файлу логу, щоб розробники могли розібратися у збої.