Skip to content

Commit ec48260

Browse files
AristurtleDevAristurtleDev
committed
Merge branch 'main' into 2d-tutorial-bounty
2 parents 3424016 + 5139a3d commit ec48260

11 files changed

+207
-59
lines changed

‎articles/getting_started/1_setting_up_your_os_for_development_macos.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,7 @@ If you intend to also work with platforms such as `Android` or `iOS`, you will n
3434
> [!NOTE]
3535
> You can use `dotnet workload search` to detect any other available workloads you wish to use.
3636
37-
# Apple Silicon Known Issues
37+
## Apple Silicon Known Issues
3838

3939
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.
4040

‎articles/getting_started/1_setting_up_your_os_for_development_ubuntu.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,9 @@ title: Setting up your OS for development on Ubuntu
33
description: This section provides a step-by-step guide for setting up your development environment on Ubuntu.
44
---
55

6+
> [!TIP]
7+
> The minimum version of Ubuntu that is supported by MonoGame is `20.04`.
8+
69
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.
710

811
## Install .NET 8 SDK

‎articles/getting_started/2_choosing_your_ide_rider.md

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,11 @@ You can download and install Rider from: [https://www.jetbrains.com/rider/downlo
2626
dotnet new install MonoGame.Templates.CSharp
2727
```
2828

29+
> [!TIP]
30+
> Alternatively, consider using the Preview Packages provided by MonoGame to get access to the latest developments.
31+
>
32+
> * [How to install MonoGame Preview packages](../getting_to_know/howto/HowTo_Install_Preview_Release.md)
33+
2934
## Creating a new MonoGame project
3035

3136
To get you started with Rider, here are the steps for setting up a new Rider MonoGame project.
@@ -42,6 +47,19 @@ To get you started with Rider, here are the steps for setting up a new Rider Mon
4247
4. Press "Create"
4348
5. You can now press `F5` to compile and debug your game, happy coding :)
4449

50+
## Update Project Tool references
51+
52+
The MonoGame Content Editor (MGCB) it a tool delivered through NuGet for your project using the tools configuration held in your `dotnet-tools.json` file (located in the `.config` folder of your project).
53+
54+
Once you have created your project you should run the following terminal/command-line command to ensure the tool (and the pipeline) is setup and read for your project:
55+
56+
```dotnetcli
57+
dotnet tool restore
58+
```
59+
60+
> [!NOTE]
61+
> If you ever change the version of the tools or want to upgrade them by editing the `dotnet-tools.json` configuration, you MUST run this command again to update te tools.
62+
4563
## Next Steps
4664

4765
Next, get to know MonoGame's code structure and project layout:

‎articles/getting_started/2_choosing_your_ide_visual_studio.md

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -37,12 +37,14 @@ To create new MonoGame projects from within Visual Studio 2022, you will need to
3737

3838
> [!WARNING]
3939
> **Visual Studio Extension Issues**
40-
>
40+
>
4141
> The extension that is installed by Visual Studio 2022 is currently outdated.
4242
> Instead of using Visual Studio 2022 to install the templates, run the following command:
43+
>
4344
> ```sh
4445
> dotnet new install MonoGame.Templates.CSharp
4546
> ```
47+
>
4648
> After doing this, you should be able to launch Visual Studio 2022 and create a new project with the newly installed templates.
4749
4850
1. Launch Visual Studio 2022
@@ -66,6 +68,11 @@ To create new MonoGame projects from within Visual Studio 2022, you will need to
6668
6769
You now have the MonoGame templates installed and are ready to create new projects.
6870
71+
> [!TIP]
72+
> Alternatively, consider using the Preview Packages provided by MonoGame to get access to the latest developments.
73+
>
74+
> - [How to install MonoGame Preview packages](../getting_to_know/howto/HowTo_Install_Preview_Release.md)
75+
6976
## Creating a new MonoGame project
7077
7178
To get you started with Visual Studio, here are the steps for setting up a new MonoGame project.

‎articles/getting_started/2_choosing_your_ide_vscode.md

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -49,6 +49,11 @@ By the end, you will be fully equipped to start creating games with MonoGame usi
4949
dotnet new install MonoGame.Templates.CSharp
5050
```
5151

52+
> [!TIP]
53+
> Alternatively, consider using the Preview Packages provided by MonoGame to get access to the latest developments.
54+
>
55+
> - [How to install MonoGame Preview packages](../getting_to_know/howto/HowTo_Install_Preview_Release.md)
56+
5257
## Install Visual Studio Code C# Extensions
5358

5459
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#.
@@ -89,6 +94,19 @@ You can find this extension by following the steps above and searching for "Mono
8994
4. Once the files are created, open up the `Game1.cs` file and wait a second for the C# extension to load
9095
5. You can now press F5, select C# and then your projects name if Visual Studio Code asks you, and it should start up your brand new game!
9196
97+
## Update Project Tool references
98+
99+
The MonoGame Content Editor (MGCB) it a tool delivered through NuGet for your project using the tools configuration held in your `dotnet-tools.json` file (located in the `.config` folder of your project).
100+
101+
Once you have created your project you should run the following terminal/command-line command to ensure the tool (and the pipeline) is setup and read for your project:
102+
103+
```dotnetcli
104+
dotnet tool restore
105+
```
106+
107+
> [!NOTE]
108+
> If you ever change the version of the tools or want to upgrade them by editing the `dotnet-tools.json` configuration, you MUST run this command again to update te tools.
109+
92110
## Next Steps
93111
94112
Next, get to know MonoGame's code structure and project layout:

‎articles/getting_started/index.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,7 @@ By the end of this tutorial set, you will have a working project to build for yo
3333

3434
- [Windows](./1_setting_up_your_os_for_development_windows.md)
3535
- [macOS](./1_setting_up_your_os_for_development_macos.md)
36-
- [Ubuntu 20.04](./1_setting_up_your_os_for_development_ubuntu.md)
36+
- [Ubuntu](./1_setting_up_your_os_for_development_ubuntu.md)
3737

3838
### 2. Choosing your IDE for development
3939

‎articles/getting_started/packaging_games.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -153,6 +153,10 @@ We recommend using the `.tar.gz` archiving format to preserve the execution perm
153153

154154
### PublishAot and PublishTrimmed
155155

156+
> [!IMPORTANT]
157+
> The WindowsDX target is not compatible with ```PublishAot``` or ```PublishTrimmed``` because it uses Windows Forms, which is (as of .NET 9) not compatible with these options. If you need trimming or AOT compilation for desktop platforms, please consider using the DesktopGL target instead of WindowsDX.
158+
159+
156160
The ```PublishAot``` option optimises your game code "Ahead of Time" for performance. It allows you to ship your game without the need to JIT (Just In Time compile), and will basically natively compile your game.
157161

158162
```PublishAot``` binaries are much faster, which is typically desired for games. It however comes with limitations, like the inability to use runtime reflection and runtime code generation (IL emition).

‎articles/getting_started/using_development_nuget_packages.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,11 @@ description: How to use the latest development NuGet packages to use the cutting
77

88
When the MonoGame develop branch builds, it publishes development NuGet packages to the MonoGame NuGet Feed on GitHub. If you want to test a new feature or just be on the very latest code you can use this Feed to do that.
99

10+
> [!TIP]
11+
> Alternatively, consider using the Preview Packages provided by MonoGame to get access to the latest preview release rather than the raw development code.
12+
>
13+
> * [How to install MonoGame Preview packages](../getting_to_know/howto/HowTo_Install_Preview_Release.md)
14+
1015
## Adding a NuGet Source
1116

1217
1. Create a `NuGet.config` in the root or top level directory of your project.

‎articles/getting_to_know/howto/HowTo_Install_Preview_Release.md

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
---
2+
title: How to install a preview release of MonoGame from NuGet
3+
description: This topic describes how to use a preview release of MonoGame in a new or existing project.
4+
---
5+
6+
## Overview
7+
8+
MonoGame provides preview deployments for testing releases prior to the full release of a new version. This gives developers early access to new features before they are made officially available.
9+
10+
> [!WARNING]
11+
> While preview releases still undergo the same rigorous testing used for full releases, some features may not work as expected as it is still classed as developmental code.
12+
>
13+
> *Preview releases should not be used for production deployments.**
14+
>
15+
> The preview packages are intended for testing and validating fixes/updates and new features in your projects without drastically affecting them.
16+
17+
## Updating NuGet package dependencies
18+
19+
To use the preview packages delivered via NuGet you need to update or replace your existing MonoGame references for your project:
20+
21+
- The Platform NuGet package reference - e.g. `MonoGame.Framework.DesktopGL`
22+
- The Builder Task package - `MonoGame.Content.Builder.Task` (Only required if using the Content Pipeline)
23+
24+
The simplest way is from the command line in the folder where your `csproj` is located (if you have multiple projects, please repeat for each) using the following syntax:
25+
26+
```dotnetcli
27+
dotnet add package MonoGame.Framework.DesktopGL -v 3.8.4-preview.1
28+
dotnet add package MonoGame.Content.Builder.Task -v 3.8.4-preview.1
29+
```
30+
31+
**Replacing the preview version with the specific version you wish to install.**
32+
33+
> [!NOTE]
34+
> For Visual Studio, use `Tools -> NuGet Package Manager -> Manage NuGet Packages for Solution/Project`, then click on the `Updates` tab and update each package.
35+
>
36+
> Make sure to select **"Include Prerelease"** for the preview packages to be detected.
37+
38+
## Update `dotnet-tools.json` for Content Manager
39+
40+
To ensure symmetry between the project version and the Content Pipeline Editor (MGCB) the `dotnet-tools.json` configuration in your project `.config` directory will also need updating.
41+
42+
This is simply a matter of updating the tools references, again from the command line in the projects folder, as follows:
43+
44+
```dotnetcli
45+
dotnet tool install dotnet-mgcb --version 3.8.4-preview.1
46+
dotnet tool install dotnet-mgcb-editor --version 3.8.4-preview.1
47+
dotnet tool install dotnet-mgcb-editor-linux --version 3.8.4-preview.1
48+
dotnet tool install dotnet-mgcb-editor-windows --version 3.8.4-preview.1
49+
dotnet tool install dotnet-mgcb-editor-mac --version 3.8.4-preview.1
50+
```
51+
52+
**Replacing the preview version with the specific version you wish to install.**
53+
54+
> [!NOTE]
55+
> Alternatively, simply edit the `dotnet-tools.json` file and replace the **"version"** value across the file.
56+
57+
58+
> [!IMPORTANT]
59+
> Make sure to run `dotnet tool restore` any time you make changes to the `dotnet-tools.json` to refresh the installation of the Content Builder and Editor.
60+
61+
## Installing the preview templates
62+
63+
This step is optional, if you intend to generate a new project using the latest templates, including any automated or templates setup
64+
65+
1. Simply run the following from the command line:
66+
67+
```dotnetcli
68+
dotnet new install MonoGame.Templates.CSharp::3.8.4-preview.1
69+
```
70+
71+
**Replacing the preview version of MonoGame at the end of the command with the specific version you wish to install.**
72+
73+
## Visual Studio Extensions with Preview releases
74+
75+
At this time, the Visual Studio marketplace does not support preview versions of extensions, if you wish to test a preview version of the Visual Studio Extension, you can install it manually.
76+
77+
The Extension can be downloaded from the latest `GitHub Actions` build used to generate the preview build.
78+
79+
1. Go to the [MonoGame GitHub repository](https://github.com/MonoGame/MonoGame/actions) and select the "Actions" tab.
80+
1. Find the build with the associated tag, e.g. [`v3.8.4-preview.1`](https://github.com/MonoGame/MonoGame/actions/runs/14713318149)
81+
1. In the `Artifacts` for the build, you should see the extensions installer `MonoGame.Templates.VSExtension.vsix`
82+
1. Click on the "Download Icon" on the far right-hand side of the row.
83+
1. Once downloaded, run the `vsix` which will update your installation of the extensions package.
84+
85+
## See Also
86+
87+
- [Getting Started with MonoGame](../../getting_started/index.md)
88+
- [Using Development NuGet Packages](../../getting_started/using_development_nuget_packages.md)

‎articles/getting_to_know/howto/index.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -72,3 +72,7 @@ This section contains articles to help make your MonoGame project successful.
7272
* [How to apply Best Practices for MonoGame Games](HowTo_MobileBestPractices.md)
7373

7474
The practices discussed here will help you have the most success possible with your MonoGame game.
75+
76+
* [How to install MonoGame Preview packages](HowTo_Install_Preview_Release.md)
77+
78+
This topic describes how to use a preview release of MonoGame in a new or existing project.

‎articles/toc.yml

Lines changed: 57 additions & 56 deletions
Original file line numberDiff line numberDiff line change
@@ -1,68 +1,69 @@
1+
items:
12
- name: Introduction
2-
href:
3+
href: index.md
34
- name: Roadmap
45
href: /roadmap/
56
- name: What's New
67
href: whats_new.md
78
- name: Getting Started
89
href: getting_started/index.md
910
items:
11+
- name: Introduction
12+
href: getting_started/
13+
- name: Supported platforms
14+
href: getting_started/platforms.md
15+
- name: 1. Setting up your OS for development
16+
items:
17+
- name: Windows
18+
href: getting_started/1_setting_up_your_os_for_development_windows.md
19+
- name: macOS
20+
href: getting_started/1_setting_up_your_os_for_development_macos.md
21+
- name: Ubuntu
22+
href: getting_started/1_setting_up_your_os_for_development_ubuntu.md
23+
- name: 2. Choosing your IDE
24+
items:
25+
- name: Visual Studio for Windows
26+
href: getting_started/2_choosing_your_ide_visual_studio.md
27+
- name: Visual Studio Code
28+
href: getting_started/2_choosing_your_ide_vscode.md
29+
- name: Rider
30+
href: getting_started/2_choosing_your_ide_rider.md
31+
- name: 3. Understanding the Code
32+
href: getting_started/3_understanding_the_code.md
33+
- name: 4. Adding Content
34+
href: getting_started/4_adding_content.md
35+
- name: 5. Adding Basic Code
36+
href: getting_started/5_adding_basic_code.md
37+
- name: Packaging
38+
href: getting_started/packaging_games.md
39+
- name: Preparing for consoles
40+
href: getting_started/preparing_for_consoles.md
41+
- name: Using Development Nuget Packages
42+
href: getting_started/using_development_nuget_packages.md
43+
- name: Tools
44+
items:
1045
- name: Introduction
11-
href: getting_started/
12-
- name: Supported platforms
13-
href: getting_started/platforms.md
14-
- name: 1. Setting up your OS for development
15-
items:
16-
- name: Windows
17-
href: getting_started/1_setting_up_your_os_for_development_windows.md
18-
- name: macOS
19-
href: getting_started/1_setting_up_your_os_for_development_macos.md
20-
- name: Ubuntu 20.04
21-
href: getting_started/1_setting_up_your_os_for_development_ubuntu.md
22-
- name: 2. Choosing your IDE
23-
items:
24-
- name: Visual Studio for Windows
25-
href: getting_started/2_choosing_your_ide_visual_studio.md
26-
- name: Visual Studio Code
27-
href: getting_started/2_choosing_your_ide_vscode.md
28-
- name: Rider
29-
href: getting_started/2_choosing_your_ide_rider.md
30-
- name: 3. Understanding the Code
31-
href: getting_started/3_understanding_the_code.md
32-
- name: 4. Adding Content
33-
href: getting_started/4_adding_content.md
34-
- name: 5. Adding Basic Code
35-
href: getting_started/5_adding_basic_code.md
36-
- name: Packaging
37-
href: getting_started/packaging_games.md
38-
- name: Preparing for consoles
39-
href: getting_started/preparing_for_consoles.md
40-
- name: Using Development Nuget Packages
41-
href: getting_started/using_development_nuget_packages.md
42-
- name: Tools
43-
items:
44-
- name: Introduction
45-
href: getting_started/tools/
46-
- name: MGCB
47-
href: getting_started/tools/mgcb.md
48-
- name: MGCB Editor
49-
href: getting_started/tools/mgcb_editor.md
50-
- name: MGFXC
51-
href: getting_started/tools/mgfxc.md
52-
- name: Content Pipeline
53-
items:
54-
- name: Introduction
55-
href: getting_started/content_pipeline/index.md
56-
- name: Why use the Content Pipeline
57-
href: getting_started/content_pipeline/why_content_pipeline.md
58-
- name: Using MGCB Editor
59-
href: getting_started/content_pipeline/using_mgcb_editor.md
60-
- name: Custom Effects
61-
href: getting_started/content_pipeline/custom_effects.md
62-
- name: TrueType fonts
63-
href: getting_started/content_pipeline/adding_ttf_fonts.md
64-
- name: Localization
65-
href: getting_started/content_pipeline/localization.md
46+
href: getting_started/tools/
47+
- name: MGCB
48+
href: getting_started/tools/mgcb.md
49+
- name: MGCB Editor
50+
href: getting_started/tools/mgcb_editor.md
51+
- name: MGFXC
52+
href: getting_started/tools/mgfxc.md
53+
- name: Content Pipeline
54+
items:
55+
- name: Introduction
56+
href: getting_started/content_pipeline/index.md
57+
- name: Why use the Content Pipeline
58+
href: getting_started/content_pipeline/why_content_pipeline.md
59+
- name: Using MGCB Editor
60+
href: getting_started/content_pipeline/using_mgcb_editor.md
61+
- name: Custom Effects
62+
href: getting_started/content_pipeline/custom_effects.md
63+
- name: TrueType fonts
64+
href: getting_started/content_pipeline/adding_ttf_fonts.md
65+
- name: Localization
66+
href: getting_started/content_pipeline/localization.md
6667
- name: Getting to know MonoGame
6768
href: getting_to_know/
6869
items:

0 commit comments

Comments
 (0)