Merge pull request #38 from MonoGame/feature/content_update

Migration of XNA upgraded documentation and general tidy up

Author: SimonDarksideJ

articles/getting_started/1_setting_up_your_development_environment_unix.md

@@ -1,15 +1,11 @@
 ---
 title: Setting up your development environment for macOS and Linux
-description: A step-by-step guide for setting up your development environment on macOS and Linux.
+description: This section provides a step-by-step guide for setting up your development environment on macOS and Linux.
 ---
 
-# Setting up your development environment for macOS and Linux
-
-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 6 SDK
+## 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
@@ -34,6 +30,7 @@ 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

articles/getting_started/1_setting_up_your_development_environment_vscode.md

@@ -1,12 +1,8 @@
 ---
 title: Setting up your development environment for Windows
-description: A step-by-step guide for setting up your development environment on Windows.
+description: This section provides a step-by-step guide for setting up your development environment on Windows.
 ---
 
-# Setting up your development environment for Windows
-
-This section provides a step-by-step guide for setting up your development environment on Windows.
-
 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/).
@@ -37,31 +33,31 @@ To create new MonoGame projects from within Visual Studio 2022, you will need to
 1. Launch Visual Studio 2022
 2. Select **Continue without code**.  This will launch Visual Studio without any project or solution opened.
 
-![Visual Studio Launcher Continue Without Code](images/1_continue_without_code.png)
+    ![Visual Studio Launcher Continue Without Code](images/1_continue_without_code.png)
 
 3. Click "*Extensions -> Manage Extensions* in the Visual Studio 2022 menu bar.  This will open the Manage Extensions dialog window.
 
-![Extensions -> Manage Extensions Menu Selection](images/1_visual_studio_extension_menu.png)
+    ![Extensions -> Manage Extensions Menu Selection](images/1_visual_studio_extension_menu.png)
 
 4. Use the search box in the top-right corner of the Manage Extensions dialog window to search for **MonoGame**, then click the **MonoGame Framework C# project templates** extension as shown below and download it to install it.
 
-![Visual Studio Extension Manager](images/1_visual_studio_extension_manager.png)
+    ![Visual Studio Extension Manager](images/1_visual_studio_extension_manager.png)
 
 5. After it is downloaded, an alert will appear at the bottom of the Manage Extensions window that states "Your changes will be scheduled.  The modifications will begin when all Microsoft Visual Studio windows are closed."  Click the **Close** button, then close Visual Studio 2022.
 
 6. After closing Visual Studio 2022, a VSIX Installer window will open confirming that you want to install the **MonoGame Framework C# project templates** extension.  Click the **Modify** button to accept the install.
 
-![VSIX Installer Window](images/1_vsix_installer_window.png)
+    ![VSIX Installer Window](images/1_vsix_installer_window.png)
 
 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)
 
 ## [Alternative] Install the .NET 6 SDK (compatible with JetBrains Rider and Visual Studio Code)
 
-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 6 SDK](https://dotnet.microsoft.com/en-us/download/dotnet/6.0).
+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).
 
-Once the .NET 6 SDK is installed, you can open a Command Prompt and install the MonoGame templates by typing the following command:
+Once the .NET 8 SDK is installed, you can open a Command Prompt and install the MonoGame templates by typing the following command:
 
 ```sh
 dotnet new --install MonoGame.Templates.CSharp

articles/getting_started/1_setting_up_your_development_environment_windows.md

@@ -1,14 +1,14 @@
 ---
-title: Creating a new project
+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.
 ---
 
-# .NET CLI (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/)).
 
-> It is assumed that you have already properly installed the .NET 6 SDK and MonoGame.
+> [!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
@@ -23,13 +23,13 @@ You can now create new MonoGame projects. To do that:
 
 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
 > ```
 

articles/getting_started/2_creating_a_new_project_netcore.md

@@ -1,12 +1,11 @@
 ---
-title: Creating a new project
+title: Creating a Project with Visual Studio 2022
 description: A step-by-step guide for creating a new project using Visual Studio
 ---
 
