Merge branch 'main' into MusicAndSoundEffectsLabelAddedToSliders

Author: jordanlhunt

articles/getting_started/1_setting_up_your_os_for_development_macos.md

@@ -36,6 +36,7 @@ If you intend to also work with platforms such as `Android` or `iOS`, you will n
 ```
 
 ### [Maui](#tab/maui)
+
 ```cli
     dotnet workload install maui
 ```
@@ -51,14 +52,6 @@ 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
-
- For the time being, MonoGame requires that you install the x64 version of the .NET runtime if you are running on an Apple Silicon mac in order to be able to build content. It is also required that [Rosetta](https://support.apple.com/en-us/HT211861) is enabled. 
-
- 1. Navigate to [https://dotnet.microsoft.com/en-us/download/dotnet/9.0](https://dotnet.microsoft.com/en-us/download/dotnet/9.0)
- 1. Download the .NET Runtime Installer for macOS x64
- 1. Once the **.pkg** file finishes downloading, run it and follow the prompts to install the .NET Runtime
-
 ## Setup Wine For Effect Compilation
 
 Effect (shader) compilation requires access to DirectX.  This means it will not work natively on macOS and Linux systems, but it can be used through [Wine](https://www.winehq.org/).

articles/getting_started/1_setting_up_your_os_for_development_ubuntu.md

@@ -37,6 +37,7 @@ If you intend to also work with platforms such as `Android` or `iOS`, you will n
 ```
 
 ### [Maui](#tab/maui)
+
 ```cli
     dotnet workload install maui
 ```

articles/getting_started/1_setting_up_your_os_for_development_windows.md

