Skip to content

Commit 312ca66

Browse files
Merge pull request MonoGame#3 from AristurtleDev/2d-tutorial-bounty--chapter-02
Added Chapter 02
2 parents b5c0f80 + c883b2e commit 312ca66

File tree

7 files changed

+211
-7
lines changed

7 files changed

+211
-7
lines changed

articles/getting_started/5_adding_basic_code.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -319,6 +319,6 @@ We recommend browsing through the [Getting to know MonoGame](../getting_to_know/
319319

320320
## Further Reading
321321

322-
Check out the [Tutorials section](../tutorials.md) for many more helpful guides and tutorials on building games with MonoGame. We have an expansive library of helpful content, all provided by other MonoGame developers in the community.
322+
Check out the [Tutorials section](../tutorials/index.md) for many more helpful guides and tutorials on building games with MonoGame. We have an expansive library of helpful content, all provided by other MonoGame developers in the community.
323323

324324
Additionally, be sure to check out the official [MonoGame Samples](../samples.md) page for fully built sample projects built with MonoGame and targeting our most common platforms.

articles/help_and_support.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ description: Where to get help and support when using MonoGame.
55

66
# Help and Support
77

8-
There is a wealth of [community created content, blogs and tutorials](tutorials.md) available.
8+
There is a wealth of [community created content, blogs and tutorials](tutorials/index.md) available.
99

1010
If you want to find an answer to a more specific problem, you can ask it on our [GitHub Discussions](https://github.com/MonoGame/MonoGame/discussions) page.
1111

articles/toc.yml

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -114,8 +114,8 @@
114114
items:
115115
- name: "01: What Is MonoGame?"
116116
href: tutorials/building_2d_games/01_what_is_monogame/
117-
- name: Community Tutorials
118-
href: tutorials.md
117+
- name: "02: Getting Started"
118+
href: tutorials/building_2d_games/02_getting_started/
119119
- name: Console Access
120120
href: console_access.md
121121
- name: Help and Support
Loading
Loading
Lines changed: 203 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,203 @@
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 />

articles/tutorials/building_2d_games/index.md

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -19,9 +19,10 @@ This documentation will introduce game development concepts using the MonoGame f
1919
> [!CAUTION]
2020
> This is currently a work in progress and is not finished.
2121
22-
| Chapter | Summary | Source Files |
23-
| -------------------- | -------------------------------------------------------------------------------- | ------------ |
24-
| [01: What Is Monogame](01_what_is_monogame) | The history of MonoGame and what features it provides developers to create games | |
22+
| Chapter | Summary | Source Files |
23+
| ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | ------------ |
24+
| [01: What Is Monogame](01_what_is_monogame/index.md) | The history of MonoGame and what features it provides developers to create games. | |
25+
| [02: Getting Started](02_getting_started/index.md) | setup with MonoGame by preparing your environment for dotnet development and setting up Visual Studio Code as your IDE. | |
2526

2627
In additional to the chapter documentation, supplemental documentation is also provided to give a more in-depth look at different topics with MonoGame. These are provided through the Appendix documentation below:
2728

0 commit comments

Comments
 (0)