Set up your project
Install what you need and create the project where your shaders will live.
In this chapter you will not write any shader yet. You will get the working folder ready, so that in the next chapters you only have to worry about the code.
You will do the whole tutorial in a C# library that does not depend on any game engine. It does not use MonoGame, or Unity, or Stride, or any other. The shaders you write there work for all of them, because the game engine is chosen at the end, when you compile.
When you finish the tutorial, you will be able to use that same library in your game engine without changing a line. In the last chapter, What now?, there is a button for each game engine with the steps to connect it.
What you need#
- The .NET 10 SDK or newer. To see which one you have, open a terminal and type
dotnet --version. If you get a number lower than 10, download the new one from dotnet.microsoft.com.
One detail: the SDK is the program that compiles, and it does not have to be the same version as your project. That is why further down we create the projects with -f net8.0: SDK 10 knows how to build them just the same. If your game uses another version, that is fine.
- A C# editor. The one you already use: Rider, Visual Studio or Visual Studio Code.
That is why you do not need to install any game engine to follow the tutorial.
What the folder will look like#
By the end of this chapter you will have this:
Tutorial/
├── MyShaders/ a normal C# library: this is where you write the shaders
└── TryIt/ a console program to use the compiled shadersNotice that MyShaders is a C# library like any other. That is the nice thing about writing shaders in C#: a shader project is simply a .NET project. This is the library you will later take to your game engine.
TryIt only exists so you can see the result while you learn. When you use the shaders in your game, your game's project takes its place.
1. Create the folder and install the compiler#
mkdir Tutorialcd Tutorialdotnet new tool-manifestdotnet tool install YotsubaShader.Compiler.CLIThe first command creates a small file, .config/dotnet-tools.json, where .NET remembers which tools this folder uses. The second one downloads the Yotsuba Shader compiler from NuGet and writes it in that file. From now on, in this folder, the compiler is called with dotnet yotsuba.
2. Create the shader project#
From the Tutorial folder:
dotnet new classlib -n MyShaders -f net8.0The template creates a Class1.cs file that you will not use. Delete it.
Now tell the project that it is going to use Yotsuba Shader. It is a single reference:
dotnet add MyShaders package YotsubaShader.GlslSyntaxThat one line brings you two things:
| Package | What it gives you |
|---|---|
YotsubaShader.GlslSyntax | The names you are going to write with: vec4, [location], sin, texture... |
YotsubaShader.Language | The basics: [ShaderStage], which you use to mark which method is a shader. |
You do not add YotsubaShader.Language yourself. GlslSyntax already uses it inside, and when a package uses another, NuGet brings you both.
3. Create the program to try things out#
dotnet new console -n TryIt -f net8.0dotnet add TryIt reference MyShaders/MyShaders.csprojTryIt is an ordinary console program. It plays the role of "your game" or "your application": the program that will ask for the compiled shaders. We will use it to see with our own eyes what the compiler produces.
4. Check that everything builds#
dotnet build TryItIf you see Build succeeded at the end, everything is ready. There is no shader yet, but the references are in place.
A shortcut for calling the compiler#
The Yotsuba Shader compiler is a terminal program (a CLI). You will run it like this, from the Tutorial folder:
dotnet yotsuba add MyShaders/MyShaders.csproj --target spirvDo not run it yet. Just look at its parts:
| Part | What it means |
|---|---|
dotnet yotsuba | "Run the compiler". yotsuba is the name of the tool you just installed. Everything after it is the orders for it. |
add | The command. add means: "compile my shaders and add the result to my project". |
MyShaders/MyShaders.csproj | The project where the shaders are. |
--target spirv | An output format. The CLI asks for at least one. spirv is built into the CLI; the engines (MonoGame, KNI, FNA, Godot) are plugins that you add later as one more --target. |
In the next chapter you will use it for real.
Next: Shader 1: a sunset.