Beam

Show Deprecated

A Beam object connects two Attachments by drawing a texture between them.

Setting up a Beam

To display, beams must be a descendant of the Workspace with their Beam.Attachment0 and Beam.Attachment1 properties set to Attachments also descending from the Workspace.

The beam's appearance can be customised using the range of properties available.

Beam Curvature

Beams are configured to use a cubic Bézier curve. This means they are not constrained to straight lines, and the curve of the beam can be modified by changing Beam.CurveSize0, Beam.CurveSize1 and the orientation of the beam's Attachments.

Cubic Bézier curves are formed of four control points. They are determined as follows:

The beam starts at P0, goes towards P1, and arrives at P3, from the direction of P2. The beam will not necessarily pass through P1 and P2.

See the image below for a visual demonstration.

Beam Curve

Code Samples

Creating a Beam From Scratch

1-- create attachments
2local att0 = Instance.new("Attachment")
3local att1 = Instance.new("Attachment")
4
5-- parent to terrain (can be part instead)
6att0.Parent = workspace.Terrain
7att1.Parent = workspace.Terrain
8
9-- position attachments
10att0.Position = Vector3.new(0, 10, 0)
11att1.Position = Vector3.new(0, 10, 10)
12
13-- create beam
14local beam = Instance.new("Beam")
15beam.Attachment0 = att0
16beam.Attachment1 = att1
17
18-- appearance properties
19beam.Color = ColorSequence.new({ -- a color sequence shifting from white to blue
20 ColorSequenceKeypoint.new(0, Color3.fromRGB(255, 255, 255)),
21 ColorSequenceKeypoint.new(1, Color3.fromRGB(0, 255, 255)),
22})
23beam.LightEmission = 1 -- use additive blending
24beam.LightInfluence = 0 -- beam not influenced by light
25beam.Texture = "rbxasset://textures/particles/sparkles_main.dds" -- a built in sparkle texture
26beam.TextureMode = Enum.TextureMode.Wrap -- wrap so length can be set by TextureLength
27beam.TextureLength = 1 -- repeating texture is 1 stud long
28beam.TextureSpeed = 1 -- slow texture speed
29beam.Transparency = NumberSequence.new({ -- beam fades out at the end
30 NumberSequenceKeypoint.new(0, 0),
31 NumberSequenceKeypoint.new(0.8, 0),
32 NumberSequenceKeypoint.new(1, 1),
33})
34beam.ZOffset = 0 -- render at the position of the beam without offset
35
36-- shape properties
37beam.CurveSize0 = 2 -- create a curved beam
38beam.CurveSize1 = -2 -- create a curved beam
39beam.FaceCamera = true -- beam is visible from every angle
40beam.Segments = 10 -- default curve resolution
41beam.Width0 = 0.2 -- starts small
42beam.Width1 = 2 -- ends big
43
44-- parent beam
45beam.Enabled = true
46beam.Parent = att0
Create a chain of beams between parts

1local function connectParts(...)
2 -- build an array of parts given
3 local parts = { ... }
4 -- make sure there is more than one part
5 if #parts > 1 then
6 -- create a template beam
7 local beam = Instance.new("Beam")
8 -- can change beam properties here
9 -- create an initial attachment in the first part
10 local lastAttachment = Instance.new("Attachment")
11 lastAttachment.Parent = parts[1]
12 -- iterate through parts from the second part
13 for i = 2, #parts do
14 local part = parts[i]
15 -- create an attachment in the part
16 local nextAttachment = Instance.new("Attachment")
17 nextAttachment.Parent = part
18 -- hook the beam up
19 local newBeam = beam:Clone()
20 newBeam.Attachment0 = lastAttachment
21 newBeam.Attachment1 = nextAttachment
22 newBeam.Parent = lastAttachment
23 -- set the last attachment
24 lastAttachment = nextAttachment
25 end
26 end
27end
28
29local objects = script.Parent:GetDescendants()
30
31local parts = {}
32
33for _index, object in ipairs(objects) do
34 if object:IsA("BasePart") then
35 table.insert(parts, object)
36 end
37end
38
39connectParts(parts)