@@ -42,6 +42,7 @@ If you intend to also work with platforms such as `Android` or `iOS`, you will n
 ```
 
 ### [Maui](#tab/maui)
+
 ```cli
     dotnet workload install maui
 ```

articles/getting_started/content_pipeline/automating_content_builder.md

@@ -4,7 +4,7 @@ description: Learn how to use the newest approach to building content in MonoGam
 ---
 
 > [!NOTE]
-> These intructions **REQUIRE** you to use the latest `MonoGame Develop` release (currently `3.8.5-develop.13)
+> These instructions **REQUIRE** you to use the latest `MonoGame Develop` release (currently `3.8.5-develop.13`)
 >
 > See the [instructions here](https://docs.monogame.net/articles/getting_to_know/howto/HowTo_Install_Preview_Release.html) for how to install the preview project templates and update your project to use `3.8.5-develop` (preview) releases.
 >
@@ -117,7 +117,7 @@ MyContentBuilder/
 
 This is the default (recommended) layout for a Content Builder project, but you can customize its use how you wish:
 
-- There is single "entry point" (command line launch point) contained in the `builder.cs` which contains all the instructions to build content.
+- There is a single "entry point" (command line launch point) contained in the `builder.cs` which contains all the instructions to build content.
 - A default `Assets` folder to host your content, but your content can be in any location you need it to be, simply update the parameters used to run the console application to point to the source directory and folder for your content.
 
 > [!TIP]
@@ -177,6 +177,70 @@ You should not need to touch anything else.
 >
 > See the [MS Documentation on Built targets](https://learn.microsoft.com/en-us/visualstudio/msbuild/msbuild-targets) for reference.
 
+## Platform specific additions - Android / iOS
+
+For platforms where the content is required to be packaged inside the output bundle, there are some additional steps required to ensure the built content is included during the Build/Publish step.
+
+Each platform has specific requirements and requires the built content to be available prior to processing the project itself.
+
+> [!NOTE]
+> Also check out the dedicated [Packaging Games advice](../packaging_games.md) published by the MonoGame team.
+
+### Android
+
+For Android, a specific `Include` section is needed in the project's `csproj` project definition, as follows:
+
+> [!NOTE]
+> Android uses a special `AndroidAsset` tag to identify content to include.
+
+```xml
+<ItemGroup>
+    <AndroidAsset Include="$(OutputPath)Content\**\*">
+        <Link>Content\%(RecursiveDir)%(Filename)%(Extension)</Link>
+    </AndroidAsset>
+</ItemGroup>
+```
+
+> [!NOTE]
+> If you change the location where the Content Builder project outputs content to, the paths above will need to be updated to the new location to find the content to include.
+
+At build time, the "BuildContent" task will run and execute the Content Builder, then with the output from the builder, the Android solution will automatically identify and package the content as per Google's packaging requirements, generating an `APK` for sideloading and an `AAB` for publishing to the Google Play Store.
+
+> [!NOTE]
+> If your content is too large to fit within the maximum size of the base application, you will need to use Asset Bundles to package your content, as demonstrated here:
+>
+> ```xml
+> <ItemGroup>
+>    <AndroidAsset Include="$(OutputPath)Content\**\*">
+>        <Link>Content\%(RecursiveDir)%(Filename)%(Extension)</Link>
+>    </AndroidAsset>
+>    <AndroidAsset Update="Content\Path\SomeLargeFile.xnb" AssetPack="foo" />
+> </ItemGroup>
+>
+> However, your game project will also need to be aware and update its strategy for loading the content to take the asset packs into account.
+>
+> For more details, see the [Microsoft Documentation](https://devblogs.microsoft.com/dotnet/android-asset-packs-in-dotnet-android/).
+
+### iOS
+
+For iOS, a specific `Include` section is needed in the project's `csproj` project definition, as follows:
+
+> [!NOTE]
+> iOS uses a special `BundleResource` tag to identify content to include.
+
+```xml
+<ItemGroup>
+    <BundleResource  Include="$(OutputPath)Content\**\*">
+        <Link>Content\%(RecursiveDir)%(Filename)%(Extension)</Link>
+    </BundleResource >
+</ItemGroup>
+```
+
+> [!NOTE]
+> If you change the location where the Content Builder project outputs content to, the paths above will need to be updated to the new location to find the content to include.
+
+At build time, the "BuildContent" task will run and execute the Content Builder, then with the output from the builder, the Android solution will automatically identify and package the content within the App as per Apple's packaging standards.
+
 ## Basic Builder Project Structure
 
 The default `Builder.cs` file looks like this, which contains everything needed to build all content in the designated Assets/Content folder using the default [Importers and Processors](/articles/getting_to_know/whatis/content_pipeline/CP_StdImpsProcs) (how MonoGame compiles content) into processed `.XNB` files for consumption by your runtime project:
@@ -224,7 +288,7 @@ The default `Include` rule simply builds a list of content to process from the t
 
 ### Core Properties
 
-Here are the main properties available work with:
+Here are the main properties available to work with:
 
 | Property | Description | Default Value |
 |----------|-------------|---------------|
@@ -561,7 +625,7 @@ contentCollection.Include("explosion.wav", audioImporter, audioProcessor);
 > [!NOTE]
 > As can be seen in the updated examples using the new Content Builder Project system, this can also be simplified to just:
 >
-> `contentCollection.Include("hero.png", new TextureImporter(), new TextureProcessor());
+> `contentCollection.Include("hero.png", new TextureImporter(), new TextureProcessor());`
 >
 > It just depends on which pattern you are more comfortable with.
 
@@ -589,6 +653,27 @@ contentCollection.Include<WildcardRule>(
 );
 ```
 
+### Handling Custom Importer / Processor caching
+
+The caching validation process that determines whether the Content Builder re-processes content by default is decided by:
+
+- The comparison between the last state of the built asset and the source
+- It will also take into account the "Version" of the Content Importer and Processor that was used at the time the content was built.
+
+The cache is only invalidated when either of these conditions are met, else it will skip over processing of the asset for performance as it has not detected a change.
+
+> [!NOTE]
+> MonoGame manages the versions of the [built-in Importers and Processors](../../getting_to_know/whatis/content_pipeline/CP_StdImpsProcs.md), so unless MonoGame makes changes to these elements, the cache will not be invalidated unless you [Force a rebuild](#understanding-contentbuilderparams).
+
+If you want content to be rebuilt when a Custom Importer or Processor has changed (content that uses the custom entities in its builder configuration), then the version of the Custom Content Pipeline Extension has to change, to do this, simply update the "Version" property on the respective Importer or Processor as follows:
+
+```csharp
+public override string Version { get; set; } = "new Version";
+```
+
+> [!NOTE]
+> The version can be anything you like, so long as it is a recognisable and readable string.  Preferably something you can increment.
+
 ### Configuring Processor Parameters
 
 Many processors have configurable parameters that control how they process content. If you need to override these parameters with specific values, here is how to customize them:
@@ -651,6 +736,8 @@ contentCollection.Include<WildcardRule>(
 
 ## Advanced Scenarios
 
+The following scenarios are of a more advanced nature for scenarios where you need specific customisation to suit your delivery needs.
+
 ### Scenario 1: Platform-Specific Content
 
 Build different content for different platforms:
@@ -714,7 +801,52 @@ public override IContentCollection GetContentCollection()
 }
 ```
 
-### Scenario 3: Debugging the Builder
+### Scenario 3: Dynamic Content from External Sources
+
+Process content from multiple sources:
+
+```csharp
+public override IContentCollection GetContentCollection()
+{
+    var contentCollection = new ContentCollection();
+    
+    // Base game content
+    contentCollection.Include<WildcardRule>("BaseGame/*");
+    
+    // DLC content (if available)
+    var dlcPath = Path.Combine(Parameters.RootedSourceDirectory, "DLC");
+    if (Directory.Exists(dlcPath))
+    {
+        contentCollection.SetContentRoot("DLC");
+        contentCollection.Include<WildcardRule>("DLC/*");
+    }
+    
+    // Mod content (if available)
+    var modPath = Path.Combine(Parameters.RootedSourceDirectory, "Mods");
+    if (Directory.Exists(modPath))
+    {
+        contentCollection.SetContentRoot("Mods");
+        contentCollection.Include<WildcardRule>("Mods/*");
+    }
+    
+    return contentCollection;
+}
+```
+
+---
+
+## Debugging
+
+At times you might need to debug your Content Builder, and while you can just run it manually in debug mode and attach your IDE to it, sometimes it is also valuable to FORCE the application to pause and let you step through importing and processing, especially when working with Content Pipeline Extensions.
+
+Alternatively, you may simply want to inject additional assets into your project for debugging purposes (such as overlays, etc) which are only consumed in a `Debug` build of your project (using `#if DEBUG` in your runtime too).
+
+> [!NOTE]
+> This is a rather advanced area which for most situations you do not need to go to these lengths.
+
+The following scenarios outline these options as they pertain to the Content Builder solution:
+
+### Scenario 1: Debugging the Builder
 
 If you wish to inject a `Debugger` breakpoint to determine the cause of any issues when building content, you can add the following before the `Builder` runs in your `ContentBuilder` project, this will cause DotNet to request to launch the default debugger and automatically attach it to the project when it is run:
 
@@ -727,14 +859,15 @@ using System.Diagnostics;
 // this, build the game, then attach the debugger when prompted.
 #if DEBUG
 Debugger.Launch();
+#endif
 
 // Launch point
 builder.Run(args);
 ```
 
-### Scenario 4: Conditional Debug Content
+### Scenario 2: Conditional Debug Content
 
-Include extra content in debug builds:
+Useful when you need to include extra content in debug only builds for testing, e.g. texture overlays or additional fonts:
 
 ```csharp
 public override IContentCollection GetContentCollection()
@@ -754,38 +887,6 @@ public override IContentCollection GetContentCollection()
 }
 ```
 
-### Scenario 5: Dynamic Content from External Sources
-
-Process content from multiple sources:
-
-```csharp
-public override IContentCollection GetContentCollection()
-{
-    var contentCollection = new ContentCollection();
-    
-    // Base game content
-    contentCollection.Include<WildcardRule>("BaseGame/*");
-    
-    // DLC content (if available)
-    var dlcPath = Path.Combine(Parameters.RootedSourceDirectory, "DLC");
-    if (Directory.Exists(dlcPath))
-    {
-        contentCollection.SetContentRoot("DLC");
-        contentCollection.Include<WildcardRule>("DLC/*");
-    }
-    
-    // Mod content (if available)
-    var modPath = Path.Combine(Parameters.RootedSourceDirectory, "Mods");
-    if (Directory.Exists(modPath))
-    {
-        contentCollection.SetContentRoot("Mods");
-        contentCollection.Include<WildcardRule>("Mods/*");
-    }
-    
-    return contentCollection;
-}
-```
-
 ---
 
 ## Summary

articles/getting_started/content_pipeline/content_builder_project.md

@@ -0,0 +1,84 @@
+---
+title: Sponsors Access
+description: Resources available exclusively to Sponsors of MonoGame.
+---
+
+At MonoGame, we are working hard to evolve the framework, to provide fresh resources, tools, samples and content to assist all consumers of the MonoGame Framework.
+
+## Requirements
+
+The minimum sponsorship level required to access the private resources is [SpriteBatch](https://monogame.net/donate/) 
+![SpriteBatch Logo](./images/spritebatch.png)
+
+## Sponsors Resources
+
+To both celebrate and reward Sponsors of MonoGame, we give you early access to the latest and greatest the team are currently working on, this includes:
+
+### Tutorials
+
+- Early access to the latest tutorial content:
+
+  - An Advanced 2D Shader tutorial - live
+  - A Mobile Deployment tutorial - incoming
+  - A Beginner 3D tutorial - incoming
+
+### Samples
+
+- Early access to new MonoGame Samples:
+
+  - The 3D Platformer sample - A migrated platformer sample from [Kenny.nl](https://www.kenney.nl/starter-kits)'s sample outfitted for MonoGame
+  - The 3D FPS sample (incoming) - A migrated FPS sample from [Kenny.nl](https://www.kenney.nl/starter-kits)'s sample outfitted for MonoGame
+
+> [!NOTE]
+> Early access is granted for several months before they become public.
+
+We are also working hard on more resources for the community.
+
+## DrawUserPrimitives exclusive content
+
+![DrawUserPrimitives Logo](./images/drawuserprimitives.png)
+
+Sponsors at DrawUserPrimitives and above also get additional resources:
+
+- The 3D Ascent demo project - An upgraded version of the old [Ship Game](https://github.com/MonoGame/MonoGame.Samples/blob/3.8.4/ShipGame/README.md) sample, modernised for today's platforms.
+
+## Accessing the Private Sponsorship site
+
+The private sponsors only documentation site can be found at the following address:
+
+### [https://sponsors.monogame.net/](https://sponsors.monogame.net/)
+
+Access is granted through your GitHub account, once your sponsorship is confirmed, we will request your GitHub account name so we can assign it to the relevant sponsorship level.
+
+## GitHub Authorisation
+
+In order to verify your identity, GitHub will request you validate the first time you access the site with the following dialog:
+
+![Sponsors site permission request](./images/sponsors_access.png)
+
+### Authorization details
+
+The Sponsors site application connects your GitHub account securely to our sponsorship system.  
+By authorizing, you allow us to:
+
+- ✅ Verify your GitHub identity (to confirm you are the correct sponsor)
+- ✅ Know which resources you can access (to match benefits to your sponsorship tier)
+- ✅ Act on your behalf (to confirm your sponsorship level, unlock exclusive content, and keep content access in sync)
+
+### Why do we need this?
+
+MonoGame needs to request permissions so we can:
+
+- Link your sponsorship to your GitHub account
+- Provide you with exclusive sponsor benefits
+- Keep your access secure and personalized
+
+### Security & Privacy
+
+- We only request the **minimum permissions** required.
+- Your data is handled according to our [Privacy Policy](https://community.monogame.net/privacy).
+- You can revoke access anytime from your [GitHub Authorized Apps](https://github.com/settings/applications).
+
+## Questions?
+
+If you have concerns regarding the sponsorship site or the content within, please contact us at [[email protected]].

articles/images/drawuserprimitives.png

@@ -81,6 +81,8 @@ items:
             href: getting_started/content_pipeline/why_content_pipeline.md
           - name: Using the Content Builder Project
             href: getting_started/content_pipeline/content_builder_project.md
+          - name: Automating the Content Builder
+            href: getting_started/content_pipeline/automating_content_builder.md
           - name: Using MGCB Editor
             href: getting_started/content_pipeline/using_mgcb_editor.md
           - name: Custom Effects