local_machine/docs/games/JA3_RUNBOOK.md

Jagged Alliance 3 (GOG) — runbook Mac / Apple Silicon

Машина: M1 Pro, macOS Sonoma+, bottle Whisky GOG-Install (9ee55e7c-a58e-411e-a93f-30530d4f1073).
Проверено: 2026-05-28 (установка) · 2026-05-29 (запуск через CrossOver).

Связанные документы: JA3_MAC_WITHOUT_GALAXY.md (установка offline), TROUBLESHOOTING.md, GOG_GALAXY_7H_RCA.md.

---

1. Быстрый путь (канон)

Установка (один раз, Whisky)

# Offline backup (5 файлов) в ~/Games/
bash ~/code/local_machine/scripts/games/gog/install-ja3-innoextract.sh
bash ~/code/local_machine/scripts/games/gog/finish-ja3-layout.sh

Запуск (каждый раз, CrossOver + D3DMetal)

brew install --cask crossover          # один раз
bash ~/code/local_machine/scripts/games/gog/setup-ja3-crossover.sh   # один раз
bash ~/code/local_machine/scripts/games/gog/run-ja3-crossover.sh

• Cmd+Tab → окно JA3.exe
• В настройках графики: отключить heat haze
• Swap: «залипший» swap после Wine (2–4 GB без процессов) не блокирует запуск — только предупреждение. Стоп: swap ≥ 4096 MB без Wine, или swap ≥ 1200 MB пока Wine/JA3 ещё работают → reset-ja3-crossover.sh / reboot. Обход: JA3_IGNORE_SWAP=1

Два «контура»

Контур	Роль	Инструмент
GOG-Install (Whisky)	innoextract, файлы игры, CommonLua, реестр GOG	install-ja3-innoextract.sh, finish-ja3-layout.sh
JA3-GOG (CrossOver)	запуск D3D12 через D3DMetal	setup-ja3-crossover.sh, run-ja3-crossover.sh

Whisky run-ja3.sh не запускает JA3 с рабочей графикой — только CrossOver (или Porting Kit GUI).

---

2. Почему CrossOver, а не Whisky

JA3 на Windows использует DirectX 12. На Apple Silicon единственный рабочий путь — Apple D3DMetal (Game Porting Toolkit), встроенный в CrossOver 23+ с флагом WINED3DMETAL=1.

