VisualShaderNodeGroupBase in Godot – Complete Guide

Welcome to our comprehensive tutorial on the VisualShaderNodeGroupBase class in Godot 4. Godot is a versatile and powerful open-source game engine that allows creators to bring their visions to life, and with the recent update, there’s a whole new world of possibilities. VisualShaderNodeGroupBase helps to manage the complexity of shaders by providing a way to group and manage multiple input and output ports. Whether you’re new to Godot or an experienced developer, understanding this class can help streamline your shader programming and take your games to the next level.

What is VisualShaderNodeGroupBase?

The VisualShaderNodeGroupBase class is a foundational element in Godot’s visual shader graph that enables the creation and management of custom nodes with variable input and output ports. Think of it as a versatile container that can adapt to the needs of your shaders, offering a flexible structure for organizing your graph’s flow.

What is It Used For?

But, why consider using VisualShaderNodeGroupBase? This class is specifically used to simplify the shader creation process. By grouping related shader operations and organizing them through custom input and output ports, you can create more readable, maintainable, and re-usable shader graphs.

Why Should I Learn It?

Understanding how to use VisualShaderNodeGroupBase is key for any developer looking to harness the full power of Godot’s visual shader system. Not only does it make shader development less daunting, it can vastly improve your workflow, paving the way for more complex and interesting visual effects with better performance and less hassle.

CTA Small Image




Creating a Custom Node with VisualShaderNodeGroupBase

To kick things off, let’s create a custom node using VisualShaderNodeGroupBase. This involves defining inputs and outputs and then incorporating our custom logic. Let’s assume we want to group color operations for a material.

var custom_color_node =
custom_color_node.set_input_port_name(0, "Base Color")
custom_color_node.set_input_port_type(0, VisualShaderNode.PORT_TYPE_VECTOR)
custom_color_node.set_input_port_name(1, "Highlight")
custom_color_node.set_input_port_type(1, VisualShaderNode.PORT_TYPE_VECTOR)
custom_color_node.set_input_port_name(2, "Shadow")
custom_color_node.set_input_port_type(2, VisualShaderNode.PORT_TYPE_VECTOR)
custom_color_node.set_output_port_name(0, "Shaded Color")
custom_color_node.set_output_port_type(0, VisualShaderNode.PORT_TYPE_VECTOR)
custom_color_node.set_output_port_name(1, "Highlight Strength")
custom_color_node.set_output_port_type(1, VisualShaderNode.PORT_TYPE_SCALAR)

This creates a custom node with three vector inputs: one for the base color of our material, one for the highlight, and another for the shadow. Also, it has two outputs: the “Shaded Color”, a combination of all inputs, and the “Highlight Strength”, which will be a scalar value.

Connecting Nodes in the VisualShader Graph

After defining our custom node, we need to integrate it into the shader graph by connecting its input and output ports. Here’s how you do that programmatically by connecting a simple Color constant to the ‘Base Color’ input:

var color_constant =
var graph =
graph.add_node(color_constant, Vector2(0, 0))
graph.add_node(custom_color_node, Vector2(150, 0))
graph.connect_nodes(color_constant.get_output_port(), custom_color_node.get_input_port(0))

The `connect_nodes` method requires the index of the output port from the first node and the index of the input port from the second node. In this example, we are connecting the Color constant’s only output to the ‘Base Color’ input of our custom node.

Using Graph Functions

The real power of VisualShaderNodeGroupBase comes into play when we define internal graph functions. The following example shows how you might start to process inputs to produce outputs within your custom node group:

