Yotsuba ShaderLearn
Documentation

Godot

12 min read

Reference for Godot: how the addon translates your shaders, what is supported and the names of the vertex data.

Godot has its own shader language, the Godot Shading Language, saved in .gdshader files. You write the shader in C# and Yotsuba Shader translates it to that language for you.

An animated plasma of colors: pink, yellow and green

1. The addon: translate every time you press Play#

Running the command by hand every time you change the shader gets old. Yotsuba Shader has an addon for the Godot editor that does it for you.

First, copy that folder, yotsubashader, into GodotGame/addons/ (create addons if it does not exist). When you open the project in Godot, the folder shows up in the file panel, as in the screenshot above.

Second, in Godot: Project → Project Settings → Plugins. YotsubaShader appears in the list, turned off.

Project Settings, Plugins tab: YotsubaShader appears turned off

Tick the box to turn it on.

Project Settings, Plugins tab: YotsubaShader turned on

Third, in the General tab, turn on Advanced Settings (the switch at the top right). A section called Yotsuba Shader appears: if you do not see it, type yotsuba in the filter. The project field is empty.

Project Settings, General: the Yotsuba Shader section with the Project field empty

Set project to ../MyShaders/MyShaders.csproj (the path is relative to the Godot project).

The Yotsuba Shader section with Project pointing to ../MyShaders/MyShaders.csproj

These are all the settings:

SettingWhat it isDefault
projectPath to the .csproj with your shaders (absolute, or relative to the Godot project)empty
output_dirWhere the .gdshader files are writtenres://yotsuba_shaders
shader_typespatial, canvas_item or bothspatial
commandThe yotsuba commanddotnet yotsuba
regenerate_on_runRegenerate when you press Playon

From now on the addon runs the same compile --target godot command that you typed, and writes the files in output_dir. It does it:

  • every time you press Play, before the game starts, and
  • from the menu Project → Tools → Regenerate YotsubaShader shaders.

Then Godot refreshes its file system. If the command fails, the error shows up in Godot's output panel. A failure in a shader type you did not choose (for example canvas_item, when you only use spatial) is not counted as an error.

Press Play (the triangle at the top right). Before the game starts, the addon translates the shader, and then the game window opens.

The Godot editor with the project running

Two things that can go wrong:

2. What gets translated#

The vertex method of your shader is the part Godot cares about most. Take Vertex:

    [ShaderStage(Stage.Vertex)]
    public Pixel Vertex(GodotVertex corner)
    {
        Pixel pixel;
        pixel.Position = Make.Vec4(corner.VERTEX.X, corner.VERTEX.Y, 0f, 1f);
        pixel.Uv = corner.UV;
        return pixel;
    }

In the .spatial.gdshader it becomes this:

void vertex() {
    vec2 corner_VERTEX = VERTEX.xy;
    vec2 corner_UV = UV;
    vec4 ys_position = vec4(0.0);
    Pixel pixel;
    pixel.Position = Vec4(corner_VERTEX.x, corner_VERTEX.y, 0.0, 1.0);
    pixel.Uv = corner_UV;
    ys_position = pixel.Position;
    v_Uv = pixel.Uv;
    POSITION = ys_position;
}

Look at the correspondences:

  • The method Vertex became void vertex(), and the fragment method Fragment became void fragment().
  • The VERTEX field of your GodotVertex reads Godot's VERTEX, and the UV field reads UV. Those are the names that Godot gives to the data of each vertex, and the plugin chose them by the name of your field.
  • What the vertex hands to the fragment (pixel.Uv) became a varying, v_Uv, that the fragment reads.
  • The position you return (gl_Position) is written in POSITION. This is a position in clip space, the -1 to 1 of before. That means Godot does not apply its own matrices (model, view and projection) to a shader made like this. If you want them, you have to send them as a uniform and multiply them yourself in the vertex method. This guide does not cover how.
  • The final color ([return: location(0)]) goes to ALBEDO and ALPHA.

