Shaders: what to change on the GPU
Choose a material or custom shader, and separate GPU stages from game logic.
Choose the tool
A shader defines how the GPU transforms vertices and evaluates a rendered surface. C# manages game objects and supplies parameters; shader code processes rendering data. A fragment() function cannot call Entity methods, read a save file or modify CollisionShape3D.
| Task | Tool |
|---|---|
| Color, textures, metallic and transparency without a custom formula | StandardMaterial3D |
| Custom coloring, masks, dissolve or surface deformation | ShaderMaterial and Shader |
| Individual mesh tint with a shared material | instance uniform |
| Inventory, damage, saving and physical shapes | C# and the appropriate engine systems |
First check whether StandardMaterial3D is sufficient. Use a custom shader for a custom formula rather than to enable a setting that already exists.
Understand the stages
vertex() runs on mesh vertices: VERTEX contains position and NORMAL contains the normal. If a plane has only two triangles, the vertex shader does not create new vertices between them. Relief needs a sufficiently dense grid.
fragment() evaluates visible-surface properties. In a spatial shader, assign ALBEDO, ROUGHNESS, METALLIC and other required values; lighting then uses them. ALBEDO is not a guaranteed screen color: lights, environment and tone mapping affect the result.
A varying transfers data from vertex() to fragment(), interpolated between vertices. The example calculates height and slope at vertices and uses them to color the material. This does not store game state between frames.
Connect program and material
Shader is the program; ShaderMaterial is a resource holding that program and regular-uniform values. Assign the material to the intended MeshInstance3D slot. In the current engine, text shader resources use .reckfellshader. Control classes remain in .cs files.
| Shader declaration | C# value |
|---|---|
| float | float |
| vec2 / vec3 | Vector2 / Vector3 |
| vec4 with source_color | Color |
| sampler2D | Texture2D, such as ImageTexture |
Names are case-sensitive. SetShaderParameter changes a material; SetInstanceShaderParameter changes a geometry parameter declared as instance uniform. Keep these paths distinct.
GetShaderParameter reads a stored override. If the shader uses a default that the material has not explicitly assigned, the verified build returns Nil. A misspelled name can also be cached without affecting the GPU. Check declarations, the uniform list and actual output.
Continue with a runnable example
First 3D shader creates heightmap relief and corrects its normals. Material and parameters covers PBR coloring, individual values, resource copies and saving.
Both lessons use one complete project verified in the current Forward+/Vulkan runtime. This introduces spatial shaders rather than establishing support for every shader type, backend or language feature.