Trail
The Trail object is used to create a trail like an effect between two points. As the points move through space a texture is drawn on the plane the points define. This is commonly used to create effects to help visualize movements like tracer trails behind projectiles, footprints, tire tracks, and many other similar effects.
When a Trail is active it will record the position of it's Trail.Attachment0 every frame. It then connects these positions to where the attachments were in the previous frame, creating a polygon. That polygon is then filled in with the Trail's Trail.Color and Trail.Texture (if that Texture exists). Each segment drawn in this way will eventually fade based on the TrailEffect's Trail.Lifetime.
Creating Trails
A Trail must be a descendant of the Workspace, and its attachment properties (Trail.Attachment0 and Trail.Attachment1) must be set to two unique Attachments. Once this has been done the effect will create a trail as soon as either of its attachments moves.
It is common practice to either store the Trail in the BasePart containing the effect's attachments, or as a child of a Folder in the Workspace with other effects objects.
Code Samples
1-- Create a new BasePart
2local part = Instance.new("Part")
3part.Parent = game.Workspace
4part.Anchored = true
5part.Position = Vector3.new(0, 5, 0)
6
7-- Create 2 attachments
8local attachment0 = Instance.new("Attachment")
9attachment0.Name = "Attachment0"
10attachment0.Parent = part
11attachment0.Position = Vector3.new(-2, 0, 0)
12
13local attachment1 = Instance.new("Attachment")
14attachment1.Name = "Attachment1"
15attachment1.Parent = part
16attachment1.Position = Vector3.new(2, 0, 0)
17
18-- Create a new Trail
19local trail = Instance.new("Trail")
20trail.Parent = part
21trail.Attachment0 = attachment0
22trail.Attachment1 = attachment1
23
24local color1 = Color3.fromRGB(15, 127, 254)
25local color2 = Color3.fromRGB(255, 255, 255)
26trail.Color = ColorSequence.new(color1, color2)
27
28-- Tween part to display trail
29local TweenService = game:GetService("TweenService")
30
31local dir = 15
32while true do
33 dir = dir * -1
34 local goal = {}
35 goal.Position = part.Position + Vector3.new(0, 0, dir)
36
37 local tweenInfo = TweenInfo.new(5)
38 local tween = TweenService:Create(part, tweenInfo, goal)
39 tween:Play()
40
41 task.wait(5)
42endSummary
Properties
Determines where the Trail will start drawing its segments.
Determines where the Trail will start drawing its segments.
Scales the light emitted from Trail when LightInfluence is 0.
The color of the trail segments throughout the lifetime of the trail.
If set to true, the trail textures will always face the camera.
Sets how much the colors of the trail are blended with the colors behind them.
Determines the factor to which the Trail is influenced by the environment's lighting.
Sets length of texture if Trail.TextureMode is Wrap or Static. If mode is Stretch sets number of times texture will repeat.
Sets how the Texture will be drawn.
Sets the transparency of the Trail's segments over the trail's Trail.Lifetime.
A NumberSequence that scales the width of the Trail over the course of its lifetime.
Events
Methods
Properties
Attachment0
A Trail starts drawing its segments at the positions of its Trail.Attachment0 and *Attachment1.
When the Trail is Trail.Enabled it will record the positions of its attachments every frame. It will connect these positions to the positions of the attachments on the previous frame. This creates a polygon that is then filled in by the Trail's Trail.Color and Trail.Texture (if that Texture exists).
When created a Trail will not have any Attachments set by default. These will need to be set in order for the effect to work.
Changing the Attachments of a Trail while a trail is drawing will remove all of the segments the trail has already drawn.
Attachment1
A Trail starts drawing its segments at the positions of its Attachment0 and Trail.Attachment1.
When the Trail is Trail.Enabled it will record the positions of its attachments every frame. It will connect these positions to the positions of the attachments on the previous frame. This creates a polygon that is then filled in by the Trail's Trail.Color and Trail.Texture (if that Texture exists).
When created a Trail will not have any Attachments set by default. These will need to be set in order for the effect to work.
Changing the Attachments of a Trail while a trail is drawing will remove all of the segments the trail has already drawn.
Brightness
Scales the light emitted from Trail. By default, this property is 1 and can set to any number within the range [0, 10000].
Increasing the value of LightInfluence decreases the effect of Brightness. Brightness doesn't have any effect when LightInfluence is 1.
Color
The color of a Trail can be set with the effect's Color property. This property determines what color the segments of the trail will have through their Trail.Lifetime.
Color is a ColorSequence, which means that the segments in a trail can shift between several colors. Note that if the color for a trail changes after some of the trail segments have been drawn, all of the old segments will be updated to match the new colors.
If a trail has a Trail.Texture then the Color property will tint that texture.
Any transparent components of a texture will not be tinted.
Enabled
The Enabled property determines whether a Trail will be drawn or not. This Enabled property defaults to true.
When enabled is true, the trail will create segments between the current position of its Trail.Attachment0 and the position of the attachments in the last frame.
If enabled is set to false while a trail is drawing no new segments will be drawn, but any existing segments will be cleaned up naturally when they reach the end of their Trail.Lifetime. If you would like to clean up any existing segments, you can use the Trail:Clear() function at the same time.
FaceCamera
The FaceCamera property determines whether the Trail is always drawn facing the camera. The default value is false.
If set to true, the trail textures will always face the camera. If set to false, the texture will be drawn in the direction of the distance between the trail's Trail.Attachment0 and Trail.Attachment1.
Note that changing this property immediately affects all existing and future trail segments. This means that all existing and new segments will adjust to face the player's camera or the direction of the attachments according to the property's new state.
FaceCamera Enabled
FaceCamera Disabled
Lifetime
The Lifetime property determines how long each segment in its Trail will last in seconds. Once a segment is drawn, it will wait for the given lifetime (measured in seconds) and then will disappear. The lifetime property defaults to 2 seconds, but can be set anywhere between 0.01 and 20.
The lifetime of a trail is also used by that effect's Trail.Color and Trail.Transparency properties to determine how each segment is drawn. Both of these properties are sequences, meaning that they define their values at certain keypoints in the segement's lifetime and then interpolate between the values as the segment ages.
If a trail's lifetime changes while there are still segments that the trail has drawn, these segments will immediately behave as if they always had the new lifetime. This means that if they have existed for longer than the lifetime they will be removed immediately.
LightEmission
The LightEmission Trail property sets how much the Colors of the trail are blended with the colors behind them. LightEmission uses additive blending to combine the colors, meaning the RGB values of the colors are added together to determine the displayed color. This addition is weighted by the value of LightEmission.
When changed this property instantly affects all particles owned by the emitter, both current and future particles.
This property is not related to the dynamic lighting engine of Roblox. If you need your trail to emit light, it is recommended to create parts with PointLight that follow the path of the trail.
LightInfluence
LightInfluence determines the factor the light in the environment affects the appearance of the Trail. A value of zero (0) ensures no influence which allows a trail to be visible even in complete darkness.
Changing this property immediately affects all existing and future segments of the trail.
See also:
- LightEmission, another Trail property related to light
- Beam.LightEmission, an identical property used by Beams
MaxLength
The MinLength of a Trail determines the maximum length of each of the segments in the trail.
Note that changing MaxLength will only affect new segments that are drawn – any old segments that have already been drawn will maintain their current length.
This value can be any number greater than or equal to 0, and defaults to 0. If the property is set to 0, the maximum length will be infinity - meaning that the trail will not have a maximum length.
Please note that, even if this property is 0, or another large number, the trail is still constrained by its Trail.Lifetime. Old segments will be erased if they reach the end of their lifetime, even if the trail is shorter than the maximum length. Be sure to set both properties fittingly.
This property can also be used alongside the Trail.MinLength property, which determines the minimum length trail must before before it is drawn.
MinLength
The MinLength of a Trail determines the minimum length of each of the segments in the trail.
If neither of the trail's Trail.Attachment0 or Trail.Attachment1 have moved at least the minimum length in studs, then no new segments will be created and the endpoints of the current segment will be moved to the current position of the attachments.
Note that changing MinLength will only affect new segments that are drawn – any old segments that have already been drawn will maintain their current length.
This value can be any number greater than or equal to 0, and defaults to 0.1.
This property can also be used alongside the Trail.MaxLength property, which determines the maximum length trail may be before its oldest segments are erased.
Texture
The Texture property is the texture to draw on a Trail's segments. This property sets which image asset to use for the texture. This is set the same way as textures in other objects, such as ImageLabel or ParticleEmitter. The simplest way to set this property is to use an image uploaded to the Asset Manager (this requires the current place to be Published to Roblox).
If a texture is not provided, then just the Trail.Color of the Trail will be used. With a texture, the trail will draw the texture as its attachments move.
Textures can be displayed in a variety of different ways based on the trail's Trail.TextureMode and Trail.TextureLength properties.
TextureLength
This property determines how Trail.Textures are drawn by Trail. The behavior of TextureLength is determined by the Trail.TextureMode of its trail.
If the TextureLength is changed after its trail has drawn some of its segments, the new length will only be applied to new segments being drawn -- old segments will be unaffected.
This value can be any number greater than 0 and defaults to 1.
TextureMode
A Trail's TextureMode property determines how the effect's Trail.Texture (if any) is drawn. The behavior of the texture in each mode is also very much dependent on the effect's Trail.TextureLength property. Note that changing an effect's TextureMode after some of the trail has been drawn will affect all of the previously drawn segments.
TextureMode defaults to Stretch.
Stretch
Stretch is the default TextureMode for Trails. In this mode the texture will be tiled a number of times equal to the number defined by TextureLength. It will stretch these tiles evenly to fit the entire length of the drawn trail. For example, if TextureLength is set to 4 then the texture will always repeat 4 times in the trail, no matter how long or short the trail is.
Wrap
In the Wrap mode, the texture will start at the attachment points and will move as the attachments move. As soon as the attachments have moved a number of studs equal to the TextureLength, then the texture will repeat. The longer the trail is, the more times the texture will repeat.
Static
In the Static mode, the texture will start at the initial position of the trail and will be drawn as the attachments move. Once the attachments move a number of studs equal to the TextureLength, then the texture will repeat.
Transparency
The Transparency property of a Trail sets how transparent the segments of the trail are over the trail's Trail.Lifetime. This value is a NumberSequence, meaning it can be a static value or can change throughout the lifetime of the trail segments.
The values in the NumberSequence can be any number, but the effective range of transparency is 0 (completely opaque) to 1 (completely see-through). The Transparency property for TrailEffects defaults to 0.5.
WidthScale
The WidthScale property is a NumberSequence that scales the width of the Trail over the course of its lifetime.
This property can range from 0 to 1. The value of the property influences the width of the trail by setting the trail's width to the product of:
For example, if the trail's attachments are 2 stud's apart, and the value of this property is 0.5, the trail's width will be 1 stud and the trail will be centered in between the two attachments.
If you would like to hide the trail entirely, consider setting Trail.Enabled to false.
Events
Methods
Clear
The Clear function clears the segments of the Trail. This means that any trail that has been drawn will be erased when this function is called, even if that segment's Trail.Lifetime duration has not yet been reached.
While this is less noticeable for trails with shorter lifetimes, this is useful when cleaning up trails that have a longer lifetime, or for cases where the trail is removed when a certain game action occurs.
Calling this function will only affect old segments that have already been done. It will not affect the drawing of any new trail segments after this function call. If you would like to clear existing trail segments, and temporarily prevent new segments from being drawn, consider toggling the trail's Trail.Enabled property to false at the same time.
Returns
Code Samples
1-- The function that tweens the part back and forth 15 studs
2local DISTANCE = 15
3local TweenService = game:GetService("TweenService")
4
5local function tweenPart(part)
6 DISTANCE *= -1
7 local goal = {}
8 goal.Position = part.Position + Vector3.new(0, 0, DISTANCE)
9
10 local tweenInfo = TweenInfo.new(5)
11 local tween = TweenService:Create(part, tweenInfo, goal)
12 tween:Play()
13
14 task.wait(5)
15end
16
17-- Create a new BasePart
18local part = Instance.new("Part")
19part.Parent = game.Workspace
20part.Anchored = true
21part.Position = Vector3.new(0, 5, 0)
22
23-- Create 2 attachments
24local attachment0 = Instance.new("Attachment")
25attachment0.Name = "Attachment0"
26attachment0.Parent = part
27attachment0.Position = Vector3.new(-2, 0, 0)
28
29local attachment1 = Instance.new("Attachment")
30attachment1.Name = "Attachment1"
31attachment1.Parent = part
32attachment1.Position = Vector3.new(2, 0, 0)
33
34-- Create a new Trail
35local trail = Instance.new("Trail")
36trail.Parent = part
37trail.Attachment0 = attachment0
38trail.Attachment1 = attachment1
39local color1 = Color3.fromRGB(15, 127, 254)
40local color2 = Color3.fromRGB(255, 255, 255)
41trail.Color = ColorSequence.new(color1, color2)
42
43-- Tween part, clear trail segments, and toggle trail between enabled/disabled
44while true do
45 tweenPart(part)
46 trail:Clear()
47 trail.Enabled = not trail.Enabled
48end