diff --git a/articles/console_access.md b/articles/console_access.md
index e9aba8f2..a3b58069 100644
--- a/articles/console_access.md
+++ b/articles/console_access.md
@@ -19,7 +19,7 @@ The process for access to the private console repositories is as follows:
The instructions below will help you gain access to each platform.
-## Nintendo Switch
+### Nintendo Switch
@@ -29,7 +29,7 @@ Once you are in the program, you can go to the middleware page and fill out the
We will then contact you with further instructions.
-## PlayStation 4, PlayStation 5
+### PlayStation 4, PlayStation 5
@@ -39,7 +39,7 @@ Once you are registered, you can submit a request in the [PlayStation 4 forums](
We will process these requests to give you access and further instructions.
-## Xbox One, Xbox Series X
+### Xbox One, Xbox Series X
diff --git a/articles/contributing.md b/articles/contributing.md
index be0c3cbc..7fae7248 100644
--- a/articles/contributing.md
+++ b/articles/contributing.md
@@ -1,13 +1,11 @@
---
-title: Contributing Guidelines
+title: Contributing to MonoGame Documentation
description: Instructions on how to contribute to the documentation of the MonoGame Framework
---
-# Contributing to MonoGame Documentation
-
Thank you for choosing to contribute to the MonoGame project! This page provides guidance on how you can help to improve the documentation for MonoGame.
-# Getting Started
+## Getting Started
> [!NOTE]
> If you are new to making contributions to open source projects, it is recommended to understand the following concepts before submitting your contribution:
@@ -17,7 +15,7 @@ Thank you for choosing to contribute to the MonoGame project! This page provides
> - [Creating a new file](https://help.github.com/articles/creating-new-files/) or [editing an existing one](https://help.github.com/articles/editing-files-in-your-repository/) using the GitHub markup editor.
> - [How to submit your contributions for review through a pull request](https://help.github.com/articles/creating-a-pull-request/).
-## Articles and API References
+### Articles and API References
The MonoGame documentation contains two types of documents: articles and API references.
@@ -25,7 +23,7 @@ Articles include manuals, guides and tutorials on how to use the MonoGame Framew
API references provide detailed explanation of each class and method found in the MonoGame Framework. The documentation is written in the [C# XML format](https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/xmldoc/xml-documentation-comments) and is inline to the MonoGame source code.
-## Generating the Documentation Site
+### Generating the Documentation Site
The pages for articles and API references are hosted on a documentation site that is generated using [DocFX](https://dotnet.github.io/docfx/).
@@ -40,7 +38,7 @@ To generate a local copy of the documentation site:
> [!TIP]
> Verify your changes in your local documentation site before submitting a pull request with said changes. It is recommended to include screenshots of the pages in the pull request to help reviewers confirm these changes.
-# General Rules
+## General Rules
The following rules **must** be observed at all times when contributing documentation to the MonoGame project.
@@ -52,31 +50,31 @@ The following rules **must** be observed at all times when contributing document
> [!WARNING]
> Breaking these rules can result in your contribution being rejected.
-# General Style Guide
+## General Style Guide
Because there are many contributors to the MonoGame documentation, it can be difficult to maintain a coherent writing style throughout the documentation site. In addition to the [General Rules](#general-rules), this style guide serves to inform contributors of the conventions needed to maintain this writing style. So please review the following expectations before contributing any documentation.
-## Every Word Should Contain Value
+### Every Word Should Contain Value
Every word in the reference documentation should provide information beyond the API itself. Documentation that only rehashes or rephrases what is already apparent in the class, method, parameter, or property name has zero value and wastes time for both the writer and reader.
-## The First Sentence Is the Most Important
+### The First Sentence Is the Most Important
There is no guarantee that the reader will read beyond the first sentence of the reference documentation. This is why that first sentence is the most important and should convey the most key piece of information. Take your time to write the most concise and clear first sentence possible. This helps users tremendously and goes a long way towards having great documentation.
-## Surface Information Hidden in the Code
+### Surface Information Hidden in the Code
Being inline with the code allows you to easily look for critical information within it that the user might not know from looking at the API alone. Take your time to explore inner method calls and platform specific sections of the code. The time to write the documentation is once you feel you fully understand the code you are documenting. If you don't feel you understand the code then leave the documentation for someone else to write.
-## Focus on What Adds Value to the Consumer
+### Focus on What Adds Value to the Consumer
Limit documentation to public methods and functions unless there is a specific reason to include internal methods, while documenting internals helps with readability of the code, it provides limited use to consumers of the MonoGame Framework.
-## Documentation Is Referenced Not Read
+### Documentation Is Referenced Not Read
Remember that the user is searching for an answer for a specific question. It is your job to predict these questions and provide them clear answers.
-## Descriptions Should Add Value and Understanding
+### Descriptions Should Add Value and Understanding
Describing a thing by naming the thing does not help the developer to understand what the concept is that you are describing, for example:
@@ -84,33 +82,33 @@ Describing a thing by naming the thing does not help the developer to understand
Which does not help someone reading the documentation if they do not know what a `Genre` is. Be descriptive and improve the readers understanding for what something is and WHY it is.
-# API Reference Style Guide
+## API Reference Style Guide
In addition to the [General Style Guide](#general-style-guide), please consider the following conventions used for code associated with the API reference docs.
-## XML Tag Guidance
+### XML Tag Guidance
By default, the standard [Microsoft recommendations](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/xmldoc/recommended-tags) should be used for filling in XML tags for each class, method and property.
With a few points to call out:
-### `<see>` and `<cref/>` should be used whenever an API reference is used in the documentation
+#### `<see>` and `<cref/>` should be used whenever an API reference is used in the documentation
To ensure that API documentation is linked to whichever reference is used, `<see>` and `<cref/>` references should be used, this helps users navigate the methods, especially when looking up initializers or use of a property or method.
-### Avoid self referencing `<cref/>` unless it provides value
+#### Avoid self referencing `<cref/>` unless it provides value
`<cref/>` blocks are there to add links and create references to other classes, functions and methods that help inform the developer for what those concepts are. Adding a `<cref/>` for the same class or property you are describing just creates a circular reference that does not add value.
References to other methods or properties in the same class is fine, just avoid self if possible.
-### Use descriptors in `<see/>` and `<cref/>` statements for better readability
+#### Use descriptors in `<see/>` and `<cref/>` statements for better readability
By default, a `<cref/>` or `<see/>` reference will use only the type you are referencing when rendered to the user, e.g. `<cref="Album.Genre"/>` will render as `Genre`.
Instead, use the descriptor in the style to render what you actually mean, for example: `<cref="Album.Genre">Album.Genre</cref>` which will always render as `Album.Genre` which is much clearer, it is the same for `<see/>` tags.
-### 120 width comments for easy reading
+#### 120 width comments for easy reading
Comments should be limited to **120** width, with overflow moving to the next line to make reading easier, for example:
@@ -125,7 +123,7 @@ and the y component uses 6 bits.
> If the `cref` description would cause the line to exceed the 120 recommendation, this is generally ok, so long as the rendered line does not exceed the limit.
> THe limit however, is more of a guideline than a hard rule, so common sense should be applied to keep the limit near 120 characters.
-### Use the packed multi-line style with surrounding tags
+#### Use the packed multi-line style with surrounding tags
To keep the documentation packed and readable, each parameter should be contained to a single line, for example:
@@ -138,7 +136,7 @@ Creates a new instance of Bgr565.
<param name="z">The z component</param>
```
-## Interface Documentation
+### Interface Documentation
If documentation is already provided by an interface or inherited class, then the `<inheritdoc />` tag should be used. Critically, **DO NOT** duplicate documentation as it increases maintenance later, for example:
@@ -152,7 +150,7 @@ public void Dispose()
This applies to all derived elements within a class, property or method.
-## Inherited Properties
+### Inherited Properties
Where a property or type is already documented in an `enum` or `static`, to avoid duplication the `<inheritdoc cref=""/>` style should be used, for example:
@@ -175,7 +173,7 @@ Where a property or type is already documented in an `enum` or `static`, to avoi
public static readonly VertexDeclaration VertexDeclaration;
```
-## Protected Methods Requiring Documentation by the Linter
+### Protected Methods Requiring Documentation by the Linter
By default, we do not document Finalizers or other protected methods, the recommendation is to apply an empty `<summary />` tag to suppress the warnings raised by the linter, for example:
diff --git a/articles/getting_started/content_pipeline/adding_ttf_fonts.md b/articles/getting_started/content_pipeline/adding_ttf_fonts.md
index 22d2ccd4..8b492891 100644
--- a/articles/getting_started/content_pipeline/adding_ttf_fonts.md
+++ b/articles/getting_started/content_pipeline/adding_ttf_fonts.md
@@ -3,8 +3,6 @@ title: Adding TTF Fonts
description: Learn how to use TrueType fonts in MonoGame.
---
-# TrueType fonts
-
MonoGame supports more than one method of using fonts, the following is an explanation of how to use TrueType fonts.
## Using TrueType Fonts with MonoGame
@@ -14,7 +12,7 @@ To be able to use a TrueType font, MonoGame requires the **TrueType font file**
> TrueType fonts may be installed on the system, or added manually in to the same directory as the .spritefont file.
1. Create the .spritefont file by selecting "Edit -> Add -> New Item" from the MGCB Editor menu, then select **SpriteFont Description** from the list and click **Create**.
-
+
2. Open the newly created .spritefont file in your text editor of choice, find this line and change it to your selected .ttf font.
diff --git a/articles/getting_started/content_pipeline/custom_effects.md b/articles/getting_started/content_pipeline/custom_effects.md
index 19c378c3..19a3bd3c 100644
--- a/articles/getting_started/content_pipeline/custom_effects.md
+++ b/articles/getting_started/content_pipeline/custom_effects.md
@@ -3,8 +3,6 @@ title: Custom Effects
description: Learn how to create and use custom effects for rendering in MonoGame.
---
-# Custom Effects
-
A core element of Microsoft XNA is the effect system which is used for all rendering.
For MonoGame we have the burden of supporting stock and custom effects for desktop GLSL, mobile GLSL, DirectX HLSL, and custom formats like that of the PlayStation Mobile. There currently is no effect system or shader language that supports all the platforms we require, forcing us to build a new custom effect system.
@@ -64,7 +62,6 @@ These are some tips for writing or converting effects for use with MonoGame.
| `HLSL` and `SM4` for DirectX |
| `OpenGL` and `GLSL` for OpenGL |
-
As an example, you can conditionally set shader models depending on the platform with the following code:
```hlsl
diff --git a/articles/getting_started/content_pipeline/index.md b/articles/getting_started/content_pipeline/index.md
index b16a3853..5d46a22a 100644
--- a/articles/getting_started/content_pipeline/index.md
+++ b/articles/getting_started/content_pipeline/index.md
@@ -3,8 +3,6 @@ title: Adding Content
description: Learn how to add content to your game using the Content Pipeline.
---
-# Adding Content
-
A big part of your game is your content. This includes standard files like textures, sound effects, music, videos, and custom effects as well as custom content like level and enemy files.
MonoGame implements its own content pipeline for transforming your unoptimized assets into platform optimized content. This is critical in building a game which runs as fast as possible under tight resource constraints.
diff --git a/articles/getting_started/content_pipeline/localization.md b/articles/getting_started/content_pipeline/localization.md
index 09e69f46..8cfd0b7c 100644
--- a/articles/getting_started/content_pipeline/localization.md
+++ b/articles/getting_started/content_pipeline/localization.md
@@ -3,8 +3,6 @@ title: Localization
description: Learn how to add localization to your game to support multiple regions.
---
-# Localization
-
Localization is an important part of any game. While it can be possible to design a game that is region independent, it is quite hard. At some point you will need to produce localized text and graphics.
MonoGame has a simple localization system built in. If you want to develop your own system you are still able to do so. But the default system should be good enough for
@@ -135,6 +133,6 @@ CultureInfo.CurrentCulture.Name // eg. "en-US"
CultureInfo.CurrentCulture.TwoLetterISOLanguageName // eg. "en"
```
-which are part of the **System.Globalization namespace**.
+which are part of the **System.Globalization namespace**.
> On a side note you can also use the `LoadLocalized` to load language specific SpriteFonts. They just need to be named in the same way as we have described above.
diff --git a/articles/getting_started/content_pipeline/using_mgcb_editor.md b/articles/getting_started/content_pipeline/using_mgcb_editor.md
index fcaa15b9..b57bce41 100644
--- a/articles/getting_started/content_pipeline/using_mgcb_editor.md
+++ b/articles/getting_started/content_pipeline/using_mgcb_editor.md
@@ -170,9 +170,9 @@ After you have done these fixes, you should be able to add these new processors
The MGCB Editor has 3 actions related to building content: Build, Rebuild and Clean:
-- **Build** - This will build all content that needs to be built and put it in the output directory (bin by default). Content will be skipped if it has not changed since the last build. The time source content was last edited is saved in the intermediate directory (obj by default) to determine if content changed since the last build.
-- **Rebuild** - Cleans the project first and then Builds it again.
-- **Clean** - Cleaning the project will empty the output and intermediate directories.
+* **Build** - This will build all content that needs to be built and put it in the output directory (bin by default). Content will be skipped if it has not changed since the last build. The time source content was last edited is saved in the intermediate directory (obj by default) to determine if content changed since the last build.
+* **Rebuild** - Cleans the project first and then Builds it again.
+* **Clean** - Cleaning the project will empty the output and intermediate directories.
## Linking Content To Your Game
@@ -200,10 +200,10 @@ If you are using Visual Studio, you can bypass the content pipeline all together
-You will now see a file dialog from which you can add your content files.
+You will now see a file dialog from which you can add your content files.
> Note that if you do not want Visual Studio to make a local copy of the files. Make sure to use “**Add As Link**” when “Linking” files.
->
+>
> 
Once the files are added you will need to select them all and change their properties in the properties window to:
diff --git a/articles/getting_started/content_pipeline/why_content_pipeline.md b/articles/getting_started/content_pipeline/why_content_pipeline.md
index 79720242..cf88fb38 100644
--- a/articles/getting_started/content_pipeline/why_content_pipeline.md
+++ b/articles/getting_started/content_pipeline/why_content_pipeline.md
@@ -3,8 +3,6 @@ title: Why use the Content Pipeline
description: Why would you use the Content Pipeline when MonoGame also supports loading assets natively, like .png, .mp3, .wav? Well, it all boils down to a couple of words, performance and efficiency.
---
-# Why use the Content Pipeline
-
The MonoGame team continues to put a lot of effort into a cross-platform content pipeline, but why would you use the Content Pipeline when MonoGame also supports loading assets natively, like .png, .mp3, .wav? Well, it all boils down to a couple of words, performance and efficiency.
## Textures
diff --git a/articles/getting_started/tools/index.md b/articles/getting_started/tools/index.md
index ee1f022c..0e4a3b2e 100644
--- a/articles/getting_started/tools/index.md
+++ b/articles/getting_started/tools/index.md
@@ -3,8 +3,6 @@ title: Tools
description: Distributed tools to help mange and build content for your game.
---
-# Tools
-
MonoGame distributes tooling to help manage and build content for your game.
These tools are available as [.NET Tools](https://docs.microsoft.com/en-us/dotnet/core/tools/global-tools) and are automatically installed if you are using the MonoGame templates.
diff --git a/articles/getting_started/tools/mgcb.md b/articles/getting_started/tools/mgcb.md
index 9f44f4b3..8fe74151 100644
--- a/articles/getting_started/tools/mgcb.md
+++ b/articles/getting_started/tools/mgcb.md
@@ -3,8 +3,6 @@ title: MonoGame Content Builder (MGCB)
description: Learn about the MonoGame Content Builder (MGCB), the command line tool for building XNB content on Windows, Mac, and Linux desktop.
---
-# MonoGame Content Builder (MGCB)
-
The MonoGame Content Builder is a command line tool for building XNB content on Windows, Mac, and Linux desktop systems.
Typically, it is executed by the [MGCB Editor](mgcb_editor.md) when editing content or by `MonoGame.Content.Builder.Task` during the build process
@@ -23,7 +21,7 @@ The options are processed “left to right”. When an option is repeated, it is
### Output Directory
-```
+```sh
/outputDir:<directory_path>
```
@@ -31,7 +29,7 @@ Specifies the directory where all content is written. Defaults to the current wo
### Intermediate Directory
-```
+```sh
/intermediateDir:<directory_path>
```
@@ -39,7 +37,7 @@ Specifies the directory where all intermediate files are written. Defaults to th
### Rebuild Content
-```
+```sh
/rebuild
```
@@ -47,7 +45,7 @@ Force a full rebuild of all content.
### Clean Content
-```
+```sh
/clean
```
@@ -55,7 +53,7 @@ Delete all previously built content and intermediate files. Only the `/intermedi
### Incremental Build
-```
+```sh
/incremental
```
@@ -63,7 +61,7 @@ Only build content that changed since the last build.
### Assembly Reference
-```
+```sh
/reference:<assembly_path>
```
@@ -71,7 +69,7 @@ An optional parameter which adds an assembly reference which contains importers,
### Target Platform
-```
+```sh
/platform:<target_Platform>
```
@@ -93,7 +91,7 @@ NOTE: PlayStation 4, PlayStation 5, Xbox One, and Switch support is only availab
### Target Graphics Profile
-```
+```sh
/profile:<graphics_Profile>
```
@@ -106,7 +104,7 @@ If not set, it will default to HiDef.
### Target Build Configuration
-```
+```sh
/config:<build_config>
```
@@ -114,7 +112,7 @@ The optional build configuration name from the build system. This is sometimes u
### Content Compression
-```
+```sh
/compress
```
@@ -122,7 +120,7 @@ Uses LZ4 compression to compress the contents of the XNB files. Content build ti
### Content Importer Name
-```
+```sh
/importer:<class_name>
```
@@ -130,7 +128,7 @@ An optional parameter which defines the class name of the content importer for r
### Content Processor Name
-```
+```sh
/processor:<class_name>
```
@@ -140,7 +138,7 @@ Note that when you change the processor all previously defined `/processorParam`
### Content Processor Parameter
-```
+```sh
/processorParam:<name>=<value>
```
@@ -150,7 +148,7 @@ Note all defined processor parameters are cleared when the `/processor` is set.
### Build Content File
-```
+```sh
/build:<content_filepath>
/build:<content_filepath>;<destination_filepath>
```
@@ -159,7 +157,7 @@ Instructs the content builder to build the specified content file using the prev
### Launch Debugger
-```
+```sh
/launchdebugger
```
@@ -167,7 +165,7 @@ Allows a debugger to attach to the MGCB executable before content is built.
### Response File
-```
+```sh
/@:<response_filepath>
```
@@ -177,7 +175,7 @@ Each switch is specified on a new line. Comment lines are prefixed with #. These
An example response file could look like this:
-```
+```sh
# Directories
/outputDir:bin/foo
/intermediateDir:obj/foo
@@ -197,14 +195,14 @@ An example response file could look like this:
Response files support preprocessor macros to allow conditionals within a response file.
-```
+```sh
$if <name>=<value>
$endif
```
Preprocessor symbols can be defined from the command line with the `define` option or in a response file with the `$set` directive.
-```
+```sh
<example command line>
MGCB.exe /define:BuildEffects=No /@:example.mgcb
@@ -217,7 +215,7 @@ $if BuildEffects=Yes
$endif
```
-```
+```sh
$set BuildEffects=Yes
$if BuildEffects=Yes
@@ -228,7 +226,7 @@ $endif
For booleans you can omit a value to set a symbol and to check if it is set:
-```
+```sh
$set BuildEffects
$if BuildEffects
@@ -243,7 +241,7 @@ When building content from your project with `MonoGame.Content.Builder.Task`, th
`RunContentBuilder` just before your project builds. If you want to do any processing before or after this process you can use the `BeforeTargets` and `AfterTargets` mechanism provided
by `msbuild` to run your own targets.
-```
+```sh
<Target Name="MyBeforeTarget" BeforeTargets="RunContentBuilder">
<Message Text="MyBeforeTarget Ran"/>
</Target>
@@ -255,6 +253,6 @@ by `msbuild` to run your own targets.
If you want to customize the arguments sent to the `MGCB.exe` as part of the build process you can use the `<MonoGameMGCBAdditionalArguments>` property to define those.
For example to pass in the current project configuration you could include the following code in a PropertyGroup in your .csproj file.
-```
+```sh
<MonoGameMGCBAdditionalArguments>-config:$(Configuration)</MonoGameMGCBAdditionalArguments>
```
diff --git a/articles/getting_started/tools/mgcb_editor.md b/articles/getting_started/tools/mgcb_editor.md
index c8e45a38..c334b339 100644
--- a/articles/getting_started/tools/mgcb_editor.md
+++ b/articles/getting_started/tools/mgcb_editor.md
@@ -24,14 +24,14 @@ The MGCB Editor is automatically installed (if you are using MonoGame's template
Alternatively, you can open the MGCB Editor from the .NET command line. This will only work if you are using the MonoGame templates and executing the command from the root directory of your project:
-```
+```sh
dotnet mgcb-editor
```
> [!NOTE]
> You will need to buid the project at least once in order for the .NET system to download and register the tool with your project utilizing the `dotnet-tools.json` configuration file located in the `.config` folder, or use the `dotnet tool restore` command shown below.
>
-> ```
+> ```sh
> dotnet tool restore
> ```
diff --git a/articles/getting_started/tools/mgfxc.md b/articles/getting_started/tools/mgfxc.md
index 981cb30d..e60c5d87 100644
--- a/articles/getting_started/tools/mgfxc.md
+++ b/articles/getting_started/tools/mgfxc.md
@@ -3,8 +3,6 @@ title: MonoGame Effects Compiler (MGFXC)
description: Learn about the MonoGame Effects Compiler (MGFXC), the tool used to compile shaders for usage in MonoGame.
---
-# MonoGame Effects Compiler (MGFXC)
-
The MGFXC tool is used to compile [DirectX Effect files](https://docs.microsoft.com/en-us/windows/win32/direct3d9/writing-an-effect) (shaders) for usage with MonoGame. It will compile shaders into mgfxo files ready to be consumed by the ```Effect``` class.
The MGCB Editor uses MGFXC to compile effects and wrap them into an xnb file, so they can be loaded using the `ContentManager`.
diff --git a/articles/help_and_support.md b/articles/help_and_support.md
index d6d6ea25..8815c31b 100644
--- a/articles/help_and_support.md
+++ b/articles/help_and_support.md
@@ -3,14 +3,12 @@ title: Help and Support
description: Where to get help and support when using MonoGame.
---
-# Help and Support
-
There is a wealth of [community created content, blogs and tutorials](tutorials/index.md) available.
-If you want to find an answer to a more specific problem, you can ask it on our [GitHub Discussions](https://github.com/MonoGame/MonoGame/discussions) page.
-
You can also chat to other MonoGame users via [Discord](https://discord.com/invite/monogame).
+If you want to find an answer to a more specific problem, you can ask it on our [GitHub Discussions](https://github.com/MonoGame/MonoGame/discussions) page.
+
## Bugs and feature requests
If you find a bug or have a feature request, [please open a new issue](https://github.com/mono/monogame/issues). Before opening any issue, please search for existing issues.
diff --git a/articles/migration/migrate_37.md b/articles/migration/migrate_37.md
index f85a1583..be3f6d99 100644
--- a/articles/migration/migrate_37.md
+++ b/articles/migration/migrate_37.md
@@ -3,8 +3,6 @@ title: Migrating from 3.7
description: A guide on migrating a MonoGame v3.7 project to the current version of MonoGame.
---
-# Migrating from 3.7
-
Previously MonoGame installed on your machine through an installer, but from 3.8 onwards everything is installed through NuGet packages and Visual Studio Extensions.
> **Note** MonoGame 3.8 project templates are not compatible with earlier versions of MonoGame. If you wish to work on or build older MonoGame projects, then you will still need to install [MonoGame 3.7.1](https://www.monogame.net/downloads/) or earlier to open them.
diff --git a/articles/migration/migrate_38.md b/articles/migration/migrate_38.md
index b5dc90d5..8e03d21c 100644
--- a/articles/migration/migrate_38.md
+++ b/articles/migration/migrate_38.md
@@ -3,15 +3,12 @@ title: Migrating from 3.8.0
description: A guide on migrating a MonoGame v3.8.0 project to the current version of MonoGame.
---
-# Migrating from 3.8.0
-
Migrating from 3.8.0 should be straightforward for most platforms.
The major difference is that 3.8.1 now requires .NET 6 and Visual Studio 2022. You can follow the [environment setup tutorial](../getting_started/index.md) to make sure that you are not missing any components.
The MGCB Editor is no longer a global .NET tool and we recommend that you use the new Visual Studio 2022 extension which helps with accessing it without the need of CLI commands.
-
> [!NOTE]
> It is also recommended that you uninstall the older global versions of the .NET tools as described below.
@@ -36,7 +33,7 @@ Then edit your MonoGame ```PackageReference``` to point to 3.8.1:
The MGCB Editor is no longer a .NET global tool, and does not need to be installed or registered. When migrating from 3.8.0, it is recommended that you **uninstall** the global versions of the tools. You can accomplish that with these commands:
-```
+```sh
dotnet tool uninstall dotnet-mgcb -g
dotnet tool uninstall dotnet-2mgfx -g
dotnet tool uninstall dotnet-mgcb-editor -g
diff --git a/articles/migration/migrate_xna.md b/articles/migration/migrate_xna.md
index 846f9c12..ffddb06a 100644
--- a/articles/migration/migrate_xna.md
+++ b/articles/migration/migrate_xna.md
@@ -3,12 +3,10 @@ title: Migrating from XNA
description: A guide on migrating an XNA project to the current version of MonoGame.
---
-# Migrating from XNA
-
MonoGame is API compatible with [XNA 4.0](https://docs.microsoft.com/en-us/previous-versions/windows/xna/bb200104(v=xnagamestudio.41)) even down to the namespaces. That means you do not have to change much of your game code to port from XNA to MonoGame. There are however some exceptions and some things to keep in mind.
> If your game targets XNA 3.1, you might want to use this archived migration cheatsheet to upgrade to 4.0:
->
+>
> [http://www.nelxon.com/blog/xna-3-1-to-xna-4-0-cheatsheet/](https://www.nelsonhurst.com/xna-cheatsheet/)
## Missing/removed API
diff --git a/articles/migration/updating_versions.md b/articles/migration/updating_versions.md
index 2d1e30f9..12605e04 100644
--- a/articles/migration/updating_versions.md
+++ b/articles/migration/updating_versions.md
@@ -3,40 +3,48 @@ title: Updating Versions
description: A guide on updating MonoGame when a new release is pushed.
---
-
- [Update Existing Projects](#update-existing-projects)
- - [Update Target Framework](#update-target-framework)
- - [Update NuGet References](#update-nuget-references)
- - [Visual Studio 2022](#visual-studio-2022)
- - [Manually Editing .csproj File (VSCode/Rider)](#manually-editing-csproj-file-vscoderider)
- - [Update MGCB Editor](#update-mgcb-editor)
+ - [Update Target Framework](#update-target-framework)
+ - [Update NuGet References](#update-nuget-references)
+ - [Visual Studio 2022](#visual-studio-2022)
+ - [Manually Editing .csproj File (VSCode/Rider)](#manually-editing-csproj-file-vscoderider)
+ - [Update MGCB Editor](#update-mgcb-editor)
- [Updating Environment for New Projects](#updating-environment-for-new-projects)
- - [Update dotnet Templates](#update-dotnet-templates)
- - [Visual Studio 2022](#visual-studio-2022-1)
- - [dotnet CLI (VSCode/Rider)](#dotnet-cli-vscoderider)
+ - [Update dotnet Templates](#update-dotnet-templates)
+ - [Visual Studio 2022](#visual-studio-2022-templates)
+ - [dotnet CLI (VSCode/Rider)](#dotnet-cli-vscoderider-templates)
When a new release of MonoGame is pushed, developers will need to manually update their development environment and/or existing project to make use of the new version. This guide is intended to walk you through the steps of performing these updates.
## Update Existing Projects
+
Developers wishing to update their current project to use a new release version only need to update the *target framework*, *NuGet package versions*, and *dotnet tools* version. Doing this depends on if you are using Visual Studio 2022 or another development environment.
### Update Target Framework
+
Developers will need to ensure the project is updated to target the .NET version used by MonoGame at minimum (currently `net8.0`). To do this, open your project's *.csproj* file and find the `<TargetFramework>` element and change the `net-X.Y` version to `net-8.0`, then save the file.
> [!NOTE]
> Only change the .NET version number. some project types have platform specifiers such as `net6.0-windows`. The only thing that should change here is the version number.
### Update NuGet References
+
The following sections cover updating your NuGet packages for existing projects based on your development environment.
#### Visual Studio 2022
-Open your existing project in Visual Studio 2022 and perform the following
+
+Open your existing project in Visual Studio 2022 and perform the following:
+
1. Right-click on the project in the *Solution Explorer* panel and select *Manage NuGet Packages...".
2. In the NuGet Packages Manager window, click the *Updates* tab.
3. Select the MonoGame Framework packages in the list on the left, then click the *Update* button for each one on the right.
#### Manually Editing .csproj File (VSCode/Rider)
-Alternatively, regardless of the development environment, developers can manually edit the *.csproj* file for their project to update to the newest MonoGame release. To do this
+
+Alternatively, regardless of the development environment, developers can manually edit the *.csproj* file for their project to update to the newest MonoGame release.
+
+To do this:
+
1. Open your project's *.csproj* file
2. Locate the `<PacakgeReference>` elements for any MonoGame referenced packages.
3. Change the `Version=` attribute for each one to the current version of MonoGame (currently this is `3.8.2.1105`)
@@ -50,9 +58,11 @@ dotnet restore
```
### Update MGCB Editor
+
Regardless of the development environment, users will need to update the dotnet tools manifest file manually to use the newest version of the *MonoGame Content Builder*. To do this:
+
1. Open the *.config/dotnet-tools.json* manifest file located in the project root directory
-2. Update the version specified for each tool to the current version of MonoGame (currently this is `3.8.2.1105`).
+2. Update the version specified for each tool to the current version of MonoGame (currently this is `3.8.4`).
3. Save the changes
Once these changes are made, open a command prompt or terminal at the root of the project directory and enter the following commands
@@ -62,15 +72,18 @@ dotnet tool restore
```
## Updating Environment for New Projects
+
The following sections will cover updating your development environment for new projects.
### Update dotnet Templates
+
Developers will need to update the MonoGame C# Templates used to create new projects. Doing this depends on if you are using Visual Studio 2022 or through the dotnet cli.
> [!NOTE]
> Updating the templates will not affect existing projects. if developers wish to update existing project, see the info in the [Update Existing Projects](#update-existing-projects) section.
-#### Visual Studio 2022
+#### Visual Studio 2022 templates
+
Developers using Visual Studio 2022 should be using the [MonoGame C# Project Templates](https://marketplace.visualstudio.com/items?itemName=MonoGame.MonoGame-Templates-VSExtension) extension. This provides not only the templates but also the functionality to open the *MonoGame Content Builder Editor* (MGCB Editor) within Visual Studio. You can update the extension by performing the following
1. Open Visual Studio 2022
@@ -80,7 +93,8 @@ Developers using Visual Studio 2022 should be using the [MonoGame C# Project Tem
If prompted to close Visual Studio to finish the update, do so now to continue installing the update.
-#### dotnet CLI (VSCode/Rider)
+#### dotnet CLI (VSCode/Rider) templates
+
Developers using the dotnet CLI with environments such as Visual Studio Code, JetBrains Rider, or other editors, can execute the following command in a command prompt/terminal to update the templates
```sh
@@ -89,7 +103,7 @@ dotnet new install MonoGame.Templates.CSharp
> [!TIP]
> If you receive a an error or warning stating there are naming conflicts in the templates, you may need to uninstall the templates first with the following command and then install them:
->
+>
> ```sh
> dotnet new uninstall MonoGame.Templates.CSharp
> ```
diff --git a/articles/samples.md b/articles/samples.md
index 6839a541..64259b21 100644
--- a/articles/samples.md
+++ b/articles/samples.md
@@ -3,16 +3,26 @@ title: Samples & Demos
description: Recommended samples and demos for learning how to use MonoGame.
---
-# Samples & Demos
-
The samples and demos below are recommended for learning how to use MonoGame.
+## Official MonoGame tutorial source
+
+- [Building 2D Games](https://github.com/MonoGame/MonoGame.Samples/tree/3.8.4/Tutorials/learn-monogame-2d)
+
## Official MonoGame Samples
These are [the official samples](https://github.com/MonoGame/MonoGame.Samples) that contain the following:
-- [Platformer 2D](https://github.com/MonoGame/MonoGame.Samples/tree/develop/Platformer2D)
-- [NeonShooter](https://github.com/MonoGame/MonoGame.Samples/tree/develop/NeonShooter)
+### 2D Samples
+
+- [AutoPong](https://github.com/MonoGame/MonoGame.Samples/tree/3.8.4/AutoPong)
+- [Platformer 2D](https://github.com/MonoGame/MonoGame.Samples/tree/3.8.4/Platformer2D)
+- [NeonShooter](https://github.com/MonoGame/MonoGame.Samples/tree/3.8.4/NeonShooter)
+
+### 3D Samples
+
+- [FuelCell](https://github.com/MonoGame/MonoGame.Samples/tree/3.8.4/NeonShooter)
+- [ShipGame](https://github.com/MonoGame/MonoGame.Samples/tree/3.8.4/ShipGame)
## XNA Game Studio Archive
diff --git a/articles/toc.yml b/articles/toc.yml
index 3e1841d1..092d1598 100644
--- a/articles/toc.yml
+++ b/articles/toc.yml
@@ -5,35 +5,42 @@ items:
href: /roadmap/
- name: What's New
href: whats_new.md
-- name: Getting Started
+- name: Getting Started - build your first 2D game
+ href: tutorials/building_2d_games/
+- name: Getting to know MonoGame
+ href: getting_to_know/
+ items:
+ - name: What is
+ href: getting_to_know/whatis/
+ items:
+ - name: Audio
+ href: getting_to_know/whatis/audio/
+ - name: Content Pipeline
+ href: getting_to_know/whatis/content_pipeline/
+ - name: Graphics
+ href: getting_to_know/whatis/graphics/
+ - name: Input
+ href: getting_to_know/whatis/input/
+ - name: The Game Loop
+ href: getting_to_know/whatis/game_loop/
+ - name: Vector / Matrix / Quaternions
+ href: getting_to_know/whatis/vector_matrix_quat/
+ - name: MonoGame Class Library
+ href: getting_to_know/whatis/monogame_class_library/
+ - name: How to
+ href: getting_to_know/howto/
+ items:
+ - name: Audio
+ href: getting_to_know/howto/audio/
+ - name: Content Pipeline
+ href: getting_to_know/howto/content_pipeline/
+ - name: Graphics
+ href: getting_to_know/howto/graphics/
+ - name: Input
+ href: getting_to_know/howto/input/
+- name: Advanced Topics
href: getting_started/index.md
items:
- - name: Introduction
- href: getting_started/
- - name: Supported platforms
- href: getting_started/platforms.md
- - name: 1. Setting up your OS for development
- items:
- - name: Windows
- 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
- href: getting_started/1_setting_up_your_os_for_development_ubuntu.md
- - name: 2. Choosing your IDE
- items:
- - name: Visual Studio for Windows
- href: getting_started/2_choosing_your_ide_visual_studio.md
- - name: Visual Studio Code
- 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
- href: getting_started/4_adding_content.md
- - name: 5. Adding Basic Code
- href: getting_started/5_adding_basic_code.md
- name: Packaging
href: getting_started/packaging_games.md
- name: Preparing for consoles
@@ -64,37 +71,6 @@ items:
href: getting_started/content_pipeline/adding_ttf_fonts.md
- name: Localization
href: getting_started/content_pipeline/localization.md
-- name: Getting to know MonoGame
- href: getting_to_know/
- items:
- - name: What is
- href: getting_to_know/whatis/
- items:
- - name: Audio
- href: getting_to_know/whatis/audio/
- - name: Content Pipeline
- href: getting_to_know/whatis/content_pipeline/
- - name: Graphics
- href: getting_to_know/whatis/graphics/
- - name: Input
- href: getting_to_know/whatis/input/
- - name: The Game Loop
- href: getting_to_know/whatis/game_loop/
- - name: Vector / Matrix / Quaternions
- href: getting_to_know/whatis/vector_matrix_quat/
- - name: MonoGame Class Library
- href: getting_to_know/whatis/monogame_class_library/
- - name: How to
- href: getting_to_know/howto/
- items:
- - name: Audio
- href: getting_to_know/howto/audio/
- - name: Content Pipeline
- href: getting_to_know/howto/content_pipeline/
- - name: Graphics
- href: getting_to_know/howto/graphics/
- - name: Input
- href: getting_to_know/howto/input/
- name: Migration
items:
- name: Migrating from XNA
diff --git a/articles/tutorials/building_2d_games/26_publish_to_itch/index.md b/articles/tutorials/building_2d_games/26_publish_to_itch/index.md
index d403e8d4..9ac9bf70 100644
--- a/articles/tutorials/building_2d_games/26_publish_to_itch/index.md
+++ b/articles/tutorials/building_2d_games/26_publish_to_itch/index.md
@@ -457,7 +457,7 @@ Your game is now publicly accessible to the itch.io community. It will appear i
## Dungeon Slime on itch.io
-To see a completed version of a project uploaded to itch.io, you can explore the Dungeon Slime example at [https://shyfoxstudio.itch.io/dungeon-slime](https://shyfoxstudio.itch.io/dungeon-slime).
+To see a completed version of a project uploaded to itch.io, you can explore the Dungeon Slime example at [https://monogame.itch.io/dungeon-slime](https://monogame.itch.io/dungeon-slime).
This published version demonstrates the concepts we covered in this chapter, showing how they come together in a finished project.
diff --git a/articles/tutorials/building_2d_games/index.md b/articles/tutorials/building_2d_games/index.md
index 12453b1c..ce57be9e 100644
--- a/articles/tutorials/building_2d_games/index.md
+++ b/articles/tutorials/building_2d_games/index.md
@@ -15,7 +15,7 @@ Throughout this tutorial series, we will build a complete game called **Dungeon
- UI menus with customized styling
- A complete game loop with scoring and game over states
-You can see the finished game here: [Dungeon Slime on itch.io](https://shyfoxstudio.itch.io/dungeon-slime)
+You can see the finished game here: [Dungeon Slime on itch.io](https://monogame.itch.io/dungeon-slime)
|  |  |
| :--------------------------------------------------------------------------------: | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: |
@@ -34,29 +34,29 @@ This documentation will introduce game development concepts using the MonoGame f
| Chapter | Summary | Source Files |
| ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
-| [Chapter 01: What Is MonoGame](01_what_is_monogame/index.md) | Learn about the history of MonoGame and explore the features it provides to developers when creating games. | [01-What-Is-MonoGame](https://github.com/shyfox-studio/learn-monogame-2d/tree/main/src/01-What-Is-MonoGame/) |
-| [Chapter 02: Getting Started](02_getting_started/index.md) | Setup your development environment for .NET development and MonoGame using Visual Studio Code as your IDE. | [02-Getting-Started](https://github.com/shyfox-studio/learn-monogame-2d/tree/main/src/02-Getting-Started/) |
-| [Chapter 03: The Game1 File](03_the_game1_file/index.md) | Explore the contents of the Game1 file generated when creating a new MonoGame project. | [03-The-Game1-File](https://github.com/shyfox-studio/learn-monogame-2d/tree/main/src/03-The-Game1-File/) |
-| [Chapter 04: Creating a Class Library](04_creating_a_class_library/index.md) | Learn how to create and structure a reusable MonoGame class library to organize game components and share code between projects. | [04-Creating-A-Class-Library](https://github.com/shyfox-studio/learn-monogame-2d/tree/main/src/04-Creating-A-Class-Library/) |
-| [Chapter 05: Content Pipeline](05_content_pipeline/index.md) | Learn the advantages of using the **Content Pipeline** to load assets and go through the processes of loading your first asset | [05-Content-Pipeline](https://github.com/shyfox-studio/learn-monogame-2d/tree/main/src/05-Content-Pipeline/) |
-| [Chapter 06: Working with Textures](06_working_with_textures/index.md) | Learn how to load and render textures using the MonoGame content pipeline and [**SpriteBatch**](xref:Microsoft.Xna.Framework.Graphics.SpriteBatch). | [06-Working-With-Textures](https://github.com/shyfox-studio/learn-monogame-2d/tree/main/src/06-Working-With-Textures/) |
-| [Chapter 07: Optimizing Texture Rendering](07_optimizing_texture_rendering/index.md) | Explore optimization techniques when rendering textures using a texture atlas. | [07-Optimize-Texture-Rendering](https://github.com/shyfox-studio/learn-monogame-2d/tree/main/src/07-Optmize-Texture-Rendering/) |
-| [Chapter 08: The Sprite Class](08_the_sprite_class/index.md) | Explore creating a reusable Sprite class to efficiently manage sprites and their rendering properties, including position, rotation, scale, and more. | [08-The-Sprite-Class](https://github.com/shyfox-studio/learn-monogame-2d/tree/main/src/08-The-Sprite-Class/) |
-| [Chapter 09: The AnimatedSprite Class](09_the_animatedsprite_class/index.md) | Create an AnimatedSprite class that builds upon our Sprite class to support frame-based animations. | [09-The-AnimatedSprite-Class](https://github.com/shyfox-studio/learn-monogame-2d/tree/main/src/09-The-AnimatedSprite-Class/) |
-| [Chapter 10: Handling Input](10_handling_input/index.md) | Learn how to handle keyboard, mouse, and gamepad input in MonoGame. | [10-Handling-Input](https://github.com/shyfox-studio/learn-monogame-2d/tree/main/src/10-Handling-Input/) |
-| [Chapter 11: Input Management](11_input_management/index.md) | Learn how to create an input management system to handle keyboard, mouse, and gamepad input, including state tracking between frames and creating a reusable framework for handling player input. | [11-Input-Management](https://github.com/shyfox-studio/learn-monogame-2d/tree/main/src/11-Input-Management/) |
-| [Chapter 12: Collision Detection](12_collision_detection/index.md) | Learn how to implement collision detection between game objects and handle collision responses like blocking, triggering events, and bouncing. | [12-Collision-Detection](https://github.com/shyfox-studio/learn-monogame-2d/tree/main/src/12-Collision-Detection/) |
-| [Chapter 14: Sound Effects and Music](14_soundeffects_and_music/index.md) | Learn how to load and play sound effects and background music in MonoGame, including managing audio volume, looping, and handling multiple simultaneous sound effects. | [14-SoundEffects-And-Music](https://github.com/shyfox-studio/learn-monogame-2d/tree/main/src/14-SoundEffects-And-Music/) |
-| [Chapter 15: Audio Controller](15_audio_controller/index.md) | Learn how to create a reusable audio controller class to manage sound effects and music, including volume control, muting/unmuting, and proper resource cleanup. | [15-Audio-Controller](https://github.com/shyfox-studio/learn-monogame-2d/tree/main/src/15-Audio-Controller/) |
-| [Chapter 16: Working with SpriteFonts](16_working_with_spritefonts/index.md) | Learn how to create and use SpriteFonts to render text in your MonoGame project, including loading custom fonts and controlling text appearance. | [16-Working-With-SpriteFonts](https://github.com/shyfox-studio/learn-monogame-2d/tree/main/src/16-Working-With-SpriteFonts/) |
-| [Chapter 17: Scenes](17_scenes/index.md) | Learn how to implement scene management to handle different game screens like menus, gameplay, and transitions between scenes. | [17-Scenes](https://github.com/shyfox-studio/learn-monogame-2d/tree/main/src/17-Scenes/) |
-| [Chapter 18: Texture Sampling](18_texture_sampling/index.md) | Learn how to use texture sampling states and add a scrolling background effect to the game. | [18-Texture-Wrapping](https://github.com/shyfox-studio/learn-monogame-2d/tree/main/src/18-Texture-Wrapping/) |
-| [Chapter 19: User Interface Fundamentals](19_user_interface_fundamentals/index.md) | Learn the core principles of game user interface design. | [19-User-Interface-Fundamentals](https://github.com/shyfox-studio/learn-monogame-2d/tree/main/src/19-User-Interface-Fundamentals/) |
-| [Chapter 20: Implementing UI with Gum](20_implementing_ui_with_gum/index.md) | Learn how to integrate and use the Gum UI framework to create functional menus, buttons, and sliders for your MonoGame projects. | [20-Implementing-UI-With-Gum](https://github.com/shyfox-studio/learn-monogame-2d/tree/main/src/20-Implementing-UI-With-Gum/) |
-| [Chapter 21: Customizing Gum UI](21_customizing_gum_ui/index.md) | Learn how to create custom UI components with animations and visual styling in Gum. | [21-Customizing-Gum-UI](https://github.com/shyfox-studio/learn-monogame-2d/tree/main/src/21-Customizing-Gum-UI/) |
-| [Chapter 22: Snake Game Mechanics](22_snake_game_mechanics/index.md) | Learn how to implement classic snake-like game mechanics and organize game objects into reusable components. | [22-Snake-Game-Mechanics](https://github.com/shyfox-studio/learn-monogame-2d/tree/main/src/22-Snake-Game-Mechanics/) |
-| [Chapter 23: Completing the Game](23_completing_the_game/index.md) | Finalize game mechanics by updating our current demo into a snake-like inspired game. | [23-Completing-The-Game](https://github.com/shyfox-studio/learn-monogame-2d/tree/main/src/23-Completing-The-Game/) |
-| [Chapter 24: Shaders](24_shaders/index.md) | Learn how to create custom visual effects using shaders in MonoGame. | [24-Completing-The-Game](https://github.com/shyfox-studio/learn-monogame-2d/tree/main/src/24-Shaders/) |
+| [Chapter 01: What Is MonoGame](01_what_is_monogame/index.md) | Learn about the history of MonoGame and explore the features it provides to developers when creating games. | [01-What-Is-MonoGame](https://github.com/MonoGame/MonoGame.Samples/tree/3.8.4/Tutorials/learn-monogame-2d/src/01-What-Is-MonoGame/) |
+| [Chapter 02: Getting Started](02_getting_started/index.md) | Setup your development environment for .NET development and MonoGame using Visual Studio Code as your IDE. | [02-Getting-Started](https://github.com/MonoGame/MonoGame.Samples/tree/3.8.4/Tutorials/learn-monogame-2d/src/02-Getting-Started/) |
+| [Chapter 03: The Game1 File](03_the_game1_file/index.md) | Explore the contents of the Game1 file generated when creating a new MonoGame project. | [03-The-Game1-File](https://github.com/MonoGame/MonoGame.Samples/tree/3.8.4/Tutorials/learn-monogame-2d/src/03-The-Game1-File/) |
+| [Chapter 04: Creating a Class Library](04_creating_a_class_library/index.md) | Learn how to create and structure a reusable MonoGame class library to organize game components and share code between projects. | [04-Creating-A-Class-Library](https://github.com/MonoGame/MonoGame.Samples/tree/3.8.4/Tutorials/learn-monogame-2d/src/04-Creating-A-Class-Library/) |
+| [Chapter 05: Content Pipeline](05_content_pipeline/index.md) | Learn the advantages of using the **Content Pipeline** to load assets and go through the processes of loading your first asset | [05-Content-Pipeline](https://github.com/MonoGame/MonoGame.Samples/tree/3.8.4/Tutorials/learn-monogame-2d/src/05-Content-Pipeline/) |
+| [Chapter 06: Working with Textures](06_working_with_textures/index.md) | Learn how to load and render textures using the MonoGame content pipeline and [**SpriteBatch**](xref:Microsoft.Xna.Framework.Graphics.SpriteBatch). | [06-Working-With-Textures](https://github.com/MonoGame/MonoGame.Samples/tree/3.8.4/Tutorials/learn-monogame-2d/src/06-Working-With-Textures/) |
+| [Chapter 07: Optimizing Texture Rendering](07_optimizing_texture_rendering/index.md) | Explore optimization techniques when rendering textures using a texture atlas. | [07-Optimize-Texture-Rendering](https://github.com/MonoGame/MonoGame.Samples/tree/3.8.4/Tutorials/learn-monogame-2d/src/07-Optmize-Texture-Rendering/) |
+| [Chapter 08: The Sprite Class](08_the_sprite_class/index.md) | Explore creating a reusable Sprite class to efficiently manage sprites and their rendering properties, including position, rotation, scale, and more. | [08-The-Sprite-Class](https://github.com/MonoGame/MonoGame.Samples/tree/3.8.4/Tutorials/learn-monogame-2d/src/08-The-Sprite-Class/) |
+| [Chapter 09: The AnimatedSprite Class](09_the_animatedsprite_class/index.md) | Create an AnimatedSprite class that builds upon our Sprite class to support frame-based animations. | [09-The-AnimatedSprite-Class](https://github.com/MonoGame/MonoGame.Samples/tree/3.8.4/Tutorials/learn-monogame-2d/src/09-The-AnimatedSprite-Class/) |
+| [Chapter 10: Handling Input](10_handling_input/index.md) | Learn how to handle keyboard, mouse, and gamepad input in MonoGame. | [10-Handling-Input](https://github.com/MonoGame/MonoGame.Samples/tree/3.8.4/Tutorials/learn-monogame-2d/src/10-Handling-Input/) |
+| [Chapter 11: Input Management](11_input_management/index.md) | Learn how to create an input management system to handle keyboard, mouse, and gamepad input, including state tracking between frames and creating a reusable framework for handling player input. | [11-Input-Management](https://github.com/MonoGame/MonoGame.Samples/tree/3.8.4/Tutorials/learn-monogame-2d/src/11-Input-Management/) |
+| [Chapter 12: Collision Detection](12_collision_detection/index.md) | Learn how to implement collision detection between game objects and handle collision responses like blocking, triggering events, and bouncing. | [12-Collision-Detection](https://github.com/MonoGame/MonoGame.Samples/tree/3.8.4/Tutorials/learn-monogame-2d/src/12-Collision-Detection/) |
+| [Chapter 14: Sound Effects and Music](14_soundeffects_and_music/index.md) | Learn how to load and play sound effects and background music in MonoGame, including managing audio volume, looping, and handling multiple simultaneous sound effects. | [14-SoundEffects-And-Music](https://github.com/MonoGame/MonoGame.Samples/tree/3.8.4/Tutorials/learn-monogame-2d/src/14-SoundEffects-And-Music/) |
+| [Chapter 15: Audio Controller](15_audio_controller/index.md) | Learn how to create a reusable audio controller class to manage sound effects and music, including volume control, muting/unmuting, and proper resource cleanup. | [15-Audio-Controller](https://github.com/MonoGame/MonoGame.Samples/tree/3.8.4/Tutorials/learn-monogame-2d/src/15-Audio-Controller/) |
+| [Chapter 16: Working with SpriteFonts](16_working_with_spritefonts/index.md) | Learn how to create and use SpriteFonts to render text in your MonoGame project, including loading custom fonts and controlling text appearance. | [16-Working-With-SpriteFonts](https://github.com/MonoGame/MonoGame.Samples/tree/3.8.4/Tutorials/learn-monogame-2d/src/16-Working-With-SpriteFonts/) |
+| [Chapter 17: Scenes](17_scenes/index.md) | Learn how to implement scene management to handle different game screens like menus, gameplay, and transitions between scenes. | [17-Scenes](https://github.com/MonoGame/MonoGame.Samples/tree/3.8.4/Tutorials/learn-monogame-2d/src/17-Scenes/) |
+| [Chapter 18: Texture Sampling](18_texture_sampling/index.md) | Learn how to use texture sampling states and add a scrolling background effect to the game. | [18-Texture-Wrapping](https://github.com/MonoGame/MonoGame.Samples/tree/3.8.4/Tutorials/learn-monogame-2d/src/18-Texture-Wrapping/) |
+| [Chapter 19: User Interface Fundamentals](19_user_interface_fundamentals/index.md) | Learn the core principles of game user interface design. | [19-User-Interface-Fundamentals](https://github.com/MonoGame/MonoGame.Samples/tree/3.8.4/Tutorials/learn-monogame-2d/src/19-User-Interface-Fundamentals/) |
+| [Chapter 20: Implementing UI with Gum](20_implementing_ui_with_gum/index.md) | Learn how to integrate and use the Gum UI framework to create functional menus, buttons, and sliders for your MonoGame projects. | [20-Implementing-UI-With-Gum](https://github.com/MonoGame/MonoGame.Samples/tree/3.8.4/Tutorials/learn-monogame-2d/src/20-Implementing-UI-With-Gum/) |
+| [Chapter 21: Customizing Gum UI](21_customizing_gum_ui/index.md) | Learn how to create custom UI components with animations and visual styling in Gum. | [21-Customizing-Gum-UI](https://github.com/MonoGame/MonoGame.Samples/tree/3.8.4/Tutorials/learn-monogame-2d/src/21-Customizing-Gum-UI/) |
+| [Chapter 22: Snake Game Mechanics](22_snake_game_mechanics/index.md) | Learn how to implement classic snake-like game mechanics and organize game objects into reusable components. | [22-Snake-Game-Mechanics](https://github.com/MonoGame/MonoGame.Samples/tree/3.8.4/Tutorials/learn-monogame-2d/src/22-Snake-Game-Mechanics/) |
+| [Chapter 23: Completing the Game](23_completing_the_game/index.md) | Finalize game mechanics by updating our current demo into a snake-like inspired game. | [23-Completing-The-Game](https://github.com/MonoGame/MonoGame.Samples/tree/3.8.4/Tutorials/learn-monogame-2d/src/23-Completing-The-Game/) |
+| [Chapter 24: Shaders](24_shaders/index.md) | Learn how to create custom visual effects using shaders in MonoGame. | [24-Completing-The-Game](https://github.com/MonoGame/MonoGame.Samples/tree/3.8.4/Tutorials/learn-monogame-2d/src/24-Shaders/) |
| [Chapter 25: Packaging Your Game for Distribution](25_packaging_game/index.md) | Learn how to package your game for distribution across Windows, macOS, and Linux platforms. | |
| [Chapter 26: Publishing Your Game to itch.io](26_publish_to_itch/index.md) | Learn how to deploy your MonoGame project to itch.io and configure it for players across different platforms. | |
| [Chapter 27: Conclusion and Next Steps](27_conclusion/index.md) | Review key MonoGame concepts learned, discover community resources, and get practical advice for beginning your own game development projects. | |
diff --git a/articles/tutorials/index.md b/articles/tutorials/index.md
index 27d00df2..94fc1277 100644
--- a/articles/tutorials/index.md
+++ b/articles/tutorials/index.md
@@ -8,14 +8,66 @@ description: Tutorials provided by MonoGame community members.
>
> Have a tutorial suggestion, article or series that really helped you? Then please [log an issue](https://github.com/MonoGame/docs.monogame.github.io/issues) to get it included.
+<section class="container-xxl mb-5">
+ <div class="row">
+ <div class="col-12 col-lg-4 mb-5">
+ <div class="mg-card mg-box-shadow h-100">
+ <a target="_self"
+ href="/tutorials/building_2d_games/index.html"
+ class="mg-no-link">
+ <div class="mg-card-body d-flex flex-column h-100">
+ <div class="mg-card-title"><i class="bi bi-files"></i> 2D Getting started tutorial</div>
+ <p>
+ The official MonoGame 2D getting started guide for MonoGame, covering everything from getting setup to publishing your first game on Itchio.
+ </p>
+ <p class="mt-auto">Click to view 2D tutorial</p>
+ </div>
+ </a>
+ </div>
+ </div>
+ <div class="col-12 col-lg-4 mb-5">
+ <div class="mg-card mg-box-shadow h-100">
+ <a target="_self"
+ href="/tutorials/index.html"
+ class="mg-no-link">
+ <div class="mg-card-body d-flex flex-column h-100">
+ <div class="mg-card-title"><i class="bi bi-filetype-cs"></i> 3D Getting started - coming soon</div>
+ <p>
+ The official MonoGame 3D getting started guide is currently in production, check back often or look at the Discord announcements.
+ </p>
+ <p class="mt-auto">Coming Soon</p>
+ </div>
+ </a>
+ </div>
+ </div>
+ <div class="col-12 col-lg-4 mb-5">
+ <div class="mg-card mg-box-shadow h-100">
+ <a target="_self"
+ href="/roadmap/index.html"
+ class="mg-no-link">
+ <div class="mg-card-body d-flex flex-column h-100">
+ <div class="mg-card-title"><i class="bi bi-lightbulb"></i> Roadmap</div>
+ <p>
+ Check out the MonoGame roadmap for more incoming educational content.
+ </p>
+ <p class="mt-auto">See what is coming</p>
+ </div>
+ </a>
+ </div>
+ </div>
+ </div>
+</section>
+
+## Other community recommended tutorials
+
Check out the awesome work of the larger MonoGame community with their own tutorials, blogs and videos.
-## Microsoft
+### Microsoft
- [XNA Game Studio educational resources archive](https://github.com/SimonDarksideJ/XNAGameStudio)
- [Archived XNA Game Studio documentation](https://docs.microsoft.com/en-us/previous-versions/windows/xna/bb200104(v=xnagamestudio.41))
-## RB Whitaker's MonoGame Tutorials
+### RB Whitaker's MonoGame Tutorials
- [1 - C# Crash Course](http://rbwhitaker.wikidot.com/c-sharp-tutorials)
- [2 - MonoGame Getting started tutorials](http://rbwhitaker.wikidot.com/monogame-getting-started-tutorials)
@@ -23,19 +75,19 @@ Check out the awesome work of the larger MonoGame community with their own tutor
- [4 - 3D tutorials](http://rbwhitaker.wikidot.com/monogame-3d-tutorials)
- [Extra - XNA tutorials](http://rbwhitaker.wikidot.com/xna-tutorials)
-## Neil Danson's F# series
+### Neil Danson's F# series
- [Part 1 - MacOS](http://neildanson.wordpress.com/2013/07/30/f-and-monogame/)
- [Part 2 - Android](http://neildanson.wordpress.com/2013/07/31/f-and-monogame-part-2-android/)
- [Part 3 - iOS](http://neildanson.wordpress.com/2013/07/31/f-and-monogame-part-3-ios/)
- [Part 4 - Content Pipeline](http://neildanson.wordpress.com/2013/08/13/f-and-monogame-part-4-content-pipeline/)
-## Shaders
+### Shaders
- [MonoGame-Pixel-Planets - a port of Pixel Planets made by DeepFold with a lot of GLSL shaders converted to HLSL](https://github.com/EnthusiastGuy/MonoGame-Pixel-Planets)
- [MonoGame-Shader-Samples](https://github.com/cpt-max/MonoGame-Shader-Samples)
-## Darkside of MonoGame video series
+### Darkside of MonoGame video series
- [Getting Started with MonoGame using Visual Studio 2019](https://www.youtube.com/watch?v=BahlvXQcJw4)
- [Getting Started with MonoGame using Visual Studio for Mac](https://www.youtube.com/watch?v=Hxo9A0-qcVo)
@@ -47,14 +99,14 @@ Check out the awesome work of the larger MonoGame community with their own tutor
- [MonoGame - Building multi-platform solutions](https://www.youtube.com/watch?v=WonVmlpPBuU&t=735s)
- [Building apps & games for Xbox One using UWP](https://www.youtube.com/watch?v=AAMToCwPy8s&t=1s)
-## Video Tutorials
+### Video Tutorials
- [CodingMadeEasy RPG Tutorial](http://www.youtube.com/watch?feature=player_embedded&v=agt9-J9RPZ0)
- [Psuedo Games Tutorials](http://www.youtube.com/watch?feature=player_embedded&v=BwtQn02oy6A)
- [Batholith Entertainment Game dev tutorials](https://www.youtube.com/playlist?list=PLZ6ofHM1rvK8lQSoKX1USZstM-ZXikFHp)
- [Let's Code: The T-Rex Runner Game with MonoGame](https://www.youtube.com/watch?v=DJCQVJ83J1U)
-## Others
+### Others
- [Dark Genesis Blog MonoGame content](https://darkgenesis.zenithmoon.com/tag.html?tag=monogame)
- [awesome-monogame - A large list of MonoGame libraries and more by aloisdeniel](https://github.com/aloisdeniel/awesome-monogame)
@@ -71,19 +123,19 @@ Check out the awesome work of the larger MonoGame community with their own tutor
- [Text rendering in MonoGame](https://roy-t.nl/2018/07/04/Text-Rendering.html)
- [Randomchaos-MonoGame-Samples](https://github.com/NemoKradXNA/Randomchaos-MonoGame-Samples)
-## Other Languages
+### Other Languages
A collection of tutorials in other languages:
-### Portuguese
+#### Portuguese
- [Desenvolvimento de jogos para Windows 8 com XNA - Alexandre Chohfi (Portuguese)](https://www.youtube.com/watch?v=gM5pRnYV1tA)
-### French
+#### French
- [French articles about MonoGame on Linux, Windows and Windows 8](http://www.demonixis.net/blog/category/tutoriels/tuto-xna/)
-## We Need Your Help!
+## We Need Your Help
MonoGame is an open-source project maintained by its community. Great open source projects require high-quality documentation. This is a call for volunteers to continue to help us make the MonoGame documentation truly great. If you can create tutorials, feature guides, code snippets, reference docs, video walkthroughs, or make any improvement to the current documentation, we could use your help!
diff --git a/articles/whats_new.md b/articles/whats_new.md
index 694afca7..f490720f 100644
--- a/articles/whats_new.md
+++ b/articles/whats_new.md
@@ -1,14 +1,45 @@
---
title: Whats New
-description: What is new with the release of MonoGame 3.8.2
+description: What is new with the release of MonoGame 3.8.*
---
-## MonoGame 3.8.2 (notes coming soon)
+## MonoGame 3.8.4
> [!NOTE]
> **Coming soon**
> Refer to the [CHANGELOG](https://github.com/MonoGame/MonoGame/blob/develop/CHANGELOG.md) for a more complete list of the changes.
+Notes for the final 3.8.4 release are still in progress. Preview builds available.
+
+> [!NOTE]
+> More details to follow
+
+## MonoGame 3.8.3
+
+> [!NOTE]
+> Refer to the [CHANGELOG](https://github.com/MonoGame/MonoGame/blob/develop/CHANGELOG.md) for a more complete list of the changes.
+
+* SDL bumped to 2.32.2
+* VS2022 Extension with new 2D cross-platform project templates
+* Content pipeline working on all supported platforms
+* Content Pipeline updated to use the new FreeType and FreeImage
+* Improved / updated content pipeline dependencies (Textures, Audio, Input)
+* Several SoundEffect fixes, including OpenAL update
+* GamePad button mappings on Android and iOS, Plus Joystick input fixes
+* MonoGame updated to be more AOT/trimming compliant
+* Fix Android MediaPlayer Song
+* Preliminary scaffolding for new Native platform
+* API Documentation updates
+* Vulkan in preview
+
+> [!NOTE]
+> More details to follow
+
+## MonoGame 3.8.2
+
+> [!NOTE]
+> Refer to the [CHANGELOG](https://github.com/MonoGame/MonoGame/blob/develop/CHANGELOG.md) for a more complete list of the changes.
+
* Update to .NET 8, including the MGCB tool (now a local tool rather than global, allowing different projects to use different versions)
* Removal of Windows UWP due to Microsoft shutting support for it (you can still use UWP if you remain on 3.8.1)
* Updated to building dependencies to improve support.
diff --git a/external/MonoGame b/external/MonoGame
index c42673d2..f7520d18 160000
--- a/external/MonoGame
+++ b/external/MonoGame
@@ -1 +1 @@
-Subproject commit c42673d2bb4d37664272951e57ad60e5948d387d
+Subproject commit f7520d18291d55d830c738a366ab0b09385931bf
diff --git a/index.md b/index.md
index 74e1e5fb..c7e720a1 100644
--- a/index.md
+++ b/index.md
@@ -47,7 +47,7 @@ description: MonoGame Documentation Hub
<div class="col-12 col-lg-4 mb-5">
<div class="mg-card mg-box-shadow h-100">
<a target="_self"
- href="/articles/tutorials.html"
+ href="/articles/tutorials/index.html"
class="mg-no-link">
<div class="mg-card-body d-flex flex-column h-100">
<div class="mg-card-title"><i class="bi bi-lightbulb"></i> Tutorials</div>