The names you can use in the input struct are in section 3. In canvas_item only the position, the color and UV exist.

More things the plugin does:

  • A [uniform] struct becomes one uniform per field, with the name <Field>_<Member>, as you saw.
  • A texture becomes uniform sampler2D <name>. How it is filtered or repeated is decided by Godot, with the options of the texture, and not by the SamplerState of your C#.
  • The spatial files are generated with render_mode unshaded, cull_disabled;. unshaded because the fragment already calculates the final color, and Godot should not add light on top. cull_disabled because a ShaderMaterial cannot turn off the culling (throwing away the faces that look backwards), and, as the position is in clip space, Godot was throwing away the faces: the rectangle of the whole screen was not visible without it.

Taking another shader from the tutorial#

Any shader of the Get Started goes to Godot with the same two changes you made to the plasma: in the vertex method, use GodotVertex instead of Corner, and read corner.VERTEX instead of corner.Position.

3. The names of the vertex data#

In the tutorial you declared GodotVertex with all the data that Godot delivers per vertex. This section explains each one.

The rule#

Vertex data is declared in a struct using these names, as in the tutorial:

public struct GodotVertex
{
    [location(0)] public vec3 VERTEX;
    [location(1)] public vec2 UV;
    [location(2)] public vec3 NORMAL;
    [location(3)] public vec4 COLOR;
}
  • The name decides the meaning, and it is Godot's. UV is the texture coordinate, NORMAL is the normal. The location number is still yours: it only has to be unique.
  • They are written exactly as in Godot: in capitals, with an underscore (BONE_INDICES). That is the form the tutorial uses and the one in the tables below.
  • The language changes nothing. These names are not translated: the Spanish tutorial uses UV, not Textura.
  • The name rules over the number and the semantic. If the field is called UV, it is UV, whatever [location(1)], [attribute(1)] or [TEXCOORD(0)] it carries.
  • A name that is not on the list is never guessed. If it also carries no semantic the plugin knows ([POSITION]...), the plugin gives an error that lists the names that exist, and never lets wrong data through silently.

The attributes#

This is the complete list of what Godot delivers per vertex in a spatial shader. The canvas_item ones are a subset, shown in each row.

NameType in spatialType in canvas_itemIn HlslSyntax
VERTEXvec3vec2POSITION
NORMALvec3Does not existNORMAL
TANGENTvec3Does not existTANGENT
BINORMALvec3Does not existBINORMAL
UVvec2vec2TEXCOORD(0)
UV2vec2Does not existTEXCOORD(1)
COLORvec4vec4COLOR
CUSTOM0vec4vec4TEXCOORD(2)
CUSTOM1vec4vec4TEXCOORD(3)
CUSTOM2vec4Does not existTEXCOORD(4)
CUSTOM3vec4Does not existTEXCOORD(5)
BONE_INDICESuvec4Does not existTEXCOORD(6)
BONE_WEIGHTSvec4Does not existTEXCOORD(7)
POINT_SIZEfloatfloatTEXCOORD(8)

The types are Godot's. If you declare a different one of the same family, the plugin adapts it: a shorter one is padded (with 0, and with 1 in the w of VERTEX and COLOR), and a longer one is cut. That is why a vec2 VERTEX, like the full-screen rectangle in the tutorial, works.

One convention for each attribute#

VERTEX: the position#

[location(0)] public vec3 VERTEX;

The vertex position in object space. In canvas_item it is a vec2.

A warning: if you return this position as-is as the final position, it is a position in clip space, and Godot applies none of its matrices to it. That is what the plasma in this guide does.

NORMAL, TANGENT and BINORMAL#

[location(2)] public vec3 NORMAL;
[location(5)] public vec3 TANGENT;
[location(6)] public vec3 BINORMAL;

All three are vec3 and exist only in spatial: 2D has no normals. A shader that reads them cannot be canvas_item, and the compiler must say so with an error rather than produce a broken file.

UV and UV2#

