ViewportTexture in Godot – Complete Guide

ViewportTexture is an incredibly versatile feature in Godot 4, offering a powerful way to integrate and manipulate different types of game objects and UI elements within your game scenes. By bridging the gap between 2D and 3D, the ViewportTexture class unlocks a new dimension of creativity for game developers, enhancing both the visual impact and gameplay experience. Whether you’re a novice dipping your toes into the world of game development or a seasoned coder looking for new tools to expand your game’s horizons, understanding ViewportTexture is invaluable.

What is ViewportTexture?

ViewportTexture in Godot 4 is a class that derives from Texture2D and allows you to use the content of a Viewport as a dynamic texture. It is commonly employed in scenarios where there is a need to display both 2D and 3D elements together, for example, a 3D model on a 2D UI or a mini-map within a 3D world.

What is ViewportTexture Used For?

The primary application of ViewportTexture is to seamlessly integrate different scene elements. You can display controls, 2D sprites, and 3D models all in the same scene. It’s perfect for creating HUDs that include 3D elements or embedding a 2D game within a 3D world, among other creative applications.

Why Should I Learn about ViewportTexture?

Learning about ViewportTexture can be a game-changer for any Godot developer:

– It makes your game’s UI more dynamic and engaging.
– It provides the means for innovative gameplay mechanics.
– It’s a step toward mastering the prowess of the Godot engine.

Embracing the potential of ViewportTexture will not only broaden your overall game development skills but will also open up new avenues for creativity and interactivity in your projects.

CTA Small Image

Creating a Basic ViewportTexture

To start using ViewportTexture, we’ll need to create a new Viewport and reference it in our texture:

var my_viewport =
var my_viewport_texture = my_viewport.get_texture()

Next, we assign this texture to a sprite:

var my_sprite =
my_sprite.texture = my_viewport_texture

This simple setup will display whatever the viewport is rendering onto the sprite.

Displaying 3D in 2D UI using ViewportTexture

To display a 3D scene inside a 2D UI, we follow these steps:

First, create a Viewport specifically for the 3D scene:

var viewport_3d =
viewport_3d.size = Vector2(200, 200) // Adjust as per your UI needs

Next, instance your 3D scene and add it to the viewport:

var my_3d_scene = preload("res://my_3d_scene.tscn").instance()

Finally, use the ViewportTexture to show it on your UI, by applying it to a TextureRect:

var texture_rect =
texture_rect.texture = viewport_3d.get_texture()

Creating Dynamic Textures

ViewportTextures can update in real-time, which is great for dynamic textures like mini-maps or security cameras within the game.

First, set up your Viewport to render your scene:

viewport.mini_map.usage = Viewport.USAGE_2D_NO_SAMPLING
viewport.mini_map.render_target_update_mode = Viewport.UPDATE_ALWAYS

Then, use the ViewportTexture for your UI element:

var mini_map_sprite =
mini_map_sprite.texture = viewport.mini_map.get_texture()

Handling Input in a ViewportTexture

If you need to interact with the items inside your ViewportTexture, you need to route the input events manually.

First, make sure to enable the input on your viewport:


For example, to manipulate a 2D control in a 3D world, you would pass the input from your main scene’s `_unhandled_input`:

func _unhandled_input(event):
    if my_viewport_texture.get_rect().has_point(event.position):

Using the methods demonstrated in these examples, you will be well on your way to effectively utilizing ViewportTextures in your Godot 4 projects. Integrating 2D and 3D elements has never been easier, which opens the door to countless creative possibilities.ViewportTextures can be quite flexible, so let’s dive a bit deeper into how we can utilize them in different scenarios.

Adding Effects to ViewportTexture

You can apply shaders and post-processing effects to the Viewport before using it as a texture:

var viewport_with_shader =
viewport_with_shader.size = Vector2(512, 512)
var viewport_texture = viewport_with_shader.get_texture()

var shader_material =
# Set Shader code or Shader resource
viewport_with_shader.material_override = shader_material

