SubViewport in Godot – Complete Guide

Welcome to an explorative journey through the realm of Godot 4, where today’s stop is the innovative SubViewport feature. This tutorial promises to guide you through the intricacies of the SubViewport class, a uniquely streamlined method of managing game worlds which adds depth and versatility to your development arsenal without the need for creating new windows or directly drawing to the screen. Whether you’re just starting or are well-versed in the Godot engine, ready your creative muscles to harness the power of isolated scene rendering for both aesthetic appeal and functional design in your games.

What Is SubViewport?

A SubViewport in Godot 4 is akin to a specialized camera in your game’s world that captures a particular scene or element without the need to draw directly onto the main screen. Think of it like having a mini-stage within your larger play, where you can orchestrate separate performances simultaneously. SubViewports are crucial for rendering different parts of your game, such as UI elements in 3D space or creating picture-in-picture effects, independent from the main viewport.

What Is It For?

SubViewports serve various purposes, greatly enhancing a developer’s toolset for creating immersive experiences. With the ability to isolate parts of a scene, they can be used for:

– Displaying multiple camera angles.
– Rendering 3D models within a 2D interface.
– Creating dynamic split-screen games.
– As a render target for post-processing effects.

Why Should I Learn It?

Understanding SubViewports opens up a new dimension of visual and interactive possibilities:

– **Increased Flexibility**: SubViewports enable a modular approach to scene management, providing the flexibility to control how and when parts of a scene are rendered.
– **Performance Optimization**: They can optimize performance by limiting rendering to only the visible or necessary parts of a game scene.
– **Creative Freedom**: With SubViewports, your creative vision is not confined to the main game screen, which means you can craft intricate gameplay mechanics and visuals that stand out.

With this fundamental knowledge, you’re well on your way to transforming your game development skills and expanding your creative horizons. Let’s embark on this coding adventure and make your game worlds come alive with SubViewports.

CTA Small Image

Creating a SubViewport

The first step in utilizing a SubViewport is to create one within the Godot editor. By doing this, you outline the area where your isolated scenes or elements will be rendered. Here’s how you could set that up in GDScript:

var sub_viewport =

Once you’ve created your SubViewport, you may need to set the size manually to ensure it renders the scene at the correct scale.

sub_viewport.size = Vector2(1280, 720)

It’s essential to add the SubViewport as a child to your main scene so that it becomes part of the node tree and is processed during the game’s runtime.

Setting Up a SubViewport Camera

After creating your SubViewport, you’ll need a camera within it to render the scene from a specific point of view.

var camera =
sub_viewport.add_child(camera) = camera

This script creates a new Camera node and assigns it as the SubViewport’s camera, allowing you to control what the SubViewport is rendering.

Rendering 3D Content in a 2D game

You can use SubViewports to include 3D elements, like a character or item, in a predominantly 2D game. You need to configure the environment settings of the SubViewport for it to render the 3D content correctly.

var environment =
environment.background_mode = Environment.BG_SKY
sub_viewport.environment = environment

By creating an environment for this SubViewport, we ensure that our 3D model will be rendered with appropriate lighting and sky settings.

Handling Input in a SubViewport

When using a SubViewport, you might want to handle inputs specifically for that viewport. It’s possible to make the SubViewport handle its own input events.

func _ready():
    sub_viewport.input_disable_input = false
    sub_viewport.connect("gui_input", self, "_on_SubViewport_input")

func _on_SubViewport_input(event):
    if event is InputEventMouseMotion:
        print("Mouse is moving within the SubViewport!")

With this setup, `input_disable_input` is set to `false` to allow handling of inputs, and we connect the `gui_input` signal to a custom function that reacts to mouse movement within the SubViewport.

These examples cover the necessary basics of creating and utilizing a SubViewport within the Godot engine. By understanding these fundamental processes, you can start incorporating this powerful feature into your game development workflow, enhancing the interactivity and complexity of your game’s scenes.SubViewports not only aid in rendering but can also serve as off-screen render targets. This capability opens the door for advanced effects, like dynamic textures and post-processing. Let’s dive further to capitalize on the capabilities that SubViewports provide us in terms of game design and creativity.

