Spatial shaders¶

Spatial shaders are used for shading 3D objects. They are the most complex type of shader Godot offers. Spatial shaders are highly configurable with different render modes and different rendering options (e.g. Subsurface Scattering, Transmission, Ambient Occlusion, Rim lighting etc). Users can optionally write vertex, fragment, and light processor functions to affect how objects are drawn.

Render modes¶

Render mode	Description
blend_mix	Mix blend mode (alpha is transparency), default.
blend_add	Additive blend mode.
blend_sub	Subtractive blend mode.
blend_mul	Multiplicative blend mode.
depth_draw_opaque	Only draw depth for opaque geometry (not transparent).
depth_draw_always	Always draw depth (opaque and transparent).
depth_draw_never	Never draw depth.
depth_prepass_alpha	Do opaque depth pre-pass for transparent geometry.
depth_test_disabled	Disable depth testing.
sss_mode_skin	Subsurface Scattering mode for skin.
cull_back	Cull back-faces (default).
cull_front	Cull front-faces.
cull_disabled	Culling disabled (double sided).
unshaded	Result is just albedo. No lighting/shading happens in material.
wireframe	Geometry draws using lines.
diffuse_lambert	Lambert shading for diffuse (default).
diffuse_lambert_wrap	Lambert wrapping (roughness dependent) for diffuse.
diffuse_burley	Burley (Disney PBS) for diffuse.
diffuse_toon	Toon shading for diffuse.
specular_schlick_ggx	Schlick-GGX for specular (default).
specular_blinn	Blinn for specular (compatibility).
specular_phong	Phong for specular (compatibility).
specular_toon	Toon for specular.
specular_disabled	Disable specular.
skip_vertex_transform	VERTEX/NORMAL/etc. need to be transformed manually in vertex function.
world_vertex_coords	VERTEX/NORMAL/etc. are modified in world coordinates instead of local.
ensure_correct_normals	Use when non-uniform scale is applied to mesh.
shadows_disabled	Disable computing shadows in shader.
ambient_light_disabled	Disable contribution from ambient light and radiance map.
shadow_to_opacity	Lighting modifies the alpha so shadowed areas are opaque and non-shadowed areas are transparent. Useful for overlaying shadows onto a camera feed in AR.
vertex_lighting	Use vertex-based lighting.
particle_trails	Enables the trails when used on particles geometry.
alpha_to_coverage	Alpha antialiasing mode, see here for more.
alpha_to_coverage_and_one	Alpha antialiasing mode, see here for more.
fog_disabled	Disable receiving depth-based or volumetric fog. Useful for blend_add materials like particles.

Built-ins¶

Values marked as "in" are read-only. Values marked as "out" are for optional writing and will not necessarily contain sensible values. Values marked as "inout" provide a sensible default value, and can optionally be written to. Samplers are not subjects of writing and they are not marked.

Global built-ins¶

Global built-ins are available everywhere, including custom functions.

Built-in	Description
in float TIME	Global time, in seconds.
in float PI	A `PI` constant (`3.141592`). A ration of circle's circumference to its diameter and amount of radians in half turn.
in float TAU	A `TAU` constant (`6.283185`). An equivalent of `PI * 2` and amount of radians in full turn.
in float E	A `E` constant (`2.718281`). Euler's number and a base of the natural logarithm.

Vertex built-ins¶

Vertex data (VERTEX, NORMAL, TANGENT, BITANGENT) are presented in local model space. If not written to, these values will not be modified and be passed through as they came.

They can optionally be presented in world space by using the world_vertex_coords render mode.

Users can disable the built-in modelview transform (projection will still happen later) and do it manually with the following code:

shader_type spatial;
render_mode skip_vertex_transform;

void vertex() {
    VERTEX = (MODELVIEW_MATRIX * vec4(VERTEX, 1.0)).xyz;
    NORMAL = normalize((MODELVIEW_MATRIX * vec4(NORMAL, 0.0)).xyz);
    // same as above for binormal and tangent, if normal mapping is used
}

Other built-ins, such as UV, UV2 and COLOR, are also passed through to the fragment function if not modified.

Users can override the modelview and projection transforms using the POSITION built-in. When POSITION is used, the value from VERTEX is ignored and projection does not happen. However, the value passed to the fragment shader still comes from VERTEX.

For instancing, the INSTANCE_CUSTOM variable contains the instance custom data. When using particles, this information is usually:

x: Rotation angle in radians.
y: Phase during lifetime (0 to 1).
z: Animation frame.

This allows you to easily adjust the shader to a particle system using default particles material. When writing a custom particle shader, this value can be used as desired.

Built-in	Description
in vec2 VIEWPORT_SIZE	Size of viewport (in pixels).
in mat4 VIEW_MATRIX	World space to view space transform.
in mat4 INV_VIEW_MATRIX	View space to world space transform.
in mat4 INV_PROJECTION_MATRIX	Clip space to view space transform.
in vec3 NODE_POSITION_WORLD	Node world space position.
in vec3 NODE_POSITION_VIEW	Node view space position.
in vec3 CAMERA_POSITION_WORLD	Camera world space position.
in vec3 CAMERA_DIRECTION_WORLD	Camera world space direction.
in bool OUTPUT_IS_SRGB	`true` when output is in sRGB color space (this is `true` in the Compatibility renderer, `false` in Forward+ and Forward Mobile).
in int INSTANCE_ID	Instance ID for instancing.
in vec4 INSTANCE_CUSTOM	Instance custom data (for particles, mostly).
in int VIEW_INDEX	The view that we are rendering. `VIEW_MONO_LEFT` (`0`) for Mono (not multiview) or left eye, `VIEW_RIGHT` (`1`) for right eye.
in int VIEW_MONO_LEFT	Constant for Mono or left eye, always `0`.
in int VIEW_RIGHT	Constant for right eye, always `1`.
in vec3 EYE_OFFSET	Position offset for the eye being rendered. Only applicable for multiview rendering.
inout vec3 VERTEX	Vertex in local coordinates.
in int VERTEX_ID	The index of the current vertex in the vertex buffer.
inout vec3 NORMAL	Normal in local coordinates.
inout vec3 TANGENT	Tangent in local coordinates.
inout vec3 BINORMAL	Binormal in local coordinates.
out vec4 POSITION	If written to, overrides final vertex position.
inout vec2 UV	UV main channel.
inout vec2