diff --git a/articles/getting_started/1_setting_up_your_development_environment_unix.md b/articles/getting_started/1_setting_up_your_development_environment_unix.md deleted file mode 100644 index 39e5ca05..00000000 --- a/articles/getting_started/1_setting_up_your_development_environment_unix.md +++ /dev/null @@ -1,63 +0,0 @@ ---- -title: Setting up your development environment for macOS and Linux -description: This section provides a step-by-step guide for setting up your development environment on macOS and Linux. ---- - -The only development environment that MonoGame officially supports on Linux is [Visual Studio Code](https://code.visualstudio.com/). - -## Install .NET 8 SDK - -- .NET SDK at: [https://dotnet.microsoft.com/en-us/download](https://dotnet.microsoft.com/en-us/download) -- If you are intending to target mobile platforms, make sure that you have the corresponding workload installed - -```sh -dotnet workload install ios -dotnet workload install android -``` - -## macOS considerations - -For the time being, MonoGame requires that you install the x64 version of the .NET SDK even if you are running on an Apple Silicon mac. It is also required that [Rosetta](https://support.apple.com/en-us/HT211861) is enabled. - -## [Optional] Install Visual Studio Code - -You can install Visual Studio Code at: [https://code.visualstudio.com/Download](https://code.visualstudio.com/Download) - -In order to code and build C# projects, you will also need to install a Visual Studio Code C# extension. You can do this with the following commands: - -```sh -code --install-extension ms-dotnettools.csharp -``` - -If you want, you can also install the C# Dev Kit extensions, which are not open source: - -```sh -code --install-extension ms-dotnettools.csdevkit -code --install-extension ms-dotnettools.dotnet-maui -``` - -## Install MonoGame templates - -```sh -dotnet new --install MonoGame.Templates.CSharp -``` - -## [Optional] Setup Wine for effect compilation - -Effect (shader) compilation requires access to DirectX, so it will not work natively on Linux systems, but it can be used through Wine. Here are instructions to get this working (providing that your distribution is using apt). - -Install wine64: - -```sh -sudo apt install wine64 p7zip-full curl -``` - -Create wine prefix: - -```sh -wget -qO- https://monogame.net/downloads/net6_mgfxc_wine_setup.sh | bash -``` - -If you ever need to undo the script, simply delete the `.winemonogame` folder in your home directory. - -**Next up:** [Creating a new project](2_creating_a_new_project_netcore.md) diff --git a/articles/getting_started/1_setting_up_your_development_environment_vscode.md b/articles/getting_started/1_setting_up_your_development_environment_vscode.md deleted file mode 100644 index af59200b..00000000 --- a/articles/getting_started/1_setting_up_your_development_environment_vscode.md +++ /dev/null @@ -1,278 +0,0 @@ ---- -title: Setting up your development environment for VSCode -description: A step-by-step guide for setting up your development environment using VSCode ---- - -This is a guide on setting up your development environment for creating games with MonoGame using Visual Studio Code. By following this guide, you will learn how to install the necessary .NET SDK for developing C# applications, set up MonoGame C# templates for new projects, and configure Visual Studio Code with recommended extensions for C# development. By the end, you'll be fully equipped to start creating games with MonoGame using Visual Studio code. - -> [!NOTE] -> The only development environment that MonoGame officially supports on Linux is [Visual Studio Code](https://code.visualstudio.com/). -> -> [Visual Studio for Mac will be discontinued](https://devblogs.microsoft.com/visualstudio/visual-studio-for-mac-retirement-announcement/) by Microsoft in August 2024. At that time, [Visual Studio Code](https://code.visualstudio.com/) will be the only development environment supported by MonoGame on macOS. - -## Install .NET 8 SDK - -To develop with C#, you will need to install the .NET SDK. At the time of this writing, the current version is .NET 8.0. You can follow the instructions below based your operating system to install the .NET 8.0 SDK - -> [!NOTE] -> The current version of MonoGame (3.8.1.303) targets .NET 6.0. Regardless you can, and it is recommended to, use .NET 8.0. The only requirement for having .NET 6.0 installed is if you are developing extensions for the MGCB Editor. - -### [Windows](#tab/windows) - -1. Navigate to [https://dotnet.microsoft.com/en-us/download](https://dotnet.microsoft.com/en-us/download) - - ![Download .NET For Windows](./images/1_setting_up_your_development_environment/vscode/windows/download-dotnet.png) - -2. Click the **.NET SDK x64** download button to download. This will take you to the download page where the **dotnet-sdk-8.x.yyy-win-x64.exe** will download. -3. When the download completes, run the **dotnet-sdk-8.x.yyy-win-x64.exe** installer and complete the steps to install .NET on your machine. -4. When the install completes, open a new **Command Prompt** window and run the command `dotnet` to verify the installation was successful. - -![Verify Installation](./images/1_setting_up_your_development_environment/vscode/windows/verify-install.png) - -### [macOS](#tab/macos) - -1. Navigate to [https://dotnet.microsoft.com/en-us/download](https://dotnet.microsoft.com/en-us/download) - - ![Download .NET For Mac](./images/1_setting_up_your_development_environment/vscode/mac/download-dotnet.png) - -2. Download the .NET SDK x64-(Intel) Installer - - > [!NOTE] - > For the time being, MonoGame requires that you install the **.NET SDK x64-(Intel)** version of the .NET SDK even if you are running on an Apple Silicon (M1/M2) Mac. For Apple Silicon Macs, it also requires that [Rosetta](https://support.apple.com/en-us/HT211861) is enabled. - -3. Once the installation **.pkg** file finishes downloading, run it and follow the prompts to install the .NET SDK - - ![Install .NET For Mac](./images/1_setting_up_your_development_environment/vscode/mac/install-dotnet.png) - -4. Once the installation is complete, open a new terminal window and run the command `dotnet` to verify the installation was successful. - -![Verify Installation](./images/1_setting_up_your_development_environment/vscode/mac/verify-install.png) - -### [Linux](#tab/linux) - -1. Open a new **Terminal** window. -2. Enter the following command in the terminal to download the **dotnet-install.sh** - - ```sh - wget https://dot.net/v1/dotnet-install.sh -O dotnet-install.sh - ``` - -3. Grant permission for the script to execute by entering the following command in the terminal: - - ```sh - chmod +x ./dotnet-install.sh - ``` - -4. Run the script to install the .NET 8 SDK by entering the following command in the terminal: - - ```sh - ./dotnet-install.sh - ``` - - ![.NET Install Script](./images/1_setting_up_your_development_environment/vscode/linux/dotnet-install-script.png) - -5. You will now need to setup your environment variables so that the `dotnet` command is recognized. To do this, open the file `~/.bashrc` in a text editor and add the following lines to the end of the file. - - ```sh - export DOTNET_ROOT=$HOME/.dotnet - export PATH=$PATH:$DOTNET_ROOT:$DOTNET_ROOT/tools - ``` - - ![Add Environment Variables](./images/1_setting_up_your_development_environment/vscode/linux/add-environment-variables.png) - -6. Save and close the file, close any open terminal windows, then open a new terminal window so the new environment variables are registered. -7. Enter the `dotnet` command to validate that the .NET 8 SDK is now installed. - - ![Verify Installation](./images/1_setting_up_your_development_environment/vscode/linux/verify-install.png) - ---- - -> [!TIP] -> If you intend to target mobile platforms, you will also need to install the corresponding workloads. Enter the following commands in a command prompt/terminal -> -> ```sh -> dotnet workload install ios -> dotnet workload install android -> ``` - -## Install MonoGame Templates - -The .NET SDK installation provides the default C# project templates but does not include the MonoGame templates. These templates must be installed manually. - -1. Open a new terminal window (**Command Prompt** on Windows). - - ```sh - dotnet new install MonoGame.Templates.CSharp - ``` - - ![Install MonoGame Templates](./images/1_setting_up_your_development_environment/vscode/install-templates.png) - - > [!NOTE] - > When installing the templates, an error message may appear regarding the UWP template failing to install. This error can be safely ignored, as the UWP templates are deprecated and will be removed in a future MonoGame release. - -## Install Visual Studio Code - -### [Windows](#tab/windows) - -1. Open your web browser and navigate to [https://code.visualstudio.com/](https://code.visualstudio.com/). - - ![Download VSCode](./images/1_setting_up_your_development_environment/vscode/windows/download-vscode.png) - -2. Click the **Download for Windows** button. This will redirect you to the download page where the installer will automatically download. -3. When the download completes, run the installer and complete the steps to install Visual Studio Code. - -### [macOS](#tab/macos) - -1. Open your web browser and navigate to [https://code.visualstudio.com/](https://code.visualstudio.com/). - - ![Download VSCode](./images/1_setting_up_your_development_environment/vscode/mac/download-vscode.png) - -2. Click the **Download Mac Universal** button. This will redirect you to the page where the application archive (.zip) file will begin downloading. -3. Extract the contents of the VSCode archive that downloaded by double-clicking it inside a Finder window. This will extract the **Visual Studio Code.app** file. -4. Drag the **Visual Studio Code.app** file into the **Applications** folder, making it available in the macOS Launchpad. - -### [Linux](#tab/linux) - -The recommended method for installing Visual Studio Code in Linux is to use Snap. This is supported by most Linux distributions. - -- [Snap Package](https://code.visualstudio.com/docs/setup/linux#_snap) - -There are also individual guides below based on your Linux distribution if you do not want to use Snap: - -- [Debian and Ubuntu base distributions](https://code.visualstudio.com/docs/setup/linux#_debian-and-ubuntu-based-distributions) -- [RHEL, Fedora, and CentOS based distributions](https://code.visualstudio.com/docs/setup/linux#_rhel-fedora-and-centos-based-distributions) -- [openSUSE and SLE-based distributions](https://code.visualstudio.com/docs/setup/linux#_opensuse-and-slebased-distributions) -- [AUR package for Arch Linux](https://code.visualstudio.com/docs/setup/linux#_aur-package-for-arch-linux) -- [Installing .rpm package manually](https://code.visualstudio.com/docs/setup/linux#_installing-rpm-package-manually) - ---- - -## Install Visual Studio Code C# Extensions - -To transform Visual Studio Code from a simple text editor into a powerful development environment for C# projects, you must install the Visual Studio Code C# extension. This extension enhances the editor by providing syntax highlighting, code analysis, IntelliSense, and other features that significantly improve the development experience and productivity when working with C#. - -1. Open Visual Studio Code. -2. Click the **Extensions** icon in the **Activity Bar** on the left. - - ![Click Extensions](./images/1_setting_up_your_development_environment/vscode/click-extensions.png) - -3. In the **Search Box** type `C#`. -4. Click **Install** for the **C# Dev Kit** extension. Installing this will also install the base **C#** extension. - -![Install C# DevKit Extension](./images/1_setting_up_your_development_environment/vscode/install-devkit.png) - ---- - -## Setup Wine For Effect Compilation - MacOS/Linux Only - -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/). - -### [Windows](#tab/windows) - -> [!NOTE] -> Windows users do not require an additional setup for effect compilation and can skip this section. - -### [macOS](#tab/macos) - -MonoGame provides a setup script that can be executed to setup the Wine environment for Effect (shader) compilation. However, this script has the following prerequisites that must first be setup: - -- **curl** must be installed -- **p7zip** must be installed -- **wine-stable** must be installed. - -These can be installed using **brew**. - -1. Open a terminal window. -2. Enter the following command: - - ```sh - brew install p7zip curl - brew install --cask wine-stable - ``` - - > [!CAUTION] - > It is recommended that you use `wine-stable` and not `wine-staging`. - -3. Now that the prerequisites are installed, download the [mgfxc_wine_setup.sh](https://monogame.net/downloads/net6_mgfxc_wine_setup.sh) script and execute it by entering the following command in the terminal: - -```sh -wget -qO- https://monogame.net/downloads/net6_mgfxc_wine_setup.sh | bash -``` - -This will create new directory called `.winemonogame` in your home directory. If you ever wish to undo the setup this script performed, just simply delete that directory. - -### [Linux](#tab/linux) - -MonoGame provides a setup script that can be executed to setup the Wine environment for Effect (shader) compilation. However, this script has the following prerequisites that must first be setup: - -- **curl** must be installed -- **p7zip** must be installed -- **wine64** must be installed. - -For Debian-based distributions like Ubuntu, you can perform the following: - -1. Open a terminal window -2. Enter the following command - - ```sh - sudo apt install curl p7zip-full wine64 - ``` - - > [!TIP] - > If you receive an error stating that either 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 - > - > ```sh - > sudo add-apt-repository universe - > sudo apt update - > ``` - > - > Then try installing the packages again. - - > [!CAUTION] - > If you plan to install Wine using the `winehq-*` package instead, it is recommended that you use the `winehq-stable` package and not `-staging`. - -3. Now that the prerequisites are installed, download the [mgfxc_wine_setup.sh](https://monogame.net/downloads/net6_mgfxc_wine_setup.sh) script and execute it by entering the following command in the terminal: - - ```sh - wget -qO- https://monogame.net/downloads/net6_mgfxc_wine_setup.sh | bash - ``` - -This will create new directory called `.winemonogame` in your home directory. If you ever wish to undo the setup this script performed, just simply delete that directory. - ---- - -## Apple Silicon Known Issues - -There is currently a two known issue when building content on an Apple Silicon (M1/M2) Mac: - -1. **Building Textures**: An exception occurs stating that the **freeimage** lib could not be found. -2. **Building SpriteFonts**: An exception occurs stating that the **freetype** lib could not be found. -3. **Building Models**: An exception occurs starting that the **assimp** lib could not be found. - -These issue occur due to needing compiled versions of these libs for the M1/M2 architecture. [There is currently work being done to resolve this](https://github.com/MonoGame/MonoGame/issues/8124), however in the meantime, you can use the following workaround that has been provided by community members. - -1. Download and install the x64 version of [.NET 6](https://dotnet.microsoft.com/en-us/download/dotnet/6.0). This will place an x64 version of .NET 6 in a `/usr/local/share/dotnet/x64` directory. -NOTE: It MUST be the x64 version in order for this to work. This will allow the x64 native libraries that the MonoGame Content Pipeline uses to function on the Apple Silicon device. -Currently it also needs to be .NET 6 for the 3.8.1 Release of MonoGame. - -2. Open your .csproj and add the following lines to the first `` section. - - ```xml - /usr/local/share/dotnet/x64/dotnet - ``` - -3. (Alternative) The directory above is not in the path. But we do not want the system to be confused on which .NET is should be using. So rather thatn putting the x64 verison in the path we should instead create a symlink named `dotnet64`. - - ```sh - sudo ln -s /usr/local/share/dotnet/x64/dotnet /usr/local/share/dotnet/dotnet64 - ``` - -We can then use this value as the value for `DotnetCommand` - -```xml -dotnet64 -``` - -## Conclusion - -By following this guide, you have successfully set up your development environment for game development with MonoGame using Visual Studio Code. You've installed the .NET SDK, added MonoGame project templates, and configured Visual Studio Code with the necessary C# extensions. Now, you're ready to start creating your games! [Continue to the next section to create your first project and begin development](2_creating_a_new_project_netcore.md). diff --git a/articles/getting_started/1_setting_up_your_os_for_development_macos.md b/articles/getting_started/1_setting_up_your_os_for_development_macos.md new file mode 100644 index 00000000..4dab2d4e --- /dev/null +++ b/articles/getting_started/1_setting_up_your_os_for_development_macos.md @@ -0,0 +1,50 @@ +--- +title: Setting up your OS for development on MacOS +description: This section provides a step-by-step guide for setting up your development environment on Mac. +--- + +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. Navigate to [https://dotnet.microsoft.com/en-us/download/dotnet/8.0](https://dotnet.microsoft.com/en-us/download/dotnet/8.0) +2. Download the `.NET SDK` Installer for your current platform of `macOS` +3. Once the **.pkg** file finishes downloading, run it and follow the prompts to install the .NET SDK + + ![Download .NET For Windows](./images/1_setting_up_your_development_environment/dotnet_8_download_page.png) + +# Apple Silicon Known Issues + + For the time being, MonoGame requires that you install the x64 version of the .NET runtime if you are running on an Apple Silicon mac in order to be able to build content. It is also required that [Rosetta](https://support.apple.com/en-us/HT211861) is enabled. + + 1. Navigate to [https://dotnet.microsoft.com/en-us/download/dotnet/8.0](https://dotnet.microsoft.com/en-us/download/dotnet/8.0) + 2. Download the .NET Runtime Installer for macOS x64 + 3. Once the **.pkg** file finishes downloading, run it and follow the prompts to install the .NET Runtime + +## 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. Install [brew.sh](https://brew.sh) +2. Enter the following command: + + ```sh + brew install p7zip curl && brew install --cask wine-stable + ``` + +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 + ``` + +This will create new directory called `.winemonogame` in your home directory. If you ever wish to undo the setup this script performed, just simply delete that directory. + +## Next Steps + +Choose from one of the two IDE options on macOS: + +- [Setting up VSCode](./2_choosing_your_ide_vscode.md) +- [Setting up Rider](./2_choosing_your_ide_rider.md) diff --git a/articles/getting_started/1_setting_up_your_os_for_development_ubuntu.md b/articles/getting_started/1_setting_up_your_os_for_development_ubuntu.md new file mode 100644 index 00000000..baf0713d --- /dev/null +++ b/articles/getting_started/1_setting_up_your_os_for_development_ubuntu.md @@ -0,0 +1,55 @@ +--- +title: Setting up your OS for development on Ubuntu +description: This section provides a step-by-step guide for setting up your development environment on Windows. +--- + +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 download the **dotnet-install.sh** + + ```sh + sudo apt-get update && sudo apt-get install -y dotnet-sdk-8.0 + ``` + +This will ensure the latest .NET 8 SDK is installed and setup in your environment. + +## 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. Enter the following command + + ```sh + sudo apt install curl p7zip-full wine64 + ``` + + > [!TIP] + > If you receive an error stating that either 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 + > + > ```sh + > sudo add-apt-repository universe + > sudo apt update + > ``` + > + > Then try installing the packages again. + +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 + ``` + +This will create new directory called `.winemonogame` in your home directory. If you ever wish to undo the setup this script performed, just simply delete that directory. + +## Next Steps + +Choose from one of the two IDE options on Ubuntu: + +- [Setting up VSCode](./2_choosing_your_ide_vscode.md) +- [Setting up Rider](./2_choosing_your_ide_rider.md) diff --git a/articles/getting_started/1_setting_up_your_os_for_development_windows.md b/articles/getting_started/1_setting_up_your_os_for_development_windows.md new file mode 100644 index 00000000..13a75850 --- /dev/null +++ b/articles/getting_started/1_setting_up_your_os_for_development_windows.md @@ -0,0 +1,31 @@ +--- +title: Setting up your OS for development on Windows +description: This section provides a step-by-step guide for setting up your development environment on Windows. +--- + +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. + +> [!IMPORTANT] +> If your chosen IDE for development is [Visual Studio](https://visualstudio.microsoft.com/) then you can skip this step as .NET 8 is included with the Visual Studio Installer. + +## Install .NET 8 SDK + +You can follow the instructions below based your operating system to install the .NET 8.0 SDK + +1. Navigate to [https://dotnet.microsoft.com/en-us/download/dotnet/8.0](https://dotnet.microsoft.com/en-us/download/dotnet/8.0) + + ![Download .NET For Windows](./images/1_setting_up_your_development_environment/dotnet_8_download_page.png) + +2. Click the **.NET SDK x64** download button to download. This will take you to the download page where the **dotnet-sdk-8.x.yyy-win-x64.exe** will download. +3. When the download completes, run the **dotnet-sdk-8.x.yyy-win-x64.exe** installer and complete the steps to install .NET on your machine. +4. When the install completes, open a new **Command Prompt** window and run the command `dotnet` to verify the installation was successful. + + ![Verify Installation](./images/1_setting_up_your_development_environment/vscode/windows/verify-install.png) + +## Next Steps + +Choose from one of the three IDE options on Windows: + +- [Setting up Visual Studio](./2_choosing_your_ide_visual_studio.md) +- [Setting up VSCode](./2_choosing_your_ide_vscode.md) +- [Setting up Rider](./2_choosing_your_ide_rider.md) diff --git a/articles/getting_started/2_choosing_your_ide_rider.md b/articles/getting_started/2_choosing_your_ide_rider.md new file mode 100644 index 00000000..5b33f71d --- /dev/null +++ b/articles/getting_started/2_choosing_your_ide_rider.md @@ -0,0 +1,50 @@ +--- +title: Setting up your development environment for Rider +description: A step-by-step guide for setting up your development IDE for Rider +--- + +This is a guide on setting up your development environment for creating games with MonoGame using Rider by DevExpress. By following this guide, you will learn how to install the tools for developing C# applications and configure Rider with recommended extensions for C# development. + +By the end, you will be fully equipped to start creating games with MonoGame using Rider. + +## Install Rider + +You can download and install Rider from: [https://www.jetbrains.com/rider/download](https://www.jetbrains.com/rider/download) + +![Rider download](./images/2_chosing_your_ide_rider_download.png) + +> [!NOTE] +> Rider has a 30 day free trial license, but after that you will need to purchase one to continue using it. It is worth trying to see how it compares it VSCode. +> +> **Hint* - or visit a nearby .NET user group, who often have JetBrains licenses available as giveaways, as they are very a generous and supportive company. + +## Setting up Rider for development with MonoGame + +1. Open up terminal (or Powershell on Windows) +1. Run the following command to install templates: + + ```sh + dotnet new install MonoGame.Templates.CSharp + ``` + +## Creating a new MonoGame project + +To get you started with Rider, here are the steps for setting up a new Rider MonoGame project. + +1. Open up Rider +2. Click on the "New Solution" button + + ![Rider new project](./images/1_setting_up_your_development_environment/rider_new_solution_button.png) + +3. Select "MonoGame Cross-Platform Desktop Application" on the list on the left + + ![Rider MonoGame template](./images/1_setting_up_your_development_environment/rider_new_solution_dialog.png) + +4. Press "Create" +5. You can now press `F5` to compile and debug you game, happy coding :) + +## Next Steps + +Next, get to know MonoGame's code structure and project layout: + +- [Understanding the code](3_understanding_the_code.md) diff --git a/articles/getting_started/1_setting_up_your_development_environment_windows.md b/articles/getting_started/2_choosing_your_ide_visual_studio.md similarity index 51% rename from articles/getting_started/1_setting_up_your_development_environment_windows.md rename to articles/getting_started/2_choosing_your_ide_visual_studio.md index ae83b91d..c0e97742 100644 --- a/articles/getting_started/1_setting_up_your_development_environment_windows.md +++ b/articles/getting_started/2_choosing_your_ide_visual_studio.md @@ -1,23 +1,26 @@ --- -title: Setting up your development environment for Windows -description: This section provides a step-by-step guide for setting up your development environment on Windows. +title: Setting up Visual Studio on Windows +description: This section provides a step-by-step guide for setting up your development IDE on Windows for Visual Studio. --- MonoGame can work with most .NET compatible tools, but we recommend [Visual Studio 2022](https://visualstudio.microsoft.com/vs/) -Alternatively, you can use [JetBrains Rider](https://www.jetbrains.com/rider/) or [Visual Studio Code](https://code.visualstudio.com/). +> [!NOTE] +> Alternatively, you can use [JetBrains Rider](https://www.jetbrains.com/rider/) or [Visual Studio Code](https://code.visualstudio.com/). +> +> Check out the guides for [Setting up VSCode](./2_choosing_your_ide_vscode.md) / [Setting up Rider](./2_choosing_your_ide_rider.md) using these links. -## [Recommended] Install Visual Studio 2022 +## Install Visual Studio 2022 -Before using MonoGame, you will need to install [Visual Studio 2022](https://visualstudio.microsoft.com/vs/) +Before using MonoGame with Visual Studio you need to ensure you have installed the latest [Visual Studio 2022](https://visualstudio.microsoft.com/vs/) along with the required components. When installing Visual Studio, the following workloads are required depending on your desired [target platform(s)](./platforms.md): -* Mandatory for all platforms: - * **.Net desktop development** -* Optional - * **.Net Multi-platform App UI Development** if you wish to target Android, iOS, or iPadOS. - * **Universal Windows Platform development** if you wish to build for Windows store or Xbox. +- Mandatory for all platforms: + - **.Net desktop development** +- Optional + - **.Net Multi-platform App UI Development** if you wish to target Android, iOS, or iPadOS. + - **Universal Windows Platform development** if you wish to build for Windows store or Xbox. ![Visual Studio optional components](images/1_installer_vs_components.png) @@ -25,6 +28,8 @@ When installing Visual Studio, the following workloads are required depending on > **Targeting Windows** > > If you are targeting the standard Windows DirectX backend, you will also need [the DirectX June 2010 runtime](https://www.microsoft.com/en-us/download/details.aspx?id=8109) for audio and gamepads to work properly. +> +> Work is underway however to update to support DirectX 12 on Windows and Xbox very soon. ### Install MonoGame extension for Visual Studio 2022 @@ -51,16 +56,34 @@ To create new MonoGame projects from within Visual Studio 2022, you will need to You now have the MonoGame templates installed and are ready to create new projects. -**Next up:** [Creating a new project](2_creating_a_new_project_vs.md) +## Creating a new MonoGame project + +To get you started with Visual Studio, here are the steps for setting up a new MonoGame project. + +1. Start Visual Studio 2022 and select **New Project...** in the upper left corner. + + ![New Solution](images/vswin_mg_new_1.png) + +2. You should see the "Create a new project" dialog pop up. From here, select the **Templates > Visual C# > MonoGame** category, and then select **MonoGame Cross Platform Desktop Project**. + + ![New Template](images/vswin_mg_new_2.png) -## [Alternative] Install the .NET 6 SDK (compatible with JetBrains Rider and Visual Studio Code) +3. Next, type in a name for your project. For this tutorial, **Pong** will be used (note: project names cannot contain spaces). After you have entered the name, click on the **...** button next to the Location text field and choose the folder you want to save the project in. Finally, click **OK** to create the project. -If you prefer to use JetBrains Rider or Visual Studio Code, and after installing either of them, you will also need to [install the .NET 8 SDK](https://dotnet.microsoft.com/en-us/download/dotnet/8.0). + ![Project Name](images/vswin_mg_new_3.png) + +4. If everything went correctly, you should see a project named **Pong** open up like in the picture below. To run your game, simply press the big **Play Button** in the toolbar, or press **F5**. + + ![Project Start](images/vswin_mg_new_4.png) + +5. You should now see your game window running. + + ![Game](images/vswin_mg_new_5.png) + +--- -Once the .NET 8 SDK is installed, you can open a Command Prompt and install the MonoGame templates by typing the following command: +## Next Steps -```sh -dotnet new --install MonoGame.Templates.CSharp -``` +Next, get to know MonoGame's code structure and project layout: -**Next up:** [Creating a new project](2_creating_a_new_project_vs.md) +- [Understanding the code](3_understanding_the_code.md) \ No newline at end of file diff --git a/articles/getting_started/2_choosing_your_ide_vscode.md b/articles/getting_started/2_choosing_your_ide_vscode.md new file mode 100644 index 00000000..754e9b4b --- /dev/null +++ b/articles/getting_started/2_choosing_your_ide_vscode.md @@ -0,0 +1,96 @@ +--- +title: Setting up your development environment for VSCode +description: A step-by-step guide for setting up your development IDE using VSCode +--- + +This is a guide on setting up your development IDE for creating games with MonoGame using Visual Studio Code. By following this guide, you will learn how to install the necessary tools for developing C# applications and configure Visual Studio Code with recommended extensions for C# development. + +By the end, you will be fully equipped to start creating games with MonoGame using Visual Studio Code. + +## Install Visual Studio Code + +### [Windows](#tab/windows) + +1. Open your web browser and navigate to [https://code.visualstudio.com/](https://code.visualstudio.com/). + + ![Download VSCode](./images/1_setting_up_your_development_environment/vscode/windows/download-vscode.png) + +2. Click the **Download for Windows** button. This will redirect you to the download page where the installer will automatically download. +3. When the download completes, run the installer and complete the steps to install Visual Studio Code. + +### [macOS](#tab/macos) + +1. Open your web browser and navigate to [https://code.visualstudio.com/](https://code.visualstudio.com/). + + ![Download VSCode](./images/1_setting_up_your_development_environment/vscode/mac/download-vscode.png) + +2. Click the **Download Mac Universal** button. This will redirect you to the page where the application archive (.zip) file will begin downloading. +3. Extract the contents of the VSCode archive that downloaded by double-clicking it inside a Finder window. This will extract the **Visual Studio Code.app** file. +4. Drag the **Visual Studio Code.app** file into the **Applications** folder, making it available in the macOS Launchpad. + +### [Ubuntu](#tab/ubuntu) + +1. Open your web browser and navigate to [https://code.visualstudio.com/](https://code.visualstudio.com/). + + ![Download VSCode](./images/1_setting_up_your_development_environment/vscode/linux/download-vscode.png) + +1. Click the Download `.deb` button. +1. Double click the `.deb` installer to add VSCode into your installation. + +--- + +## Setting up VS Code for development with MonoGame + +1. Open Visual Studio Code +1. Open up its terminal window (`Ctrl/Cmd` + `J`) +1. Run the following command to install MonoGame Templates + + ```sh + dotnet new install MonoGame.Templates.CSharp + ``` + +## Install Visual Studio Code C# Extensions + +To transform Visual Studio Code from a simple text editor into a powerful development environment for C# projects, you must install the Visual Studio Code C# extension. This extension enhances the editor by providing syntax highlighting, code analysis, IntelliSense, and other features that significantly improve the development experience and productivity when working with C#. + +1. Open Visual Studio Code. +2. Click the **Extensions** icon in the **Activity Bar** on the left. + + ![Click Extensions](./images/1_setting_up_your_development_environment/vscode/click-extensions.png) + +3. In the **Search Box** type `C#`. +4. Click **Install** for the **C# Dev Kit** extension. Installing this will also install the base **C#** extension. + +![Install C# DevKit Extension](./images/1_setting_up_your_development_environment/vscode/install-devkit.png) + +## (Optional) Install the "MonoGame for VSCode" extension + +A community member has built a VSCode extension for VS code to enable: + +- Automatically install MonoGame templates +- Create new projects from the file menu or command palette +- Open the MGCB editor with the click of a button (very useful) + +You can find this extension by following the steps above and searching for "MonoGame for VS Code" by r88. + +> [!NOTE] +> While not built by the MonoGame team, we regularly use this extension ourselves and fully support it. + +## Creating a new MonoGame project + +1. Open up an empty folder in Visual Studio Code +1. Open up its terminal window (`Ctrl/Cmd` + `J`) +1. Run the following command to create an empty project for desktop platforms: + + ```sh + dotnet new mgdesktopgl + ``` + +1. When VS Code asks you about automatic creation of launch / task files, press yes +1. You can now press F5 to compile and debug you game, happy coding :) + +## Next Steps + +Next, get to know MonoGame's code structure and project layout: + +- [Understanding the code](3_understanding_the_code.md) diff --git a/articles/getting_started/2_creating_a_new_project_netcore.md b/articles/getting_started/2_creating_a_new_project_netcore.md deleted file mode 100644 index c0464e19..00000000 --- a/articles/getting_started/2_creating_a_new_project_netcore.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: .NET CLI (JetBrains Rider or Visual Studio Code) -description: A step-by-step guide for creating a new project using JetBrains Rider or Visual Studio Code. ---- - -This guide will walk you through building a starter game with MonoGame using only the command line/terminal on your operating system and a lightweight coding tool of your choice (such as [Visual Studio Code](https://code.visualstudio.com/) or [JetBrains Rider](https://www.jetbrains.com/rider/)). - -> [!NOTE] -> It is assumed that you have already properly installed the .NET 8 SDK and MonoGame. - -> [!IMPORTANT] -> Be aware that for iOS/iPadOS and Android, development might be limited when using the .NET CLI. Many of the development features for those targets are exclusive to Visual Studio 2022. - -## Create a MonoGame Project - -You can now create new MonoGame projects. To do that: - -- Create a new directory for your project. - -- Open a new terminal window or command prompt and navigate to your project directory. - -- Run `dotnet new -o ` to create your project, where `` is a platform identifier, and `` the name of your project. - -For example: - -```cli -dotnet new mgdesktopgl -o MyGame -``` - -> To know which platform identifier (short name) to use for your project, please refer to [Target Platforms](./platforms.md), or type the following command into the command prompt to list the installed templates and their corresponding short names: -> -> ```cli -> dotnet new -l -> ``` - -Once created, you can open your code editor of choice in the new folder and begin editing. - -> To run your project, check the instructions for [packaging your game](./packaging_games.md) to build the executable using the .NET tooling. - -**Next up:** [Understanding the code](3_understanding_the_code.md) diff --git a/articles/getting_started/2_creating_a_new_project_vs.md b/articles/getting_started/2_creating_a_new_project_vs.md deleted file mode 100644 index 85160a38..00000000 --- a/articles/getting_started/2_creating_a_new_project_vs.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: Creating a Project with Visual Studio 2022 -description: A step-by-step guide for creating a new project using Visual Studio ---- - -This guide will walk you through building a starter game with MonoGame using Windows and Visual Studio 2022. - -> [!NOTE] -> It is assumed that you have already properly installed Visual Studio 2022 and MonoGame. - -Start Visual Studio 2022 and select **New Project...** in the upper left corner. - -![New Solution](images/vswin_mg_new_1.png) - -You should see the "Create a new project" dialog pop up. From here, select the **Templates > Visual C# > MonoGame** category, and then select **MonoGame Cross Platform Desktop Project**. - -![New Template](images/vswin_mg_new_2.png) - -Next, type in a name for your project. For this tutorial, **Pong** will be used (note: project names cannot contain spaces). After you have entered the name, click on the **...** button next to the Location text field and choose the folder you want to save the project in. Finally, click **OK** to create the project. - -![Project Name](images/vswin_mg_new_3.png) - -If everything went correctly, you should see a project named **Pong** open up like in the picture below. To run your game, simply press the big **Play Button** in the toolbar, or press **F5**. - -![Project Start](images/vswin_mg_new_4.png) - -You should now see your game window running. - -![Game](images/vswin_mg_new_5.png) - -**Next up:** [Understanding the code](3_understanding_the_code.md) diff --git a/articles/getting_started/3_understanding_the_code.md b/articles/getting_started/3_understanding_the_code.md index 2ba87509..7a106cf9 100644 --- a/articles/getting_started/3_understanding_the_code.md +++ b/articles/getting_started/3_understanding_the_code.md @@ -6,21 +6,21 @@ description: This tutorial will go over the code that is generated when you star > [!NOTE] > For help with creating a project, please look at the Creating a New Project section of the [Getting Started guide](index.md). -Within the **Game.cs** class file, which is the core of any MonoGame project, you will find several critical sections necessary for your game to run: +Within the `Game.cs` class file, which is the core of any MonoGame project, you will find several critical sections necessary for your game to run: -* **Using statements** - which provide easy access to the various components of MonoGame. +- `Using statements` - which provide easy access to the various components of MonoGame. -* The **Game Class** definition - the heart of any MonoGame project. +- The `Game` Class definition - the heart of any MonoGame project. -* The **Game constructor** and key variables - which tell the project how to start. +- The `Game constructor` and key variables - which tell the project how to start. -* The **Initialize** method - to initialize the game upon its startup. +- The `Initialize` method - to initialize the game upon its startup. -* The **Load and Unload Content** methods - which are used to add and remove assets from the running game from the [Content project](4_adding_content.md). +- The `Load and Unload Content` methods - which are used to add and remove assets from the running game from the [Content project](4_adding_content.md). -* The **Update** method - which is called on a regular interval to update your game state, e.g. take player inputs, move ships, or animate entities. +- The `Update` method - which is called on a regular interval to update your game state, e.g. take player inputs, move ships, or animate entities. -* The **Draw** method - which is called on a regular interval to take the current game state and draw your game entities to the screen. +- The `Draw` method - which is called on a regular interval to take the current game state and draw your game entities to the screen. Read further for more details and examples while looking through the code of your new project. @@ -45,7 +45,7 @@ These using statements make it easier to use the code that MonoGame has to offer public class Game1 : Game ``` -The main **Game1** class inherits from the **Game** class, which provides all the core methods for your game (ie. Load/Unload Content, Update, Draw etc.). You usually only have one Game class per game, so its name is not that important. +The main `Game1` class inherits from the `Game` class, which provides all the core methods for your game (ie. Load/Unload Content, Update, Draw etc.). You usually only have one Game class per game, so its name is not that important. ## Instance Variables @@ -54,7 +54,7 @@ GraphicsDeviceManager graphics; SpriteBatch spriteBatch; ``` -The two default variables that the blank template starts with are the **GraphicsDeviceManager** and **SpriteBatch**. Both of these variables are used for drawing to the screen, as you will see in a later tutorial. +The two default variables that the blank template starts with are the `GraphicsDeviceManager` and `SpriteBatch`. Both of these variables are used for drawing to the screen, as you will see in a later tutorial. ## Constructor @@ -66,7 +66,7 @@ public Game1() } ``` -The main game constructor is used to initialize the starting variables. In this case, a new **GraphicsDeviceManager** is created, and the root directory containing the game's content files is set. +The main game constructor is used to initialize the starting variables. In this case, a new `GraphicsDeviceManager` is created, and the root directory containing the game's content files is set. ## Initialize Method @@ -79,7 +79,7 @@ protected override void Initialize() } ``` -The **Initialize** method is called after the constructor but before the main game loop (Update/Draw). This is where you can query any required services and load any non-graphic related content. +The `Initialize` method is called after the constructor but before the main game loop (Update/Draw). This is where you can query any required services and load any non-graphic related content. ## LoadContent Method @@ -93,7 +93,7 @@ protected override void LoadContent() } ``` -The **LoadContent** method is used to load your game content. It is called only once per game, within the **Initialize** method, before the main game loop starts. +The `LoadContent` method is used to load your game content. It is called only once per game, within the `Initialize` method, before the main game loop starts. ## Update Method @@ -109,7 +109,7 @@ protected override void Update(GameTime gameTime) } ``` -The **Update** method is called multiple times per second, and it is used to update your game state (checking for collisions, gathering input, playing audio, etc.). +The `Update` method is called multiple times per second, and it is used to update your game state (checking for collisions, gathering input, playing audio, etc.). ## Draw Method @@ -124,6 +124,12 @@ protected override void Draw(GameTime gameTime) } ``` -Similar to the Update method, the **Draw** method is also called multiple times per second. This, as the name suggests, is responsible for drawing content to the screen. +Similar to the Update method, the `Draw` method is also called multiple times per second. This, as the name suggests, is responsible for drawing content to the screen. -**Next up:** [Adding Content](4_adding_content.md) +--- + +## Next Steps + +Next, learn how to add and import content into your game project: + +- [Adding Content](4_adding_content.md) diff --git a/articles/getting_started/4_adding_content.md b/articles/getting_started/4_adding_content.md index a8ae2052..25e678b3 100644 --- a/articles/getting_started/4_adding_content.md +++ b/articles/getting_started/4_adding_content.md @@ -4,13 +4,18 @@ description: This tutorial will go over adding content such as images or sounds --- > [!NOTE] -> For help with creating a project, please look at the [Creating a New Project](index.md) section of the Getting Started guide. +> this tutorial continues from where [3. Understanding the Code](3_understanding_the_code.md) left off. ## MonoGame Content Builder Tool (MGCB Editor) -This tutorial assumes that you are using Visual Studio 2022 with its MonoGame extension installed. If you are not using the extension, you will need to manually install and use the [MGCB Editor](./tools/mgcb_editor.md). +The [MGCB Editor](./tools/mgcb_editor.md) is used to organize and build content for use with MonoGame. It is accessed by either: -> This is technically optional, since you can edit the .mgcb files manually if you wish, but the editor is highly recommended for ease of use. +- Double-clicking a "`.mgcb`" file from within the Visual Studio solution explorer (providing that you installed [MonoGame's Visual Studio extension](./2_choosing_your_ide_visual_studio.md#install-monogame-extension-for-visual-studio-2022)). +- Right-clicking a "`.mgcb`" file from within the Visual Studio code and selecting "Open in MGCB Editor" (provided you have installed the [VSCode extension](./2_choosing_your_ide_vscode.md#optional-install-the-monogame-for-vscode-extension)) + +Alternatively, you can build it [directly from source](https://github.com/MonoGame/MonoGame/tree/develop/Tools/MonoGame.Content.Builder.Editor) if needed. + +> This is all technically optional, since you can edit the `.mgcb` files manually if you wish, but the editor is highly recommended for ease of use. ## Adding content @@ -18,41 +23,45 @@ First, you will need some content for your game. For this tutorial, use the foll ![Open Content](images/ball.png) -Copy the image to your machine by using **right-click > Save Image As** and save it somewhere locally with the name “ball.png”. - -Now open up your game project and look at the Solution Explorer window. Expand the **Content** folder and open up **Content.mgcb** file by double-clicking on it. +Copy the image to your machine by using `right-click > Save Image As` and save it somewhere locally with the name “ball.png”. -![Open Content](images/3_open_content.png) +## Open the MGCB Editor -You should now see the MGCB Editor window open up. If a text file opens instead, then right-click on **Content.mgcb** and select **Open With**, then select **MGCB Editor** in the list, click **Set as Default** and then click **OK**, then try again. +- In Visual Studio you can up your game project and look at the Solution Explorer window. Expand the `Content` folder and open up `Content.mgcb` file by double-clicking on it. +- Right-clicking a "`.mgcb`" file from within the Visual Studio code and selecting "Open in MGCB Editor". -> If you do not see the **MGCB Editor** option when you right-click and select **Open With**, then please review the [Tools documentation](./tools/index.md) for installing the MGCB Editor tool for your operating system. +You should now see the MGCB Editor window open up. ![MGCB Editor](images/3_mgcb_editor_tool.png) +>[!NOTE] +> If a text file opens instead, then right-click on `Content.mgcb` and select `Open With`, then select `MGCB Editor` in the list, click `Set as Default` and then click `OK`, then try again. +> +> If you do not see the `MGCB Editor` option when you right-click and select `Open With`, then please review the [Tools documentation](./tools/index.md) for installing the MGCB Editor tool for your operating system. + +## Understanding the MGCB Editor + Your game content is managed from this external tool. You can add content to your game in one of the following ways: -- **Add Existing Item** toolbar button -- **Edit > Add > Existing Item...** menu button -- **right-click > Add > Existing Item...** context menu +- `Add Existing Item` toolbar button +- `Edit > Add > Existing Item...` menu button +- `right-click > Add > Existing Item...` context menu -Make sure the "Content" MGCB file is selected to the left, then click the **Add Existing Item** toolbar button. +Make sure the "Content" Node is selected to the left, then click the `Add Existing Item` toolbar button. ![Add Content](images/3_add_content.png) -You should now be prompted to select a file. Select the “**ball.png**” image that you downloaded a moment ago. Once you have confirmed your selection, you will be asked whether to copy the file, add a link to it, or skip it. Make sure "**Copy the file to the directory**" option is selected and click **Add**. +You should now be prompted to select a file. Select the `ball.png` image that you downloaded a moment ago. Once you have confirmed your selection, you will be asked whether to copy the file, add a link to it, or skip it. Make sure ``Copy the file to the directory`` option is selected and click `Add`. ![Copy Content](images/3_copy_content.png) -Now click the **Save** toolbar button and close the MGCB Editor tool. +Now click the `Save` toolbar button and close the MGCB Editor tool. ![Save Content](images/3_save_content.png) ---- - ## Adding the content in your game -Now that you have added the asset to the Content project, it is time to load it into your game. First, open up the **Game1.cs** class file and declare a new **ballTexture** variable of type **Texture2D** in the **Game1** class, so you can store the ball image into memory. +Now that you have added the asset to the Content project, it is time to load it into your game. First, open up the `Game1.cs` class file and declare a new `ballTexture` variable of type `Texture2D` in the `Game1` class, so you can store the ball image into memory. ```csharp public class Game1 : Game @@ -63,7 +72,7 @@ public class Game1 : Game private SpriteBatch _spriteBatch; ``` -Next, find the **LoadContent** method. Here, use **Content.Load()** function to load the "ball" sprite and store it in the **ballTexture** parameter. **Content.Load()** requires you to specify what type of content you are trying to load, in this case it is a **Texture2D**. +Next, find the `LoadContent` method. Here, use `Content.Load()` function to load the "ball" sprite and store it in the `ballTexture` parameter. `Content.Load()` requires you to specify what type of content you are trying to load, in this case it is a `Texture2D`. ```csharp protected override void LoadContent() @@ -78,13 +87,13 @@ protected override void LoadContent() Finally, find the Draw method to draw the ball onto the screen. This is done by: -- Opening a SpriteBatch (an image drawing collection function). +- Opening a `SpriteBatch` (an image drawing collection function) by calling the `Begin` function. - Adding the images you want to draw and specifying where you want to draw them. -- Then finally closing the SpriteBatch to commit the textures you want drawn to the screen. +- Then finally finishing the `SpriteBatch` to commit the textures you want drawn to the screen by calling the `End` function. -> **Note**: if you add multiple images, they will be drawn in the order you place them from back to front (each drawn on top of each other). +> `Note`: if you add multiple images, they will be drawn in the order you place them from back to front (each drawn on top of each other). As shown below: @@ -106,4 +115,10 @@ Now run the game. You should get the following: ![Game](images/3_game.png) -**Next up:** [Adding Basic Code](5_adding_basic_code.md) +--- + +## Next Steps + +Next, learn how to get your first basic game concept running: + +- [Adding Basic Code](5_adding_basic_code.md) diff --git a/articles/getting_started/5_adding_basic_code.md b/articles/getting_started/5_adding_basic_code.md index d035913b..8c69a58a 100644 --- a/articles/getting_started/5_adding_basic_code.md +++ b/articles/getting_started/5_adding_basic_code.md @@ -4,36 +4,40 @@ description: This tutorial will go over adding basic logic to your game --- > [!NOTE] -> this tutorial continues from where [4. Adding Content](4_adding_content.md) left off. - ---- +> this tutorial continues from where [5. Adding Content](4_adding_content.md) left off. ## Positioning the content -First, you need to add few new variables in the Game1.cs class file: one for position and one for speed. +First, you need to add few new variables in the `Game1.cs` class file: A `Vector2` for position and a `float` for speed. ```csharp -public class Game1 : Game -{ - Texture2D ballTexture; - Vector2 ballPosition; - float ballSpeed; + public class Game1 : Game + { + _graphics = new GraphicsDeviceManager(this); + Content.RootDirectory = "Content"; + Texture2D ballTexture; + Vector2 ballPosition; + float ballSpeed; + } ``` -Next, you need to initialize them. Find the **Initialize** method and add the following lines. +Next, you need to initialize them. Find the `Initialize` method and add the following lines. ```csharp -// TODO: Add your initialization logic here -ballPosition = new Vector2(_graphics.PreferredBackBufferWidth / 2, -_graphics.PreferredBackBufferHeight / 2); -ballSpeed = 100f; - -base.Initialize(); + protected override void Initialize() + { + // TODO: Add your initialization logic here + ballPosition = new Vector2(_graphics.PreferredBackBufferWidth / 2, + _graphics.PreferredBackBufferHeight / 2); + ballSpeed = 100f; + + base.Initialize(); + } ``` -With this, you are setting the ball's starting position to the center of the screen based on the dimensions of the screen determined by the current **BackBufferWidth** and **BackBufferHeight** that was obtained from the Graphics Device (the current resolution the game is running at). +With this, you are setting the ball's starting position to the center of the screen based on the dimensions of the screen determined by the current `BackBufferWidth` and `BackBufferHeight` that was obtained from the `Graphics Device` (the current resolution the game is running at). -Lastly, change the Draw method to draw the ball at the correct position. Find the **Draw** method and update the **spriteBatch.Draw** call to: +Lastly, change the `Draw` method to draw the ball at the correct position. Find the `Draw` method and update the `spriteBatch.Draw` call to: ```csharp _spriteBatch.Draw(ballTexture, ballPosition, Color.White); @@ -43,7 +47,7 @@ Now run the game. ![Draw Ball 1](images/4_ball_not_center.png) -As you can see, the ball is not quite centered yet. That is because the default origin of a texture is its top-left corner, or (0, 0) relative to the texture, so the ball texture is drawn with its top-left corner exactly centered, rather than its actual center. You can specify a different origin when drawing, as shown in the following code snippet. The new origin takes into account the height and width of the image when drawing: +As you can see, the ball is not quite centered yet. That is because the default `origin` of a texture is its `top-left corner`, or `(0, 0)` relative to the texture. The ball texture is drawn with its top-left corner exactly centered, rather than its actual center. You can specify a different origin when drawing, as shown in the following code snippet. The new origin takes into account the height and width of the image when drawing: ```csharp _spriteBatch.Draw( @@ -59,74 +63,105 @@ _spriteBatch.Draw( ); ``` -This change adds a few extra parameters to the spriteBatch.Draw call, but do not worry about that for now. This new code sets the actual center (width / 2 and height / 2) of the image as its origin (drawing point). +> [!NOTE] +> For more details on drawing textures, check out the [How To Draw a Sprite](../getting_to_know/howto/graphics/HowTo_Draw_A_Sprite.md) series which goes in to greater detail. + +This change adds a few extra parameters to the spriteBatch.Draw call, but do not worry about that for now. This new code sets the actual center `(width / 2 and height / 2)` of the image as its origin (drawing point). Now the image will get drawn to the center of the screen. ![Draw Ball 2](images/4_ball_center.png) ---- - -## Getting user input +## Getting user input via keyboard -Time to set up some movement. Find the **Update** method in the Game1.cs class file and add: +Time to set up some movement. Find the `Update` method in the `Game1.cs` class file and add: ```csharp -// TODO: Add your update logic here -var kstate = Keyboard.GetState(); + protected override void Update(GameTime gameTime) + { + if (GamePad.GetState(PlayerIndex.One).Buttons.Back == ButtonState.Pressed || + Keyboard.GetState().IsKeyDown(Keys.Escape)) + Exit(); + + // TODO: Add your update logic here + + // The time since Update was called last. + float updatedBallSpeed = ballSpeed * (float)gameTime.ElapsedGameTime.TotalSeconds; + + var kstate = Keyboard.GetState(); + + if (kstate.IsKeyDown(Keys.Up)) + { + ballPosition.Y -= updatedBallSpeed; + } + + if (kstate.IsKeyDown(Keys.Down)) + { + ballPosition.Y += updatedBallSpeed; + } + + if (kstate.IsKeyDown(Keys.Left)) + { + ballPosition.X -= updatedBallSpeed; + } + + if (kstate.IsKeyDown(Keys.Right)) + { + ballPosition.X += updatedBallSpeed; + } + + base.Update(gameTime); + } +``` -if (kstate.IsKeyDown(Keys.Up)) -{ - ballPosition.Y -= ballSpeed * (float)gameTime.ElapsedGameTime.TotalSeconds; -} +The following is a line-by-line analysis of the above code. -if (kstate.IsKeyDown(Keys.Down)) -{ - ballPosition.Y += ballSpeed * (float)gameTime.ElapsedGameTime.TotalSeconds; -} +### Calculating speed based on framerate -if (kstate.IsKeyDown(Keys.Left)) -{ - ballPosition.X -= ballSpeed * (float)gameTime.ElapsedGameTime.TotalSeconds; -} +```csharp +float updatedBallSpeed = ballSpeed * (float)gameTime.ElapsedGameTime.TotalSeconds; +``` -if (kstate.IsKeyDown(Keys.Right)) -{ - ballPosition.X += ballSpeed * (float)gameTime.ElapsedGameTime.TotalSeconds; -} +This code caches how much time, in seconds, since the last `Update` call was run, which gives us the duration of a single frame drawn to the screen. This is then multiplied by the `ballSPeed` value to allow us to control just how fast the ball moves each frame. -base.Update(gameTime); -``` +The reason why `ballSpeed` is multiplied by `gameTime.ElapsedGameTime.TotalSeconds` is because, when not using fixed time step, the time between Update calls varies. To account for this, the ballSpeed is multiplied by the amount of time that has passed since the last Update call. The result is that the ball appears to move at the same speed regardless of what framerate the game happens to be running at. -The following is a line-by-line analysis of the above code. +> [!NOTE] +> Try experimenting with what happens if you do not multiply the `ballSpeed` by `gameTime.ElapsedGameTime.TotalSeconds`, to see the difference it makes. + +### Getting Keyboard state ```csharp var kstate = Keyboard.GetState(); ``` -This code fetches the current keyboard state ('Keyboard.GetState()') and stores it into a variable called **kstate**. +This code fetches the current keyboard state (`Keyboard.GetState()`) and stores it into a variable called `kstate`. + +### Checking Keyboard state ```csharp if (kstate.IsKeyDown(Keys.Up)) ``` -This line checks to see if the Up Arrow key is pressed. +This line checks to see if the `Up Arrow` key is pressed. + +### Updating the graphics position to draw to ```csharp - ballPosition.Y -= ballSpeed * (float)gameTime.ElapsedGameTime.TotalSeconds; + ballPosition.Y -= updatedBallSpeed; ``` -If the **Up Arrow** key is pressed, the ball moves using the value you assigned to **ballSpeed**. The reason why **ballSpeed** is multiplied by **gameTime.ElapsedGameTime.TotalSeconds** is because, when not using fixed time step, the time between Update calls varies. To account for this, the ballSpeed is multiplied by the amount of time that has passed since the last Update call. The result is that the ball appears to move at the same speed regardless of what framerate the game happens to be running at. - -> Try experimenting with what happens if you do not multiply the **ballSpeed** by **gameTime.ElapsedGameTime.TotalSeconds**, to see the difference it makes. +If the `Up Arrow` key is pressed, the ball moves using the value you assigned to by the calculated `ballSpeed` variable. -The rest of the lines of code do the same thing but for the Down, Left and Right Arrow keys, and down, left, and right movement, respectively. +The rest of the lines of code do the same thing but for the `Down`, `Left` and `Right` Arrow keys, and down, left, and right movement, respectively. If you run the game, you should be able to move the ball with the arrow keys. +## Getting user input via Joystick / GamePad + Another option for user input is the or classes. Setting up input for Joysticks and GamePads is very similar to setting up keyboard input, the following example is designed while using a single joystick connected to the host, to support more, you will need to evaluate all the connected joysticks and read their input (see for reference). -Find the **Update** method in the Game1.cs class file and add: +Find the `Update` method in the Game1.cs class file and add: ```csharp if(Joystick.LastConnectedIndex == 0) @@ -157,35 +192,48 @@ if(Joystick.LastConnectedIndex == 0) The following is a line-by-line analysis of the above code. +### Check Joysticks connection state + ```csharp if(Joystick.LastConnectedIndex == 0) ``` -This code assumes that we have a single controller plugged into our device. `LastConnectedIndex` is the index of the last connected controller. The default is `-1`, which would mean no controller is plugged in. +This code assumes that we have a single controller plugged into our device. `LastConnectedIndex` is the index of the last connected controller. The default is `-1`, which would mean no controller is plugged in. If there is no controller, the code inside the if statement will be skipped over. +### Get the current state of Joystick 1 + ```csharp JoystickState jstate = Joystick.GetState(0); ``` -This code fetches the current first joystick state `Joystick.GetState(0)` and stores it into a variable called **`jstate`**. +This code fetches the current first joystick state `Joystick.GetState(0)` and stores it into a variable called `jstate`. + +### CHeck the current value of "Axis" 2 ```csharp if (jstate.Axes[1] < 0) ``` -This line checks whether the second Joystick axis is less than 0. The Joystick class stores multiple axis of direction for anything with an integer based range. For any number of 2D axis sticks, it stores it in an x,y format inside of an integer array. -The axis of movement for 2D joysticks goes from -32768 to 32768 on most modern controllers. Aiming the Joystick upwards results in a negative value on the Y-axis `Axes[1]`. +This line checks whether the "second" `Joystick axis` is less than 0. + +> [!NOTE] +> The Joystick class stores multiple axis of direction for anything with an integer based range. For any number of 2D axis sticks, it stores it in an x,y format inside of an integer array. + +The axis of movement for 2D joysticks goes from `-32768` to `32768` on most modern controllers. Aiming the Joystick upwards results in a negative value on the `Y-axis` (Axes[1]). The rest of the lines of the code do the same thing but for their relevant x and y directions. If you run the game, you should be able to move the ball with the left Joystick on your controller if one is plugged in. For GamePads, just use the `GamePad` versions of the same `JoyStick` classes, but remember, GamePads usually have multiple "sticks" for the left and right hand sides of the controller. -You will probably notice that the ball slightly moves on its own. This will likely be the result of your Joystick having a slight drift. You can fix that by adding a deadzone and changing the conditions to use this deadzone. +## Handling "Dead Zones" with Joysticks/GamePads + +You will probably notice that the ball slightly moves on its own when controlled via a JoyStick or GamePad, which is likely be the result of your Joystick having a slight drift, a common scenario. You can fix that by adding a `deadzone` and changing the conditions to use this `deadzone` (a value range that needs to be exceeded in order to "act" on the Joystick/Keyboard input). ```csharp public class Game1 : Game { + ... Texture2D ballTexture; Vector2 ballPosition; float ballSpeed; @@ -193,13 +241,13 @@ public class Game1 : Game int deadZone; ``` -Next, you need to initialize the deadzone. Find the **Initialize** method and add the following lines. +Next, you need to initialize the deadzone. Find the `Initialize` method and add the following line. ```csharp deadZone = 4096; ``` -Now, replace the conditions for the Joystick movement in **Update** to the following: +Now, replace the conditions for the Joystick movement in `Update` to the following: ```csharp if (jstate.Axes[1] < -deadZone) @@ -222,14 +270,18 @@ else if (jstate.Axes[0] > deadZone) ``` If you run the game and move the Joystick around, you should notice that your Joystick has to move a decent distance before the ball starts moving. This is what a deadZone does, it allows for there to be a minimum distance before the input is reflected in the game. + +> [!NOTE] > Try experimenting with what happens when you change the value of the deadZone. Mess around and find an amount that fits your project. +## Handling screen borders + You will probably notice that the ball is not confined to the window. You can fix that by setting bounds onto the ballPosition after it has already been moved to ensure it cannot go further than the width or height of the screen. ```csharp if (kstate.IsKeyDown(Keys.Right)) { - ballPosition.X += ballSpeed * (float)gameTime.ElapsedGameTime.TotalSeconds; + ballPosition.X += updatedBallSpeed; } if (ballPosition.X > _graphics.PreferredBackBufferWidth - ballTexture.Width / 2) @@ -257,6 +309,16 @@ Now run the game to test for yourself that the ball cannot go beyond the window Happy Coding ^^ +--- + +## Next Steps + +We recommend browsing through the [Getting to know MonoGame](../getting_to_know/index.md) section to learn more and get some tips and tricks from the MonoGame team. + +- [Getting to know MonoGame](../getting_to_know/index.md) +- [What Is articles](../getting_to_know/whatis/index.md) +- [How To articles](../getting_to_know/howto/index.md) + ## Further Reading 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. diff --git a/articles/getting_started/content_pipeline/using_mgcb_editor.md b/articles/getting_started/content_pipeline/using_mgcb_editor.md index c47c5e41..fcaa15b9 100644 --- a/articles/getting_started/content_pipeline/using_mgcb_editor.md +++ b/articles/getting_started/content_pipeline/using_mgcb_editor.md @@ -3,9 +3,10 @@ title: Using MGCB Editor description: Learn how to use the MGCB Editor to organize and build content for use with MonoGame. --- -# Using MGCB Editor +The [MGCB Editor](../tools/mgcb_editor.md) is used to organize and build content for use with MonoGame. It is accessed by either: -The [MGCB Editor](../tools/mgcb_editor.md) is used to organize and build content for use with MonoGame. It is accessed by double-clicking a "**.mgcb**" file from within the Visual Studio solution explorer (providing that you installed [MonoGame's Visual Studio extension](../1_setting_up_your_development_environment_windows.md)). +* Double-clicking a "**.mgcb**" file from within the Visual Studio solution explorer (providing that you installed [MonoGame's Visual Studio extension](../2_choosing_your_ide_visual_studio.md#install-monogame-extension-for-visual-studio-2022)). +* Right-clicking a "**.mgcb**" file from within the Visual Studio code and selecting "Open in MGCB Editor" (provided you have installed the [VSCode extension](../2_choosing_your_ide_vscode.md#install-visual-studio-code-c-extensions)) Alternatively, you can build it [directly from source](https://github.com/MonoGame/MonoGame/tree/develop/Tools/MonoGame.Content.Builder.Editor) if needed. diff --git a/articles/getting_started/images/1_setting_up_your_development_environment/dotnet_8_download_page.png b/articles/getting_started/images/1_setting_up_your_development_environment/dotnet_8_download_page.png new file mode 100644 index 00000000..3ba1abe4 Binary files /dev/null and b/articles/getting_started/images/1_setting_up_your_development_environment/dotnet_8_download_page.png differ diff --git a/articles/getting_started/images/1_setting_up_your_development_environment/rider_new_solution_button.png b/articles/getting_started/images/1_setting_up_your_development_environment/rider_new_solution_button.png new file mode 100644 index 00000000..dfc6f49e Binary files /dev/null and b/articles/getting_started/images/1_setting_up_your_development_environment/rider_new_solution_button.png differ diff --git a/articles/getting_started/images/1_setting_up_your_development_environment/rider_new_solution_dialog.png b/articles/getting_started/images/1_setting_up_your_development_environment/rider_new_solution_dialog.png new file mode 100644 index 00000000..4e8c9e89 Binary files /dev/null and b/articles/getting_started/images/1_setting_up_your_development_environment/rider_new_solution_dialog.png differ diff --git a/articles/getting_started/images/2_chosing_your_ide_rider_download.png b/articles/getting_started/images/2_chosing_your_ide_rider_download.png new file mode 100644 index 00000000..5d957c78 Binary files /dev/null and b/articles/getting_started/images/2_chosing_your_ide_rider_download.png differ diff --git a/articles/getting_started/index.md b/articles/getting_started/index.md index e735023e..b51d5b6f 100644 --- a/articles/getting_started/index.md +++ b/articles/getting_started/index.md @@ -5,19 +5,44 @@ description: This section walks you through the basics of MonoGame, and helps yo First, select the operating system and toolset you will be working with to create your first MonoGame project, then continue reading to understand the basic layout of a MonoGame project. +## [Supported platforms](./platforms.md) + +MonoGame supports the following platforms by default: + +- Windows +- macOS +- Linux +- iOS +- iPadOS +- Android +- Xbox* +- PlayStation 4* +- PlayStation 5* +- Nintendo Switch* +- Google Stadia* + +> [!IMPORTANT] +> Platforms marked with a *"*"* require developer access from their host vendor platforms. + +See [Supported Platforms](./platforms.md) for more information. + +## Setting up and creating your first MonoGame Project + By the end of this tutorial set, you will have a working project to build for your target platform and will be ready to tackle your next steps. -## 1. Setting up your development environment +### 1. Setting up your OS for development -- [Windows](1_setting_up_your_development_environment_windows.md) -- [macOS and Linux](1_setting_up_your_development_environment_unix.md) +- [Windows](./1_setting_up_your_os_for_development_windows.md) +- [macOS](./1_setting_up_your_os_for_development_macos.md) +- [Ubuntu 20.04](./1_setting_up_your_os_for_development_ubuntu.md) -## 2. Creating a new project +### 2. Choosing your IDE for development -- With [Visual Studio 2022](2_creating_a_new_project_vs.md) -- With [the .NET command line interface](2_creating_a_new_project_netcore.md) (compatible with JetBrains Rider and Visual Studio Code) +- [Visual Studio for Windows](./2_choosing_your_ide_visual_studio.md) +- [VS Code](./2_choosing_your_ide_vscode.md) +- [Rider](./2_choosing_your_ide_rider.md) -## 3. Building your game +### 3. Building your game - [Understanding the Code](3_understanding_the_code.md) - [Adding Content](4_adding_content.md) diff --git a/articles/getting_started/packaging_games.md b/articles/getting_started/packaging_games.md index 26763cea..9c1b738a 100644 --- a/articles/getting_started/packaging_games.md +++ b/articles/getting_started/packaging_games.md @@ -7,7 +7,9 @@ description: How to package your game for distribution. To publish desktop games, it is recommended that you build your project as a [self-contained](https://docs.microsoft.com/en-us/dotnet/core/deploying/#publish-self-contained) .NET application. As such, your game will require absolutely no external dependencies and should run out-of-the-box as-is. -### Building and packaging for Windows +### Building and packaging + +### [Windows](#tab/windows) From the .NET CLI: @@ -17,17 +19,7 @@ You can then zip the content of the publish folder and distribute the archive as If you are targeting WindowsDX, note that players will need [the DirectX June 2010 runtime](https://www.microsoft.com/en-us/download/details.aspx?id=8109) to be installed on their machine for audio and gamepads to work properly. -### Building and packaging for Linux - -From the .NET CLI: - -`dotnet publish -c Release -r linux-x64 /p:PublishReadyToRun=false /p:TieredCompilation=false --self-contained` - -You can then archive the content of the publish folder and distribute the archive as-is. - -We recommend using the .tar.gz archiving format to preserve the execution permissions. - -### Build and packaging for macOS +### [macOS](#tab/macos) From the .NET CLI: @@ -115,6 +107,18 @@ After completing these steps, your .app folder should appear as an executable ap For archiving, we recommend using the .tar.gz format to preserve the execution permissions (you will likely run into permission issues if you use .zip at any point). +### [Ubuntu](#tab/ubuntu) + +From the .NET CLI: + +`dotnet publish -c Release -r linux-x64 /p:PublishReadyToRun=false /p:TieredCompilation=false --self-contained` + +You can then archive the content of the publish folder and distribute the archive as-is. + +We recommend using the .tar.gz archiving format to preserve the execution permissions. + +--- + ## Special notes about .NET parameters .NET proposes several parameters when publishing apps that may sound helpful, but have many issues when it comes to games (because they were never meant for games in the first place, but for small lightweight applications). @@ -146,10 +150,6 @@ While it sounds very convenient, be aware that it's not magical and is in fact a We highly recommend not using it for better compatibility across systems. -## Windows Store games - -Please refer to the [Windows Store documentation](https://docs.microsoft.com/en-us/windows/uwp/publish/). - ## Mobile games Please refer to the Xamarin documentation: diff --git a/articles/getting_started/platforms.md b/articles/getting_started/platforms.md index 35dbde1d..8d967db3 100644 --- a/articles/getting_started/platforms.md +++ b/articles/getting_started/platforms.md @@ -43,6 +43,9 @@ Beside these target platforms, MonoGame provides additional templates for shared WindowsDX uses WinForms to manage the game window, **DirectX** (9.0c or newer) is used for graphics, and XAudio is used for audio. +> [!NOTE] +> DX 12 for Windows and Xbox coming very soon. + You can target **Windows*** 8.1 and up with this platform. WindowsDX requires the [DirectX June 2010](https://www.microsoft.com/en-us/download/details.aspx?id=8109) runtime to both build and run games. Make sure that your players have it installed (otherwise you might be missing sound and gamepad rumble support). @@ -65,6 +68,9 @@ You can target Windows 8.1 (and up), macOS Catalina 10.15 (and up), and Linux wi DesktopGL currently does not have a `VideoPlayer` implementation. +> [!NOTE] +> New native platform with upgraded libraries and Metal/Vulkan support coming very soon. + ### Android | **Supported Systems** | **NuGet Package** | **Template ID** | @@ -77,6 +83,9 @@ Building for Android requires the .NET Xamarin component to be installed. You ca Building for Android also requires the Java 11 JDK (we recommend that you use [the Microsoft's distribution](https://docs.microsoft.com/en-us/java/openjdk/download#openjdk-11)) as well as the Android SDK 31. +> [!NOTE] +> New native platform with upgraded libraries and Metal/Vulkan support coming very soon. + ### iOS | **Supported Systems** | **NuGet Package** | **Template ID** | @@ -91,6 +100,9 @@ The latest version of Xcode will also be required. You can test and deploy an iOS game on Windows by [pairing your Visual Studio 2022 with a mac on your local network](https://docs.microsoft.com/en-us/xamarin/ios/get-started/installation/windows/connecting-to-mac/). This feature is not available for Rider, Visual Studio Code, or the CLI. +> [!NOTE] +> New native platform with upgraded libraries and Metal/Vulkan support coming very soon. + ## Other templates ### .NET Class Library @@ -99,6 +111,9 @@ You can test and deploy an iOS game on Windows by [pairing your Visual Studio 20 A project template to create [.NET](https://learn.microsoft.com/en-us/dotnet/standard/class-library-overview) libraries to distribute code through a DLL. This can be used to redistribute libraries or to share code between multiple projects (like different platforms). +> [!NOTE] +> See the [MonoGame Samples](https://github.com/MonoGame/MonoGame.Samples) for examples of how a .NET class library is used to share code between platforms. + ### Shared Project **Template ID**: mgshared @@ -110,3 +125,6 @@ A project template to create a [shared project](https://docs.microsoft.com/en-us **Template ID**: mgpipeline A project template for writing custom logic for handling content and building it into XNB files. + +> [!NOTE] +> See [What Is the Content Pipeline?](../getting_to_know/whatis/content_pipeline/CP_Overview.md) for more infomation and read about [What is a Custom Importer](../getting_to_know/whatis/content_pipeline/CP_AddCustomProcImp.md) here. diff --git a/articles/toc.yml b/articles/toc.yml index 5fa23a5c..a0c3b666 100644 --- a/articles/toc.yml +++ b/articles/toc.yml @@ -5,25 +5,28 @@ - name: What's New href: whats_new.md - name: Getting Started + href: getting_started/index.md items: - name: Introduction href: getting_started/ - name: Supported platforms - href: getting_started/platforms.md - - name: 1. Setting up your development environment + href: getting_started/platforms.md + - name: 1. Setting up your OS for development items: - name: Windows - href: getting_started/1_setting_up_your_development_environment_windows.md - - name: macOS / Linux - href: getting_started/1_setting_up_your_development_environment_unix.md - - name: VSCode - href: getting_started/1_setting_up_your_development_environment_vscode.md - - name: 2. Creating a new project + href: getting_started/1_setting_up_your_os_for_development_windows.md + - name: macOS + href: getting_started/1_setting_up_your_os_for_development_macos.md + - name: Ubuntu 20.04 + href: getting_started/1_setting_up_your_os_for_development_ubuntu.md + - name: 2. Choosing your IDE items: - - name: Visual Studio 2022 - href: getting_started/2_creating_a_new_project_vs.md - - name: .NET CLI (Rider or Visual Studio Code) - href: getting_started/2_creating_a_new_project_netcore.md + - name: Visual Studio for Windows + href: getting_started/2_choosing_your_ide_visual_studio.md + - name: VSCode + href: getting_started/2_choosing_your_ide_vscode.md + - name: Rider + href: getting_started/2_choosing_your_ide_rider.md - name: 3. Understanding the Code href: getting_started/3_understanding_the_code.md - name: 4. Adding Content diff --git a/external/MonoGame b/external/MonoGame index fb3ba797..ca12d948 160000 --- a/external/MonoGame +++ b/external/MonoGame @@ -1 +1 @@ -Subproject commit fb3ba7979fb119a7331be03bdcc498f4cc49aa43 +Subproject commit ca12d948d7838cfb427f3ab6d1ecd851ec9cfdf8