Whisky использует Gcenx Wine — maintainer явно пишет, что сборки не содержат D3DMetal hooks (Gcenx/macOS_Wine_builds#97). В этом случае d3d12.dll (94 KB) идёт через wined3d → Vulkan, а на Mac нет Vulkan physical device:

fixme:d3d12:d3d12_get_vk_physical_device Could not find Vulkan physical device for DXGI adapter.

→ UI: «Failed to initialize graphics subsystem»
→ лог JA3: Failed creating render device

Копирование D3DMetal.framework + libd3dshared.dylib + моста d3d12.so не достаточно, если PE d3d12.dll / ntdll от Gcenx — unix-вызовы D3DMetal не подключены.

---

3. RCA: злоключения 2026-05-28 — 2026-05-29

Хронология попыток на этой машине (чат + логи JA3.exe-*.log, Wine debug).

Фаза A — установка и ложные следы (28.05)

#	Симптом / действие	Реальная причина	Итог
A1	GOG web-stub, пустые кнопки	Нет gdiplus (winetricks)	✅ install-gdiplus.sh + corefonts
A2	Galaxy CEF, окна нет	HWND/CEF в Wine, swap	Galaxy не нужен для JA3 offline
A3	Лог Steam initialized … Beta branch GOG	GOG API-шим (steam_api64.dll), не Steam.app	❌ не причина краша
A4	CreateSubsystem failed MatchmakingServers/Music	GOG wrapper без Galaxy service	❌ шум, не графика
A5	Game name not defined	innoextract не выполнил Inno-постскрипты	⚠️ косметика; фикс: register-ja3-registry.sh
A6	Swap ~3 GB, скрипт блокирует запуск	«Залипший» swap после Wine; macOS не отдаёт без reboot	✅ gog_swap_guard_ja3_launch: warn до 4 GB без процессов; reboot если Mac тормозит

Фаза B — «графика» в Whisky (28–29.05)

#	Попытка	Лог / ошибка	Почему не работает
B1	DXVK + -graphicsapi d3d11	Failed creating render device	DXVK = D3D10/11, не D3D12
B2	DXMT v0.80	dxgi.dll c000007b	Несовместимость с Gcenx Wine 11 + overrides
B3	upgrade-whisky-wine-gcenx.sh (11.9) + GPTK bridge	d3d12_get_vk_physical_device	Gcenx d3d12 = Vulkan, не Metal
B4	GPTK PE d3d12.dll/dxgi.dll (114/86 KB) в system32	Всё ещё Vulkan path или dxgi not found	PE GPTK 7.7 ≠ ntdll Gcenx 11
B5	GPTK PE в wine/lib/x86_64-windows	Library dxgi.dll not found (c0000135)	__wine_unix_call не реализован в Gcenx ntdll
B6	Замена ntdll.so на GPTK	virtual_alloc_first_teb / wine не стартует	Нельзя мешать ntdll разных Wine
B7	ditto всего GPTK lib/ в Whisky	Wine 7.7 GPTK поверх bottle	Перезаписал wine64 → comctl32 и др.
B8	prepare-ja3-d3dmetal.sh (убрать d3d12 из system32)	Всё равно render device fail	Builtin Gcenx d3d12 без Metal
B9	forceD3D11: true в Metadata.plist	Противоречие с D3D12 backend	Исправлено на false — без эффекта на Gcenx
B10	GPTK Wine 7.7, отдельный prefix	comctl32.dll failed to initialize (c0000005)	GPTK Wine 7.7 сломан на этой macOS
B11	fixmywhisky.sh (ditto GPTK lib)	Как B7	Только D3DMetal.framework + bridge без подмены всего Wine

Фаза C — CrossOver (29.05, успех)

#	Шаг	Результат
C1	brew install --cask crossover	CrossOver 26.1, встроенный apple_gptk
C2	Bottle JA3-GOG, template win10_64 (не win32 Wow64!)	kernel32 c000007b на 32-bit bottle
C3	WINED3DMETAL=1, WINEDXVK=0 в cxbottle.conf	D3D12 → Metal
C4	Symlink игры из Whisky bottle	CommonLua/Core/autorun.lua: File Not Found — Wine не читает symlink вне prefix
C5	cp -cR (APFS clonefile) игры в CrossOver bottle	Файлы видны Wine; ~0 доп. места на APFS
C6	start /d "C:\GOG Games\Jagged Alliance 3" JA3.exe -unpacked	CWD с CommonLua/; не --cx-app без /d
C7	Запуск	JA3.exe стабильно работает, нет Failed creating render device
C8	Курсор: смещение клика → RetinaMode=y + LogPixels=192	Курсор не опускается ниже середины экрана (Y делится пополам)

Сигнатуры в логах (диагностика)

Строка	Значение
Failed creating render device	D3D12 не дошёл до GPU — Whisky/Gcenx, не CrossOver
d3d12_get_vk_physical_device Could not find Vulkan	Gcenx wined3d path — нужен CrossOver D3DMetal
Failed to initialize graphics subsystem (UI)	То же, пользовательский текст JA3
Error opening 'CommonLua/Core/autorun.lua'	Нет CWD (start /d) или symlink вместо клона в bottle
comctl32.dll failed to initialize	GPTK Wine 7.7 — не использовать
__wine_unix_call / aborting	GPTK PE на чужом Wine
dxgi.dll c000007b	DXMT + неправильные overrides
Language: English без Failed creating	Графика OK; смотреть CommonLua / crash дальше
Курсор виден, клик смещён по Y	HiDPI без согласованного масштаба Wine
Курсор не ниже середины экрана	RetinaMode=y + LogPixels=192 / двойной DPI

Логи JA3:
…/AppData/Roaming/Jagged Alliance 3/logs/JA3.exe-*.log
Whisky: …/Containers/com.franke.Whisky/Bottles/9ee55e7c-…/
CrossOver: ~/Library/Application Support/CrossOver/Bottles/JA3-GOG/

---

4. Антипаттерны (полный список)

Установка

❌ Не делать	✅ Вместо
GOG web-stub GOG_Galaxy_Jagged_Alliance_3.exe	Offline backup 5 частей в ~/Games/
install-ja3-multipart.sh (Wine Inno)	install-ja3-innoextract.sh
Распаковка в scripts/games/cache/	Сразу в drive_c/GOG Games/…
Bottle HoMM-OldenEra (Steam)	Bottle GOG-Install
Удалять steam_api64.dll в папке игры	Это GOG-шим, оставить
Steam client в GOG-bottle	purge-steam-from-bottle.sh

Графика / Wine

❌ Не делать	✅ Вместо
Whisky run-ja3.sh для игры	run-ja3-crossover.sh
upgrade-whisky-wine-gcenx.sh «для D3DMetal»	Gcenx не поддерживает D3DMetal hooks
ditto всего GPTK lib/ в Whisky Libraries	Только D3DMetal.framework + libd3dshared + .so bridge (см. install-gptk-whisky.sh)
GPTK PE d3d12/dxgi в system32 Whisky	CrossOver со встроенным apple_gptk
Замена ntdll.so GPTK в Gcenx Wine	Ломает preloader
DXVK / DXMT для JA3 как «замена D3D12»	Не подтверждено; JA3 = D3D12
dxgi,d3d11=n,b с DXMT	Ломает цепочку → c000007b
Whisky Run JA3.exe без CWD	start /d или run-ja3.cmd (Whisky) / CrossOver start /d
Symlink игры из Whisky в CrossOver bottle	cp -cR (APFS clone)
CrossOver bottle win32 / Wow64	win10_64
--cx-app JA3.exe без start /d	start /d "…Jagged Alliance 3" JA3.exe -unpacked
forceD3D11: true + backend d3dMetal	forceD3D11: false (Metadata Whisky — не решает Gcenx)

Окружение

❌ Не делать	✅ Вместо
Считать «залипший» swap 2–4 GB блокером JA3	Запуск разрешён (warn); reboot — если Mac тормозит
Запуск JA3 при swap ≥ 1200 MB + Wine/JA3 ещё работают	reset-ja3-crossover.sh → reboot
Запуск JA3 при swap ≥ 4096 MB без Wine	Reboot Mac или JA3_IGNORE_SWAP=1
Жёсткий лимит 800 MB для run-ja3-crossover.sh	Устарело; см. gog_swap_guard_ja3_launch в config.sh
Путать лог Galaxy с JA3	JA3 offline без Galaxy UI
Чинить «graphics» через Galaxy service	MatchmakingServers/Music — шум GOG API

Мышь (CrossOver / Retina)

❌ Не делать	✅ Вместо
RetinaMode=y + LogPixels=192 + Win8DpiScaling=1 «по умолчанию»	fix-ja3-crossover-mouse.sh — профиль legacy (RetinaMode=n)
CrossOver GUI High Resolution Mode без проверки	Если клип Y на середине → legacy
Менять реестр мыши без перезапуска JA3	reset-ja3-crossover.sh → run-ja3-crossover.sh
Профиль retina при клипе на середине экрана	legacy; при смещении клика — retina-lite
Ожидать фикс мыши «на лету»	Workaround: верхний левый угол окна = угол экрана

---

5. Скрипты

Скрипт	Назначение	Статус
install-ja3-innoextract.sh	Multipart offline → bottle	✅ канон установки
finish-ja3-layout.sh	CommonLua, реестр, upscale DLL	✅ после innoextract
setup-ja3-crossover.sh	Bottle JA3-GOG, clone игры, D3DMetal	✅ один раз
run-ja3-crossover.sh	Запуск игры	✅ канон
reset-ja3-crossover.sh	Stop JA3 / Wine перед перезапуском	✅
fix-ja3-crossover-mouse.sh	Профили мыши (legacy / retina-lite / retina)	✅ default legacy
run-ja3.sh	Whisky (эксперимент; графика fail)	⚠️ только с предупреждением
prepare-ja3-d3dmetal.sh	Whisky D3DMetal prep	⚠️ не решает Gcenx d3d12
upgrade-whisky-wine-gcenx.sh	Wine 11.9	❌ для JA3 не использовать
run-ja3-gptk-wine.sh	GPTK Wine 7.7 prefix	❌ comctl32 на этой Mac
install-ja3-dxmt.sh	DXMT fallback d3d11	❌ c000007b
emergency-stop.sh	Kill Wine/GOG перед запуском	✅

---

6. CrossOver bottle (детали)

Путь: ~/Library/Application Support/CrossOver/Bottles/JA3-GOG/

cxbottle.conf (минимум):

"WINED3DMETAL" = "1"
"WINEDXVK" = "0"

Игра: drive_c/GOG Games/Jagged Alliance 3/ — APFS-клон из Whisky GOG-Install (не symlink).

Проверка:

pgrep -fl 'JA3\.exe'
grep -E 'Failed creating|autorun|CRASH' \
  "$HOME/Library/Application Support/CrossOver/Bottles/JA3-GOG/drive_c/users/"*/AppData/Roaming/Jagged\ Alliance\ 3/logs/*.log | tail

---

7. Альтернативы

Вариант	Комментарий
Porting Kit + GOG offline	Тот же GPTK/D3DMetal; GUI, «просто работает» на M-series
CrossOver GUI	Bottle JA3-GOG → Install → Run exe; D3DMetal в Advanced Settings
Whisky + GPTK drag DMG	Whisky#124 — для DX12 на Gcenx всё равно нет hooks

---

9. Курсор: HiDPI / Retina (CrossOver)

Проверено 2026-05-29 на M1 Pro + CrossOver 26.1, bottle JA3-GOG.

Симптомы

Симптом	Типичная причина
Клик «выше/ниже» UI, курсор виден	Wine отдаёт logical pixels, игра рисует в другом масштабе
Курсор не опускается ниже середины экрана	RetinaMode=y + LogPixels=192 — координата Y делится пополам

Профили (fix-ja3-crossover-mouse.sh)

Профиль	Реестр	Когда
legacy (default)	RetinaMode=n, LogPixels/Win8Dpi удалены	Канон — полный ход курсора по Y; возможен небольшой сдвиг клика
retina-lite	RetinaMode=y, без LogPixels	Если legacy смещает клик, но нет клипа на середине
retina	RetinaMode=y, LogPixels=192, Win8DpiScaling=1	❌ часто клип Y на 50% — не использовать как default

# Канон (после смены профиля — перезапуск JA3)
bash ~/code/local_machine/scripts/games/gog/fix-ja3-crossover-mouse.sh
bash ~/code/local_machine/scripts/games/gog/reset-ja3-crossover.sh
bash ~/code/local_machine/scripts/games/gog/run-ja3-crossover.sh

# Если legacy смещает клик
JA3_MOUSE_PROFILE=retina-lite bash ~/code/local_machine/scripts/games/gog/fix-ja3-crossover-mouse.sh
bash ~/code/local_machine/scripts/games/gog/reset-ja3-crossover.sh
bash ~/code/local_machine/scripts/games/gog/run-ja3-crossover.sh

Без перезапуска (workaround): перетащите окно JA3 так, чтобы верхний левый угол окна совпал с верхним левым углом экрана.

CrossOver GUI: Bottle JA3-GOG → High Resolution Mode — при клипе на середине выключить (эквивалент legacy).

---

10. Быстрые команды (терминал)

Действие	Команда
Запуск	bash ~/code/local_machine/scripts/games/gog/run-ja3-crossover.sh
Стоп / reset Wine	bash ~/code/local_machine/scripts/games/gog/reset-ja3-crossover.sh
Стоп всё GOG/Wine	bash ~/code/local_machine/scripts/games/gog/emergency-stop.sh
Первичная настройка bottle	bash ~/code/local_machine/scripts/games/gog/setup-ja3-crossover.sh
Фикс мыши	bash ~/code/local_machine/scripts/games/gog/fix-ja3-crossover-mouse.sh
Swap «залип» 2–4 GB, Wine нет	просто run-ja3-crossover.sh (warn)
Swap + Wine/JA3 живы ≥ 1200 MB	reset-ja3-crossover.sh → reboot
Swap ≥ 4096 MB без Wine	reboot Mac
Обход swap	JA3_IGNORE_SWAP=1 bash …/run-ja3-crossover.sh
Профиль мыши	JA3_MOUSE_PROFILE=legacy|retina-lite|retina + fix + reset + run

Полный цикл перезапуска:

bash ~/code/local_machine/scripts/games/gog/reset-ja3-crossover.sh
bash ~/code/local_machine/scripts/games/gog/run-ja3-crossover.sh

---

8. Ссылки

• Gcenx — нет D3DMetal в packages
• CrossOver — D3DMetal advanced settings
• Whisky — GPU / GPTK tracking
• Proton JA3 — graphics / LocalStorage (Linux; отражения Off/Low — аналог для Wine при других GPU)