local_machine/docs/games/WINE_MAC_RUNBOOK.md

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

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

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

Источники: Whisky (архив, Apple Silicon + macOS 14+), Whisky #1220 CEF, CodeWeavers GOG Galaxy tip, практика 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 ~/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 ~/code/local_machine/scripts/games/setup-wine-bottle.sh --force

Не полагайтесь на winetricks corefonts из GUI Whisky — зеркала Microsoft часто отдают 404 (Whisky #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.

# 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 → библиотека → игра → offline backup installer (полный .exe, ГБ).
2. Скопировать в bottle: …/drive_c/Setup_Game.exe
3. Запуск:

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 §1, §6).

Полный runbook: JA3_MAC_WITHOUT_GALAXY.md.

---

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

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 ~/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. Команды (шпаргалка)

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 · TROUBLESHOOTING.md

---

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

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