rojo/.cursor/rules/roblox/reference/engine/classes/Beam.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: 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`

  <img src="/assets/engine-api/classes/Beam/Curvature-Diagram.png" width="800" alt="Beam curvature diagram" />
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
      	}
      )
      ```

      <img src="/assets/lighting-and-effects/beam/ColorSequence-Applied.png" width="800" />

      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&nbsp;studs)
      divided by its `Class.Beam.TextureLength|TextureLength`.

      <img src="/assets/engine-api/enums/TextureMode/Wrap-Static.png" width="720" alt="TextureMode diagram with Wrap mode" />

      When set to `Enum.TextureMode.Stretch`, the texture will repeat
      `Class.Beam.TextureLength|TextureLength` times across the beam's overall
      length.

      <img src="/assets/engine-api/enums/TextureMode/Stretch.png" width="720" alt="TextureMode diagram with Stretch mode" />
    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
      	}
      )
      ```

      <img src="/assets/lighting-and-effects/beam/Transparency-Applied.png" width="800" />

      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: []