# Runbook: подготовка Windows-приложений в Wine на macOS (Whisky)

Один раз: bottle, шрифты, сеть, установка по **типу** приложения. **Ежедневный запуск** любых `.exe` — [WINE_APPS_LAUNCH_RUNBOOK.md](./WINE_APPS_LAUNCH_RUNBOOK.md).

Антипаттерны (GOG в HoMM-bottle, swap/winedbg): [TROUBLESHOOTING.md](./TROUBLESHOOTING.md).

Источники: [Whisky](https://github.com/Whisky-App/Whisky) (архив, Apple Silicon + macOS 14+), [Whisky #1220 CEF](https://github.com/IsaacMarovitz/Whisky/issues/1220), [CodeWeavers GOG Galaxy tip](https://www.codeweavers.com/compatibility/crossover/tips/gog-galaxy/gog-galaxy-working), практика bottle на этой машине (2026-05).

---

## 1. Жёсткие требования (без этого не обещаем успех)

| Условие | Значение |
|--------|----------|
| Mac | **Apple Silicon** (M1+) |
| macOS | **14 Sonoma+** (Whisky 3 / GPTK) |
| Whisky | Установлен, bottle **Windows 10, 64-bit** |
| Свободное место | **≥20 GB** для GOG/игр (web-stub + установка); **≥3 GB** минимум для Steam/лаунчеров |
| Один лаунчер | Не запускать **нативный Steam.app** параллельно с Wine Steam |
| Один установщик | Не открывать **два** `GOG_Galaxy_*.exe` — будет «Installer Already Running» |
| GOG web-stub | **Отдельный bottle** + `scripts/games/gog/` (не HoMM/Steam) |
| Подготовка HoMM/Steam | **Один раз:** `setup-wine-bottle.sh` |

---

## 2. Один раз: подготовка bottle

```bash
bash ~/code/local_machine/scripts/games/setup-wine-bottle.sh
```

Делает автоматически:

- Копирует **Arial, Tahoma, Verdana** и др. из macOS в `C:\windows\Fonts`
- По возможности `winetricks liberation` (GOG web-installer / .NET WinForms)
- Реестр: **MS Shell Dlg → Tahoma**, GenericSansSerif → Arial
- **DnsIPv6Enabled=0**, ProxyEnable=0 в bottle
- Steam **DWriteEnable=0** (пустой текст VGUI)

Повтор при сбое шрифтов:

```bash
bash ~/code/local_machine/scripts/games/setup-wine-bottle.sh --force
```

> **Не полагайтесь на `winetricks corefonts` из GUI Whisky** — зеркала Microsoft часто отдают 404 ([Whisky #515](https://github.com/Whisky-App/Whisky/issues/515)). Наш скрипт копирует шрифты с Mac.
>
> Опционально (медленно): `WINE_SETUP_WINETRICKS=1 bash …/setup-wine-bottle.sh --force`

---

## 3. Типы приложений и как запускать

### 3.1 Steam + Unity (HoMM Olden Era)

| Шаг | Команда |
|-----|---------|
| DXVK в bottle (один раз) | `bash …/start.sh dxvk` |
| Steam UI + логин | `bash …/start.sh steam-ui` |
| Пустой текст Steam | `bash …/start.sh fix-steam-ui` |
| Игра (сейвы 1/2/3) | `bash …/start.sh play` |
| Зависло | `bash …/start.sh reset` |

**CEF Steam (обязательно):** `-allosarches -cef-force-32bit -cef-in-process-gpu -no-cef-sandbox -cef-disable-gpu` — уже в `config.sh`.

**Игра:** DXVK + `d3d11=n,b`. **Не** смешивать с `export_wine_env_steam` при запуске exe.

### 3.2 GOG Galaxy 2.0 (лаунчер)

| Шаг | Команда |
|-----|---------|
| Установка (один раз) | `bash …/start.sh gog-install` |
| Запуск | `bash …/start.sh gog` |
| Перезапуск | `bash …/start.sh gog-restart` |
| Логин сбрасывает пароль | `bash …/start.sh fix-gog-auth` + `diagnose-gog-auth` |

**CEF GOG:** `-allosarches -cef-force-32bit -no-cef-sandbox -cef-disable-gpu` (без `-cef-in-process-gpu` — иначе CPU spin).

**Ограничение Wine:** нативный HTTP клиент Galaxy (`auth.gog.com/token`, `cfg.gog.com`) часто **таймаут 15–20 с** → логин в клиенте **ненадёжен**. Обходы ниже в §5.

### 3.3 GOG web-stub (~500 KB) — **отдельный bottle, без Steam**

**Не** запускать в bottle HoMM-OldenEra (там Steam, дампы, `winedbg`). См. `scripts/games/gog/README.md`.

```bash
# Whisky → New Bottle → Windows 10 64-bit → «GOG-Install»
bash ~/code/local_machine/scripts/games/gog/list-bottles.sh
bash ~/code/local_machine/scripts/games/gog/use-bottle.sh <UUID> GOG-Install

bash ~/code/local_machine/scripts/games/gog/create-bottle.sh GOG-Install
bash ~/code/local_machine/scripts/games/gog/setup-bottle.sh
bash ~/code/local_machine/scripts/games/gog/install-gdiplus.sh   # обязательно для .NET
brew install cabextract
bash ~/code/local_machine/scripts/games/gog/install-corefonts.sh

bash ~/code/local_machine/scripts/games/gog/run-web-installer.sh \
  ~/path/to/GOG_Galaxy_Jagged_Alliance_3.exe
```

Старые обёртки (`run-gog-web-installer.sh`, `setup-wine-bottle.sh` для GOG) перенаправляют в `gog/`.

**Типичные сбои:**

| Симптом | Действие |
|---------|----------|
| Пустые подписи / `FontFamilyNotFound` | `gog/install-corefonts.sh` → `gog/setup-bottle.sh --force` |
| «Installer Already Running» | `bash …/gog/reset.sh` |
| Нет bottle.env | `gog/use-bottle.sh <UUID>` |

Лог: `/tmp/gog-web-installer-GOG-Install.log`

### 3.4 GOG offline backup (рекомендуется при проблемах с сетью)

1. На [gog.com](https://www.gog.com) → библиотека → игра → **offline backup installer** (полный `.exe`, ГБ).
2. Скопировать в bottle: `…/drive_c/Setup_Game.exe`
3. Запуск:

```bash
source ~/code/local_machine/scripts/games/config.sh
export_wine_env
"$WINE64" 'C:\Setup_Game.exe'
```

Или через Whisky: Run → выбрать exe в `drive_c`.

### 3.5 JA3 multipart — innoextract, экономия диска

Для **Jagged Alliance 3** (и похожих GOG multipart backup): Wine-Inno **не доводит**; канон — **`gog/install-ja3-innoextract.sh`**.

Кратко:

1. Пять файлов в **`~/Games/`**: `setup_jagged_alliance_3_1.5.2_(80730).exe` + `-1.bin` … `-4.bin`.
2. Bottle **GOG-Install** (`gog/bottle.env`).
3. `bash …/gog/install-ja3-innoextract.sh` — распаковка в `drive_c/GOG Games/Jagged Alliance 3/`, `.bin` удаляются по мере чтения, после успеха — все архивы в `~/Games` (~15 GB).
4. Запуск: `bash …/gog/run-ja3.sh` (swap guard: см. [JA3_RUNBOOK.md](JA3_RUNBOOK.md) §1, §6).

Полный runbook: [JA3_MAC_WITHOUT_GALAXY.md](JA3_MAC_WITHOUT_GALAXY.md).

---

## 4. Переменные окружения (уже в скриптах)

```bash
export WINEPREFIX="<bottle>"
export WINEMSYNC=1
export WINEESYNC=1
export DYLD_LIBRARY_PATH="<Whisky>/Libraries/Wine/lib:…"
```

| Профиль | WINEDLLOVERRIDES | Когда |
|---------|------------------|--------|
| Steam / GOG UI | `dwrite=n,b` | steam-ui, gog |
| Unity / DX11 игра | `d3d11,d3d10core=n,b` | play, game |

---

## 5. GOG: если «не подключается» / сброс пароля

1. Логи: `bash …/start.sh diagnose-gog-auth`
2. `bash …/start.sh fix-gog-auth` → `gog-restart`
3. Если в логе `timeout … auth.gog.com/token` — **вход в Galaxy под Wine часто не сохраняется**; используйте **offline installer** или покупку/ключ через браузер на Mac.
4. Mac до `auth.gog.com` отвечает <1 с — проблема в **Poco/Qt в Wine**, не в пароле.

---

## 6. Диагностика (чеклист)

```bash
bash ~/code/local_machine/scripts/games/start.sh disk      # место
bash ~/code/local_machine/scripts/games/start.sh reset     # убить Wine Steam/GOG
pgrep -fl 'GalaxyClient|GOG_Galaxy|steam\.exe'             # дубликаты
```

| Лог | Путь |
|-----|------|
| GOG client | `…/ProgramData/GOG.com/Galaxy/logs/GalaxyClient.log` |
| GOG CEF | `…/ProgramData/GOG.com/Galaxy/logs/cef.log` |
| Web-stub | `/tmp/gog-web-installer.log` |
| Steam | `…/Steam/logs/connection_log.txt` |

---

## 7. Команды (шпаргалка)

```bash
BASE=~/code/local_machine/scripts/games

bash "$BASE/setup-wine-bottle.sh"              # один раз
bash "$BASE/start.sh" steam-ui                 # Steam
bash "$BASE/start.sh" play                     # HoMM
bash "$BASE/start.sh" gog-install && gog       # GOG Galaxy
bash "$BASE/run-gog-web-installer.sh" …/GOG_Galaxy_*.exe
bash "$BASE/start.sh" reset                      # всё убить в bottle
```

Документация: [WINE_APPS_LAUNCH_RUNBOOK.md](WINE_APPS_LAUNCH_RUNBOOK.md) · [TROUBLESHOOTING.md](TROUBLESHOOTING.md)

---

## 8. Честные ограничения

- **Whisky архивен** ([maintenance notice](https://docs.getwhisky.app/maintenance-notice)); альтернатива — [Moonshine](https://github.com/ybmeng/moonshine) (Wine 11.x).
- **GOG Galaxy login** в Wine на этой конфигурации — **best effort**, не гарантия.
- **Web-stub** требует сеть из Wine; при таймаутах — только **offline backup**.
- **Диск <10% свободно** — CEF crash loop, freeze; см. `docs/disk_cleanup/`.