[location(1)] public vec2 UV;
[location(4)] public vec2 UV2;

UV goes from (0, 0) to (1, 1) over the surface. UV2 is the second coordinate, which Godot uses for things like lightmaps. In canvas_item only UV exists.

COLOR#

[location(3)] public vec4 COLOR;

In spatial it is the vertex color. In canvas_item, Godot multiplies it by the node's modulate and self_modulate, so the value you read is not the one stored in the mesh.

CUSTOM0 to CUSTOM3#

[location(7)] public vec4 CUSTOM0;

Four vec4 for your own data. They are the way out for data that fits none of the other names, and they have a cost: to fill them you must build the mesh by hand in Godot (with ArrayMesh), because the built-in meshes (QuadMesh, SphereMesh...) do not carry them.

In canvas_item only CUSTOM0 and CUSTOM1 exist. In HlslSyntax they travel as TEXCOORD(2) to TEXCOORD(5).

BONE_INDICES and BONE_WEIGHTS#

[location(11)] public uvec4 BONE_INDICES;
[location(12)] public vec4 BONE_WEIGHTS;

A skeleton's data: which bones the vertex belongs to and how much each weighs. They exist only in spatial and are read-only. HlslSyntax has no semantic for bones or for the point size: that is why the HLSL variant uses an arbitrary [TEXCOORD(n)], and it is the name of the field that decides.

POINT_SIZE#

[location(13)] public float POINT_SIZE;

The size of a point when the mesh is drawn as points. In the tests, reading it inside vertex() made Godot draw nothing, so the plugin always delivers 1.0.

VERTEX_ID: not a field#

The vertex index does not come from the mesh: it is a built-in variable, like gl_VertexIndex in GLSL. It is not declared as a field named VERTEX_ID, but with the built-in variable of the syntax you use. Godot delivers it as VERTEX_ID in spatial and canvas_item.

How it is applied#

The priority the compiler follows to know what each piece of data is:

  1. The standard name from this page: always wins.
  2. The semantic the field carries ([POSITION]...), if the name is not on the list.
  3. An error that lists the names that exist. Never a silent guess.

And the rule has to hold for every engine. If it only failed on Godot, a shader would compile in MonoGame and not in Godot, and the promise is that what compiles works anywhere.

In the engines where you build the vertex yourself (MonoGame, KNI and FNA), the location number still rules, and the name only adds meaning to it. Your VertexDeclaration does not change.

What is pending#

  • Publish the Godot plugin with the name recognition (today it only exists as an unpublished change).
  • Translate VERTEX_ID, which is a built-in variable and not a field.
  • Generate the VertexDeclaration and the channel map automatically, so the programmer does not write them.
  • A strict portability rule: a shader with [location(n)] and no standard name should fail to compile for any engine, not only for Godot.

What is not possible#

The plugin does not translate these, and it tells you with a clear error (it does not leave a broken file):

A shader that reads NORMAL cannot be a canvas_item (2D has no normals). In that case the CLI warns about that file and finishes with exit code 1, but the .spatial.gdshader is still written.

Summary#

What belongs to Godot, from everything you did:

The plugin (for the CLI)godot (--target godot)
What it producesText: a .gdshader, spatial or canvas_item
The commanddotnet yotsuba compile MyShaders/MyShaders.csproj --target godot --output ...
Its method in C#ToGodotShader(GodotShaderType), which returns a string
The names of the uniforms<Field>_<Member>, like Time_Seconds
The addonaddons/yotsubashader, which regenerates the files when you press Play

What is the same as in the guides of MonoGame, KNI and FNA:

  • The plugin is a tool of the yotsuba CLI, and your game does not use it.
  • The first --target godot downloads the plugin by itself.
  • The data of a uniform is sent by name, with the rule Field_Member.

What is different: for Godot you write the vertex data with Godot's names (VERTEX, UV), you get a text file instead of a binary, and Godot loads it with load(...) and a ShaderMaterial, not with new Effect(...).