# 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-06-17 (CrossOver удалён; запуск только Whisky).

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

> **Примечание (2026-06):** CrossOver и связанные скрипты (`run-ja3-crossover.sh`, `JA3-GOG`, `JA3-WINE`, `sync-ja3-saves.sh`) **удалены** с машины. Запуск JA3 — только через Whisky GOG-Install.

---

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

### Запуск (каждый раз)

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

- **Cmd+Tab** → окно **`JA3.exe`**
- **Swap:** «залипший» swap после Wine **не блокирует** запуск — только предупреждение. Стоп: swap ≥ **4096 MB** без Wine, или swap ≥ **1200 MB** пока **Wine/JA3 ещё работают** → `reset-ja3-whisky.sh` / reboot. Обход: `JA3_IGNORE_SWAP=1`
- **Задержка cold start:** 15–60 с до появления окна — норма

---

## 2. Графика: Whisky vs D3D12

JA3 на Windows использует **DirectX 12**. На Apple Silicon рабочий путь раньше был **CrossOver + D3DMetal** — CrossOver снят.

**Сейчас:** `run-ja3.sh` запускает игру в **Whisky GOG-Install**:
- с **GPTK/D3DMetal** в bottle (если установлен Game Porting Toolkit) — D3D12;
- иначе **DXVK D3D11 fallback** (`-graphicsapi d3d11`).

При ошибке `Failed to initialize graphics subsystem` / `dxgi.dll not found`:
```bash
brew install --cask gcenx/wine/game-porting-toolkit
bash ~/code/local_machine/scripts/games/gog/install-gptk-whisky.sh
bash ~/code/local_machine/scripts/games/gog/configure-ja3-d3dmetal.sh
bash ~/code/local_machine/scripts/games/gog/run-ja3.sh
```

---

## 3. Пути на диске

| Что | Путь |
|-----|------|
| Игра (Whisky) | `…/Containers/com.franke.Whisky/Bottles/9ee55e7c-…/drive_c/GOG Games/Jagged Alliance 3/` |
| Сейвы | `…/drive_c/users/eternal/AppData/Roaming/Jagged Alliance 3/<account_id>/` |
| Логи JA3 | `…/AppData/Roaming/Jagged Alliance 3/logs/JA3.exe-*.log` |

---

## 4. Скрипты

| Скрипт | Назначение |
|--------|------------|
| `install-ja3-innoextract.sh` | Установка из offline backup |
| `finish-ja3-layout.sh` | CommonLua, реестр GOG |
| **`run-ja3.sh`** | **Канон запуска** |
| `reset-ja3-whisky.sh` | Остановить JA3/Wine в GOG-Install |
| `emergency-stop.sh` | Полный стоп GOG/Wine |
| `prepare-ja3-d3dmetal.sh` / `configure-ja3-d3dmetal.sh` | D3DMetal в Whisky |

**Удалено (CrossOver):** `run-ja3-crossover.sh`, `setup-ja3-crossover.sh`, `run-ja3-wine.sh`, `sync-ja3-saves.sh`, `fix-ja3-crossover-mouse.sh`.

---

## 5. Антипаттерны

| Не делать | Вместо |
|-----------|--------|
| `launch-galaxy.sh` / Galaxy CEF для JA3 | `run-ja3.sh` |
| Whisky Run **`JA3.exe`** без CWD | `run-ja3.sh` (`start /d`) |
| Дважды подряд `run-ja3.sh` без reset при живом JA3 | `reset-ja3-whisky.sh` |
| Galaxy web-stub для JA3 | offline innoextract |

---

## 6. Быстрые команды

| Действие | Команда |
|----------|---------|
| **Запуск** | `bash ~/code/local_machine/scripts/games/gog/run-ja3.sh` |
| **Стоп** | `bash ~/code/local_machine/scripts/games/gog/reset-ja3-whisky.sh` |
| Стоп всё GOG/Wine | `bash ~/code/local_machine/scripts/games/gog/emergency-stop.sh` |
| Проверить процесс | `pgrep -fl 'JA3\.exe'` |
| Обход swap | `JA3_IGNORE_SWAP=1 bash …/run-ja3.sh` |

**Полный цикл:**

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

---

## 7. Ссылки

- [Gcenx — нет D3DMetal в packages](https://github.com/Gcenx/macOS_Wine_builds/issues/97)
- [Whisky — GPU / GPTK tracking](https://github.com/Whisky-App/Whisky/issues/124)
- [Proton JA3 — graphics](https://github.com/ValveSoftware/Proton/issues/7039)