Here you’d replace `# Set Shader code or Shader resource` with the actual shader code or resource. This setup could be used to create unique visual effects like water reflections, heat haze, etc.

Multiple Layers in a ViewportTexture

If you want to create a complex scene with multiple layers, you can add multiple viewports and stack them:

var viewport_background =
var viewport_foreground =

var bg_texture = viewport_background.get_texture()
var fg_texture = viewport_foreground.get_texture()

# Add backgrounds and foregrounds as children to appropriate Viewports
# ...

var bg_sprite =
bg_sprite.texture = bg_texture
var fg_sprite =
fg_sprite.texture = fg_texture

# Position foreground sprite over the background by changing its z-index
fg_sprite.z_index = 1

# Now, add both sprites to the main node

This technique allows you to composite different elements before bringing them together in the main scene.

ViewportTexture as a Render Target

You can use Viewport as an off-screen render target and apply the texture to a 3D object:

var my_viewport =
my_viewport.render_target_v_flip = true
var my_texture = my_viewport.get_texture()

var my_3d_object = $MeshInstance
my_3d_object.material_override =
my_3d_object.material_override.albedo_texture = my_texture

Flipping the render target is often required because the default coordinate system for textures in 3D is vertically flipped compared to 2D.

Controlling Viewport Updates

You might not always need or want the viewport to update every frame. You can control this to save on performance:

var viewport =
viewport.render_target_update_mode = Viewport.UPDATE_ONCE
# or, to update when visible
viewport.render_target_update_mode = Viewport.UPDATE_WHEN_VISIBLE
# to update manually
viewport.render_target_update_mode = Viewport.UPDATE_DISABLED

# To manually trigger an update when necessary:

By setting the update mode to `UPDATE_DISABLED`, you can manually call `update()` on the viewport when you need to refresh its content, which is especially useful for static images or infrequently updated content.

Resolving Screen Clipping

When using ViewportTextures, sometimes the content may clip at the edges. You may need to adjust the size or disable the parent viewport’s own overlay:

var my_viewport =
my_viewport.size = Vector2(1024, 768)
# Add other setup and children nodes
# Disable parent viewport's overlay if it's not needed
get_tree().get_root().disable_3d = true

Disabling the 3D overlay on the root viewport can resolve some clipping issues, especially in UI-heavy games where 3D is less prominent

With these examples and tips, you’re equipped with the knowledge to implement ViewportTexture in various creative ways. Remember to experiment and see what unique features you can bring to your game with this powerful tool.ViewportTextures in Godot 4 can also be incredibly useful for creating interactive environments or objects within your games, such as interactive menus or even in-game screens like computers or TVs. Below, we’ll continue with additional examples that showcase the power and flexibility of ViewportTextures.

// Setup a viewport as a render target for an in-game screen.
var screen_viewport =
screen_viewport.size = Vector2(1920, 1080)
var screen_texture = screen_viewport.get_texture()

// Create a sprite representing the in-game screen.
var in_game_screen =
in_game_screen.texture = screen_texture

In this example, we’re setting up a viewport to act as the content of an in-game 3D screen. The texture is rendered to appear on the model of a screen within the game world, which creates the illusion of functioning screens.

Creating a Reflection with ViewportTexture

ViewportTextures can be used for environmental effects like dynamic reflections:

// Create a viewport for the reflective surface.
var reflection_viewport =
reflection_viewport.size = Vector2(512, 512)
var reflection_texture = reflection_viewport.get_texture()

// Assign the ViewportTexture to a reflective material.
var reflective_material =
reflective_material.set_texture(SpatialMaterial.TEXTURE_ALBEDO, reflection_texture)

// Apply the reflective material to a plane mesh which will act as a mirror.
var mirror =
mirror.mesh =
mirror.material_override = reflective_material

This example demonstrates how to create a simple reflection effect that could be on water surfaces or mirrors.

Using ViewportTexture for Scene Transitions

