Add setup information for Arch Linux users

articles/getting_started/1_setting_up_your_os_for_development_arch.md

@@ -0,0 +1,158 @@
+---
+title: Setting up your OS for development on Arch Linux
+description: This section provides a step-by-step guide for setting up your development environment on Arch Linux.
+---
+
+> [!TIP]
+> Arch Linux is a rolling release distribution. This guide was tested in October 2025 with kernel `version 6.15.9-arch1-1`.
+
+To develop with MonoGame in C#, you will need to install the .NET SDK. As of MonoGame 3.8.2 the minimum supported version is .NET 8.
+
+## Install .NET 8 SDK
+
+1. Open a new **Terminal** window.
+2. Enter the following command in the terminal to install the latest .NET 8 SDK:
+
+    ```sh
+    sudo pacman -Syu
+    sudo pacman -S dotnet-sdk-8.0
+    ```
+
+## Install additional workloads
+
+If you intend to also work with platforms such as `Android` or `iOS`, you will need to install the additional .NET workload templates for those platforms which include additional features and simulators to support those platforms.  Just run the following commands from the terminal for the platforms below you wish to install.
+
+> [!IMPORTANT]
+> For mobile development with iOS and Android, you must also install the MAUI workload even though MonoGame does not use MAUI. The MAUI workload contains the debugging tools required to run and debug mobile .NET applications. Without it, you will not be able to properly debug your MonoGame mobile projects.
+
+### [Android](#tab/android)
+
+```cli
+dotnet workload install android
+```
+
+### [iOS](#tab/iOS)
+
+```cli
+dotnet workload install ios
+```
+
+### [Maui](#tab/maui)
+
+```cli
+dotnet workload install maui
+```
+
+### [Android, iOS, and Maui](#tab/all)
+
+```cli
+dotnet workload install android ios maui
+```
+
+---
+
+> [!NOTE]
+> You can use `dotnet workload search` to detect any other available workloads you wish to use.
+
+## Setup Wine For Effect Compilation
+
+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](https://www.winehq.org/).
+
+MonoGame provides a setup script that can be executed to setup the Wine environment for Effect (shader) compilation.
+
+1. Open a terminal window
+2. Install Wine and required dependencies
+
+    ```sh
+    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 will 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
+    >
+    > ```sh
+    > sudo ln -s /usr/bin/wine /usr/local/bin/wine64
+    > ```
+
+3. Now that the prerequisites are installed, download the [mgfxc_wine_setup.sh](https://monogame.net/downloads/net8_mgfxc_wine_setup.sh) script and execute it by entering the following command in the terminal:
+
+    ```sh
+    wget -qO- https://monogame.net/downloads/net8_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 cancel/close this popup.  It's 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, just simply delete that directory.
+
+4. 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:
+
+    ```sh
+    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
+
+5. For the environment variable to take effect, you can either log out and back in (recommended) or reboot your system.
+
+6. After logging back in, verify the environment variable is set:
+
+    ```sh
+    echo $MGFXC_WINE_PATH
+    ```
+
+    > [!NOTE]
+    > When running the above command you should see an output similar to the following
+    >
+    > ```sh
+    > /home/yourusername/.winemonogame
+    > ```
+
+## Next Steps
+
+Choose from one of the two IDE options on Arch Linux:
+
+- [Setting up VSCode](./2_choosing_your_ide_vscode.md)
+- [Setting up Rider](./2_choosing_your_ide_rider.md)
+
+## Troubleshooting
+
+### Issue: "wine64 not found error"
+
+If the setup script fails with `wine64 not found`, ensure you created the symlink from step 2 above
+
+```sh
+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.  Ensure you:
+
+1. Added it to `/etc/environment` as shown above in step 4
+2. Logged out and logged back in
+3. 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:
+
+```sh
+wine --version
+```
+
+If it's too old, update your system:
+
+```sh
+sudo pacman -Syu
+```

articles/getting_started/2_choosing_your_ide_vscode.md

@@ -37,6 +37,43 @@ By the end, you will be fully equipped to start creating games with MonoGame usi
 2. Click the Download `.deb` button.
 3. Double click the `.deb` file and press the `Install` button.
 
+### [Arch Linux](#tab/arch)
+
+On Arch Linux, you have two options for installing Visual Studio Code:
+
+#### Option 1: Code OSS (Open Source Version)
+
+Code OSS is the fully open-source version available under the MIT License. It's available in the official Arch repositories and can be installed with a single command:
+
+```sh
+sudo pacman -S code
+```
+
+> [!IMPORTANT]
+> Code OSS **cannot** use the proprietary Microsoft **C# Dev Kit** extension. However, it can use the base **C#** extension (formerly OmniSharp, now LSP-based), which provides IntelliSense, syntax highlighting, debugging, and code navigation, sufficient for MonoGame development.
+
+#### Option 2: Visual Studio Code (Official Microsoft Version) - Recommended
+
+The official Microsoft version includes proprietary features like settings sync, Microsoft account integration, and **support for the C# Dev Kit extension**. It's available through the AUR (Arch User Repository).
+
+1. First, ensure you have an AUR helper installed. If you don't have one, install `yay`:
+
+    ```sh
+    sudo pacman -S git base-devel
+    git clone https://aur.archlinux.org/yay.git
+    cd yay
+    makepkg -si
+    ```
+
+2. Install Visual Studio Code using yay:
+
+    ```sh
+    yay -S visual-studio-code-bin
+    ```
+
+> [!TIP]
+> For the best MonoGame development experience with full C# Dev Kit support (enhanced project management, integrated testing, better solution support), install the official Visual Studio Code. Code OSS works but has limitations with Microsoft extensions.
+
 ---
 
 ## Setting up VS Code for development with MonoGame
@@ -68,6 +105,9 @@ To transform Visual Studio Code from a simple text editor into a powerful develo
 
 ![Install C# DevKit Extension](./images/1_setting_up_your_development_environment/vscode/install-devkit.png)
 
+> [!NOTE]
+> **For Arch Linux Code OSS users:** The C# Dev Kit extension is not compatible with Code OSS. Instead, install only the base **C#** extension (by Microsoft), which provides all the core functionality needed for MonoGame development including IntelliSense, debugging, and code navigation.
+
 ## (Optional) Install the "MonoGame for VSCode" extension
 
 A community member has built a VSCode extension for VS code to enable:
@@ -94,8 +134,10 @@ The .NET MAUI extension adds features for building mobile apps, including:
 ![Install .NET MAUI DevKit Extension](../tutorials/building_2d_games/02_getting_started/images/maui-extension.png)
 
 > [!NOTE]
-> This extension is recommended if you wish to do iOS or Android development. It is required for debugging support when working on mobile games. 
+> This extension is recommended if you wish to do iOS or Android development. It is required for debugging support when working on mobile games.
 
+> [!WARNING]
+> **For Arch Linux Code OSS users:** The .NET MAUI extension requires C# Dev Kit and therefore is not compatible with Code OSS. You will need to use the official Visual Studio Code for mobile development support.
 
 ## Creating a new MonoGame project
 

articles/toc.yml

@@ -10,8 +10,12 @@ items:
     items:
       - name: Setting up MacOS
         href: /articles/getting_started/1_setting_up_your_os_for_development_macos.html
-      - name: Setting up Ubuntu
-        href: /articles/getting_started/1_setting_up_your_os_for_development_ubuntu.html
+      - name: Setting up Linux
+        items:
+          - name: Setting up Arch Linux
+            href: /articles/getting_started/1_setting_up_your_os_for_development_arch.html
+          - name: Setting up Ubuntu
+            href: /articles/getting_started/1_setting_up_your_os_for_development_ubuntu.html
       - name: Setting up Windows
         href: /articles/getting_started/1_setting_up_your_os_for_development_windows.html
       - name: Using Visual Studio