Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

Trail3D

Inherits: Line3D < GeometryInstance3D < VisualInstance3D < Node3D < Node < Object

A node to draw lines behind moving objects.

Description

The Trail3D node draws a flat line in space, with an optional billboard mode.

Note: This node is designed for visual effects. For solid lines, pipes, and tubes, use a CSGPolygon3D node in CSGPolygon3D.MODE_PATH mode.

Properties

Color	color	`Color(1, 1, 1, 1)`
Gradient	color_gradient
bool	emitting	`true`
float	lifetime	`0.2`
LimitMode	limit_mode	`0`
ShaderMaterial	material
MaterialMode	material_mode	`0`
float	max_length
MeshAlignment	mesh_alignment	`1`
float	min_section_length	`0.2`
bool	pin_uv	`false`
TilingMode	tiling_mode	`1`
float	tiling_multiplier	`1.0`
float	width	`0.3`
Curve	width_curve

Methods

void	clear()
float	get_current_length() const

Enumerations

enum LimitMode: 🔗

LimitMode LIMIT_MODE_LIFETIME = 0

Limit the trail length in time.

LimitMode LIMIT_MODE_MAX_LENGTH = 1

Limit the trail length in size.

LimitMode LIMIT_MODE_MAX = 2

Represents the size of the LimitMode enum.

Property Descriptions

Color color = Color(1, 1, 1, 1) 🔗

void set_color(value: Color)
Color get_color()

The color of the trail.

Note: Colors with values above 1.0 (overbright) are not supported.

Note: To have a visible effect on a BaseMaterial3D, BaseMaterial3D.vertex_color_use_as_albedo must be true. For a ShaderMaterial, ALBEDO *= COLOR.rgb; must be inserted in the shader's fragment() function. Otherwise, color will have no visible effect.

Gradient color_gradient 🔗

void set_color_gradient(value: Gradient)
Gradient get_color_gradient()

The color gradient over the trail length.

Note: Colors with values above 1.0 (overbright) are not supported.

Note: To have a visible effect on a BaseMaterial3D, BaseMaterial3D.vertex_color_use_as_albedo must be true. For a ShaderMaterial, ALBEDO *= COLOR.rgb; must be inserted in the shader's fragment() function. Otherwise, color will have no visible effect.

bool emitting = true 🔗

void set_emitting(value: bool)
bool is_emitting()

If true, the trail will generate new points from its head.

Note: Only one active trail is supported. Setting this property to true will cause the existing trail mesh to be cleared.

float lifetime = 0.2 🔗

void set_lifetime(value: float)
float get_lifetime()

The lifetime of the trail when limit_mode is LIMIT_MODE_LIFETIME.

LimitMode limit_mode = 0 🔗

void set_limit_mode(value: LimitMode)
LimitMode get_limit_mode()

Whether to limit the trail by lifetime or length.

ShaderMaterial material 🔗

void set_material(value: ShaderMaterial)
ShaderMaterial get_material()

The material to assign to the trail mesh when material_mode is Line3D.MATERIAL_MODE_CUSTOM.

Tip: To preserve billboarding, use the following shader as a base:

shader_type spatial;
render_mode blend_mix, depth_draw_never, unshaded, skip_vertex_transform, cull_disabled;

void vertex() {
    // Billboarding code for trails
    // CUSTOM0 contains the tangent of the trail and the width.
    if (dot(CUSTOM0.xyz, CUSTOM0.xyz) > 0.0) {
        vec3 p = (inverse(MODELVIEW_MATRIX) * vec4(0.0, 0.0, 0.0, 1.0)).xyz;
        p = VERTEX - p;
        vec3 t = CUSTOM0.xyz;
        vec3 binormal = normalize(cross(p, t));
        vec3 normal = normalize(cross(t, binormal));
        vec3 tangent = normalize(cross(binormal, normal));
        VERTEX += CUSTOM0.w * binormal;
        NORMAL = normal;
        TANGENT = tangent;
        BINORMAL = binormal;
    }
}

void fragment() {
    ALBEDO = COLOR.rgb;
    ALPHA = COLOR.a;
}

MaterialMode material_mode = 0 🔗

void set_material_mode(value: MaterialMode)
MaterialMode get_material_mode()

The material mode for the trail.

float max_length 🔗

void set_max_length(value: float)
float get_max_length()

The maximum length of the trail when limit_mode is LIMIT_MODE_MAX_LENGTH.

MeshAlignment mesh_alignment = 1 🔗

void set_mesh_alignment(value: MeshAlignment)
MeshAlignment get_mesh_alignment()

Alignment of the trail. Possible options are Line3D.MESH_ALIGNMENT_LOCAL for a 3D line, and Line3D.MESH_ALIGNMENT_BILLBOARD for a billboarded line.

float min_section_length = 0.2 🔗

void set_min_section_length(value: float)
float get_min_section_length()

Minimum required distance before adding a new section.

bool pin_uv = false 🔗

void set_pin_uv(value: bool)
bool get_pin_uv()

If true, pins the UVs to their positions in space.

TilingMode tiling_mode = 1 🔗

void set_tiling_mode(value: TilingMode)
TilingMode get_tiling_mode()

How to tile the UVs across the length of the trail.

float tiling_multiplier = 1.0 🔗

void set_tiling_multiplier(value: float)
float get_tiling_multiplier()

UV multiplier across the length of the trail.

float width = 0.3 🔗

void set_width(value: float)
float get_width()

Width of the trail.

Curve width_curve 🔗

void set_width_curve(value: Curve)
Curve get_width_curve()

Width across the length of the trail.

Method Descriptions

void clear() 🔗

Clears the trail.

float get_current_length() const 🔗

Returns the current length of the trail.

User-contributed notes

Please read the User-contributed notes policy before submitting a comment.