// Assume we have a function defined in our shader logic to mix colors
var function_code = """
vec3 mix_colors(vec3 base_color, vec3 highlight, vec3 shadow, float mix_ratio) {
    vec3 mixed_color = mix(mix(base_color, highlight, mix_ratio), shadow, mix_ratio);
    return mixed_color;

// We add this function to our custom node

By setting a function within your custom node, you effectively encapsulate the logic that operates on the inputs to produce the desired outputs.

Implementing Group Logic into Shaders

Now, let’s use our `mix_colors` function within a shader. We need to create a visual shader, add our custom node to it, and write the logic connecting the various inputs and outputs.

var visual_shader =
visual_shader.add_node(custom_color_node, Vector2(300, 300))

// Define shader inputs
var u_time =
u_time.set_output_port_type(0, VisualShaderNode.PORT_TYPE_SCALAR)
visual_shader.add_node(u_time, Vector2(150, 150))

// Connect time to the 'mix_ratio' in our custom node
visual_shader.connect_nodes(u_time.get_output_port(), custom_color_node.get_input_port(3))

// Finally, set the custom node outputs to shader output for rendering
var output_node =
visual_shader.add_node(output_node, Vector2(450, 300))
visual_shader.connect_nodes(custom_color_node.get_output_port(0), output_node.get_input_port(0))

// And assign the shader to a material
var material =

Here, we’re using a uniform input (`u_time`) to serve as a mixing ratio in our color mixing logic. Our custom node processes the colors with the time uniform, and the result is passed to the shader output, allowing us to visualize it in a ShaderMaterial.

Stay tuned for the final part of our tutorial, where we’ll refine our shader, add complexity to our node group, and explore practical applications for visual effects and material design. By mastering these techniques, you can craft stunning visuals that truly bring your game worlds to life!Absolutely, let’s build upon our initial example to further harness the capabilities of the VisualShaderNodeGroupBase class by refining and expanding our shader logic.

Refining Our Custom Node

With the foundation in place, let’s refine the internal workings of our custom node. We can add a blending function that takes the time uniform into account for animating the transitions between colors.

// Modify the function to include a time-based blending
var updated_function_code = """
vec3 blend_colors(vec3 base, vec3 highlight, vec3 shadow, float time) {
    float blend = sin(time * 2.0 * PI) * 0.5 + 0.5;
    return mix(mix(base, highlight, blend), shadow, blend);

Now, the `blend_colors` function dynamically changes the mix ratio based on the sine of the time, which provides an oscillating effect.

Adding Texture Sampling

To demonstrate the versatility of our custom node, let’s consider texture sampling. Assume we want to overlay our blended color with a texture based on a given mix ratio.

// Create a texture uniform and connect it to the custom node
var texture_uniform =
visual_shader.add_node(texture_uniform, Vector2(150, 0))
visual_shader.connect_nodes(texture_uniform.get_output_port(), custom_color_node.get_input_port(4))

// Update our function code in the custom node to use the texture
var texture_function_code = """
vec4 apply_texture(vec3 color, sampler2D texture, vec2 uv, float mix_ratio) {
    vec4 tex_color = texture(texture, uv);
    return vec4(mix(color, tex_color.rgb, mix_ratio), 1.0);

This snippet demonstrates adding a texture uniform and modifying the function to mix it with our color output.

Integrating User Controls

Often, you’ll want the end user to be able to control things like the mix ratio for blending. We can easily add a uniform to our visual shader for this purpose.

// Add a uniform for controlling the mix ratio
var mix_ratio_uniform =
visual_shader.add_node(mix_ratio_uniform, Vector2(0, 300))
visual_shader.connect_nodes(mix_ratio_uniform.get_output_port(), custom_color_node.get_input_port(5))

The user can now manipulate the `u_mix_ratio` in the material to interactively blend between the texture and the color output.

Creating a Panner Functionality

For some dynamic texture effects, like moving water or clouds, we need to implement a panner within our node group.

// Define a panning operation for UV coordinates
var panner_function_code = """
vec2 pan_uv(vec2 uv, vec2 speed, float time) {
    return uv + speed * time;

// Add speed uniform for the panning direction and rate
var speed_uniform =
visual_shader.add_node(speed_uniform, Vector2(50, 150))
visual_shader.connect_nodes(speed_uniform.get_output_port(), custom_color_node.get_input_port(6))

The panner function modifies the UV coordinates based on the speed and the time, allowing for texture motion over time.

Fine-tuning Outputs

Finally, it’s essential to ensure that our node’s outputs are correctly formatted before we feed them into the final shader output. Here’s an example that ensures the color is in the correct format.

// Adjust the output formatting of colors
var output_formatting_code = """
vec4 finalize_output(vec3 color) {
    return vec4(color, 1.0); // Ensure alpha is set to 1

// Connect custom node's color output to the shader's COLOR output
visual_shader.connect_nodes(custom_color_node.get_output_port(0), output_node.get_input_port(VisualShaderNodeOutput.OUTPUT_COLOR))

This piece of code makes sure that the final color output has a complete alpha channel, which is crucial for proper rendering.

By exploring these code examples, you will be increasingly familiar with the flexibility and control provided by the VisualShaderNodeGroupBase class. Each project may require different configurations, but with a strong grasp of these foundations, you can craft custom shader nodes that precisely meet your game’s visual needs. Experiment, iterate, and let your creativity flow – that’s the essence of pushing the boundaries with Godot’s visual shaders!As we delve deeper into using the VisualShaderNodeGroupBase class, let’s focus on further enhancing our shader functionality. We will explore how to add conditional logic, utilize loops, incorporate noise for organic effects, and manage multiple textures.

Integrating Conditional Logic

Conditional branching enables shaders to execute different code paths based on certain conditions. Below is an example where we apply a condition to switch between two different color blends based on a user-controlled factor.

// Extend our function to include a conditional branch
var conditional_function_code = """
vec3 conditional_blend(vec3 color1, vec3 color2, float threshold, float factor) {
    return factor < threshold ? color1 : color2;

// Add a factor uniform for users to control the condition
var factor_uniform =
visual_shader.add_node(factor_uniform, Vector2(50, 400))
visual_shader.connect_nodes(factor_uniform.get_output_port(), custom_color_node.get_input_port(7))

Users can modify `u_factor` to switch between `color1` and `color2`, providing a dynamic change in the shader effect based on the threshold.

Employing Loops for Repetitive Tasks

Shaders often need to perform repetitive tasks, which can be handled efficiently with loops. Here, we’re using a loop to create a striped pattern effect by alternating between two colors.

// Loop within the shader to create a striped pattern
var loop_function_code = """
vec3 striped_pattern(vec3 base_color, vec3 stripe_color, int stripe_count) {
    vec3 result_color = base_color;
    for (int i = 0; i < stripe_count; i++) {
        result_color = mix(result_color, stripe_color, step(0.5, mod(float(i)/stripe_count, 1.0)));
    return result_color;

This loop will constantly blend between the base color and the stripe color, creating an effect of `stripe_count` number of stripes.

Utilizing Noise for Organic Effects

Noise functions can be used to create organic textures like clouds or marble. Below is an example illustrating how to integrate noise into our shader effect.

// Add a 2D noise texture generator into the custom node
var noise_function_code = """
vec3 apply_noise(vec3 base_color, vec2 uv, float scale) {
    float noise_value = texture(simplex_noise_texture, uv * scale).r;
    return base_color * noise_value;

// Add a scale uniform to control the noise scale
var scale_uniform =
visual_shader.add_node(scale_uniform, Vector2(250, 400))
visual_shader.connect_nodes(scale_uniform.get_output_port(), custom_color_node.get_input_port(8))

In this snippet, we’re adding a simplex noise texture to the node and a uniform to control the scale of the noise applied to the base color.

Managing Multiple Textures

Many modern materials require multiple textures for effects like ambient occlusion, roughness, or metallic properties. Here’s an example of handling two textures: a base texture and an overlay, with the option to blend them together.

// Define how to blend two different textures
var multi_texture_function_code = """
vec3 blend_textures(sampler2D base_texture, sampler2D overlay_texture, vec2 uv, float blend_factor) {
    vec3 base_tex_color = texture(base_texture, uv).rgb;
    vec3 overlay_tex_color = texture(overlay_texture, uv).rgb;
    return mix(base_tex_color, overlay_tex_color, blend_factor);

// Create additional texture uniform
var overlay_texture_uniform =
visual_shader.add_node(overlay_texture_uniform, Vector2(350, 0))
visual_shader.connect_nodes(overlay_texture_uniform.get_output_port(), custom_color_node.get_input_port(9))

This code allows for the blending of a base texture and an overlay texture, providing the artist with creative control over the material’s appearance.

By incorporating these advanced techniques, you can create robust and dynamic shaders that contribute to the immersive experience of your game. Each code example is a building block towards crafting comprehensive, high-performance visual effects. Experimenting with these functionalities will elevate the visual appeal of your projects while ensuring optimal performance and flexibility.

Continue Your Game Development Journey

Now that you’ve dived into the world of shaders with the VisualShaderNodeGroupBase class in Godot 4, you’re one step closer to realizing your game development dreams. But where should you head next? To deepen your expertise and unlock the full potential of your game creation skills, we invite you to explore our Godot Game Development Mini-Degree. Our comprehensive course collection guides learners through the nuances of building cross-platform games with Godot 4, offering rich insights into 2D and 3D game development, GDScript programming, gameplay mechanics, and much more.

Whether you’re a seasoned developer or just starting out, Zenva’s tailored curriculum adapts to your skill level, allowing you to skip ahead to the content that challenges you the most. With our structured learning path, live-coding lessons, and practical projects, you can craft an impressive portfolio while gaining the hands-on experience necessary to bring your visions to life. For an even broader selection of topics and advanced techniques, take a look at our overall offering of Godot courses. Each course provides challenges, quizzes, and completion certificates, fitting perfectly into your schedule and enabling 24/7 access to high-quality content.

By choosing Zenva, you embark on a journey that could transform your curiosity into professional mastery. Continue learning, keep creating, and stay ahead in the ever-evolving world of game development. Embrace the tools and knowledge at your fingertips, and who knows what fantastic games you’ll bring to players around the world.


The journey through the depths of Godot’s VisualShaderNodeGroupBase has illuminated just how customizable and powerful the world of shaders can be. Armed with this knowledge, you’re now poised to paint your games with a palette of visual wizardry, adding depth and life to your creations. Remember, the tools you’ve learned here are but a brushstroke in the grand canvas of game development.

We at Zenva are thrilled to accompany you as you hone your skills and craft your unique game experiences. Explore our Godot Game Development Mini-Degree for a treasure trove of resources that promise to elevate your projects from great ideas to finished games. With each step on this path, you build not just games, but also the future of your dreams. So, take that leap, and let’s create something extraordinary together!


Python Blog Image

FINAL DAYS: Unlock coding courses in Unity, Unreal, Python, Godot and more.