ViewportTextures can be captured and then manipulated as a part of a scene transition effect:

// Save the current screen as a texture.
var snapshot_viewport = get_tree().get_root().create_texture_screen()
snapshot_viewport.texture_flags = Texture.FLAGS_DEFAULT
snapshot_viewport.flip_v = true

// Apply this texture to a fullscreen Sprite to create a transition effect.
var transition_sprite =
transition_sprite.texture = snapshot_viewport
transition_sprite.scale = Vector2(2, 2) // Scale up to cover full screen

// Now you can animate the sprite, fade it out, or apply shader effects for the transition.

This is particularly useful for creating custom transition effects between scenes, like fades, slides, or pixelizes.

ViewportTexture for In-Game Cameras

Create an in-game camera system, where you can see through the lens of a camera within the game:

// Create a viewport for the in-game camera.
var camera_viewport =
camera_viewport.size = Vector2(256, 256)
var camera_texture = camera_viewport.get_texture()

// Set up a camera as a child of the viewport.
var camera =
camera.current = true

// Render the ViewportTexture to a sprite or UI element.
var camera_monitor =
camera_monitor.texture = camera_texture

Using this setup, you can simulate surveillance cameras, sniper scopes, or any other situation where you’re viewing the scene from a specific point.

Dynamic Portals with ViewportTexture

Create magical or sci-fi portals that the player can see and walk through to another part of the game world:

// Setup a viewport for each side of the portal.
var enter_portal_viewport =
var exit_portal_viewport =
enter_portal_viewport.size = exit_portal_viewport.size = Vector2(256, 256)

// Capture the respective opposite sides of the portal.
var enter_portal_texture = enter_portal_viewport.get_texture()
var exit_portal_texture = exit_portal_viewport.get_texture()

// Apply the textures to respective portal plane objects.
var enter_portal_plane =
var exit_portal_plane =
enter_portal_plane.material_override.albedo_texture = exit_portal_texture
exit_portal_plane.material_override.albedo_texture = enter_portal_texture

// Position the portals appropriately and add viewports to the scene.

This technique is a creative way to connect different parts of your game world and can create a visually stunning experience for players as they move through portals.

These examples showcase just the tip of the iceberg when it comes to ViewportTexture applications in Godot 4. With this level of control and flexibility, you can build and enhance your game’s environments, UI elements, and special effects to create a richer gaming experience. The ability to dynamically render and manipulate textures in real-time is a powerful tool in any game developer’s toolkit.

Continue Your Game Development Journey

The world of game development is vast and ever-evolving, with new tools and techniques consistently emerging. If you’re excited about what you’ve learned and eager to dive deeper into the realms of game creation, particularly with the versatile and powerful Godot 4 engine, we have incredible resources tailored for you at Zenva Academy.

Our Godot Game Development Mini-Degree is meticulously designed to take you from the fundamentals through to crafting polished games. You’ll gain hands-on experience building projects, learning about 2D and 3D assets, mastering GDScript, and understanding gameplay control flows – all at your own pace. This comprehensive course collection is perfect for newcomers and those seeking to solidify their game development skills alike.

For a broader look at the Godot courses we offer, explore our extensive collection at Zenva’s Godot Courses. Embrace the journey, continue to learn and experiment, and soon, you’ll see your game development aspirations come to life!


By stepping into the exciting world of ViewportTexture in Godot 4, you unlock a treasure trove of possibilities for game development. It’s a testament to your creativity and ingenuity as a developer to leverage such features, paving the way for truly immersive and interactive gaming experiences. Whether it’s by shaping dynamic UIs, creating portals that stitch worlds together, or crafting reflections that bring environments to life, your journey in game development is bound only by the limits of your imagination.

Continue to grow, innovate, and challenge yourself with Zenva Academy. Take the next step and flourish as a game developer with our Godot Game Development Mini-Degree. This is where your learning curve transforms into the launchpad for your dreams. We can’t wait to see the amazing games you’ll create!

Python Blog Image

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