|
| 1 | +--- |
| 2 | +title: "Chapter 02: Getting Started" |
| 3 | +description: In this chapter, you'll get setup with MonoGame by preparing your environment for dotnet development and setting up Visual Studio Code as your IDE. |
| 4 | +--- |
| 5 | + |
| 6 | +Unlike game engines, MonoGame is a *framework*. This means it does not come as a standalone program that you download an install with a graphical user interface used to create games. Instead, MonoGame integrates into the standard .NET development workflow, offering a code-first approach to game development. This approach offers several advantages |
| 7 | + |
| 8 | +* **Flexibility**: Developers are not locked into using a specific editor or interface, allowing them to use their preferred development tools. |
| 9 | +* **Integration**: As a .NET library itself, MonoGame can easily integrate with other .NET libraries and tools. |
| 10 | +* **Cross-platform Development**: Since C# is cross-platform, and MonoGame is cross-platform, developers can develop MonoGame projects on Windows, macOS, or Linux, with only slight differences in the setup process for each operating system. |
| 11 | +* **Version Control Friendly**: The code-first approach makes it easier to use version control systems like Git for you game projects. |
| 12 | + |
| 13 | +While the environment setup process is similar to the standard setup process for C# development, there are some MonoGame specific steps. These can vary slightly depending on your operating system and the *Integrated Development Environment* (IDE). |
| 14 | + |
| 15 | +## Installing the .NET SDK |
| 16 | + |
| 17 | +The first thing we need to do is install the .NET *Software Development Kit* (SDK). At the time of this writing, MonoGame targets the .NET 8.0 SDK. To install it, follow the instructions based on your operating system below |
| 18 | + |
| 19 | +### Windows |
| 20 | +1. Open a web browser and navigate to https://dotnet.microsoft.com/en-us/download. |
| 21 | +2. Click the *Download .NET SDK x64* button to start the download of the .NET SDK Installer. |
| 22 | +3. Once the download finishes, run the installer |
| 23 | + |
| 24 | +### macOS |
| 25 | +1. Open a web browser and navigate to https://dotnet.microsoft.com/en-us/download. |
| 26 | +2. Click the *Download .NET SDK x64 (Intel)* button start the download of the .NET SDK Installer |
| 27 | +3. Once the download finishes, run the installer. |
| 28 | + |
| 29 | +> [!NOTE] |
| 30 | +> 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](https://support.apple.com/en-us/HT211861) is enabled. |
| 31 | +
|
| 32 | +### Linux |
| 33 | +1. Open a new *Terminal* window |
| 34 | +2. Enter the following command to install the .NET SDK |
| 35 | + |
| 36 | +```sh |
| 37 | +sudo apt-get update && sudo apt-get install -y dotnet-sdk-8.0 |
| 38 | +``` |
| 39 | + |
| 40 | +## Install Additional Workloads (Optional) |
| 41 | + |
| 42 | +After installing the .NET SDK, if you intend to target mobile devices such as Android or iOS, you will also need to install the corresponding mobile workloads. To do this, open a *Command Prompt* or *Terminal* window and enter the following commands |
| 43 | + |
| 44 | +```sh |
| 45 | +dotnet workload install ios |
| 46 | +dotnet workload install android |
| 47 | +``` |
| 48 | + |
| 49 | +## Install MonoGame Project Templates |
| 50 | + |
| 51 | +MonoGame provides project templates that can be installed to create new projects that are pre-configured to target the current version of MonoGame as a base to begin creating games. As of this writing, the current version of MonoGame targeted is 3.8.2.1105. To install the MonoGame templates, open a *Command Prompt* or *Terminal* window and enter the following command |
| 52 | + |
| 53 | +```sh |
| 54 | +dotnet new install MonoGame.Templates.CSharp |
| 55 | +``` |
| 56 | + |
| 57 | +## Installing Visual Studio Code |
| 58 | + |
| 59 | +*Visual Studio Code* (VSCode) is a free, light weight editor. Depending on the programming language you are using, it's just a matter of installing the correct extension to support that language. VSCode is also cross-platform, meaning you can use it for development on Windows, macOS, and Linux. To ensure that all readers can follow this tutorial regardless of operating system, we'll be using VSCode as our IDE. |
| 60 | + |
| 61 | +To install VSCode, follow the instructions for your operating system below: |
| 62 | + |
| 63 | +### Windows |
| 64 | +1. Open a browser and navigate to https://code.visualstudio.com/. |
| 65 | +2. Click the *Download for Windows* button to start the download of the installer. |
| 66 | +3. Once the download finishes, run the installer. |
| 67 | + |
| 68 | +### macOS |
| 69 | + |
| 70 | +1. Open a web browser and navigate to https://code.visualstudio.com/. |
| 71 | +2. Click the *Download for macOS* button to start the download of the *.zip* archive. |
| 72 | +3. Once the download finishes, double click the *.zip* archive to extract the *Visual Studio Code.app* application package |
| 73 | +4. Drag-and-drop the *Visual Studio Code.app* application package into your *Application* directory to make it available in the macOS *LaunchPad*. |
| 74 | + |
| 75 | +### Linux |
| 76 | +1. Open a web browser and navigate to https://code.visualstudio.com/. |
| 77 | +2. Click the *.deb* download button to download the package for Debian based Linux distributions, or the *.rpm* download button for Red Hat based Linux distributions. |
| 78 | +3. Once the download finishes, open the package downloaded to install. |
| 79 | + |
| 80 | +## Install the C# Dev Kit Extension |
| 81 | + |
| 82 | +For C# development using VSCode, it's recommended to use the official *C# Dev Kit* extension provided by Microsoft. Installing this extension will add additional features to VSCode such as a project system and *Solution Explorer* for C# projects. It also provides code editing features such as syntax highlighting, code completion, code navigation, refactoring, NuGet package management, and debugging tools. |
| 83 | + |
| 84 | +To install the C# Dev Kit extension, perform the following: |
| 85 | + |
| 86 | +1. Launch the Visual Studio Code application. |
| 87 | +2. Open the *Extensions Panel* by clicking the icon in the *Activity Bar* on the left or choosing *View > Extensions* from the top menu. |
| 88 | +3. Enter `C#` in the *Search Box* |
| 89 | +4. Click install for the *C# Dev Kit* extension. |
| 90 | + |
| 91 | +> [!NOTE] |
| 92 | +> When you search `C#` in the *Extension Panel* you may notice there is the C# Dev Kit extension and a base standard C# extension. When installing the C# Dev Kit extension, the base extension will also be installed as a requirement. |
| 93 | +
|
| 94 | +## Installing the "MonoGame for VSCode" Extension |
| 95 | + |
| 96 | +Throughout this tutorial, we'll be using the MonoGame Content Builder (MGCB) Editor to add content to the game. MonoGame offers an official extension for Visual Studio 2022 that allows you to double-click the *Content.mgcb* file to automatically open it in the MGCB Editor. While there is no official tool for VSCode, there is a an extension developed by community member r88 to provide similar functionality and is regularly used by the MonoGame developers themselves. We'll be using that extension throughout this tutorial. |
| 97 | + |
| 98 | +To install it, with VSCode open: |
| 99 | + |
| 100 | +1. Open the *Extensions Panel* by clicking the icon in the *Activity Bar* on the left or choosing *View > Extensions* from the top menu. |
| 101 | +2. Enter `MonoGame for VSCode` as in the *Search Box* |
| 102 | +3. Click install for the *MonoGame for VSCode* extension by r88. |
| 103 | + |
| 104 | +## Setup WINE for Effect Compilation (macOS and Linux Only) |
| 105 | + |
| 106 | +*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. Below you can find the steps based on your operating system. To do this, follow the instructions for your operating system below: |
| 107 | + |
| 108 | +### macOS |
| 109 | +Open a new *Terminal* window and enter execute the following commands: |
| 110 | + |
| 111 | +```sh |
| 112 | +brew install p7zip |
| 113 | +brew install --cask wine-stable |
| 114 | +wget -qO- https://monogame.net/downloads/net8_mgfxc_wine_setup.sh | bash |
| 115 | +``` |
| 116 | + |
| 117 | +### Linux |
| 118 | +Open a new *Terminal* window and execute the following commands: |
| 119 | + |
| 120 | +```sh |
| 121 | +sudo apt-get update && sudo apt-get install -y curl p7zip-full wine64 |
| 122 | +wget -qO- https://monogame.net/downloads/net8_mgfxc_wine_setup.sh | bash |
| 123 | +``` |
| 124 | + |
| 125 | +> [!NOTE] |
| 126 | +> After performing these steps, regardless of macOS or Linux, a new directory called *.winemonogame* will be created in your home directory. If you ever wish to undo the setup this script performed, you can just simply delete this directory. |
| 127 | +
|
| 128 | +## Creating Your First MonoGame Application |
| 129 | + |
| 130 | +Now that you have your development environment setup, it's time to create your first MonoGame application. |
| 131 | + |
| 132 | +1. Launch the VSCode application |
| 133 | +2. Open the *Command Palette* by clicking *View > Command Palette* or by using the keyboard shortcut `CTRL+SHIFT+P`. |
| 134 | +3. Type `.NET New Project` in the *Command Palette* and choose the *.NET New Project* command |
| 135 | +4. Next you'll be shown a list of the available .NET project templates. Enter `MonoGame` into the prompt to filter the project templates to only show the MonoGame ones, then choose the *MonoGame Cross-Platform Desktop Application* project template. |
| 136 | +5. After choosing the template, a dialog window will appear asking you to choose a location to save the project. |
| 137 | +6. Next you'll be prompted to enter a name for the project. Enter the name `MonoGameSnake`. |
| 138 | +7. Finally, select the *Create Project* prompt. |
| 139 | + |
| 140 | +After selecting *Create Project*, a new C# project will be created based on the MonoGame template we choose and opened automatically in VSCode. |
| 141 | + |
| 142 | +<figure><img src="./images/vscode.png" alt="Figure 2-1: A new MonoGame project after being created in Visual Studio Code"><figcaption><p><em>Figure 2-1: A new MonoGame project after being created in Visual Studio Code</em></p></figcaption></figure> |
| 143 | + |
| 144 | +Now that we have the project created, press the `F5` key on your keyboard, or choose *Run > Start Debugging* from the top menu. If prompted for a configuration, choose *C#*. The project will compile and run, displaying a screen similar to the following |
| 145 | + |
| 146 | +<figure><img src="./images/cornflower-blue.png" alt="Figure 2-2: The default MonoGame cornflower blue game window."><figcaption><p><em>Figure 2-2: The default MonoGame cornflower blue game window.</em></p></figcaption></figure> |
| 147 | + |
| 148 | +Be amazed, the default MonoGame Cornflower Blue game window. You have just created your very first MonoGame application. While there isn't much happening here visually, there is a log going on behind the scenes that the MonoGame framework is handling for you. When you ran the application, the following occurred: |
| 149 | + |
| 150 | +1. The application started |
| 151 | +2. The game window was created and graphics were initialized |
| 152 | +3. A loop is entered which performs the following over and over until the game is told to exit: |
| 153 | + 1. The game is updated |
| 154 | + 2. The game is rendered to the window |
| 155 | + |
| 156 | +You can exit the game at any time by pressing the `Esc` key on your keyboard. |
| 157 | + |
| 158 | +> [!NOTE] |
| 159 | +> Above, I mentioned that a loop is entered. This is commonly referred to as the *game loop*, which we'll discuss in more detail in the next chapter. The reason the application enters this loop is because game applications work differently than a traditional desktop application like your web browser. |
| 160 | +> |
| 161 | +> Desktop application are event based, meaning once loaded, the do not do much at all while waiting for input from the user, and then it response to that input event and redraws the window if needed based on the interaction. |
| 162 | +> |
| 163 | +> In games, things are always happening such as objects moving around like the player or particles. The handle this, games implement a loop structure that runs continuously, first calling a method to update the game logic, and then a draw method to render the current frame, until it has been told to exit. |
| 164 | +
|
| 165 | +## Conclusion |
| 166 | + |
| 167 | +Let's review what you accomplished in this chapter: |
| 168 | + |
| 169 | +* You setup your operating system to develop .NET applications by installing the .NET SDK |
| 170 | +* You install the MonoGame project templates. |
| 171 | +* You installed VSCode and the necessary extension to develop C# applications with VSCode |
| 172 | +* You created and ran your first MonoGame project. |
| 173 | + |
| 174 | +Now that your development environment is setup and ready to go, you can dive in and start building your first game. In the next chapter, we'll cover the contents of the *Game1.cs* file that was included in the MonoGame project you just created. |
| 175 | + |
| 176 | +## Test Your Knowledge |
| 177 | + |
| 178 | +1. What version of the .NET SDK is currently targeted by MonoGame applications? |
| 179 | + |
| 180 | + <details> |
| 181 | + <summary>Question 1 Answer</summary> |
| 182 | + |
| 183 | + > .NET 8.0 |
| 184 | +
|
| 185 | + </details><br /> |
| 186 | + |
| 187 | +2. What is the current version of MonoGame? |
| 188 | + |
| 189 | + <details> |
| 190 | + <summary>Question 2 Answer</summary> |
| 191 | + |
| 192 | + > 3.8.2.1105 |
| 193 | +
|
| 194 | + </details><br /> |
| 195 | + |
| 196 | +3. What is the color of the game window when you run a MonoGame project for the first time? |
| 197 | + |
| 198 | + <details> |
| 199 | + <summary>Question 3 Answer</summary> |
| 200 | + |
| 201 | + > Cornflower Blue |
| 202 | +
|
| 203 | + </details><br /> |
0 commit comments