Summary

Properties

The Attachment the Beam originates from.

Scales the light emitted from Beam when LightInfluence is 0.

Determines the color of the Beam across its segments.

Determines, along with Beam.Attachment0 the position of the first control point in the Beam's Bézier curve.

Determines, along with Beam.Attachment1 the position of the second control point in the Beam's Bézier curve.

Determines whether the Beam is visible or not.

Determines whether the Beam.Segments of the Beam will always face the camera regardless of its orientation.

Determines to what degree the colors of the Beam are blended with the colors behind it.

Determines the degree to which the Beam is influenced by the environment's lighting.

Sets how many straight segments the Beam is made up of.

The content ID of the texture to be displayed on the Beam.

Sets the length of the Beams texture if Beam.TextureMode is 'Wrap' or 'Static'. If Beam.TextureMode is 'Stretch' then it determines the size of the texture relative to the Beam's length.

Determines the manner in which the Beam.Texture scales and repeats.

Determines the speed at which the Beam.Texture image moves along the Beam.

Determines the transparency of the Beam across its segments.

The width in studs of the Beam at its base.

The width in studs of the Beam at its end.

The distance, in studs, the Beams display is offset by relative to the Workspace.CurrentCamera.

Events

Methods


Sets the current offset of the Beam's texture cycle.

Properties

Attachment0

The Attachment the Beam originates from.

A Beam's Attachment0 is the first control point on the Beam's cubic Bézier curve. The orientation of Attachment0, alongside the Beam's Beam.CurveSize0, property determine the position of the second control point.

For the Attachment where the Beam ends see Beam.Attachment1.

For more information how a Beam curves, see Beam.CurveSize0.

Attachment1

The Attachment the Beam ends at.

A Beam's Attachment1 is the fourth and final control point on the Beam's cubic Bézier curve. The orientation of Attachment1, alongside the Beam's Beam.CurveSize1 property, determine the position of the third control point.

For the Attachment where the Beam starts see Beam.Attachment0.

For more information how a Beam curves, see Beam.CurveSize1.

Brightness

Scales the light emitted from Beam. 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.

Determines the color of the Beam.

If the Beam's Beam.Texture is set, this color will be applied to the Beam's texture. If no Beam.Texture has been set then the Beam will appear as a solid bar colored in accordance with this property.

Beams and ColorSequences

This property is a ColorSequence, allowing the color to be configured to vary across the length of the Beam. Take for example the following ColorSequence.


1local colorSequence = ColorSequence.new({
2 ColorSequenceKeypoint.new(0, Color3.fromRGB(255, 0, 0)), -- red
3 ColorSequenceKeypoint.new(0.5, Color3.fromRGB(0, 255, 0)), -- green
4 ColorSequenceKeypoint.new(1, Color3.fromRGB(0, 0, 255)), -- blue
5 }
6)
7

Applying this ColorSequence to a Beam would yield the following result:

enter image description here

Note the Beam's coloration also depends on the number of Beam.Segments the Beam has. Each segment of the beam can only show a transition between two colors. Therefore a Beam will need to have at least n-1 segments in order for the color to display correctly, where n is the number of ColorSequenceKeypoints in the ColorSequence

CurveSize0

Determines, along with Beam.Attachment0 the position of the first control point in the Beam's Bézier curve.

The position of this point can be determined by the following equation:


1local controlPoint1 = Beam.Attachment0.WorldPosition + (Beam.Attachment0.CFrame.rightVector * Beam.CurveSize0)
2

Beam Curvature

Beams are configured to use a cubic Bézier curve. This means they are not constrained to straight lines, and the curve of the beam can be modified by changing CurveSize0, Beam.CurveSize1 and the orientation of the beam's Attachments.

Cubic Bézier curves are formed of four control points. They are determined as follows:

The beam starts at P0, goes towards P1, and arrives at P3, from the direction of P2. The beam will not necessarily pass through P1 and P2.

See the images below for a visual demonstration.

BeamCurve1 BeamCurve2

CurveSize1

