# 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: Beam
type: class
memory_category: Instances
summary: |
Connects two `Class.Attachment|Attachments` by drawing a texture between them.
description: |
A **Beam** object connects two `Class.Attachment|Attachments` by drawing a
texture between them.
To display, a beam must be a descendant of the `Class.Workspace` with its
`Class.Beam.Attachment0|Attachment0` and `Class.Beam.Attachment1|Attachment1`
properties set to `Class.Attachment|Attachments` also descending from the
`Class.Workspace`.
The beam's appearance can be customized using the range of properties outlined
below. Also see the [Beams](../../../effects/beams.md) guide for visual
examples.
#### Beam Curvature
Beams are configured to use a cubic Bézier curve formed by four control
points. This means they are not constrained to straight lines and the curve of
the beam can be modified by changing `Class.Beam.CurveSize0|CurveSize0`,
`Class.Beam.CurveSize1|CurveSize1`, and the orientation of the beam's
`Class.Attachment|Attachments`.
- **P0** — The start of the beam; position of
`Class.Beam.Attachment0|Attachment0`.
- **P1** — `Class.Beam.CurveSize0|CurveSize0` studs away from
`Class.Beam.Attachment0|Attachment0`, in the positive **X** direction of
`Class.Beam.Attachment0|Attachment0`.
- **P2** — `Class.Beam.CurveSize1|CurveSize1` studs away from
`Class.Beam.Attachment1|Attachment1`, in the negative **X** direction of
`Class.Beam.Attachment1|Attachment1`.
- **P3** — The end of the beam; position of
`Class.Beam.Attachment1|Attachment1`
code_samples:
- Creating-a-Beam-From-Scratch
inherits:
- Instance
descendants: []
tags: []
deprecation_message: ''
properties:
- name: Beam.Attachment0
summary: |
The `Class.Attachment` the beam originates from.
description: |
The `Class.Attachment` the beam originates from. This attachment is the
first control point on the beam's cubic Bézier curve; its orientation,
alongside the `Class.Beam.CurveSize0|CurveSize0` property, determines the
position of the second control point. See
[Beams](../../../effects/beams.md#curve) for more details.
For the `Class.Attachment` where the beam ends, see
`Class.Beam.Attachment1|Attachment1`.
code_samples: []
type: Attachment
tags: []
deprecation_message: ''
security:
read: None
write: None
thread_safety: ReadSafe
category: Shape
serialization:
can_load: true
can_save: true
capabilities:
- Basic
- name: Beam.Attachment1
summary: |
The `Class.Attachment` the beam ends at.
description: |
The `Class.Attachment` the beam ends at. This attachment is the fourth and
final control point on the beam's cubic Bézier curve; its orientation,
alongside the `Class.Beam.CurveSize1|CurveSize1` property, determines the
position of the third control point. See
[Beams](../../../effects/beams.md#curve) for more details.
For the `Class.Attachment` where the beam originates from, see
`Class.Beam.Attachment0|Attachment0`.
code_samples: []
type: Attachment
tags: []
deprecation_message: ''
security:
read: None
write: None
thread_safety: ReadSafe
category: Shape
serialization:
can_load: true
can_save: true
capabilities:
- Basic
- name: Beam.Brightness
summary: |
Scales the light emitted from the beam when
`Class.Beam.LightInfluence|LightInfluence` is less than 1.
description: |
Scales the light emitted from the beam when
`Class.Beam.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.Beam.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: Beam.Color
summary: |
Determines the color of the beam across its
`Class.Beam.Segments|Segments`.
description: |
Determines the color of the beam across its
`Class.Beam.Segments|Segments`. If `Class.Beam.Texture|Texture` is set,
this color will be applied to the beam's texture. If no
`Class.Beam.Texture|Texture` is set, the `Class.Beam` will appear as a
solid line colored in accordance with this property.
This property is a `Datatype.ColorSequence`, allowing the color to be
configured to vary across the length of the beam. Consider the following
`Datatype.ColorSequence` which, when applied to a beam, would yield the
pictured result.
```lua
local colorSequence = ColorSequence.new({
ColorSequenceKeypoint.new(0, Color3.fromRGB(255, 0, 0)), -- Red
ColorSequenceKeypoint.new(0.5, Color3.fromRGB(0, 188, 203)), -- Cyan
ColorSequenceKeypoint.new(1, Color3.fromRGB(196, 0, 255)), -- Purple
}
)
```
Note the beam's coloration also depends on the number of
`Class.Beam.Segments|Segments` the `Class.Beam` has. Each segment of the
beam can only show a transition between two colors. Therefore a
`Class.Beam` will need to have at least `n-1` segments in order for the
color to display correctly, where `n` is the number of
`Datatype.ColorSequenceKeypoint|ColorSequenceKeypoints` in the
`Datatype.ColorSequence`.
code_samples: []
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: Beam.CurveSize0
summary: |
Determines, along with `Class.Beam.Attachment0|Attachment0`, the position
of the second control point in the beam's Bézier curve.
description: |
Determines, along with `Class.Beam.Attachment0|Attachment0`, the position
of the second control point in the beam's Bézier curve. See
[Beams](../../../effects/beams.md#curve) for more details.
The position of this point can be determined by the following equation:
```lua
local controlPoint2 = Beam.Attachment0.WorldPosition + (Beam.Attachment0.CFrame.RightVector * Beam.CurveSize0)
```
code_samples: []
type: float
tags: []
deprecation_message: ''
security:
read: None
write: None
thread_safety: ReadSafe
category: Shape
serialization:
can_load: true
can_save: true
capabilities:
- Basic
- name: Beam.CurveSize1
summary: |
Determines, along with `Class.Beam.Attachment1|Attachment1`, the position
of the third control point in the beam's Bézier curve.
description: |
Determines, along with `Class.Beam.Attachment1|Attachment1`, the position
of the third control point in the beam's Bézier curve. See
[Beams](../../../effects/beams.md#curve) for more details.
The position of this point can be determined by the following equation:
```lua
local controlPoint3 = Beam.Attachment1.WorldPosition - (Beam.Attachment1.CFrame.RightVector * Beam.CurveSize1)
```
code_samples: []
type: float
tags: []
deprecation_message: ''
security:
read: None
write: None
thread_safety: ReadSafe
category: Shape
serialization:
can_load: true
can_save: true
capabilities:
- Basic
- name: Beam.Enabled
summary: |
Determines whether the beam is visible or not.
description: |
Determines whether the beam is visible or not.
When this property is set to false, the beam's
`Class.Beam.Segments|Segments` will not be displayed.
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: Beam.FaceCamera
summary: |
Determines whether the `Class.Beam.Segments|Segments` of the beam will
always face the camera, regardless of its orientation.
description: |
A `Class.Beam` 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 beam always faces the
`Class.Workspace.CurrentCamera|CurrentCamera`, regardless of its
orientation.
code_samples: []
type: boolean
tags: []
deprecation_message: ''
security:
read: None
write: None
thread_safety: ReadSafe
category: Shape
serialization:
can_load: true
can_save: true
capabilities:
- Basic
- name: Beam.LightEmission
summary: |
Determines to what degree the colors of the beam are blended with the
colors behind it.
description: |
Determines to what degree the colors of the beam 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.Beam.LightInfluence|LightInfluence` which determines how the beam
is affected by environmental light.
This property does **not** cause the beam 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: Beam.LightInfluence
summary: |
Determines the degree to which the beam is influenced by the environment's
lighting.
description: |
Determines the degree to which the beam is influenced by the environment's
lighting, clamped between 0 and 1. When 0, the beam will be unaffected by
the environment's lighting. When 1, it will be fully affected by lighting
as a `Class.BasePart` would be.
See also `Class.Beam.LightEmission|LightEmission` which specifies to what
degree the colors of the beam 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: Beam.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: Beam.Segments
summary: |
Sets how many straight segments the beam is made up of.
description: |
Rather than being a perfect curve, a beam is made up of straight segments.
The more segments, the higher the resolution of the curve. The
**Segments** property sets how many straight segments the beam is made up
of, with a default value of 10.
Note that the `Class.Beam.Color|Color` and
`Class.Beam.Transparency|Transparency` properties require a certain number
of segments to display correctly. This is because each segment can only
show a transition between two colors or transparencies. Therefore a
`Class.Beam` requires at least `n-1` segments to display correctly, where
`n` is the number of keypoint associated with the beam's
`Class.Beam.Color|Color` and `Class.Beam.Transparency|Transparency`.
code_samples: []
type: int
tags: []
deprecation_message: ''
security:
read: None
write: None
thread_safety: ReadSafe
category: Shape
serialization:
can_load: true
can_save: true
capabilities:
- Basic
- name: Beam.Texture
summary: |
The content ID of the texture to be displayed on the beam.
description: |
The content ID of the texture to be displayed on the beam. If this
property is not set, the beam will be displayed as a solid line; 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 beam
properties including `Class.Beam.Color|Color` and
`Class.Beam.Transparency|Transparency`.
Scaling of the texture is determined by the
`Class.Beam.TextureMode|TextureMode`,
`Class.Beam.TextureLength|TextureLength`, `Class.Beam.Width0|Width0`, and
`Class.Beam.Width1|Width1` properties.
code_samples: []
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: Beam.TextureLength
summary: |
Sets the length of the beam's texture, dependent on
`Class.Beam.TextureMode|TextureMode`.
description: |
Sets the length of the beam's texture, dependent on
`Class.Beam.TextureMode|TextureMode`.
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: Beam.TextureMode
summary: |
Determines the manner in which the `Class.Beam.Texture|Texture` scales and
repeats.
description: |
This property, alongside `Class.Beam.TextureLength|TextureLength`,
determines how a beam's `Class.Beam.Texture|Texture` repeats.
When set to `Enum.TextureMode.Wrap` or `Enum.TextureMode.Static`, the
texture repetitions will equal the beam's overall length (in studs)
divided by its `Class.Beam.TextureLength|TextureLength`.
When set to `Enum.TextureMode.Stretch`, the texture will repeat
`Class.Beam.TextureLength|TextureLength` times across the beam's overall
length.
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: Beam.TextureSpeed
summary: |
Determines the speed at which the `Class.Beam.Texture|Texture` image moves
along the beam.
description: |
Determines the speed at which the `Class.Beam.Texture|Texture` image moves
along the beam. When this property is a positive value, the beam's texture
will move from `Class.Beam.Attachment0|Attachment0` to
`Class.Beam.Attachment1|Attachment1`. This direction can be inverted by
setting this property to a negative number.
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: Beam.Transparency
summary: |
Determines the transparency of the beam across its segments.
description: |
Determines the transparency of the beam across its segments. This property
is a `Datatype.NumberSequence`, allowing the transparency to be configured
to vary across the length of the beam.
Consider the following `Datatype.NumberSequence` which, when applied to a
beam, would yield the pictured result.
```lua
local numberSequence = NumberSequence.new({
NumberSequenceKeypoint.new(0, 0), -- Opaque
NumberSequenceKeypoint.new(0.5, 1), -- Transparent
NumberSequenceKeypoint.new(1, 0), -- Opaque
}
)
```
Note that the beam's transparency also depends on the number of
`Class.Beam.Segments|Segments`. Each segment of the beam can only show a
transition between two transparencies. Therefore a beam will need to have
at least `n-1` segments in order to display correctly, where `n` is the
number of `Datatype.NumberSequenceKeypoint|NumberSequenceKeypoints` in the
`Datatype.NumberSequence`.
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: Beam.Width0
summary: |
The width of the beam at its origin
(`Class.Beam.Attachment0|Attachment0`), in studs.
description: |
The width of the beam at its origin
(`Class.Beam.Attachment0|Attachment0`), in studs. The beam's width will
change linearly to `Class.Beam.Width1|Width1` studs at its end
(`Class.Beam.Attachment1|Attachment1`).
code_samples: []
type: float
tags: []
deprecation_message: ''
security:
read: None
write: None
thread_safety: ReadSafe
category: Shape
serialization:
can_load: true
can_save: true
capabilities:
- Basic
- name: Beam.Width1
summary: |
The width of the beam at its end (`Class.Beam.Attachment1|Attachment1`),
in studs.
description: |
The width of the beam at its end (`Class.Beam.Attachment1|Attachment1`),
in studs. The beam's width will change linearly from
`Class.Beam.Width0|Width0` studs at its origin
(`Class.Beam.Attachment0|Attachment0`).
code_samples: []
type: float
tags: []
deprecation_message: ''
security:
read: None
write: None
thread_safety: ReadSafe
category: Shape
serialization:
can_load: true
can_save: true
capabilities:
- Basic
- name: Beam.ZOffset
summary: |
The distance, in studs, the beam display is offset relative to the
`Class.Workspace.CurrentCamera|CurrentCamera`.
description: |
The distance, in studs, the beam display is offset relative to the
`Class.Workspace.CurrentCamera|CurrentCamera`. When 0, the beam will be
displayed in its standard position between
`Class.Beam.Attachment0|Attachment0` and
`Class.Beam.Attachment1|Attachment1`. **ZOffset** can be either positive
or negative.
This property is particularly useful to avoid "Z‑fighting" when using
multiple `Class.Beam|Beams` between the same
`Class.Attachment|Attachments`.
code_samples:
- Beam-ZOffset
type: float
tags: []
deprecation_message: ''
security:
read: None
write: None
thread_safety: ReadSafe
category: Appearance
serialization:
can_load: true
can_save: true
capabilities:
- Basic
methods:
- name: Beam:SetTextureOffset
summary: |
Sets the current offset of the beam's texture cycle.
description: |
The offset of a beam's texture cycle represents the progress of its
texture animation. This method sets the current offset of the beam's
texture cycle; hence, it can be used to reset the cycle by passing `0` as
the `offset` parameter.
#### Notes
- The given `offset` parameter is expected to be a value between 0 and 1,
but greater values can be used.
- The texture cycle wraps at 0 and 1, meaning the texture is in the same
position when the offset is at 0 or 1.
- If the `Class.Beam.Texture|Texture` property is not set, this method
does nothing.
- Increasing the offset will act in the inverse direction to the
`Class.Beam.TextureSpeed|TextureSpeed` property, meaning it will move
the texture in the opposite direction to the direction the texture
animates when `Class.Beam.TextureSpeed|TextureSpeed` is greater than 0.
code_samples: []
parameters:
- name: offset
type: float
default: 0
summary: |
The desired offset of the texture cycle.
returns:
- type: ()
summary: ''
tags: []
deprecation_message: ''
security: None
thread_safety: Unsafe
capabilities:
- Basic
events: []
callbacks: []