2d shader tutorial #171

cdhanna · 2025-08-30T01:39:59Z

I've modified a bit of this fork to enable a live build from the branch. Here are the rendered docs,
https://cdhanna.github.io/docs.monogame.github.io/articles/tutorials/advanced/2d_shaders/

(I'm currently having an issue maybe with one of the submodules, not sure what is going on there)

The code samples are available here,
https://github.com/cdhanna/MonoGame.Samples/tree/2dshaders/Tutorials/2dShaders/src

And the code sample PR: MonoGame/MonoGame.Samples#95

(I'll be opening a pull request soon on the samples repo)

* Updated samples page (#149) * Add samples section to main docs links * Updated samples page * Update index.md (#147) corrected spelling on line 20 * Update index.md (#146) Lines 211 - 214 (Key changes made): There was an update needed to this. Previous stated the file name was "04B_11.ttf" and the size was "32". The update is to match the snippet and the download. * Update textureregion.cs (#153) Fix the comments for the constructor * typo (#152) * Update WhatIs_Sprite.md (#151) Corrected coordinates in the overview section * removed accidental backtick in CLI command (#150) * "the" (#154) * Update core.cs * Update tilemap.cs * Update core.cs * Update core.cs * Update core.cs * Update index.md * Fix for AudioController.Update() at 2d game tutorial. (#148) * fix for AudioController.Update() at 2d game tutorial. * update code with backward iteration --------- Co-authored-by: Hyunwook Ha <[email protected]> * fix(docs): correct typos and improve consistency across articles (#145) * Clarify distance labels in circle collision explanation - Added missing word "circles" in description of 'a' - Reworded all three distance descriptions for clarity and consistency * fix(title scene draw): remove unused color assignment to dropShadowColor * fix(title scene draw): add missing comment above dropShadowColor assignment * refactor: fix typo in textureatlas.cs filename * fix(docs): correct typos and improve wording across documentation * (Fix)Removed < > from xref links and set unordered list to ordered list --------- Co-authored-by: Simon (Darkside) Jackson <[email protected]> * Update Roadmap - Resolves #137 * Add Maui instructions to "Getting Started guide" and add image - resolves #157 * Fix formatting of Tip Admonition (#159) * Changes to satisfy #225 (#156) * Changes to satisfy #226 * Remove create as it moved to the main site * Fix footer to match * Update links for Bsky and mastodon * Revert MonoGame checkout to 3.8.4 * fix spelling mistake in the ContentManager Methods section of chapter 5 bulding 2d games tutorial (#160) * working * Remove exiting from Game1 class and make ExitOnEscape true by default in the core class (#163) * Update to remove the usage of the word "objects" which can be confused for OOP (#162) * Add info about security and protection (#161) * material class * debug ui * working * Gum styling update 2025 8 (#164) * Updated styling docs to use ButtonVisual Updated using statements to match new gum namespace * Fixed usings * Upped NuGet versions for MonoGame Docs * Oops forgot this using statement. * Upped version number * Addressed feedback from AristurtleDev * Updated Cartblanch's Samples links and text. * color swap mostly complete * vertex shaders * Fix typo with iOS build instructions (#167) * Fix minor Markdown error in CH 21 of the 2D game tutorial (#168) * getting started on lighting * in progress * finishing draft of lighitng chapter * shadow stuff * before stencil * mostly done * stencil shadows * zug zug * remove old name * rename folder, update toc, and gif support * metadata * typos * links and callouts * hlsl highlighting support * fixing indentation --------- Co-authored-by: Simon (Darkside) Jackson <[email protected]> Co-authored-by: Mckeehan <[email protected]> Co-authored-by: jani-r <[email protected]> Co-authored-by: bo <[email protected]> Co-authored-by: Quaspen <[email protected]> Co-authored-by: Hyunwook Ha <[email protected]> Co-authored-by: Hyunwook Ha <[email protected]> Co-authored-by: Quest <[email protected]> Co-authored-by: Christopher Whitley <[email protected]> Co-authored-by: Sean Buchas <[email protected]> Co-authored-by: Victor Chelaru <[email protected]> Co-authored-by: Dominique Louis <[email protected]> Co-authored-by: buymyhubs <[email protected]> Co-authored-by: alfuwu <[email protected]>

# Conflicts: # articles/toc.yml

SimonDarksideJ

Reviewed chapters 1 - 5 and comments added

Overall very good, but a few points to clean up. Also check the end comment on Chapter 4, it seems to stop and the rest of the chapter is missing?

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

articles/tutorials/advanced/2d_shaders/02_hot_reload/index.md

articles/tutorials/advanced/2d_shaders/03_the_material_class/index.md

articles/tutorials/advanced/2d_shaders/05_transition_effect/index.md

SimonDarksideJ

Chapters 6 & 7 reviewed

articles/tutorials/advanced/2d_shaders/06_color_swap_effect/index.md

articles/tutorials/advanced/2d_shaders/07_sprite_vertex_effect/index.md

…teBatchItem" (https://docs.monogame.net/api/index.html?)

cdhanna · 2025-09-01T23:59:40Z

about the SpriteBatchItem, ugh, I guess it's just part of the implementation of sprite batch. Originally I had linked to the public source code for it I feel it is helpful to understand.

I think I'll revert the change and just reference the GitHub source code directly. I feel like it has gotten MORE confusing than 2 commits ago

SimonDarksideJ · 2025-09-02T02:07:20Z

You can link directly to source if you wish and belive it helps with understanding, but if it is not public then you cannot use xref.
Just use a permalink to the source line instead, no issues with that.

SimonDarksideJ

Initial tutorial review complete (apologies, some comments were noted against the 2D shaders branch and not main, so might have been fixed already)

Once corrections are done, we can continue with the code review pass

articles/tutorials/advanced/2d_shaders/08_light_effect/index.md

articles/tutorials/advanced/2d_shaders/10_next_steps/index.md

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

SimonDarksideJ

Notes for chapters 1-2 from code review

articles/tutorials/advanced/2d_shaders/02_hot_reload/index.md

SimonDarksideJ · 2025-09-21T09:02:00Z

articles/tutorials/advanced/2d_shaders/02_hot_reload/index.md

+[!code-sh[](./snippets/snippet-2-12.sh)]
+
+
+We now have a way to dynamically recompile shaders on file changes and copy the `.xnb` files into the game folder! There are a few final adjustments to make to the configuration. 


Worth adding an admonition here to note that changes to the CS files are no longer watched and do not recompile (at least for me), I changed the example above for the title screen and nothing happened.

If this is expected, then highlight it to the reader.

Also annoying it no longer launches the game when the command is run, but that is dotnet for you I guess.

Worth highlighting how the reader is now supposed to launch the game in debug, debug -> start new instance, or simply run the compiled exe?

I tested running the same command from this tutorials chapter source and it worked? But following the instructions from the final chapter of the 2D tutorial did not?

It's all dotnet 9's fault

spoke with Simon privately as well; but public summary is that it is the terminal logger's fault specifically. https://learn.microsoft.com/en-us/dotnet/core/compatibility/sdk/9.0/terminal-logger

If you add --tl:off to the invocation, it'll work. I'm thinking about how to address this as well as some other issues in one swoop.

SimonDarksideJ · 2025-09-21T09:08:56Z

articles/tutorials/advanced/2d_shaders/02_hot_reload/index.md

+
+[!code-sh[](./snippets/snippet-2-15.sh)]
+
+And then cause some sort of compiler-error in the `grayscaleEffect.fx` file, such as adding the line, `"tunafish"` to the top of the file. When you save it, you should see the terminal spit out an error containing information about the compilation failure, 


Actually, I think I have run into a problem here.

When I added the WatchContent block, I thought it was just a different build, but the process is continually building (counter going up)
Confirmed at this point because WatchContent is not finishing its build.

Ran dotnet build and the build finished (but errors thanks tot he shader change)

Can you re-test using ONLY the steps in this chapter from the original 27-conclusion source.

Just tried again with a fresh clone of the original tutorial, same result.

I also note that you GUM reference is NEWER than what is currently in the 2D tutorial, best not to change versions from the original (even if it has been updated) as the tutorial makes reference to specific versions.

I saw some feedback from the other PR saying that GUM needed to be updated. Idk, just trying to be proactive.
Which is a pain, becuase there are compile time breaking changes in that upgrade 😢

I'll discuss it with @vchelaru to see what should be used, as the 2D tutorial text and references needs to be updated with any version change

Sorry I'm just catching up here. Which versions of Gum are we talking about?

The original 2D tutorial was written linking version 2025.5.1.1. That has since been updated to version 2025.8.3.3, which is fairly recent. If you feel more comfortable linking 2025.8.3.3, that's fine.

ed50658

Since that release there has been one major release which has had some breaking changes which are outlined here; however, the breaking changes should not affect the tutorials: https://github.com/vchelaru/Gum/releases/tag/Release_August_28_2025

@cdhanna if there are breaking changes you are aware of, can you let me know what those are?

articles/tutorials/advanced/2d_shaders/02_hot_reload/index.md

SimonDarksideJ · 2025-09-21T09:37:47Z

articles/tutorials/advanced/2d_shaders/02_hot_reload/index.md

+
+At the top of the `GameScene.Update()` method, add the following line to opt into reloading the `_grayscaleEffect` asset:
+
+[!code-csharp[](./snippets/snippet-2-24.cs?highlight=3-4)]


Code is inverted between the sample in source and this snipped ( lines are reversed) please ensure they are consistant between sample and tutorial

* Ch 2 fixes * Clean usings * Ch 3 code review

* Chapter two patch * Second grammar pass and finishing chapter 3 * CH 4 review and consistency updates to end of previous chapters * Ch 5 review, needs final grammar proof * Final proof, plus note about dotnet tools * Address feedback

* Quick fix * Minor corrections * Add clean up for old timing code * Chapter 7 * Pausing at "Combining Light and colour" * Ch7 code pass complete * Grammar review * Address feedback * Checkpoint - The Stencil Buffer next * Reviewed up to "Improving Look and Feel" * Chapter 9 reviewed * Typo proof

cdhanna and others added 3 commits August 28, 2025 08:38

update action to allow deploying other branches

33381d6

Merge branch 'main-monogame'

827d325

# Conflicts: # articles/toc.yml

cdhanna mentioned this pull request Aug 30, 2025

2d shader tutorial code samples MonoGame/MonoGame.Samples#95

Closed

edits to toc

8499c83

SimonDarksideJ requested changes Aug 30, 2025

View reviewed changes

cdhanna added 11 commits August 30, 2025 20:03

restore missing chapter 4.

dbfe09a

pass to remove all contractions

a84df78

tracking: 2.1

9c4143d

tracking 3.1

eb08554

tracking 3.2

cb91fd0

tracking 3.3

d623455

tracking 3.4

2b1b856

tracking 3.5

c27012b

tracking 3.6

8093200

tacking 3.7

9dfa203

tracking 3.8

00a7f5e

SimonDarksideJ requested changes Aug 31, 2025

View reviewed changes

cdhanna and others added 9 commits September 1, 2025 13:39

update submodules

1398f3f

struggling with submodules

aaebb02

restore inside submodule

3fc677a

copying premake step from main repo

414f8a3

restore mg stuff

0c9437d

Merge branch 'main' into main

b59721e

Merge branch 'main' into main

9be7a65

Merge branch 'main' into main

dafd0fc

Fixed SpriteBatch xref, no such item in the MonoGame API called "Spri…

60d7a86

…teBatchItem" (https://docs.monogame.net/api/index.html?)

SimonDarksideJ requested changes Sep 2, 2025

View reviewed changes

cdhanna and others added 4 commits September 18, 2025 23:51

tracking 10.1

7e802ba

format sig

c94437a

minor clerical errors

dc05dd9

Review fixes

6ddec86

SimonDarksideJ requested changes Sep 21, 2025

View reviewed changes

SimonDarksideJ and others added 24 commits September 21, 2025 15:36

Revert code block fixes

a0214b6

tracking b2-1

4e4975e

tracking b2-2

df41d18

Review/simon (#2)

81306e6

* Ch 2 fixes * Clean usings * Ch 3 code review

update hot reload for auto-start, net9, and support dotnet-run

a6acacf

Rename snippet

31c7a84

Chapter 6 changes

bac8e9f

Feature/review continues (#3)

611fbbc

* Chapter two patch * Second grammar pass and finishing chapter 3 * CH 4 review and consistency updates to end of previous chapters * Ch 5 review, needs final grammar proof * Final proof, plus note about dotnet tools * Address feedback

updates for chapter 2

f6094a5

chapter 3 updates

a7d3c48

chapter 4 edits

f8530ae

chapter 5 edits

f5d039f

chapter 6 notes

7039e08

some chapter 7 edits

056a034

more chap7 notes

d95ce15

some chap 8 comments

014a349

more chap 8 comments

9288f99

fix chap 6 content dir, and fix chap 8 w confusion

2c76f1a

very minor changes

1b446d1

figure 9-7

a087b1d

fix fig numbers in 09

b7e5362

some chap 9 comments

56a9926

more chap 9 comments

d71cd17

SimonDarksideJ closed this Nov 7, 2025

		[!code-sh[](./snippets/snippet-2-12.sh)]


		We now have a way to dynamically recompile shaders on file changes and copy the `.xnb` files into the game folder! There are a few final adjustments to make to the configuration.


		[!code-sh[](./snippets/snippet-2-15.sh)]

		And then cause some sort of compiler-error in the `grayscaleEffect.fx` file, such as adding the line, `"tunafish"` to the top of the file. When you save it, you should see the terminal spit out an error containing information about the compilation failure,


		At the top of the `GameScene.Update()` method, add the following line to opt into reloading the `_grayscaleEffect` asset:

		[!code-csharp[](./snippets/snippet-2-24.cs?highlight=3-4)]

2d shader tutorial #171

2d shader tutorial #171

Uh oh!

Conversation

cdhanna commented Aug 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

SimonDarksideJ left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

SimonDarksideJ left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cdhanna commented Sep 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

SimonDarksideJ commented Sep 2, 2025

Uh oh!

SimonDarksideJ left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

SimonDarksideJ left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cdhanna Sep 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

vchelaru Sep 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

cdhanna commented Aug 30, 2025 •

edited

Loading

cdhanna commented Sep 1, 2025 •

edited

Loading

cdhanna Sep 21, 2025 •

edited

Loading

vchelaru Sep 22, 2025 •

edited

Loading