Beam

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.

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.

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:

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

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:

• P0: The start of the beam, the position of Beam.Attachment0
• P1: CurveSize0 studs away from Beam.Attachment0, in Beam.Attachment0's positive X direction.
• P2: Beam.CurveSize1 studs away from Beam.Attachment1, in Beam.Attachment1's negative X direction.
• P3: The end of the beam, the position of Beam.Attachment1

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.

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:

• P0: The start of the beam, the position of Beam.Attachment0
• P1: Beam.CurveSize0 studs away from Beam.Attachment0, in Beam.Attachment0's positive X direction.
• P2: CurveSize1 studs away from Beam.Attachment1, in Beam.Attachment1's negative X direction.
• P3: The end of the beam, the position of Beam.Attachment1

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.

Determines whether the Beam is visible or not.

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

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.

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.

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.

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.

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:

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.

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.

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:

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:

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:

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.

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:

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

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.

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

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.

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

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. It can be used to layer the Beams and avoid Z-fighting.

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