2d shader tutorial

.github/workflows/main.yml

@@ -27,6 +27,7 @@ jobs:
       - name: Clone Repository
         uses: actions/checkout@v4
         with:
+          ref: ${{ github.ref }}
           submodules: recursive
 
       - name: Setup .NET SDK
@@ -50,4 +51,5 @@ jobs:
 
       - name: Deploy to GitHub Pages
         id: deployment
-        uses: actions/deploy-pages@v4
+
+        uses: actions/deploy-pages@v4

articles/toc.yml

@@ -156,6 +156,29 @@ items:
             href: tutorials/building_2d_games/26_publish_to_itch/index.md
           - name: "27: Conclusion and Next Steps"
             href: tutorials/building_2d_games/27_conclusion/index.md
+      - name: 2D Shaders
+        href: tutorials/advanced/2d_shaders/
+        items:
+          - name: "01: Introduction"
+            href: tutorials/advanced/2d_shaders/01_introduction/
+          - name: "02: Hot Reload"
+            href: tutorials/advanced/2d_shaders/02_hot_reload/
+          - name: "03: The Material Class"
+            href: tutorials/advanced/2d_shaders/03_the_material_class/
+          - name: "04: Debug UI"
+            href: tutorials/advanced/2d_shaders/04_debug_ui/
+          - name: "05: Transition Effect"
+            href: tutorials/advanced/2d_shaders/05_transition_effect/
+          - name: "06: Color Swap Effect"
+            href: tutorials/advanced/2d_shaders/06_color_swap_effect/
+          - name: "07: Sprite Vertex Effect"
+            href: tutorials/advanced/2d_shaders/07_sprite_vertex_effect/
+          - name: "08: Light Effect"
+            href: tutorials/advanced/2d_shaders/08_light_effect/
+          - name: "09: Shadow Effect"
+            href: tutorials/advanced/2d_shaders/09_shadows_effect/
+          - name: "10: Next Steps"
+            href: tutorials/advanced/2d_shaders/10_next_steps/                              
   - name: Console Access
     href: console_access.md
   - name: Help and Support

articles/tutorials/advanced/2d_shaders/01_introduction/index.md

@@ -0,0 +1,33 @@
+---
+title: "Chapter 01: Getting Started"
+description: "Prepare your project and get ready"
+---
+
+Welcome to the advanced 2D shaders tutorial! Before we dive into writing complex effects, this first chapter will make sure you're ready to go. We will get the starting project set up and take a quick look at the technical foundation of how shaders work with MonoGame's `SpriteBatch`.
+
+## The Starting Code
+
+This tutorial series builds directly on top of the final code from the "Building 2D Games" tutorial. It is essential that you start with this project.
+
+> [!note]
+> You can get the complete starting source code for this tutorial here: 
+> [The final chapter's source code](https://github.com/MonoGame/MonoGame.Samples/tree/3.8.4/Tutorials/learn-monogame-2d/src/24-Shaders/)
+
+Once you have the code downloaded, open it in your IDE and run the `DungeonSlime` project to make sure everything is working correctly. You should see the title screen from the previous tutorial.
+
+## Project Structure
+
+The solution is organized into two main projects:
+
+- **`DungeonSlime`**: The main game project. This contains our game logic and game-specific content.
+- **`MonoGameLibrary`**: Our reusable class library. We will be adding new, generic helper classes here that could be used in any of your future MonoGame projects.
+
+Most of our shader files (`.fx`) will be created in the `Content/effects` folder within the `DungeonSlime` project to start, and later within the `MonoGameLibrary` for shared effects.
+
+## What's Next
+
+Now that our project is set up, we can get to work. The focus for the first several chapters will be to create a workflow for developing shaders in MonoGame. Once we have a hot-reload system, a class to manage the effects, and a debug UI ready, we will carry on and build up 5 effects. The effects will range from simple pixel shaders and vertex shaders up to rendering techniques. As we develop these shaders together, we will build an intuition for how to tackle shader development. 
+
+Continue to the next chapter, [Chapter 02: Hot Reload](../02_hot_reload/index.md)
+
+

articles/tutorials/advanced/2d_shaders/02_hot_reload/snippets/DungeonSlime.csproj

@@ -0,0 +1,5 @@
+<ItemGroup>
+    <PackageReference Include="Gum.MonoGame" Version="2025.5.1.1" />
+    <PackageReference Include="MonoGame.Framework.DesktopGL" Version="3.8.*" />
+    <PackageReference Include="MonoGame.Content.Builder.Task" Version="3.8.*" />
+</ItemGroup>

articles/tutorials/advanced/2d_shaders/02_hot_reload/snippets/WatchedAsset.cs

@@ -0,0 +1,42 @@
+#region declaration
+using System;
+using Microsoft.Xna.Framework.Content;
+
+namespace MonoGameLibrary.Content;
+
+public class WatchedAsset<T>
+{
+
+}
+
+#endregion
+{
+#region members
+    /// <summary>
+    /// The latest version of the asset.
+    /// </summary>
+    public T Asset { get; set; }
+
+    /// <summary>
+    /// The last time the <see cref="Asset"/> was loaded into memory.
+    /// </summary>
+    public DateTimeOffset UpdatedAt { get; set; }
+
+    /// <summary>
+    /// The name of the <see cref="Asset"/>. This is the name used to load the asset from disk. 
+    /// </summary>
+    public string AssetName { get; init; }
+
+    /// <summary>
+    /// The <see cref="ContentManager"/> instance that loaded the asset.
+    /// </summary>
+    public ContentManager Owner { get; init; }
+    #endregion
+
+    #region methods
+    public bool TryRefresh(out T oldAsset)
+    {
+        return Owner.TryRefresh(this, out oldAsset);
+    }
+    #endregion
+}

articles/tutorials/advanced/2d_shaders/02_hot_reload/snippets/dotnet-tools.json

@@ -0,0 +1,36 @@
+{
+  "version": 1,
+  "isRoot": true,
+  "tools": {
+    "dotnet-mgcb": {
+      "version": "3.8.3",
+      "commands": [
+        "mgcb"
+      ]
+    },
+    "dotnet-mgcb-editor": {
+      "version": "3.8.3",
+      "commands": [
+        "mgcb-editor"
+      ]
+    },
+    "dotnet-mgcb-editor-linux": {
+      "version": "3.8.3",
+      "commands": [
+        "mgcb-editor-linux"
+      ]
+    },
+    "dotnet-mgcb-editor-windows": {
+      "version": "3.8.3",
+      "commands": [
+        "mgcb-editor-windows"
+      ]
+    },
+    "dotnet-mgcb-editor-mac": {
+      "version": "3.8.3",
+      "commands": [
+        "mgcb-editor-mac"
+      ]
+    }
+  }
+}