Using SubViewports for Dynamic Textures

One intriguing use of SubViewports is for creating dynamic textures. You can render a scene to a texture and apply it to a 3D object as a material. Below is a basic setup to achieve this:

var render_texture =
render_texture.viewport = sub_viewport
var material =
material.albedo_texture = render_texture

Here we’re creating a ViewportTexture that is linked to our SubViewport, which is then used as the albedo texture for a material typically applied to a 3D object.

Now, suppose you require more control over when the SubViewport renders. You can manually tell the SubViewport to update its render using the following functionality:

sub_viewport.render_target_update_mode = Viewport.UPDATE_ONCE

This snippet sets the `render_target_update_mode` to `UPDATE_ONCE`, meaning the SubViewport will render its content just a single time, which is useful when you have a static scene that doesn’t need constant updates.

Post-Processing with SubViewports

SubViewports are also fantastic for applying post-processing effects. Let’s go over how to set this up, starting by ensuring your SubViewport has the following properties:

sub_viewport.render_target_v_flip = true
sub_viewport.usage = Viewport.USAGE_2D

Here, `render_target_v_flip` ensures that the rendered texture is not vertically flipped, while `usage` is set to `2D` when you’re dealing with a 2D game or UI elements. For 3D scenes, you would use `Viewport.USAGE_3D` or `Viewport.USAGE_3D_NO_EFFECTS` depending on whether you want post-processing effects to be applied within the SubViewport.

Let’s assume you have a ShaderMaterial that you’re using to apply a grayscale effect. To apply it using a SubViewport, you could do the following:

var shader_material =
# Assume you've set up your shader code already
shader_material.shader_code = "..."
render_texture.viewport = sub_viewport

This code block attaches the shader to a material and applies it to the SubViewport, which will then render everything in grayscale.

Manipulating SubViewport Cameras for Split-Screen

For creating a split-screen setup, you would have multiple SubViewports, each with its own camera. Here’s a basic approach to setting up a camera for each player in a split-screen game: = camera_player_1 = camera_player_2

Each player gets a unique SubViewport and camera setup, rendering their perspective independently.

Optimizing SubViewports

Lastly, let’s consider optimizing our SubViewports. Since unnecessary processing can affect performance, especially on lower-end hardware, you might want to toggle the visibility of objects within a SubViewport depending on the game state:

if not player_within_viewport_area:
    sub_viewport.visible = false
    sub_viewport.visible = true

By toggling the `visible` property of the SubViewport, you control when it should render content, conserving resources when that content isn’t needed. This is particularly handy for off-screen elements that only become relevant under certain conditions.

These examples have hopefully illuminated the depth and breadth of what you can achieve with SubViewports in Godot 4. From improving performance to adding rich, dynamic visual elements, SubViewports are an indispensable part of a game developer’s toolkit when using Godot. Happy coding!Let’s delve into more applications and optimizations surrounding the use of SubViewports in Godot 4. As we integrate additional code examples, keep in mind how these can be fine-tuned to fit the needs of your specific project.

Advanced SubViewport Management

Beyond rendering, SubViewports can be used to manage complex scenes. For instance, you might want to load or unload parts of a level dynamically. Here’s how you could set up a SubViewport to dynamically handle scenes:

var level_sub_viewport =
var level_scene = preload("res://levels/part_of_level.tscn").instance()

By loading a part of the level into the SubViewport, you can manage the active sections of your game world with greater precision.

Customizing SubViewport Rendering

Customizing render options for a SubViewport can enhance the visual result or optimize performance. Let’s say you want to render your SubViewport without environmental effects to achieve a particular style or boost FPS:

sub_viewport.render_direct_to_screen = false
sub_viewport.environment = null

With `render_direct_to_screen` set to `false` and `environment` to `null`, the SubViewport will render without any environment, like skyboxes or ambient light.