Determines, along with Beam.Attachment0 the position of the first control point in the Beam's Bézier curve.

The position of this point can be determined by the following equation:


1local controlPoint2 = Beam.Attachment1.WorldPosition - (Beam.Attachment1.CFrame.rightVector * Beam.CurveSize1)
2

Beam Curvature

Beams are configured to use a cubic Bézier curve. This means they are not constrained to straight lines, and the curve of the beam can be modified by changing Beam.CurveSize0, CurveSize1 and the orientation of the beam's Attachments.

Cubic Bézier curves are formed of four control points. They are determined as follows:

The beam starts at P0, goes towards P1, and arrives at P3, from the direction of P2. The beam will not necessarily pass through P1 and P2.

See the images below for a visual demonstration.

enter image description here enter image description here

Enabled

Determines whether the Beam is visible or not.

When this property is set to false, the Beam's Beam.Segments will not be displayed.

FaceCamera

Determines whether the Beam.Segments of the Beam will always face the Workspace.CurrentCamera regardless of its orientation.

A Beam has no depth, and is hence a two dimensional projection existing in three dimensional space. This means that, by default, a Beam is not visible from every angle.

When FaceCamera is set to true, the Beam will always be orientated towards the Workspace.CurrentCamera.

LightEmission

Determines to what degree the colors of the Beam are blended with the colors behind it.

The LightEmission property determines the blending of the Beam with the colors behind it. It should be set in the range [0, 1]. A value of 0 uses normal blending modes, and a value of 1 will use additive blending. The value of the additive blending is determined by this property.

Pictured below are two sets of overlapping Beams. The right one has its LightEmission set to 1, so the texture appears brighter due to the additive blending on the overlaps.

enter image description here

This property should not be confused with Beam.LightInfluence, which determines how particles are affected by environment light. This property does not cause the Beam to light the environment. To do that, consider using a SurfaceLight.

LightInfluence

Determines the degree to which the Beam is influenced by the environment's lighting.

LightInfluence is clamped between 0 and 1. When LightInfluence is 0, the Beam will be unaffected by the environment's lighting. When LightInfluence is 1 however, it will be fully affected by lighting (as a BasePart would be).

For an example of this, and a demonstration of how this property interacts with Beam.LightEmission, please see the images below.

enter image description here

enter image description here

Segments

Sets how many straight segments the Beam is made up of.

This value can be any integer greater than 0. The default value is 10.

Beam Segments and curvature

Rather than being a perfect curve, a beam is made up of straight segments. The more segments, the higher the resoloution of the curve. See the image below for a demonstration of this:

enter image description here

For more information on how a Beam is configured to curve, see the page for Beam.CurveSize0.

Beam Segments with Color and Transparency

The Beam.Color and Beam.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 Beam requires at least n-1 segments to display correctly, where n is the number of keypoint associated with the Beam's Beam.Color and Beam.Transparency.

Texture

The content ID of the texture to be displayed on the Beam.

If the Texture property of the beam 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 Beam.Color and Beam.Transparency.

The scaling of the texture is determined by the Beam.TextureMode, Beam.TextureLength, Beam.Width0 and Beam.Width1 properties.

TextureLength

Sets the length of the Beams texture if Beam.TextureMode is 'Wrap' or 'Static'. If Beam.TextureMode is 'Stretch' then it determines the size of the texture relative to the Beam's length.

Beam texture behavior

How a Beam's texture scales or repeats is dependent on the Beam.TextureMode property.

When Beam.TextureMode is 'Wrap' the size of the repeating texture is equal to TextureLength in studs. For an example of this see the image below:

beamTexture1

Note, the 'Static' TextureMode type is not used for Beams and therefore behaves identically to 'Wrap'.

When Beam.TextureMode is set to 'Stretch' however the texture will be stretched relative to the beam's length. The size of the texture relative to the Beam's length will be one over the TextureLength. In practice, this means the texture will repeat TextureLength times. For an example of this see the image below:

beamTexture2

TextureMode

Determines the manner in which the Beam.Texture scales and repeats.

Beam Texture Behavior