-# Creating a Project with Visual Studio 2022
-
 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.

articles/getting_started/2_creating_a_new_project_vs.md

@@ -1,12 +1,9 @@
 ---
 title: Understanding the Code
-description: A look at the code that is generated after creating a new project.
+description: This tutorial will go over the code that is generated when you start a blank project.
 ---
 
-# Understanding the Code
-
-This tutorial will go over the code that is generated when you start a blank project.
-
+> [!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:

articles/getting_started/3_understanding_the_code.md

@@ -1,12 +1,9 @@
 ---
 title: Adding Content
-description: Learn how to add content such as images or sounds to your game.
+description: This tutorial will go over adding content such as images or sounds to your game.
 ---
 
-# Adding Content
-
-This tutorial will go over adding content such as images or sounds to your game.
-
+> [!NOTE]
 > For help with creating a project, please look at the [Creating a New Project](index.md) section of the Getting Started guide.
 
 ## MonoGame Content Builder Tool (MGCB Editor)

articles/getting_started/4_adding_content.md

@@ -1,11 +1,10 @@
 ---
 title: Adding Basic Code
-description: Learn how to add basic logic to your game.
+description: This tutorial will go over adding basic logic to your game
 ---
 
-# Adding Basic Code
-
-This tutorial will go over adding basic logic to your game, continuing from where [Adding Content](4_adding_content.md) left off.
+> [!NOTE]
+> this tutorial continues from where [4. Adding Content](4_adding_content.md) left off.
 
 ---
 
@@ -133,14 +132,14 @@ Find the **Update** method in the Game1.cs class file and add:
 if(Joystick.LastConnectedIndex == 0)
 {
     JoystickState jstate = Joystick.GetState(PlayerIndex.One);
-	
+
     float updatedBallSpeed = ballSpeed * (float)gameTime.ElapsedGameTime.TotalSeconds;
-	
+
     if (jstate.Axes[1] < 0)
     {
         ballPosition.Y -= updatedBallSpeed;
     }
-	else if (jstate.Axes[1] > 0)
+    else if (jstate.Axes[1] > 0)
     {
         ballPosition.Y += updatedBallSpeed;
     }

articles/getting_started/5_adding_basic_code.md

@@ -1,12 +1,8 @@
 ---
 title: Getting Started
-description: Get started creating games with MonoGame.
+description: This section walks you through the basics of MonoGame, and helps you to create your first game.
 ---
 
-# Getting Started
-
-This section walks you through the basics of MonoGame, and helps you to create your first game.
-
 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.
 
 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.

articles/getting_started/index.md

@@ -3,10 +3,6 @@ title: Package games for distribution
 description: How to package your game for distribution.
 ---
 
-# Package games for distribution
-
-Once your game is ready to be published, it is recommended that you package it properly for consumption by players.
-
 ## Desktop games
 
 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.
@@ -35,14 +31,14 @@ We recommend using the .tar.gz archiving format to preserve the execution permis
 
 From the .NET CLI:
 
-```
+```cli
 dotnet publish -c Release -r osx-x64 /p:PublishReadyToRun=false /p:TieredCompilation=false --self-contained
 dotnet publish -c Release -r osx-arm64 /p:PublishReadyToRun=false /p:TieredCompilation=false --self-contained
 ```
 
 We recommend that you distribute your game as an [application bundle](https://developer.apple.com/library/archive/documentation/CoreFoundation/Conceptual/CFBundles/BundleTypes/BundleTypes.html). Application bundles are directories with the following file structure:
 
-```
+```text
 YourGame.app                    (this is your root folder)
     - Contents
         - Resources
@@ -56,6 +52,7 @@ YourGame.app                    (this is your root folder)
 ```
 
 The contents of the entry point script:
+
 ```sh
 #!/bin/bash
 
@@ -67,7 +64,7 @@ else
 fi
 ```
 
-The Info.plist file is a standard macOS file containing metadata about your game. Here's an example file with required and recommended values set:
+The `Info.plist` file is a standard macOS file containing metadata about your game. Here is an example file with required and recommended values set:
 
 ```xml
 <?xml version="1.0" encoding="UTF-8"?>

articles/getting_started/packaging_games.md

@@ -3,16 +3,14 @@ title: Supported Platforms
 description: Platforms that MonoGame supports building games for.
 ---
 
-
-# Supported Platforms
-
 MonoGame supports building games for the following **systems**:
 
 | **Desktop PCs**             | **Mobiles**                | **Gaming consoles***                                                           |
 | --------------------------- | -------------------------- | ------------------------------------------------------------------------------ |
 | Windows<br/>macOS<br/>Linux | iOS<br/>iPadOS<br/>Android | Xbox<br/>PlayStation 4<br/>PlayStation 5<br/>Nintendo Switch<br/>Google Stadia |
 
-**Gaming consoles are restricted to registered developers and are not publicly available nor publicly documented. To get access to those platforms, please contact your console account manager(s). MonoGame documentation for closed platforms is available in their respective repositories.*
+> [!IMPORTANT]
+> **Gaming consoles are restricted to registered developers and are not publicly available nor publicly documented. To get access to those platforms, please contact your console account manager(s). MonoGame documentation for closed platforms is available in their respective repositories.*
 
 ## Understanding MonoGame's platform types
 
@@ -26,7 +24,6 @@ Below is a list of public platforms with their corresponding NuGet package, the
 
 - [WindowsDX](#windowsdx)
 - [DesktopGL](#desktopgl)
-- [Windows Universal](#windowsuniversal)
 - [Android](#android)
 - [iOS](#ios)
 
@@ -68,28 +65,6 @@ 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.
 
-### WindowsUniversal
-
-| **Supported Systems**                | **NuGet Package**                   | **Template ID**                                     |
-| ------------------------------------ | ----------------------------------- | --------------------------------------------------- |
-| Windows 10, Xbox (UWP-only, not XDK) | MonoGame.Framework.WindowsUniversal | mguwpcore (core app, no xaml), mguwpxaml (xaml app) |
-
-The WindowsUniversal platform runs on [Universal Windows Platform (UWP)](https://docs.microsoft.com/en-us/windows/uwp/get-started/universal-application-platform-guide).
-
-WindowsUniversal uses **DirectX** for graphics, and XAudio for audio just like the WindowsDX platform.
-
-UWP comes in two flavors, each with its own project template:
-
-- **XAML app template**: an app in which your game will be hosted within an XAML page. This can be useful if you wish to offer a more complex UWP experience with multiple pages or XAML controls.
-
-- **Core app template**: a raw app without any XAML, more straightforward if you don't need XAML controls.
-
-This platform is meant to publish games on the **Windows Store**, for both **Windows** and **Xbox** (through the [Xbox Live Creators Program](https://www.xbox.com/en-US/developers/creators-program)).
-
-Note that UWP games running on Xbox get [restricted access](https://docs.microsoft.com/en-us/windows/uwp/xbox-apps/system-resource-allocation) to the console capabilities. To unlock those restrictions, MonoGame has a dedicated Xbox platform for registered [ID@Xbox](https://www.xbox.com/en-US/Developers/id) developers targeting the XDK (this platform is private and requires you to contact your ID@Xbox manager).
-
-Building for UWP requires the Windows SDK version 19041 or better to be installed.
-
 ### Android
 
 | **Supported Systems** | **NuGet Package**          | **Template ID** |
@@ -135,5 +110,3 @@ 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.
-
-# 

articles/getting_started/platforms.md

@@ -1,12 +1,8 @@
 ---
 title: Preparing for consoles
-description: How to get your game ready to run on consoles.
+description: If you would like to port your game to consoles, there are some best practices to follow if you want to avoid running into issues while porting.
 ---
 
-# Preparing for consoles
-
-If you would like to port your game to consoles, there are some best practices to follow if you want to avoid running into issues while porting.
-
 MonoGame for gaming consoles uses a dedicated .NET runtime that is not maintained by Microsoft. Therefore, a 100% accuracy and reliability is not guaranteed. Moreover, the console runtime makes use of `ahead-of-time` native compilation (AOT), which means that some .NET features will not, and cannot work on consoles.
 
 This article explains the most common pitfalls and suggested guidelines to optimize your chances of having a smoother porting experience.
@@ -27,7 +23,7 @@ To publish with AOT:
 - Add `<PublishAot>true</PublishAot>` to your `.csproj`.
 - Then run `dotnet publish` from the command-line/terminal.
 
-This will nativily compile your game in a fashion similar to consoles. The output executable will be in your output folder, within a sub-folder nammed `publish`.
+This will natively compile your game in a fashion similar to consoles. The output executable will be in your output folder, within a sub-folder named `publish`.
 
 From there, you can try running this executable. If it does not start or crashes later on, you likely are using reflection or another unsupported feature in a AOT runtime.
 
@@ -41,7 +37,7 @@ It should show you on which C# lines it crashed.
 
 It is important to note that you should test every aspect of your game, and not just if it starts.  Run through all the menus/screens, scene transitions and gameplay.
 
-Another way to make sure that everything is safe is to enable `<EnableTrimAnalyzer>true</EnableTrimAnalyzer>` in your `.csproj`, and then **rebuild** (not just build) your game and check the build output for AOT warnings. Those warnings will tell you which parts of your code might trigger crashes or unexecpted results when running on AOT compilation. You should seek to resolve all of them.
+Another way to make sure that everything is safe is to enable `<EnableTrimAnalyzer>true</EnableTrimAnalyzer>` in your `.csproj`, and then **rebuild** (not just build) your game and check the build output for AOT warnings. Those warnings will tell you which parts of your code might trigger crashes or unexpected results when running on AOT compilation. You should seek to resolve all of them.
 
 ## No runtime compilation / IL emit
 
@@ -61,7 +57,7 @@ It is advised to choose very carefully the libraries that you are using when por
 
 The best way to make sure if they will work, is to search if they are **"AOT-compatible"**, or try to compile with the `<EnableTrimAnalyzer>true</EnableTrimAnalyzer>` setting in your `.csproj` and check if there are any warnings related to those libraries.
 
-For example, here are some parsing libraries known for their compliance with AOT compilation and good handling of memrory:
+For example, here are some parsing libraries known for their compliance with AOT compilation and good handling of memory:
 
 - [TurboXML](https://github.com/xoofx/TurboXml)
 - [TinyJSON](https://github.com/zanders3/json)
@@ -88,7 +84,7 @@ Even though your game has good performance on PC and does not show stutters, you
 
 The garbage collector is slower on consoles and if your game generates a lot of garbage memory, there will be visible stutters.
 
-To verify that your game is not too garbage-prone, you can run Visual Studio's Perfomance Profiler (`Debug/Performance Profiler...`) and check the **".NET Object Allocation Tracking"** tool.
+To verify that your game is not too garbage-prone, you can run Visual Studio's Performance Profiler (`Debug/Performance Profiler...`) and check the **".NET Object Allocation Tracking"** tool.
 
 From there, you can check which parts of your code generate garbage and you can pinpoint where to optimize.
 
@@ -103,7 +99,7 @@ In order to avoid garbage, here are some best practices:
 
 ## Do not rely on system calls
 
-If your game calls directly to system functions, like kernel, win32 or unix commands, you might want to get rid of them.
+If your game calls directly to system functions, like kernel, win32 or Unix commands, you might want to get rid of them.
 
 ## Consider I/O to be asynchronous
 
@@ -116,4 +112,3 @@ If you consider all your I/O and system operations as asynchronous, you will lik
 ## Suggestions
 
 If you have other tips or suggestions when building for consoles, then let the MonoGame team know by raising an issue and we will improve this article even further over time.
-