World Layers and SubViewports

Godot’s use of layers and SubViewports can be leveraged to layer additional effects or UI elements. Here’s how you could ensure that only certain layers are rendered in your SubViewport:

sub_viewport.cull_mask = 1 << 2 # Only render layer 2

By setting `cull_mask`, you can filter which layers the SubViewport’s camera takes into account during the rendering process.

Render Target Management

If your SubViewport is meant to act as a render target for post-processing, memory management becomes critical. You can set your SubViewport to only render when you’re actually going to use the resulting texture:

sub_viewport.update_mode = SubViewport.UPDATE_WHEN_VISIBLE

With `UPDATE_WHEN_VISIBLE`, the SubViewport will only update its render target when it’s visible, which is an excellent method to conserve processing power.

Handling Shaders and Reflections in SubViewports

SubViewports can also be utilized for rendering specific shaders or reflections. Below, we outline setting up a SubViewport for a reflection effect on water:

sub_viewport.clear_mode = Viewport.CLEAR_ALWAYS
sub_viewport.render_target_clear_color = Color(0, 0, 0, 0) # Clear with transparent black
# Reflection-specific setup goes here...

By setting the `clear_mode` to `CLEAR_ALWAYS`, the viewport is cleared each frame to ensure no artifacts remain from the last render. Moreover, customizing the `render_target_clear_color` aids in creating effects such as water reflections by starting with a transparent canvas.

SubViewport as a Render Texture for Sprites

Using a SubViewport as a render texture for a sprite can allow for unique in-game displays. Here’s a simple setup that applies the SubViewport’s render as a texture for an in-game monitor:

var sprite =
sprite.texture = sub_viewport.get_texture()

By getting the texture from the SubViewport and applying it to a sprite, you effectively create an in-game screen displaying whatever the SubViewport renders.

Through these examples, it becomes apparent how SubViewports can be manipulated and optimized for a variety of uses, from managing different levels to optimizing shaders and rendering techniques. The power of SubViewports lies in their flexibility and the creative options they offer to game developers. As you grow accustomed to these features and start applying them to your own projects, you may find even more innovative ways to make your games shine!

Continuing Your Godot Journey

The realm of game development is vast and constantly evolving, with much to explore and create. If this introduction to SubViewports in Godot 4 has sparked your curiosity and you’re eager to delve deeper into game creation, we wholeheartedly encourage you to continue your learning journey. To aid you along this path, our Godot Game Development Mini-Degree is an excellent resource to expand your knowledge and skills in building cross-platform games.

In this comprehensive collection of courses, you’ll explore various game mechanics and genres, from RPGs and platformers to RTS and survival games. By creating a portfolio of real projects, you’ll solidify your understanding and gain hands-on experience that’s essential for tackling the challenges of game development with confidence. The flexibility of our courses ensures that regardless of your current level—from beginner to an experienced developer—you’ll find valuable content tailored to your needs.

For those who seek a broader selection, we invite you to check out our full range of Godot courses. We take pride in equipping learners with real-world skills through structured lessons featuring live coding, quizzes, and project-based learning. With Zenva, you’ll have the chance to not just play games but to create them, potentially opening doors to a vibrant career in the game development industry. Let the adventure continue, and may your passion for game creation grow ever stronger with each line of code you write.


As we reach the end of our adventure with SubViewports in Godot 4, we hope your mind brims with the possibilities that this powerful feature unlocks for your projects. Remember, what we’ve covered today is just the tip of the iceberg in the boundless sea of game development with Godot. Embrace these tools, experiment with them, and craft immersive experiences that leave players in awe.

Continue with us on your journey to mastery by diving into our Godot Game Development Mini-Degree. Let each course be a stepping stone towards realizing your dream games. With dedication and the right resources at your fingertips, there’s no limit to what you can create. Let your creativity soar, and transform your virtual worlds into reality with Zenva—your gateway to becoming a champion of game development.

Python Blog Image

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