# 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](JA3_MAC_WITHOUT_GALAXY.md) (установка offline), [TROUBLESHOOTING.md](TROUBLESHOOTING.md), [GOG_GALAXY_7H_RCA.md](GOG_GALAXY_7H_RCA.md).

---

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

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

```bash
# 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)

```bash
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](https://github.com/Gcenx/macOS_Wine_builds/issues/97)). В этом случае `d3d12.dll` (94 KB) идёт через **wined3d → Vulkan**, а на Mac нет Vulkan physical device:

```text
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 делится пополам) | ✅ профиль **`legacy`**: `RetinaMode=n`, без LogPixels — **подтверждено 2026-05-29** |

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

| Строка | Значение |
|--------|----------|
| `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 | `fix-ja3-crossover-mouse.sh` → профиль **legacy** |
| Курсор **не ниже середины экрана** | `RetinaMode=y` + `LogPixels=192` / двойной DPI | **legacy** (не retina); перезапуск JA3 |

Логи 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** (минимум):

```ini
"WINED3DMETAL" = "1"
"WINEDXVK" = "0"
```

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

**Проверка:**

```bash
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](https://www.paulthetall.com/jagged-aliance-3-for-mac/) + GOG offline | Тот же GPTK/D3DMetal; GUI, «просто работает» на M-series |
| CrossOver GUI | Bottle JA3-GOG → Install → Run exe; D3DMetal в Advanced Settings |
| Whisky + GPTK drag DMG | [Whisky#124](https://github.com/Whisky-App/Whisky/issues/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 |

```bash
# Канон (после смены профиля — перезапуск 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
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](https://github.com/Gcenx/macOS_Wine_builds/issues/97)
- [CrossOver — D3DMetal advanced settings](https://support.codeweavers.com/miscellanous/advanced-settings-in-crossover-mac-26)
- [Whisky — GPU / GPTK tracking](https://github.com/Whisky-App/Whisky/issues/124)
- [Proton JA3 — graphics / LocalStorage](https://github.com/ValveSoftware/Proton/issues/7039) (Linux; отражения Off/Low — аналог для Wine при других GPU)