Skip to content

setup.md

Latest commit

 

History

History
179 lines (120 loc) · 4.87 KB

setup.md

File metadata and controls

179 lines (120 loc) · 4.87 KB
Raw

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:

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

External storage:

$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:

$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:

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

Configure Paths

Create a config file:

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

Edit it:

open -e ~/.rippermoon-gptk.env

Important settings:

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:

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:

$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:

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.

./install.zsh

The installer writes a detailed log:

$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, gptk.md, and steam.md for details.

Install the local SwiftUI app from source with:

zsh scripts/install-gui-app.zsh

Open a new terminal, or reload shell config:

source ~/.zshrc

Confirm the commands are visible:

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:

gptk-launch --prefix MyGame --init

Full-path prefix:

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

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

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:

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

See drives.md for the full format.

Logging

Logs default to:

$GPTK_HOME/logs

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

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