diff --git a/articles/getting_started/1_setting_up_your_os_for_development_macos.md b/articles/getting_started/1_setting_up_your_os_for_development_macos.md index c32bcada..f11d2a64 100644 --- a/articles/getting_started/1_setting_up_your_os_for_development_macos.md +++ b/articles/getting_started/1_setting_up_your_os_for_development_macos.md @@ -34,7 +34,7 @@ If you intend to also work with platforms such as `Android` or `iOS`, you will n > [!NOTE] > You can use `dotnet workload search` to detect any other available workloads you wish to use. -# Apple Silicon Known Issues +## Apple Silicon Known Issues For the time being, MonoGame requires that you install the x64 version of the .NET runtime if you are running on an Apple Silicon mac in order to be able to build content. It is also required that [Rosetta](https://support.apple.com/en-us/HT211861) is enabled. diff --git a/articles/getting_started/2_choosing_your_ide_rider.md b/articles/getting_started/2_choosing_your_ide_rider.md index 7dcab840..2e73a7a3 100644 --- a/articles/getting_started/2_choosing_your_ide_rider.md +++ b/articles/getting_started/2_choosing_your_ide_rider.md @@ -26,6 +26,11 @@ You can download and install Rider from: [https://www.jetbrains.com/rider/downlo dotnet new install MonoGame.Templates.CSharp ``` +> [!TIP] +> Alternatively, consider using the Preview Packages provided by MonoGame to get access to the latest developments. +> +> * [How to install MonoGame Preview packages](../getting_to_know/howto/HowTo_Install_Preview_Release.md) + ## Creating a new MonoGame project To get you started with Rider, here are the steps for setting up a new Rider MonoGame project. diff --git a/articles/getting_started/2_choosing_your_ide_visual_studio.md b/articles/getting_started/2_choosing_your_ide_visual_studio.md index 45b1168c..79beddff 100644 --- a/articles/getting_started/2_choosing_your_ide_visual_studio.md +++ b/articles/getting_started/2_choosing_your_ide_visual_studio.md @@ -37,12 +37,14 @@ To create new MonoGame projects from within Visual Studio 2022, you will need to > [!WARNING] > **Visual Studio Extension Issues** -> +> > The extension that is installed by Visual Studio 2022 is currently outdated. > Instead of using Visual Studio 2022 to install the templates, run the following command: +> > ```sh > dotnet new install MonoGame.Templates.CSharp > ``` +> > After doing this, you should be able to launch Visual Studio 2022 and create a new project with the newly installed templates. 1. Launch Visual Studio 2022 @@ -66,6 +68,11 @@ To create new MonoGame projects from within Visual Studio 2022, you will need to You now have the MonoGame templates installed and are ready to create new projects. +> [!TIP] +> Alternatively, consider using the Preview Packages provided by MonoGame to get access to the latest developments. +> +> - [How to install MonoGame Preview packages](../getting_to_know/howto/HowTo_Install_Preview_Release.md) + ## Creating a new MonoGame project To get you started with Visual Studio, here are the steps for setting up a new MonoGame project. diff --git a/articles/getting_started/2_choosing_your_ide_vscode.md b/articles/getting_started/2_choosing_your_ide_vscode.md index 14e5a282..e0f9a793 100644 --- a/articles/getting_started/2_choosing_your_ide_vscode.md +++ b/articles/getting_started/2_choosing_your_ide_vscode.md @@ -49,6 +49,11 @@ By the end, you will be fully equipped to start creating games with MonoGame usi dotnet new install MonoGame.Templates.CSharp ``` +> [!TIP] +> Alternatively, consider using the Preview Packages provided by MonoGame to get access to the latest developments. +> +> - [How to install MonoGame Preview packages](../getting_to_know/howto/HowTo_Install_Preview_Release.md) + ## Install Visual Studio Code C# Extensions To transform Visual Studio Code from a simple text editor into a powerful development environment for C# projects, you must install the Visual Studio Code C# extension. This extension enhances the editor by providing syntax highlighting, code analysis, IntelliSense, and other features that significantly improve the development experience and productivity when working with C#. diff --git a/articles/getting_started/using_development_nuget_packages.md b/articles/getting_started/using_development_nuget_packages.md index 91635aa3..9bbc57fe 100644 --- a/articles/getting_started/using_development_nuget_packages.md +++ b/articles/getting_started/using_development_nuget_packages.md @@ -7,6 +7,11 @@ description: How to use the latest development NuGet packages to use the cutting 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. +> [!TIP] +> Alternatively, consider using the Preview Packages provided by MonoGame to get access to the latest preview release rather than the raw development code. +> +> * [How to install MonoGame Preview packages](../getting_to_know/howto/HowTo_Install_Preview_Release.md) + ## Adding a NuGet Source 1. Create a `NuGet.config` in the root or top level directory of your project. diff --git a/articles/getting_to_know/howto/HowTo_Install_Preview_Release.md b/articles/getting_to_know/howto/HowTo_Install_Preview_Release.md new file mode 100644 index 00000000..6c006f61 --- /dev/null +++ b/articles/getting_to_know/howto/HowTo_Install_Preview_Release.md @@ -0,0 +1,88 @@ +--- +title: How to install a preview release of MonoGame from NuGet +description: This topic describes how to use a preview release of MonoGame in a new or existing project. +--- + +## Overview + +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. + +> [!WARNING] +> 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. +> +> *Preview releases should not be used for production deployments.** +> +> The preview packages are intended for testing and validating fixes/updates and new features in your projects without drastically affecting them. + +## Updating NuGet package dependencies + +To use the preview packages delivered via NuGet you need to update or replace your existing MonoGame references for your project: + +- The Platform NuGet package reference - e.g. `MonoGame.Framework.DesktopGL` +- The Builder Task package - `MonoGame.Content.Builder.Task` (Only required if using the Content Pipeline) + +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: + +```dotnetcli +dotnet add package MonoGame.Framework.DesktopGL -v 3.8.4-preview.1 +dotnet add package MonoGame.Content.Builder.Task -v 3.8.4-preview.1 +``` + +**Replacing the preview version with the specific version you wish to install.** + +> [!NOTE] +> For Visual Studio, use `Tools -> NuGet Package Manager -> Manage NuGet Packages for Solution/Project`, then click on the `Updates` tab and update each package. +> +> Make sure to select **"Include Prerelease"** for the preview packages to be detected. + +## Update `dotnet-tools.json` for Content Manager + +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. + +This is simply a matter of updating the tools references, again from the command line in the projects folder, as follows: + +```dotnetcli +dotnet tool install dotnet-mgcb --version 3.8.4-preview.1 +dotnet tool install dotnet-mgcb-editor --version 3.8.4-preview.1 +dotnet tool install dotnet-mgcb-editor-linux --version 3.8.4-preview.1 +dotnet tool install dotnet-mgcb-editor-windows --version 3.8.4-preview.1 +dotnet tool install dotnet-mgcb-editor-mac --version 3.8.4-preview.1 +``` + +**Replacing the preview version with the specific version you wish to install.** + +> [!NOTE] +> Alternatively, simply edit the `dotnet-tools.json` file and replace the **"version"** value across the file. + + +> [!IMPORTANT] +> 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. + +## Installing the preview templates + +This step is optional, if you intend to generate a new project using the latest templates, including any automated or templates setup + +1. Simply run the following from the command line: + +```dotnetcli +dotnet new install MonoGame.Templates.CSharp::3.8.4-preview.1 +``` + +**Replacing the preview version of MonoGame at the end of the command with the specific version you wish to install.** + +## Visual Studio Extensions with Preview releases + +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. + +The Extension can be downloaded from the latest `GitHub Actions` build used to generate the preview build. + +1. Go to the [MonoGame GitHub repository](https://github.com/MonoGame/MonoGame/actions) and select the "Actions" tab. +1. Find the build with the associated tag, e.g. [`v3.8.4-preview.1`](https://github.com/MonoGame/MonoGame/actions/runs/14713318149) +1. In the `Artifacts` for the build, you should see the extensions installer `MonoGame.Templates.VSExtension.vsix` +1. Click on the "Download Icon" on the far right-hand side of the row. +1. Once downloaded, run the `vsix` which will update your installation of the extensions package. + +## See Also + +- [Getting Started with MonoGame](../../getting_started/index.md) +- [Using Development NuGet Packages](../../getting_started/using_development_nuget_packages.md) diff --git a/articles/getting_to_know/howto/index.md b/articles/getting_to_know/howto/index.md index 72625d5b..3a9944fc 100644 --- a/articles/getting_to_know/howto/index.md +++ b/articles/getting_to_know/howto/index.md @@ -72,3 +72,7 @@ This section contains articles to help make your MonoGame project successful. * [How to apply Best Practices for MonoGame Games](HowTo_MobileBestPractices.md) The practices discussed here will help you have the most success possible with your MonoGame game. + +* [How to install MonoGame Preview packages](HowTo_Install_Preview_Release.md) + + This topic describes how to use a preview release of MonoGame in a new or existing project. diff --git a/articles/toc.yml b/articles/toc.yml index 14bad1b9..aa673967 100644 --- a/articles/toc.yml +++ b/articles/toc.yml @@ -1,5 +1,6 @@ +items: - name: Introduction - href: + href: index.md - name: Roadmap href: /roadmap/ - name: What's New