Settings
Every setting belongs to one environment. Change one with grapple set, remove it again with grapple unset, and see the current state with grapple info. A key that is not in the file is at its default.
$ grapple set games graphics d3dmetal
==> games: graphics=d3dmetal| Key | Values | Default | What it does |
|---|---|---|---|
| engine | An engine name | grapple-wine | Which Wine build the environment runs. grapple-wine (Grapple's own build, the default), wine-staging and wine-devel are downloaded and installed on the spot if missing; gptk has to be linked in first. Changing it stops the environment and updates the prefix. |
| graphics | auto, dxmt, dxvk, d3dmetal, wined3d | auto | Which DirectX-to-Metal layer the environment uses. See below. On a gptk engine this is always d3dmetal and nothing else is accepted. |
| winver | A Windows version winecfg accepts, e.g. win10, win11, win7 | win10 | What the environment reports to programs. Applied straight away with winecfg. The CLI passes the value through without checking it, so a typo simply does nothing. |
| esync | on, off | on | Sets WINEESYNC. Faster thread synchronisation inside Wine. Turn it off only if a game deadlocks or crashes in a way that looks like a threading bug. |
| msync | on, off | on | Sets WINEMSYNC, the macOS-native version of the same idea. Same advice: leave it on unless you are chasing a hang. |
| avx | on, off | on | Sets ROSETTA_ADVERTISE_AVX, so Rosetta tells the game it has AVX instructions. Some games refuse to start without it. |
| hud | on, off | off | Sets MTL_HUD_ENABLED, which draws Metal's own performance overlay on top of the game. Frame rate and frame time, straight from the system. |
| retina | on, off | off | Writes RetinaMode into the environment's registry. On means the game renders at the display's full pixel density, which looks sharper and costs a lot of GPU. |
| dxr | on, off | off | Sets D3DM_SUPPORT_DXR, asking D3DMetal to advertise ray tracing. Only meaningful on D3DMetal, and expect it to be slow where it works at all. |
| winedebug | A Wine debug channel string | -all | Sets WINEDEBUG. The default silences Wine's own logging. +loaddll or +relay produce a great deal of output in the environment's log, which is occasionally what you need. |
| env.VAR | Any value | — | Exports VAR before the program starts. The name after env. has to be a valid shell variable name. Use it for a game's own switches, or a layer's, e.g. env.DXVK_ASYNC=1. |
esync, msync, avx, hud and dxr take effect the next time you start a program. retina and winver are written into the Windows registry the moment you set them. engine and graphics stop everything running in that environment and then update the prefix, so quit your game first.
Setting an engine can change the graphics layer
Setting engine to gptk also sets graphics=d3dmetal, because that engine brings its own. Moving from gptk to another engine while D3DMetal is not installed puts graphics back to auto, so an environment is never left pointing at a layer that is not there.
The graphics setting
A Mac has no DirectX. Every Windows game that draws anything needs a layer that translates its DirectX calls into Metal, the graphics API your Mac actually speaks. Which one suits a game is not predictable, so it is a setting. The long version is in the DirectX on Mac guide; this is what the CLI does with each value.
| Value | Covers | Translates to | When to pick it |
|---|---|---|---|
| auto | Whatever the layer it picks covers | — | The default. Uses D3DMetal when the component is installed, and DXMT when it is not. Leave it here unless a game gives you a reason to move. |
| d3dmetal | DirectX 9 to 12 | Metal | Apple's layer, from the Game Porting Toolkit, included with Grapple. The widest coverage and the only one that handles DirectX 12, so it is the answer for anything modern. Needs the component installed. |
| dxmt | DirectX 10 and 11 | Metal | Open source, and dropped into a copy of the engine rather than loaded from outside it. Worth trying when a DirectX 11 game misbehaves on D3DMetal. |
| dxvk | DirectX 10 and 11 | Vulkan, then Metal through MoltenVK | An older, well-travelled route (DXVK-macOS 1.10.3). Two translations instead of one, but some games are simply happier on it. |
| wined3d | DirectX up to 11 | OpenGL | Wine's own built-in translation, with nothing added. Slow, and OpenGL is deprecated on macOS — a last resort for an old game that refuses everything else. |
dxmt and dxvk replace Wine's own DirectX DLLs, so the CLI keeps a separate copy of the engine for each — grapple-wine+dxmt, grapple-wine+dxvk — cloned the moment you first need it. grapple-wine carries the DXMT build it was tested with, so that copy needs no download at all; on the other engines the CLI fetches DXMT or DXVK and checks its sha256 first. d3dmetal works the other way round: it lives beside the engines and is loaded into whichever engine you are running, so one copy serves everything.
DXMT needs the right Wine build
DXMT draws through functions the Wine macOS driver has to expose, and not every Wine build exposes them.grapple-wine, the default, does. The third-party wine-staging and wine-devel builds do not, so DXMT loads there but nothing is drawn. If a game shows a black window on dxmt and is fine on d3dmetal or dxvk, this is why — it is the engine, not the game.
Environment variables
Variables the CLI reads from your shell.
| Variable | Default | What it does |
|---|---|---|
| GRAPPLE_HOME | ~/Library/Application Support/Grapple | The data directory: engines, environments and downloads. Set it to keep a separate set of environments, or to work on a scratch copy. grapple home prints the one in use. |
| GRAPPLE_COMPONENTS_URL | https://getgrapple.io/components.json | Where the CLI reads the list of things it downloads for itself — the engine and D3DMetal — with the version, address, size and sha256 of each. Point it at your own copy (an http:// or file:// address) to install from somewhere else. If it cannot be reached, the CLI says so and falls back to the addresses built into it. |
| D3DMETAL_URL | from the components manifest | Overrides where grapple d3dmetal install downloads from when you give it no path. Setting it by hand also skips the sha256 check, because nothing published says what that address should contain — so it is for your own builds and for testing. |
| WINEDEBUG | unset | If this is already set in your shell it wins over the environment's winedebug setting, so you can turn Wine's logging up for one command without changing anything. |
| WINEDLLOVERRIDES | unset | Passed through to Wine. grapple steam prepends its own override, which disables Steam's overlay DLL, and keeps whatever you had after it. |
| DYLD_FALLBACK_LIBRARY_PATH | unset | When the environment uses D3DMetal, the component's folder is put in front of whatever you had, so its libraries are found first. |
| TMPDIR | /tmp | Where grapple report stages files before zipping them. |
| HOME | your home folder | Where the default data directory, ~/Applications launchers and the Trash that grapple delete moves things to all live. |
For completeness, these are the variables the CLI sets before it starts a program, most of them from the settings above: WINEPREFIX, WINE, WINESERVER, WINEDEBUG, WINEESYNC, WINEMSYNC, MTL_HUD_ENABLED, ROSETTA_ADVERTISE_AVX, D3DM_SUPPORT_DXR, CX_APPLEGPTK_LIBD3DSHARED_PATH and WINEDLLPATH_PREPEND, plus anything you added with an env. key.
The data directory
Everything Grapple installs or creates lives under one folder, and nothing outside it except the launchers grapple shortcut writes to ~/Applications. Delete the folder and you are back to a fresh install — along with your games and saves, so do not do that casually.
~/Library/Application Support/Grapple/
├── engines/
│ ├── grapple-wine/ an engine: a Wine build (the default one)
│ ├── grapple-wine+dxmt/ the same engine with DXMT's DLLs (APFS clone)
│ ├── grapple-wine+dxvk/ the same engine with DXVK's DLLs (APFS clone)
│ ├── d3dmetal/
│ │ ├── 4.0-beta-2/ one installed version of the component
│ │ └── current -> 4.0-beta-2 the one in use
│ └── d3dmetal-bridge the older path, kept as a link to d3dmetal/current
├── bottles/
│ └── games/ one Windows environment
│ ├── grapple.conf its settings
│ ├── prefix/ the Wine prefix: drive_c, the registry, everything
│ └── logs/ one log per program that has run in it
└── cache/ downloads (the Steam installer, layer archives,
and components.json, the list of what to fetch)The bottles folder name is the CLI's internal term showing through; each folder in it is one Windows environment, named exactly as grapple list shows it. An environment is self contained, so you can copy one to another Mac by copying its folder, as long as the same engine is installed there.
An engine can carry a grapple-engine.env file of KEY=VALUE lines, which are exported before it runs; {ENGINE} in a value expands to the engine's own folder. That is how an engine packaged for a different host describes what it needs. You will not normally write one.
The settings file
Each environment's settings are plain KEY=value lines in bottles/<name>/grapple.conf. grapple info prints the file as it is:
engine=grapple-wine
winver=win10
esync=on
msync=on
avx=on
retina=off
graphics=dxvk
env.DXVK_ASYNC=1
hud=on
env.WINE_D3D_CONFIG=renderer=vulkanOrder does not matter and the last line for a key wins. You can edit it by hand, but prefer grapple set: it validates the value, and it writes retina and winver into the Windows registry, which editing the file does not.