# Setup Guide

This toolkit is built around a simple rule: keep generated state outside the repository.

The repository contains scripts, examples, and documentation. Each user provides their own paths through environment variables.

## Recommended Layout

Internal SSD:

```text
$HOME/GPTK/
$HOME/GPTK/libexec/
$HOME/GPTK/logs/
$HOME/WinePrefixes/
$HOME/bin/
```

External storage:

```text
$GPTK_EXTERNAL_ROOT/
    Games/
    Installers/
    SteamLibrary/
```

These are defaults, not requirements. Change them in `~/.rippermoon-gptk.env`.

## Game Folder Workflow

For fragile Windows games and installers, prefer copying an already-installed Windows game folder into:

```text
$GPTK_EXTERNAL_ROOT/Games/<GameName>/
```

Do not copy only the installer files when the documentation says a pre-installed folder is required. Some installers do not behave well under this GPTK/Wine build, while the already-installed game folder can still run correctly.

For Elden Ring ERSC, the tested layout is:

```text
$GPTK_EXTERNAL_ROOT/Games/EldenRing/Game/
    eldenring.exe
    ersc_launcher.exe
    SeamlessCoop/
```

## Configure Paths

Create a config file:

```zsh
cp env.example ~/.rippermoon-gptk.env
```

Edit it:

```zsh
open -e ~/.rippermoon-gptk.env
```

Important settings:

```zsh
export GPTK_EXTERNAL_ROOT="/Volumes/YourGameDrive"
export GPTK_PREFIX_ROOT="$HOME/WinePrefixes"
export GPTK_HOME="$HOME/GPTK"
export GPTK_APP_PATH="$GPTK_HOME/apps/Game Porting Toolkit.app"
export GPTK_WINE_HOME="$GPTK_APP_PATH/Contents/Resources/wine"
```

## Install From DMG

For the app-first install, download the latest DMG:

```text
https://github.com/MoonTheRipper/RipperMoonKit/releases/latest/download/RipperMoonKit-Launcher.dmg
```

Open the DMG, run **Install to My Applications.command** or copy **RipperMoonKit Launcher.app** into `~/Applications`, then open it. The first-run setup can guide the GPTK download/mount step and install the local helper scripts. RipperMoonKit is intentionally user-scoped; avoid `/Applications` unless you want a system-wide copy.

After GPTK and the required local runner are verified, the app starts Windows Steam installation in the background. The setup screen can move to **You're all set** while Steam continues, so users can configure paths, add copied game folders, and add a TheGamesDB cover-art API key instead of waiting on Steam updates.

When Steam is ready, open the Steam profile to sign in. If Steam is still installing, the app shows that state and the background log is written under:

```text
$GPTK_HOME/logs/steam-install-background-YYYYmmdd-HHMMSS.log
```

## Install From Source

Before running the installer, download **Game Porting Toolkit 3** from Apple Developer and mount the DMG:

```text
https://developer.apple.com/games/game-porting-toolkit/
```

Leave the mounted GPTK volume available under `/Volumes`. If it contains a nested **Evaluation environment for Windows games 3.0** image, the installer will try to attach it automatically.

```zsh
./install.zsh
```

The installer writes a detailed log:

```text
$GPTK_HOME/logs/rippermoon-install-YYYYmmdd-HHMMSS.log
```

It installs host dependencies, installs the prebuilt `Game Porting Toolkit.app` runner through Homebrew if needed, copies the Apple GPTK 3 runtime from the mounted media, downloads `SteamSetup.exe`, and verifies the local pinned GPTK/Wine runtime path. Steam can be installed later with either the foreground `./install.zsh --install-steam` command or the app-style background `./install.zsh --install-steam-background` command. See [dependencies.md](dependencies.md), [gptk.md](gptk.md), and [steam.md](steam.md) for details.

Install the local SwiftUI app from source with:

```zsh
zsh scripts/install-gui-app.zsh
```

Open a new terminal, or reload shell config:

```zsh
source ~/.zshrc
```

Confirm the commands are visible:

```zsh
which gptk-launch
which gptk-steam
which gptk-game
```

## Prefix Model

A prefix is a Windows environment. Prefixes are isolated from each other, so games can have different registry settings, DLL overrides, and installed runtimes.

Named prefix:

```zsh
gptk-launch --prefix MyGame --init
```

Full-path prefix:

```zsh
gptk-launch --prefix "$HOME/WinePrefixes/MyGame" --init
```

The scripts create Wine drive mappings from `GPTK_DRIVE_MAPS` when the target folders exist:

```text
S: -> $GPTK_STEAM_LIBRARY
X: -> $GPTK_EXTERNAL_ROOT/Games
I: -> $GPTK_EXTERNAL_ROOT/Installers
```

You can map as many host folders as you want and choose the letters yourself, except for `C:`. Wine owns `C:` inside each prefix.

Example:

```zsh
export GPTK_DRIVE_MAPS="D=/Volumes/FastSSD;E=/Volumes/Archive;S=$GPTK_STEAM_LIBRARY;X=$GPTK_EXTERNAL_ROOT/Games"
```

See [drives.md](drives.md) for the full format.

## Logging

Logs default to:

```text
$GPTK_HOME/logs
```

Use a fixed log path when you are debugging one game repeatedly:

```zsh
gptk-launch --prefix MyGame --log-file "$GPTK_HOME/logs/MyGame-debug.log" -- ./Game.exe
```