Scripting Support (C#)

advanced scripting

Trails FX · Scripting Support (C#)

Class: All members on this page belong to the TrailEffect component (namespace TrailsFX). Access via GetComponent<TrailEffect>().

Tip: Trails FX supports profiles for saving/loading configurations. Check the demo scenes for practical usage examples.

Getting Started

Add the namespace and get a reference to the component:

using TrailsFX;

TrailEffect trail = GetComponent<TrailEffect>();

Core Properties

bool active

IncludedTarget[] include

Execution

bool executeInEditMode

Enable trail generation in the Unity Editor (edit mode).

int ignoreFrames

Number of initial frames to skip before starting trail generation.

Array of additional targets to include in trail generation.

bool combineMeshesWithChildren

Combine meshes with children renderers into a single trail.

Enable or disable trail generation.

TrailStyle effect

Visual style of the trail: Color, TextureStamp, Clone, Outline, SpaceDistortion, Dash, or Custom.

float duration

Duration of the trail effect in seconds. Default: 0.5.

bool continuous

Generate trails continuously (useful for persistent motion trails).

Transform target

Target renderer to create trails from. If null, uses the object's own renderer.

TrailEffectProfile profile

Trail effect profile asset for preset configurations.

bool profileSync

Automatically sync settings when the profile changes.

Trail Triggering Conditions

bool checkWorldPosition

PositionChangeRelative worldPositionRelativeOption

Position change reference: World or OtherTransform.

Transform worldPositionRelativeTransform

Reference transform for relative position change detection.

Trigger trail snapshots when the object moves in world space.

float minDistance

Minimum world-space distance to trigger a new snapshot. Default: 0.1.

bool checkScreenPosition

Trigger snapshots when the object moves on screen. Default: true.

int minPixelDistance

Minimum pixel distance to trigger a new snapshot. Default: 10.

bool checkTime

Trigger snapshots based on a time interval.

float timeInterval

Time in seconds between snapshots when checkTime is enabled.

bool checkCollisions

Trigger trail snapshots on collision detection.

LayerMask collisionLayerMask

Layer mask for collision-based trail triggering.

Mask & Stencil

Texture2D mask

Mask texture for limiting trail generation to specific areas.

bool clearStencil

Clear the stencil buffer before rendering the trail.

bool hierarchyOccluder

Enable hierarchy-based occlusion for trail rendering.

Transform hierarchyOccluderRoot

Root transform for hierarchy occluder detection.

LayerMask hierarchyOccluderLayerMask

Layer mask for hierarchy occluder detection.

bool hierarchyIncludeInactive

Include inactive GameObjects in hierarchy occluder detection. Default: true.

Color & Appearance

Color color

bool colorCycleLoop

Loop the color cycle animation. Default: true.

float pingPongSpeed

Speed of the ping-pong color animation. Default: 1.

bool colorRamp

Enable color ramp based on world-space position.

Texture2D colorRampTexture

Texture used for color ramp sampling.

Transform colorRampStart

Start transform for color ramp world-space mapping.

Transform colorRampEnd

End transform for color ramp world-space mapping.

Base trail color.

Gradient colorOverTime

Color progression over the trail lifetime.

ColorSequence colorSequence

Color mode: Fixed, Cycle, PingPong, Random, or FixedRandom.

Gradient colorStartPalette

Palette gradient used for color sequences.

float colorCycleDuration

Duration of one full color cycle in seconds.

bool fadeOut

Fade trail alpha over time. Default: true.

Texture2D texture

Texture used for the trail (for TextureStamp style).

float textureCutOff

Alpha cutoff threshold for texture (0–1). Default: 0.25.

Color trailTint

Tint color used for the SpaceDistortion effect.

Scale & Position

Vector3 scale

Vector3 scaleStartRandomMin

Minimum random scale applied to new trail snapshots. Default: Vector3.one.

Vector3 scaleStartRandomMax

Maximum random scale applied to new trail snapshots. Default: Vector3.one.

bool ignoreTransformScale

Ignore the object's transform scale when generating trail snapshots.

Base scale of the trail snapshots.

AnimationCurve scaleOverTime

Scale progression over the trail lifetime.

bool scaleUniform

Apply uniform scaling to all axes.

Vector3 localPositionRandomMin

Minimum random local position offset per snapshot.

Vector3 localPositionRandomMax

Maximum random local position offset per snapshot.

Transform lookTarget

Target transform that trail snapshots orient toward.

bool lookToCamera

Orient trail snapshots toward the camera. Default: true.

Surface & Ground Alignment

bool ground

Snap trail to the ground surface.

bool orientToSurface

Orient trail snapshots to match the surface normal. Default: true.

float surfaceOffset

Offset from the surface to prevent z-fighting. Default: 0.05.

Smoothing & Performance

bool smooth

Create smooth trails with interpolated steps.

int maxStepsPerFrame

Maximum trail snapshots per frame. Default: 12.

int stepsBufferSize

Total trail buffer capacity. Default: 1023.

int maxBatches

Maximum render batches. Default: 50.

int meshPoolSize

Pool size for dynamically allocated meshes. Default: 256.

Rendering

TrailRenderOrder renderOrder

CullMode cullMode

Face culling mode for trail rendering. Default: Back.

int subMeshMask

Bitmask for sub-mesh selection (-1 = all sub-meshes). Default: -1.

Camera cam

Camera used for trail rendering. If null, uses the main camera.

Render order: BeforeObject, DrawBehind (default), or AlwaysOnTop.

bool ignoreVisibility

Generate trails even when the renderer is not visible.

Material customMaterial

Custom material used when effect is set to TrailStyle.Custom.

bool cameraDistanceFade

Fade trail based on camera distance.

float cameraDistanceFadeNear

Near fade distance.

float cameraDistanceFadeFar

Far fade distance. Default: 1000.

Laser / Dash Effect

float laserBandWidth

Width of the laser band. Default: 0.1.

float laserIntensity

Laser intensity multiplier. Default: 20.

float laserFlash

Laser flash duration. Default: 0.2.

Outline Effect Settings

OutlineMethod outlineMethod

Outline detection: Normals or Rim.

float normalThreshold

Normal threshold for outline detection (0–1). Default: 0.3.

float rimPower

Rim lighting power for rim-based outlines. Default: 2.

Animation State Filtering

Animator animator

Animator component for animation-state-based trail filtering.

string animationStates

Comma-separated animation state names. Supports time ranges: "Attack(0.1-1.5)".

bool useLastAnimationState

Use only the last animation frame for the trail.

Other Settings

Transform parent

Parent transform for trail snapshots. If set, trail snapshots are parented to this transform.

bool preserveMultiMaterials

Preserve multiple materials on cloned trail meshes.

bool interpolate

Enable interpolation between trail snapshots for smoother trails.

Methods

void Clear()

void CheckEditorSettings()

Validates and updates editor-specific settings. Call after changing properties that affect editor preview.

void RefreshHierarchyOccluders()

Refreshes the hierarchy occluder cache. Call after modifying hierarchy occluder settings at runtime.

Clears the current trail and restarts the cycle.

void Restart()

Restarts the trail cycle but keeps existing trail snapshots visible.

void Refresh()

Refreshes internal caches (children renderers, hierarchy occluders). Call after modifying included targets at runtime.

void UpdateMaterialProperties()

Updates all material properties. Call after changing visual properties via script.

void SetProfile(TrailEffectProfile profile)

Loads and applies a different trail profile.

Vector3 GetTrailPosition(int index)

Returns the world-space position of a trail snapshot at the given index.

index: Index of the trail snapshot (0 to stepsBufferSize-1).

Enums Reference

TrailStyle

PositionChangeRelative

World, OtherTransform

Color, TextureStamp, Clone, Outline, SpaceDistortion, Dash, Custom

ColorSequence

Fixed, Cycle, PingPong, Random, FixedRandom

TrailRenderOrder

BeforeObject, DrawBehind, AlwaysOnTop

OutlineMethod

Normals, Rim

Code Examples

using UnityEngine;
using TrailsFX;

public class TrailDemo : MonoBehaviour {
    TrailEffect trail;

    void Start() {
        trail = GetComponent<TrailEffect>();

        // Configure a color trail
        trail.effect = TrailStyle.Color;
        trail.color = Color.cyan;
        trail.duration = 0.8f;
        trail.fadeOut = true;

        // Trigger on world-space movement
        trail.checkWorldPosition = true;
        trail.minDistance = 0.05f;

        // Enable continuous generation
        trail.continuous = true;

        // Start the trail
        trail.active = true;
    }

    void ResetTrail() {
        // Clear all visible trail snapshots
        trail.Clear();
    }
}

// Clone-based trail with animation filtering
public class CloneTrailDemo : MonoBehaviour {
    void Start() {
        var trail = GetComponent<TrailEffect>();
        trail.effect = TrailStyle.Clone;
        trail.duration = 1.0f;

        // Only generate trail during "Attack" animation
        trail.animator = GetComponent<Animator>();
        trail.animationStates = "Attack(0.1-0.9)";

        trail.active = true;
    }
}

Was this page helpful? |