How a Beam's texture scales or repeats is dependent on the TextureMode property.

When TextureMode is 'Wrap' the size of the repeating texture corresponds to Beam.TextureLength in studs. For an example of this see the image below:

Note, the 'Static' TextureMode type is not used for Beams and therefore behaves identically to 'Wrap'.

When Beam.TextureMode is set to 'Stretch' however the texture will be stretched relative to the beam's length. The size of the texture relative to the Beam's length will be one over the Beam.TextureLength. In practice, this means the texture will repeat Beam.TextureLength times. For an example of this see the image below:

TextureSpeed

Determines the speed at which the Beam.Texture image moves along the Beam.

When TextureSpeed is positive, the beam's texture will move from Beam.Attachment0 to Beam.Attachment1. This direction can be inverted by setting TextureSpeed to a negative number.

Note the speed at which the texture moves is relative to the length of the texture. Meaning the more stretched the beam's Beam.Texture is, the faster it will move at the same TextureSpeed.

Transparency

Determines the transparency of the Beam across its segments.

Beams and Transparency

This property is a NumberSequence, allowing the transparency to be configured to vary across the length of the Beam. Take for example the following NumberSequence.


1local numberSequence = NumberSequence.new({
2 NumberSequenceKeypoint.new(0, 1), -- transparent
3 NumberSequenceKeypoint.new(0.5, 0), -- opaque
4 NumberSequenceKeypoint.new(1, 1), -- transparent
5 }
6)
7

Applying this NumberSequence to a Beam would yield the following result:

enter image description here

Note the Beam's transparency also depends on the number of Beam.Segments the Beam has. 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 NumberSequenceKeypoints in the NumberSequence

Width0

The width in studs of the Beam at its base.

The beam will be Width0 studs wide at Beam.Attachment0 and the width will change linearly to Beam.Width1 studs at Beam.Attachment1. For a visual demonstration of this, see the image below.

Width

The width properties should not be confused with Beam.CurveSize0 and Beam.CurveSize1 which control the curvature of the beam.

Width1

The width in studs of the Beam at its end.

The beam will be Beam.Width0 studs wide at Beam.Attachment0 and the width will change linearly to Width1 studs at Beam.Attachment1. For a visual demonstration of this, see the image below.

Width

The width properties should not be confused with Beam.CurveSize0 and Beam.CurveSize1 which control the curvature of the beam.

ZOffset

The distance, in studs, the Beams display is offset by relative to the Workspace.CurrentCamera.

When ZOffset is 0, the Beam will be displayed in its standard position between Beam.Attachment0 and Beam.Attachment1. ZOffset can be both positive and negative.

This property can be particularly useful when using multiple Beams between the same Attachments. Here, ZOffset can be used to layer the Beams and avoid Z-fighting. For example:

See the image below for a visual demonstration of ZOffset:

ZOffset

Events

Methods

SetTextureOffset

Sets the current offset of the Beam's texture cycle.

The offset of a Beams texture cycle represents the progress of the Beams texture animation. Hence, a Beam's texture cycle can be reset as follows:


1beam:SetTextureOffset(0)
2

Where manual control is not required over the Beam's texture cycle, Beam.TextureSpeed can be used instead to animate the Beam. Although, for illustrative purposes, a similar function can be achieved with SetTextureOffset.


1local RunService = game:GetService("RunService")
2while true do
3 for i = 1, 0, -0.01 do
4 RunService.RenderStepped:Wait()
5 beam:SetTextureOffset(i)
6 end
7end
8

Note:

  • The given offset parameter is expected to be a value between 0 and 1, but greater values can still be used
  • The texture cycle wraps at 0 and 1, meaning the texture is in the same position when the offset is 0 or at 1
  • If the Beam.Texture property is not set, this function will do nothing
  • Increasing the offset will act in the inverse direction to the Beam.TextureSpeed property. Meaning, it will move the texture in the opposite direction to the direction the texture animates when Beam.TextureSpeed is more than 0

Parameters

offset: number

The desired offset of the texture cycle.

Default Value: "0"

Returns