GeometryInstance3D in Godot – Complete Guide

Welcome to our tutorial on the GeometryInstance3D class in Godot 4, one of the core components in creating immersive 3D environments in your games. This tutorial will shine a light on the significance of GeometryInstance3D, revealing why it’s a powerful tool in your game development arsenal. By understanding the features and functionalities this class provides, you will be able to enhance the visual complexity and performance of your 3D projects, thereby creating more engaging experiences for your players. Join us as we delve deep into the world of Godot’s 3D space, and discover how mastering GeometryInstance3D can elevate your game to the next level.

What Is GeometryInstance3D?

GeometryInstance3D is a foundational building block for all types of geometry-based visuals in Godot Engine. It’s the base node class from which a variety of other 3D visual instances inherit. This includes widely-used nodes such as MeshInstance3D, CPUParticles3D, and MultiMeshInstance3D, among others. Essentially, any element that entails mesh rendering and manipulation in the 3D space extends from this versatile class.

What Is It For?

GeometryInstance3D serves as the central hub for managing features like custom materials, shadow casting, and global illumination modes. It equips you with a range of properties and methods to finely tune the visual behavior of your 3D models. This control extends to how objects cast shadows, how they are included in lightmap baking processes, and even how they deal with occlusion culling, to name just a few capabilities.

Why Should I Learn It?

For anyone interested in game development, especially in 3D environments, understanding and utilizing the GeometryInstance3D class unlocks the potential to create visually stunning and performance-optimized games. Learning how to use GeometryInstance3D allows you to:

– Create detailed game scenes with control over each object’s visual properties.
– Implement performance improvements through properties like level of detail (LOD), occlusion culling, and shadow casting settings.
– Customize the rendering pipeline by overriding materials and leveraging visual effects, like transparency and lightmap scaling.

By mastering GeometryInstance3D, you will have the knowledge to create visually impressive games that stand out, while also ensuring smooth performance across a wide range of hardware. Whether you’re just starting your game development journey or looking to enhance your existing skills, this tutorial will provide valuable insights into 3D rendering with Godot.

CTA Small Image

Creating a Basic GeometryInstance3D

Before diving into advanced features, let’s start with the basics. Any 3D geometry in Godot begins with creating a GeometryInstance3D node. Here’s how to add and configure a basic GeometryInstance3D in code:

var geometry =
geometry.transform = Transform(Basis(), Vector3(0, 0, 0))

This snippet creates a new GeometryInstance3D and adds it to the current scene. The transform property is used to position and orient the geometry in 3D space.

Setting Up Materials

Materials define how light interacts with surfaces. To make an object renderable and visually distinct, we apply materials to our GeometryInstance3D. Here’s a snippet showing how to set up a material for a 3D object:

var material =
material.albedo_color = Color(1, 0, 0)  # Red color
geometry.material_override = material

We create a SpatialMaterial, set its albedo (base) color to red, and assign it to the GeometryInstance3D using the `material_override` property.

Enabling Shadows and Global Illumination

Shadows add a realistic touch to your scenes. To enable or disable shadow casting for a GeometryInstance3D, you use the `cast_shadow_mode` property. You can also specify how the instance interacts with global illumination using `gi_mode`.

geometry.cast_shadow_mode = GeometryInstance3D.SHADOW_CASTING_SETTING_ON
geometry.gi_mode = GeometryInstance3D.GI_MODE_BAKED

These lines set the GeometryInstance3D node to cast shadows and participate in global illumination baking.

Level of Detail (LOD)

Level of detail is crucial for performance optimization, especially in complex scenes with many objects. You can set up different LODs through code, adjusting the level of detail based on the distance from the camera:

var lod =

These lines create a new GeometryInstance3D node and configure the minimum and maximum distances where the LOD will change, as well as the hysteresis to prevent LOD popping.

By effectively using GeometryInstance3D and its subclasses, you can start crafting richly detailed and high-performance 3D scenes. These basics lay the groundwork for more intricate and evolved 3D visuals. As you grow more comfortable with these properties and their implementation, you’ll be on your way to leveraging the full power of Godot’s 3D engine.Improving performance and aesthetics in your 3D scenes can often require more detailed control over your GeometryInstance3D nodes. Let’s explore some additional features and code examples that will help you take further advantage of this powerful class.

Manipulating Visibility with GeometryInstance3D

There are times when you may want certain objects to be visible only under specific conditions. To hide or show your GeometryInstance3D dynamically in code, adjust the `visible` property as shown:

geometry.visible = true # Makes the geometry visible
geometry.visible = false # Makes the geometry invisible

Visibility is a key aspect of optimizing performance and directing player focus within your game.

Using Layers for Collision and Rendering

GeometryInstance3D nodes can be assigned to different layers for rendering and physics calculations. This allows for selective interaction with lights or cameras:

geometry.render_layer_mask = 1 # Only visible to cameras using this layer
geometry.collision_layer = 1 # Only interact with objects on the same collision layer

Layers are an effective way to manage complex interactions in a multi-object environment.

Adjusting the Extra Cull Margin

For complex scenes with objects that have non-standard shapes, you might need to adjust the GeometryInstance3D’s bounding box to ensure it’s rendered correctly:

geometry.extra_cull_margin = 1.0

The `extra_cull_margin` property adds an additional margin to the bounding box used for view frustum culling, which can prevent graphical glitches at the boundaries of the object.

Customizing Rendering Priority

In instances where you need to control the order in which objects are rendered, you can set the `render_priority` attribute. This helps to sort objects and can be crucial for transparent materials to render correctly:

