Setting up Wine for effect compilation

Learn how to set up Wine on macOS and Linux so that MonoGame can compile effects (shaders).

Effect (shader) compilation requires access to DirectX. This means it will not work natively on macOS and Linux systems, but it can be used through Wine.

MonoGame provides a setup script that sets up the Wine environment for effect compilation. The MonoGame Effects Compiler (MGFXC) then uses that environment to compile your effects.

Note

You do not need Wine on Windows. On macOS and Linux, you only need it if your game uses its own effects.

Set up Wine

Follow the steps for your operating system.

Install Homebrew

Open a terminal window and enter the following commands:

brew install wget p7zip curl
brew install --cask xquartz
curl -L -o wine.tar.xz "https://github.com/Gcenx/macOS_Wine_builds/releases/download/11.0_1/wine-stable-11.0_1-osx64.tar.xz"
tar -xJf wine.tar.xz
sudo mv "Wine Stable.app" /Applications/
sudo xattr -dr com.apple.quarantine "/Applications/Wine Stable.app"
echo "export PATH="/Applications/Wine Stable.app/Contents/Resources/wine/bin:$PATH"" >> ~/.zprofile
source ~/.zprofile
wine --version

Now that the prerequisites are installed, download the mgfxc_wine_setup.sh script and execute it by entering the following command in the terminal:
```
wget -qO- https://monogame.net/downloads/net9_mgfxc_wine_setup.sh | bash
```

This will create a new directory called .winemonogame in your home directory. If you ever wish to undo the setup this script performed, delete that directory.

Note

For the time being, MonoGame requires that you install the Intel version even if you are using an Apple Silicon (M1/M2) Mac. For Apple Silicon Macs, it also requires that Rosetta be enabled.

Download the latest Wine for your version of Ubuntu from the WineHQ Debian and Ubuntu page.
Open a terminal window and enter the following command:
```
sudo apt install wget curl p7zip-full
```
Tip

If you receive an error stating that any of the packages do not have an install candidate, you may need to enable the universe apt repository. To do this, enter the following commands in the terminal:
```
sudo add-apt-repository universe
sudo apt update
```
Then try installing the packages again.
Now that the prerequisites are installed, download the mgfxc_wine_setup.sh script and execute it by entering the following command in the terminal:
```
wget -qO- https://monogame.net/downloads/net9_mgfxc_wine_setup.sh | bash
```

This will create a new directory called .winemonogame in your home directory. If you ever wish to undo the setup this script performed, delete that directory.

Open a terminal window.
Install Wine and the required dependencies:
```
sudo pacman -S wget curl 7zip wine
```
Important

Arch Linux recently transitioned the Wine package to a pure wow64 build to align with upstream Wine development. Because of this, when you install Wine using pacman, you will not get a separate wine64 executable that the MonoGame tools expect.

Reference: https://archlinux.org/news/transition-to-the-new-wow64-wine-and-wine-staging/

This means you will need to create a symlink for MonoGame to reference with the following command:
```
sudo ln -s /usr/bin/wine /usr/local/bin/wine64
```
Now that the prerequisites are installed, download the mgfxc_wine_setup.sh script and execute it by entering the following command in the terminal:
```
wget -qO- https://monogame.net/downloads/net9_mgfxc_wine_setup.sh | bash
```
Tip

When running the Wine setup script, you may see a popup asking to install Wine Mono for .NET support. You can close this popup. It is not needed because the MonoGame script installs the actual Windows .NET SDK instead.

Note

This script will create a new directory called .winemonogame in your home directory. If you ever wish to undo the setup this script performed, delete that directory.
After the script completes, you must add the MGFXC_WINE_PATH environment variable to your system environment for it to be accessible to all applications:
```
echo 'MGFXC_WINE_PATH="'$HOME'/.winemonogame"' | sudo tee -a /etc/environment
```
Important

Unlike other Linux distributions, such as Ubuntu, Arch Linux may not automatically load environment variables from your user profile at ~/.profile for all applications. Adding MGFXC_WINE_PATH to /etc/environment ensures it is available system-wide, including for GUI applications (such as the MGCB Editor) and IDEs.
For the environment variable to take effect, you can either log out and back in (recommended) or reboot your system.
After logging back in, verify the environment variable is set:
```
echo $MGFXC_WINE_PATH
```
Note

When running the above command you should see an output similar to the following:
```
/home/yourusername/.winemonogame
```

Troubleshooting

Issue: "wine64 not found" error on Arch Linux

If the setup script fails with wine64 not found, ensure you created the symlink from step 2 of the Arch Linux instructions:

sudo ln -s /usr/bin/wine /usr/local/bin/wine64

Issue: Shader compilation fails with "MGFXC effect compiler requires a valid Wine installation"

This means the MGFXC_WINE_PATH environment variable is not set. On Arch Linux, ensure you:

Added it to /etc/environment as shown in step 4 of the Arch Linux instructions.
Logged out and logged back in.
Can see it with echo $MGFXC_WINE_PATH.

Issue: Wine creates a `.wine-mgfxc` directory instead of using `.winemonogame`

This is another symptom of the environment variable not being set. Follow the steps in the previous issue to resolve it.

Issue: Wine version too old

The MonoGame setup script requires Wine 8.0 or later. Check your version:

wine --version

If it is too old on Arch Linux, update your system:

sudo pacman -Syu

Issue: Rider cannot compile effects on Linux

You might need to add the MGFXC_WINE_PATH environment variable to /etc/environment for Rider to pick it up. See Rider cannot see all Environmental Variables for details.

Table of Contents

Setting up Wine for effect compilation

Note

Set up Wine

Note

Troubleshooting

Issue: "wine64 not found" error on Arch Linux

Issue: Shader compilation fails with "MGFXC effect compiler requires a valid Wine installation"

Issue: Wine creates a .wine-mgfxc directory instead of using .winemonogame

Issue: Wine version too old

Issue: Rider cannot compile effects on Linux

Issue: Wine creates a `.wine-mgfxc` directory instead of using `.winemonogame`