mirror of
https://github.com/rojo-rbx/rojo.git
synced 2026-10-23 22:11:38 +00:00
536 lines
18 KiB
YAML
536 lines
18 KiB
YAML
# This file is automatically generated. Please don't edit it manually.
|
|
# To submit a bug report on the content, see
|
|
# https://devforum.roblox.com/c/bug-reports/documentation-issues/72
|
|
|
|
name: Trail
|
|
type: class
|
|
memory_category: Instances
|
|
summary: |
|
|
Used to create a trail effect between two attachments.
|
|
description: |
|
|
The **Trail** object is used to create a trail effect between two attachments.
|
|
As the attachments move through space, a texture is drawn on their defined
|
|
plane. This is commonly used to create effects that visualize movements like
|
|
tracer trails behind projectiles, footprints, tire tracks, and similar
|
|
effects.
|
|
|
|
See [Trails](../../../effects/trails.md) for more information.
|
|
code_samples:
|
|
- creating-a-part-with-a-basic-trail
|
|
inherits:
|
|
- Instance
|
|
descendants: []
|
|
tags: []
|
|
deprecation_message: ''
|
|
properties:
|
|
- name: Trail.Attachment0
|
|
summary: |
|
|
Along with `Class.Trail.Attachment1|Attachment1`, determines where the
|
|
trail will start drawing its segments.
|
|
description: |
|
|
A `Class.Trail` starts drawing its segments at the positions of its
|
|
**Attachment0** and `Class.Trail.Attachment1|Attachment1`. When the trail
|
|
is `Class.Trail.Enabled|Enabled`, it records the positions of its
|
|
attachments every frame and connects these positions to the attachments'
|
|
positions on the previous frame, creating a polygon that is then filled in
|
|
by the trail's `Class.Trail.Color|Color` and
|
|
`Class.Trail.Texture|Texture`.
|
|
|
|
Changing the attachments of a trail while a trail is drawing will remove
|
|
all of the segments the trail has already drawn.
|
|
code_samples: []
|
|
type: Attachment
|
|
tags: []
|
|
deprecation_message: ''
|
|
security:
|
|
read: None
|
|
write: None
|
|
thread_safety: ReadSafe
|
|
category: Data
|
|
serialization:
|
|
can_load: true
|
|
can_save: true
|
|
capabilities:
|
|
- Basic
|
|
- name: Trail.Attachment1
|
|
summary: |
|
|
Along with `Class.Trail.Attachment0|Attachment0`, determines where the
|
|
trail will start drawing its segments.
|
|
description: |
|
|
A `Class.Trail` starts drawing its segments at the positions of its
|
|
`Class.Trail.Attachment0|Attachment0` and **Attachment1**. When the trail
|
|
is `Class.Trail.Enabled|Enabled`, it records the positions of its
|
|
attachments every frame and connects these positions to the attachments'
|
|
positions on the previous frame, creating a polygon that is then filled in
|
|
by the trail's `Class.Trail.Color|Color` and
|
|
`Class.Trail.Texture|Texture`.
|
|
|
|
Changing the attachments of a trail while a trail is drawing will remove
|
|
all of the segments the trail has already drawn.
|
|
code_samples: []
|
|
type: Attachment
|
|
tags: []
|
|
deprecation_message: ''
|
|
security:
|
|
read: None
|
|
write: None
|
|
thread_safety: ReadSafe
|
|
category: Data
|
|
serialization:
|
|
can_load: true
|
|
can_save: true
|
|
capabilities:
|
|
- Basic
|
|
- name: Trail.Brightness
|
|
summary: |
|
|
Scales the light emitted from the trail when
|
|
`Class.Trail.LightInfluence|LightInfluence` is less than 1.
|
|
description: |
|
|
Scales the light emitted from the trail when
|
|
`Class.Trail.LightInfluence|LightInfluence` is less than 1. This property
|
|
is 1 by default and can set to any number within the range of 0 to 10000.
|
|
Increasing the value of `Class.Trail.LightInfluence|LightInfluence`
|
|
decreases the effect of this property's value.
|
|
code_samples: []
|
|
type: float
|
|
tags: []
|
|
deprecation_message: ''
|
|
security:
|
|
read: None
|
|
write: None
|
|
thread_safety: ReadSafe
|
|
category: Appearance
|
|
serialization:
|
|
can_load: true
|
|
can_save: true
|
|
capabilities:
|
|
- Basic
|
|
- name: Trail.Color
|
|
summary: |
|
|
The color of the trail throughout its lifetime.
|
|
description: |
|
|
Determines the color of the trail throughout its lifetime. If
|
|
`Class.Trail.Texture|Texture` is set, this color will tint the texture.
|
|
|
|
This property is a `Datatype.ColorSequence`, allowing the color to be
|
|
configured to vary across the length of the trail. If the color changes
|
|
after some of the trail segments have been drawn, all of the old segments
|
|
will be updated to match the new colors.
|
|
code_samples:
|
|
- creating-a-trail-with-a-color-gradient
|
|
type: ColorSequence
|
|
tags: []
|
|
deprecation_message: ''
|
|
security:
|
|
read: None
|
|
write: None
|
|
thread_safety: ReadSafe
|
|
category: Appearance
|
|
serialization:
|
|
can_load: true
|
|
can_save: true
|
|
capabilities:
|
|
- Basic
|
|
- name: Trail.Enabled
|
|
summary: |
|
|
Determines whether the trail will be drawn or not.
|
|
description: |
|
|
This property determines whether the trail will be drawn or not.
|
|
|
|
If 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 `Class.Trail.Lifetime|Lifetime`. To forcibly clean up
|
|
existing segments, call the `Class.Trail:Clear()|Clear()` method at the
|
|
same time.
|
|
code_samples: []
|
|
type: boolean
|
|
tags: []
|
|
deprecation_message: ''
|
|
security:
|
|
read: None
|
|
write: None
|
|
thread_safety: ReadSafe
|
|
category: Emission
|
|
serialization:
|
|
can_load: true
|
|
can_save: true
|
|
capabilities:
|
|
- Basic
|
|
- name: Trail.FaceCamera
|
|
summary: |
|
|
Determines whether the trail will always face the camera, regardless of
|
|
its orientation.
|
|
description: |
|
|
A `Class.Trail` is a 2D projection existing in 3D space, meaning that it
|
|
may not be visible from every angle. The **FaceCamera** property, when set
|
|
to `true`, ensures that the trail always faces the
|
|
`Class.Workspace.CurrentCamera|CurrentCamera`, regardless of its
|
|
orientation.
|
|
|
|
Changing this property immediately affects all existing and future trail
|
|
segments.
|
|
code_samples: []
|
|
type: boolean
|
|
tags: []
|
|
deprecation_message: ''
|
|
security:
|
|
read: None
|
|
write: None
|
|
thread_safety: ReadSafe
|
|
category: Appearance
|
|
serialization:
|
|
can_load: true
|
|
can_save: true
|
|
capabilities:
|
|
- Basic
|
|
- name: Trail.Lifetime
|
|
summary: |
|
|
Determines how long each segment in a trail will last, in seconds.
|
|
description: |
|
|
The **Lifetime** property determines how long each segment in a trail will
|
|
last, in seconds, before it disappears. 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
|
|
`Class.Trail.Color|Color` and `Class.Trail.Transparency|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 segment's lifetime and then interpolate between the
|
|
values as the segment ages.
|
|
|
|
If a trail's lifetime changes, existing segments will immediately behave
|
|
as if they always had the new lifetime, meaning that if they've existed
|
|
for longer than the new lifetime, they will be removed immediately.
|
|
code_samples: []
|
|
type: float
|
|
tags: []
|
|
deprecation_message: ''
|
|
security:
|
|
read: None
|
|
write: None
|
|
thread_safety: ReadSafe
|
|
category: Emission
|
|
serialization:
|
|
can_load: true
|
|
can_save: true
|
|
capabilities:
|
|
- Basic
|
|
- name: Trail.LightEmission
|
|
summary: |
|
|
Determines to what degree the colors of the trail are blended with the
|
|
colors behind it.
|
|
description: |
|
|
Determines to what degree the colors of the trail are blended with the
|
|
colors behind it. It should be set in the range of 0 to 1. A value of 0
|
|
uses normal blending modes and a value of 1 uses additive blending.
|
|
|
|
This property should not be confused with
|
|
`Class.Trail.LightInfluence|LightInfluence` which determines how the trail
|
|
is affected by environmental light.
|
|
|
|
Changing this property immediately affects all existing and future
|
|
segments of the trail.
|
|
|
|
This property does **not** cause the trail to light the environment.
|
|
code_samples: []
|
|
type: float
|
|
tags: []
|
|
deprecation_message: ''
|
|
security:
|
|
read: None
|
|
write: None
|
|
thread_safety: ReadSafe
|
|
category: Appearance
|
|
serialization:
|
|
can_load: true
|
|
can_save: true
|
|
capabilities:
|
|
- Basic
|
|
- name: Trail.LightInfluence
|
|
summary: |
|
|
Determines the degree to which the trail is influenced by the
|
|
environment's lighting.
|
|
description: |
|
|
Determines the degree to which the trail is influenced by the
|
|
environment's lighting, clamped between 0 and 1. When 0, the trail will be
|
|
unaffected by the environment's lighting. When 1, it will be fully
|
|
affected by lighting as a `Class.BasePart` would be.
|
|
|
|
Changing this property immediately affects all existing and future
|
|
segments of the trail.
|
|
|
|
See also `Class.Trail.LightEmission|LightEmission` which specifies to what
|
|
degree the colors of the trail are blended with the colors behind it.
|
|
code_samples: []
|
|
type: float
|
|
tags: []
|
|
deprecation_message: ''
|
|
security:
|
|
read: None
|
|
write: None
|
|
thread_safety: ReadSafe
|
|
category: Appearance
|
|
serialization:
|
|
can_load: true
|
|
can_save: true
|
|
capabilities:
|
|
- Basic
|
|
- name: Trail.LocalTransparencyModifier
|
|
summary: ''
|
|
description: ''
|
|
code_samples: []
|
|
type: float
|
|
tags:
|
|
- Hidden
|
|
- NotReplicated
|
|
deprecation_message: ''
|
|
security:
|
|
read: None
|
|
write: None
|
|
thread_safety: ReadSafe
|
|
category: Appearance
|
|
serialization:
|
|
can_load: false
|
|
can_save: false
|
|
capabilities:
|
|
- Basic
|
|
- name: Trail.MaxLength
|
|
summary: |
|
|
Sets the maximum length of the trail.
|
|
description: |
|
|
This property determines the maximum length of the trail, in studs. Its
|
|
value defaults to 0, meaning that the trail will not have a maximum length
|
|
and trail segments will expire in their `Class.Trail.Lifetime|Lifetime`.
|
|
|
|
This property can be used alongside the `Class.Trail.MinLength|MinLength`
|
|
property which determines the minimum length a trail must be before it's
|
|
drawn.
|
|
code_samples: []
|
|
type: float
|
|
tags: []
|
|
deprecation_message: ''
|
|
security:
|
|
read: None
|
|
write: None
|
|
thread_safety: ReadSafe
|
|
category: Emission
|
|
serialization:
|
|
can_load: true
|
|
can_save: true
|
|
capabilities:
|
|
- Basic
|
|
- name: Trail.MinLength
|
|
summary: |
|
|
Sets the minimum length of the trail.
|
|
description: |
|
|
This property determines the minimum length of the trail, in studs. If
|
|
neither of the trail's attachments have moved at least this value, 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 this property will only affect **new** segments that
|
|
are drawn; any old segments that have already been drawn will maintain
|
|
their current length.
|
|
|
|
This property can be used alongside the `Class.Trail.MaxLength|MaxLength`
|
|
property which determines the maximum trail length before its oldest
|
|
segments are erased.
|
|
code_samples: []
|
|
type: float
|
|
tags: []
|
|
deprecation_message: ''
|
|
security:
|
|
read: None
|
|
write: None
|
|
thread_safety: ReadSafe
|
|
category: Emission
|
|
serialization:
|
|
can_load: true
|
|
can_save: true
|
|
capabilities:
|
|
- Basic
|
|
- name: Trail.Texture
|
|
summary: |
|
|
The content ID of the texture to be displayed on the trail.
|
|
description: |
|
|
The content ID of the texture to be displayed on the trail. If this
|
|
property is not set, the trail will be displayed as a solid plane; this
|
|
also occurs when the texture is set to an invalid content ID or the image
|
|
associated with the texture has not yet loaded.
|
|
|
|
The appearance of the texture can be further modified by other trail
|
|
properties including `Class.Trail.Color|Color` and
|
|
`Class.Trail.Transparency|Transparency`.
|
|
|
|
Scaling of the texture is determined by the distance between
|
|
`Class.Trail.Attachment0|Attachment0` and
|
|
`Class.Trail.Attachment1|Attachment1`, as well as the
|
|
`Class.Trail.TextureMode|TextureMode`,
|
|
`Class.Trail.TextureLength|TextureLength`, and
|
|
`Class.Trail.WidthScale|WidthScale` properties.
|
|
code_samples:
|
|
- creating-a-trail-with-a-pawprint-texture
|
|
type: ContentId
|
|
tags: []
|
|
deprecation_message: ''
|
|
security:
|
|
read: None
|
|
write: None
|
|
thread_safety: ReadSafe
|
|
category: Appearance
|
|
serialization:
|
|
can_load: true
|
|
can_save: true
|
|
capabilities:
|
|
- Basic
|
|
- name: Trail.TextureLength
|
|
summary: |
|
|
Sets the length of the trail's texture, dependent on
|
|
`Class.Trail.TextureMode|TextureMode`.
|
|
description: |
|
|
Sets the length of the trail's texture, dependent on
|
|
`Class.Trail.TextureMode|TextureMode`. Changing this property immediately
|
|
affects all existing and future trail segments.
|
|
code_samples: []
|
|
type: float
|
|
tags: []
|
|
deprecation_message: ''
|
|
security:
|
|
read: None
|
|
write: None
|
|
thread_safety: ReadSafe
|
|
category: Appearance
|
|
serialization:
|
|
can_load: true
|
|
can_save: true
|
|
capabilities:
|
|
- Basic
|
|
- name: Trail.TextureMode
|
|
summary: |
|
|
Determines the manner in which the `Class.Trail.Texture|Texture` scales,
|
|
repeats, and moves along with the trail's attachments.
|
|
description: |
|
|
This property, alongside `Class.Trail.TextureLength|TextureLength`,
|
|
determines how a trail's `Class.Trail.Texture|Texture` scales, repeats,
|
|
and moves along with the trail's attachments. Changing this property
|
|
immediately affects all existing and future trail segments.
|
|
|
|
#### Scale and Repetition
|
|
|
|
When **TextureMode** is set to `Enum.TextureMode.Wrap` or
|
|
`Enum.TextureMode.Static`, the `Class.Trail.TextureLength|TextureLength`
|
|
property sets the length of the texture as it repeats across the trail's
|
|
length.
|
|
|
|
<img src="/assets/engine-api/enums/TextureMode/Wrap-Static.png" width="720" alt="TextureMode diagram with Wrap mode" />
|
|
|
|
When **TextureMode** is set to `Enum.TextureMode.Stretch`, the texture
|
|
will repeat `Class.Trail.TextureLength|TextureLength` times across the
|
|
trail's overall length.
|
|
|
|
<img src="/assets/engine-api/enums/TextureMode/Stretch.png" width="720" alt="TextureMode diagram with Stretch mode" />
|
|
|
|
#### Movement
|
|
|
|
The **TextureMode** property also affects the **movement** of the trail's
|
|
texture as follows:
|
|
|
|
- If set to `Enum.TextureMode.Stretch`, the texture will stretch out based
|
|
on the lifetime of the trail, and shrink inwards if the trail's
|
|
attachments stop moving.
|
|
|
|
- If set to `Enum.TextureMode.Wrap`, the texture will be tiled as the
|
|
length of the trail changes, but the textures will remain stationary
|
|
relative to their attachments.
|
|
|
|
- If set to `Enum.TextureMode.Static`, the texture will be rolled out as
|
|
the attachments move, and they will remain in place until their lifetime
|
|
is met. This setting is ideal for trail textures that should appear
|
|
"stamped" where rendered, such as paw prints or tire tracks.
|
|
code_samples: []
|
|
type: TextureMode
|
|
tags: []
|
|
deprecation_message: ''
|
|
security:
|
|
read: None
|
|
write: None
|
|
thread_safety: ReadSafe
|
|
category: Appearance
|
|
serialization:
|
|
can_load: true
|
|
can_save: true
|
|
capabilities:
|
|
- Basic
|
|
- name: Trail.Transparency
|
|
summary: |
|
|
Sets the transparency of the trail's segments over its
|
|
`Class.Trail.Lifetime|Lifetime`.
|
|
description: |
|
|
Sets the transparency of the trail's segments over its
|
|
`Class.Trail.Lifetime|Lifetime`. This value is a
|
|
`Datatype.NumberSequence`, meaning it can be a static value or can change
|
|
throughout the lifetime of the trail segments.
|
|
code_samples: []
|
|
type: NumberSequence
|
|
tags: []
|
|
deprecation_message: ''
|
|
security:
|
|
read: None
|
|
write: None
|
|
thread_safety: ReadSafe
|
|
category: Appearance
|
|
serialization:
|
|
can_load: true
|
|
can_save: true
|
|
capabilities:
|
|
- Basic
|
|
- name: Trail.WidthScale
|
|
summary: |
|
|
Scales the width of the trail over the course of its lifetime.
|
|
description: |
|
|
This property is a `Datatype.NumberSequence` that scales the width of the
|
|
trail over the course of its lifetime. Values can range between 0 and 1,
|
|
acting as a multiplier on the distance between the trail's attachments.
|
|
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 between the two attachments.
|
|
code_samples: []
|
|
type: NumberSequence
|
|
tags: []
|
|
deprecation_message: ''
|
|
security:
|
|
read: None
|
|
write: None
|
|
thread_safety: ReadSafe
|
|
category: Emission
|
|
serialization:
|
|
can_load: true
|
|
can_save: true
|
|
capabilities:
|
|
- Basic
|
|
methods:
|
|
- name: Trail:Clear
|
|
summary: |
|
|
Clears the segments of the trail.
|
|
description: |
|
|
This method immediately clears all segments of the trail and is useful for
|
|
cleaning up trails with longer lifetimes or for cases where the trail
|
|
should be removed because of a specific action.
|
|
|
|
Calling this method only affects existing segments. To clear existing
|
|
trail segments **and** temporarily prevent new segments from being drawn,
|
|
toggle the trail's `Class.Trail.Enabled|Enabled` property to `false` at
|
|
the same time.
|
|
code_samples: []
|
|
parameters: []
|
|
returns:
|
|
- type: ()
|
|
summary: ''
|
|
tags: []
|
|
deprecation_message: ''
|
|
security: None
|
|
thread_safety: Unsafe
|
|
capabilities:
|
|
- Basic
|
|
events: []
|
|
callbacks: []
|