geometry.render_priority = 0 # Default priority
geometry.render_priority = 10 # Higher priority, rendered later

Transparent objects often need to be rendered after opaque ones to look correct, and this setting will be critical for that kind of scenario.

These code examples offer a glimpse into the diverse set of features that GeometryInstance3D provides. With these tools at your disposal, you can now efficiently manage the many aspects of your 3D objects in Godot, enhancing both the performance and quality of your games. As you incorporate these techniques into your projects, remember that fine-tuning these properties to suit your specific needs is vital for achieving the best results in your unique game environment. Keep experimenting and learning, and your skills in utilizing GeometryInstance3D will continue to grow, leading to ever-more impressive and immersive 3D worlds for your players to explore.In complex scenes where lighting and materials interact in various ways, understanding how to tweak advanced settings of GeometryInstance3D nodes can make a significant difference. Below are additional code examples that showcase some of these advanced features, allowing for a greater enhancement of your 3D scenes in Godot 4.

Baking Parameters for Global Illumination

When participating in global illumination, GeometryInstance3D has specific properties that control its baking behavior. This is essential when setting up scenes for lightmapping:

geometry.gi_mode = GeometryInstance3D.GI_MODE_BAKED
geometry.gi_probe_data = preload("res://path_to_your_probe_data.tres")

Here, we’re telling the engine that the geometry should use baked global illumination and we’re providing it with the necessary probe data resource.

Controlling Reflections

Reflection probes are used to create realistic reflections in your 3D environments. Here’s how to link your GeometryInstance3D to a reflection probe:

geometry.reflection_probe_instance = preload("res://path_to_your_reflection_probe_instance.tres")

Assigning a reflection probe instance to your geometry ensures that the reflective properties of the material are influenced by the surrounding environment.

Distance Fade for Objects

Creating visual effects where objects fade with distance can be implemented using distance fade properties. This is particularly useful for things like fog or creating the illusion that objects are part of the background as they move away:

material.distance_fade_mode = SpatialMaterial.DISTANCE_FADE_PIXEL_ALPHA
material.distance_fade_min_distance = 10.0
material.distance_fade_max_distance = 50.0

Distance fading can help meld objects into your scenes more naturally, particularly in large, open environments.

Adjusting the Emission of Materials

Emission properties can make your objects glow and contribute to the scene’s lighting. Here, we adjust the emission strength and color of the material applied to the GeometryInstance3D:

material.emission = Color(0.5, 0.5, 1.0)  # Bluish emission
material.emission_energy = 2.0

This can create powerful visual effects, such as glowing signs, magic spells, or other light-emitting objects.

Custom Shader Parameters

Godot supports custom shaders, allowing for extensive customization of how objects are rendered. If you’re using a shader with custom parameters, you can set these parameters on the GeometryInstance3D easily:

var shader_material =
shader_material.set_shader_param("your_param", value)
geometry.material_override = shader_material

This example allows you to tailor visual effects to your exact requirements by modifying shader parameters directly from your scripts.

Overriding Environment Settings

If required, you can override environment settings for a specific GeometryInstance3D, such as ensuring an object does not get affected by the World Environment or setting it to use its own Environment:

geometry.environment_override = preload("res://path_to_your_custom_environment.tres")

By overriding environment settings selectively, you can create unique atmospheres or visual conditions for particular objects without changing the entire scene’s environment.

With these examples, you can see just how flexible the GeometryInstance3D node is when it comes to rendering control in Godot 4. The node acts as a swiss knife for 3D rendering, capable of handling various rendering features that can push your game’s visual fidelity. Understanding and manipulating these properties can not only bring your game environments to life but also provide a granular level of control over performance and rendering quality. Remember that each of these features, when used appropriately, plays a part in enriching the visual storytelling of your game.

Continuing Your Learning Journey in Godot

Embarking on your journey to master the Godot Engine is an exciting adventure that opens up a world of creativity and innovation in game development. If you’re ready to take the next step and further your skills, we invite you to explore our Godot Game Development Mini-Degree. Our comprehensive collection of courses guides you through the ins and outs of this powerful engine, from 2D and 3D game development to intricate gameplay mechanisms and beyond.

With our curriculum, learners of all levels—from beginners to more advanced developers—can fortify their knowledge and discover new techniques. Our interactive lessons and coding challenges provide hands-on experience, ensuring you gain the practical skills needed to create stunning, cross-platform games. And while our courses culminate in certificates to mark your achievements, the real reward is the ability to bring your game ideas to life and thrive in the burgeoning game industry.

For those who wish to broaden their horizons with a variety of comprehensive and up-to-date Godot courses, we’ve got you covered. Visit our full range of Godot courses and let us support you in becoming a versatile and skilled game developer. At Zenva, we take pride in empowering you with the tools to go from beginner to professional, one lesson at a time. Let’s continue making games, learning, and growing together!


As we wrap up our exploration of the GeometryInstance3D class in Godot 4, it’s clear that the power to craft visually rich and performant 3D games is at your fingertips. By leveraging these in-depth features, your ability to fine-tune details and optimize your game scenes has no bounds. The journey of learning and mastering new skills in Godot continues, and each step taken is a stride toward becoming a proficient game developer capable of turning creative visions into playable realities.

Embrace the challenge and continue your educational adventure with our Godot Game Development Mini-Degree. Unlock your potential and join a thriving community of developers who share your passion. Let us accompany you every step of the way as you harness the full potential of Godot 4, creating games that resonate with players and stand the test of time. The time to bring your game ideas to life is now, with Zenva as your guide!

Python Blog Image

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