# Runbook: запуск Windows-приложений в Wine (Whisky)

**Главный документ по пуску** любых `.exe` в bottle на Mac. Подготовка bottle, шрифты, GOG/сеть — [WINE_MAC_RUNBOOK.md](./WINE_MAC_RUNBOOK.md). Сбои — [TROUBLESHOOTING.md](./TROUBLESHOOTING.md). **Шрифты / пустой UI:** [TROUBLESHOOTING § шрифты](./TROUBLESHOOTING.md#шрифты-антипаттерны-сводка) (`dwrite` для Steam, `gdiplus=n,b` для GOG stub).

- **Скрипты:** [`../../scripts/games`](../../scripts/games)
- **Универсальный запуск:** `bash …/scripts/games/run-wine-exe.sh` (см. §2)

---

## 1. Новая программа — пройти по порядку

Скопируйте чеклист; для каждого пункта есть команда ниже.

| # | Вопрос | Действие |
|---|--------|----------|
| 1 | **Какой тип?** | Таблица §1.1 → профиль Wine |
| 2 | **Свой bottle?** | Steam/Unity/много игр → часто **да**; GOG web-stub → **отдельный** `GOG-Install`; один офлайн-setup → можно общий |
| 3 | **Место на диске** | `bash …/start.sh disk` → **≥20 GB** для установщиков/игр, **≥3 GB** для лаунчера |
| 4 | **Один раз: bottle** | Whisky → **Windows 10 64-bit** → Sync **MSync**; Wine: `install-whiskywine-manual.sh` |
| 5 | **Один раз: шрифты/сеть** | `bash …/setup-wine-bottle.sh` (HoMM/Steam bottle) или `gog/setup-bottle.sh` (GOG bottle) |
| 6 | **Установка** | Steam/GOG/офлайн `.exe` — §1.1; **не** два установщика GOG одновременно |
| 7 | **Запуск** | §2 — `run-wine-exe.sh`, `start.sh …`, или Whisky → Run |
| 8 | **Зафиксировать** | Добавить строку в §6 и при необходимости обёртку в `scripts/games/` |

### 1.1 Тип приложения → установка и профиль

| Тип | Примеры | Установка (один раз) | Профиль запуска (`run-wine-exe.sh`) |
|-----|---------|----------------------|-------------------------------------|
| **Steam + игра** | HoMM Olden Era | `install-steam-extract.sh`, игра из Steam | `steam` → UI; `game` → exe + DXVK |
| **GOG Galaxy (лаунчер)** | Galaxy 2.0 | `start.sh gog-install` или `gog/install-galaxy-extract.sh` | `gog` |
| **GOG web-stub** | `GOG_Galaxy_*.exe` | Только bottle `gog/` — [gog/README.md](../../scripts/games/gog/README.md) | `gog` |
| **Офлайн setup .exe** | backup с gog.com | Скопировать в `drive_c/`, запустить установщик | `plain` или `gog` |
| **GOG multipart + innoextract** | JA3 offline backup | `gog/install-ja3-innoextract.sh` — [JA3 runbook](JA3_RUNBOOK.md) | `gog/run-ja3.sh` |
| **.NET WinForms installer** | web-stub, мастера GOG | **`gog/install-gdiplus.sh`** + corefonts | `gog` |
| **CEF (Steam/GOG UI)** | Steam.exe, GalaxyClient | CEF-флаги в `config.sh` / `gog/config.sh` | `steam` / `gog` |
| **DX11 игра (Unity и т.д.)** | Olden Era | `install-dxvk-macos.sh` | `game` |
| **Прочий Win32 .exe** | утилиты, старые игры | Обычно только setup bottle + шрифты | `plain` |

**Inno Setup + botva2** (GOG `GalaxySetup.exe`, **JA3 offline setup**): в Wine часто **gdi32** — не полагаться на `/VERYSILENT`. Galaxy — **innoextract**; **JA3 multipart** — `gog/install-ja3-innoextract.sh`. Запуск JA3 — [JA3_RUNBOOK.md](JA3_RUNBOOK.md). См. [TROUBLESHOOTING.md § Setup](./TROUBLESHOOTING.md).

Подробная подготовка по типам: [WINE_MAC_RUNBOOK.md §3](./WINE_MAC_RUNBOOK.md).

---

## 2. Запуск (любая программа)

### 2.1 Универсально: `run-wine-exe.sh`

```bash
# Справка
bash ~/code/local_machine/scripts/games/run-wine-exe.sh --help

# Программа уже в drive_c (путь Wine)
bash ~/code/local_machine/scripts/games/run-wine-exe.sh \
  --bottle HoMM-OldenEra \
  --profile game \
  'C:\Program Files (x86)\Steam\steamapps\common\My Game\game.exe'

# Установщик с Mac (копируется в C:\)
bash ~/code/local_machine/scripts/games/run-wine-exe.sh \
  --bottle GOG-Install \
  --profile gog \
  ~/Downloads/Setup_Game.exe

# Bottle GOG из gog/bottle.env (без --bottle)
bash ~/code/local_machine/scripts/games/run-wine-exe.sh --profile gog 'C:\Program Files (x86)\GOG Galaxy\GalaxyClient.exe'
```

| `--profile` | `WINEDLLOVERRIDES` / env | Когда |
|-------------|--------------------------|--------|
| `plain` | по умолчанию Wine | утилиты, простые exe |
| `steam` | `dwrite=n,b` | Steam.exe, VGUI |
| `gog` | `gdiplus=n,b` | GOG Galaxy, .NET installers |
| `game` | DXVK + `d3d11=n,b` | DX11/Unity после `install-dxvk-macos.sh` |

Переменные bottle: `WINE_BOTTLE_ID=<UUID>` или `WINE_BOTTLE_NAME=HoMM-OldenEra`. GOG-bottle: `GOG_BOTTLE=1` (читает `gog/bottle.env`).

Фон + лог:

```bash
bash …/run-wine-exe.sh --background --log /tmp/my-app.log --profile plain 'C:\app\foo.exe'
```

### 2.2 Через Whisky GUI

1. Открыть bottle → **Run** → выбрать `.exe` из `drive_c` **или** с Mac (Whisky скопирует).
2. Окно: **Cmd+Tab** → `wine64` / имя процесса, не только окно Whisky.

### 2.3 Готовые обёртки (`start.sh`)

| Задача | Команда |
|--------|---------|
| Steam UI | `bash …/start.sh steam-ui` |
| HoMM (игра + сейвы) | `bash …/start.sh play` |
| GOG Galaxy | `bash …/start.sh gog` |
| Сброс процессов bottle | `bash …/start.sh reset` |
| Место на диске | `bash …/start.sh disk` |
| GOG bottle: клиент | `bash …/gog/launch-galaxy.sh` |
| GOG bottle: JA3 установка | `bash …/gog/install-ja3-innoextract.sh` |
| GOG bottle: JA3 запуск | `bash …/gog/run-ja3.sh` — [JA3_RUNBOOK.md](JA3_RUNBOOK.md) |

Полный список: `bash …/start.sh` без аргументов.

### 2.4 Вручную (если нет скрипта)

```bash
export WINEPREFIX="$HOME/Library/Containers/com.franke.Whisky/Bottles/<UUID>"
WINE64="$HOME/Library/Application Support/com.franke.Whisky/Libraries/Wine/bin/wine64"
export DYLD_LIBRARY_PATH="$HOME/Library/Application Support/com.franke.Whisky/Libraries/Wine/lib"
export WINEMSYNC=1 WINEESYNC=1
"$WINE64" 'C:\path\app.exe'
```

Профили overrides — [WINE_MAC_RUNBOOK.md §4](./WINE_MAC_RUNBOOK.md).

---

## 3. Инфраструктура (один раз на машину)

| Компонент | Путь |
|-----------|------|
| Whisky 3 | `brew install --cask frankea/whisky/whisky` |
| Wine | `bash …/install-whiskywine-manual.sh` |
| Bottle | `~/Library/Containers/com.franke.Whisky/Bottles/<UUID>/` |
| Кэш установщиков | `scripts/games/cache/` |

Проверка места: `bash …/start.sh disk`.

Создание bottle: Whisky **+** → Windows 10 → имя; для GOG: `bash …/gog/create-bottle.sh GOG-Install`.

---

## 4. Шаблон: добавить программу в репозиторий

1. **Имя и bottle** — зафиксировать UUID в `config.sh` или `gog/bottle.env`.
2. **Скрипт установки** (если повторяемо) — `scripts/games/install-<app>.sh` или секция в `gog/`.
3. **Скрипт запуска** — команда в `start.sh` *или* документированный `run-wine-exe.sh --profile …`.
4. **Строка в §6** ниже — тип, bottle, команда запуска, путь к exe.
5. **Сбои** — краткий симптом в [TROUBLESHOOTING.md](./TROUBLESHOOTING.md).

---

## 5. Уже настроенные приложения

| Приложение | Bottle | Запуск | Примечание |
|------------|--------|--------|------------|
| **Steam** | HoMM-OldenEra | `start.sh steam-ui` | Не параллельно с Steam.app |
| **HoMM Olden Era** | HoMM-OldenEra | `start.sh play` | Не Play в Steam UI; нужен DXVK — §7 |
| **GOG Galaxy 2.0** | HoMM-OldenEra | `start.sh gog` | Логин в Wine — best effort |
| **Jagged Alliance 3** | GOG-Install (Whisky) | `gog/run-ja3.sh` | Установка: `install-ja3-innoextract.sh` ([runbook](JA3_RUNBOOK.md)) |
| **GOG Galaxy 2.0** | GOG-Install | `gog/launch-galaxy.sh` | Best effort; JA3 — **не** через Galaxy на этом Mac |
| **Любой новый .exe** | свой / общий | `run-wine-exe.sh` | §2.1 |

---

## 6. Справочник скриптов

| Файл | Назначение |
|------|------------|
| **run-wine-exe.sh** | Универсальный пуск exe в выбранном bottle |
| **start.sh** | Steam / HoMM / GOG / reset / disk / dxvk |
| **setup-wine-bottle.sh** | Шрифты + реестр + сеть (HoMM bottle) |
| **config.sh** | UUID HoMM, `export_wine_env_*` |
| **gog/** | Отдельный bottle, gdiplus, web-stub |
| **install-dxvk-macos.sh** | DX11 для Unity |

---

## 7. HoMM Olden Era (ежедневно)

Краткая выжимка; детали сейвов/графики — прежние §4–5 методички.

### Однократно

```bash
brew install p7zip
bash ~/code/local_machine/scripts/games/install-whiskywine-manual.sh
bash ~/code/local_machine/scripts/games/install-steam-extract.sh
bash ~/code/local_machine/scripts/games/install-dxvk-macos.sh
bash ~/code/local_machine/scripts/games/setup-wine-bottle.sh
```

Bottle **HoMM-OldenEra**, Sync **MSync**.

### Каждый запуск

Steam **Logged On** → затем:

```bash
bash ~/code/local_machine/scripts/games/start.sh play
```

Не **Play** у Olden Era в окне Steam (нет DXVK).

Альтернатива: `start.sh game`; сейвы: `start.sh saves`; диагностика: `start.sh diagnose-saves`.

### Переменные (`start.sh game`)

| Переменная | По умолчанию | Назначение |
|------------|----------------|------------|
| `HOMM_VDESKTOP` | `1920x1080` | Виртуальный стол Wine |
| `HOMM_USE_WINEVDESKTOP` | `1` | `0` — без explorer /desktop |
| `HOMM_UNITY_WINDOWED` | `1` | Оконный режим Unity |
| `HOMM_UNITY_EXTRA` | *(пусто)* | напр. `-popupwindow` |

### Сейвы (singleplayer 1/2/3)

```
~/Library/Containers/com.franke.Whisky/Bottles/38412122-AAE1-4831-9F2E-6A0EB364B3F9/drive_c/users/eternal/AppData/LocalLow/Unfrozen/HeroesOldenEra/users/Steam_<ID>/saves/singleplayer/
```

*Bottle ID: `38412122-AAE1-4831-9F2E-6A0EB364B3F9` · Whisky 3 · WhiskyWine 3*

---

## 8. Шпаргалка

```bash
G=~/code/local_machine/scripts/games
bash "$G/run-wine-exe.sh" --help
bash "$G/start.sh" disk
bash "$G/setup-wine-bottle.sh"
bash "$G/start.sh" play
bash "$G/gog/launch-galaxy.sh"
```