Lumberyard
User Guide (Version 1.16)

Lighting Arc

This feature is in preview release and is subject to change.

You can use the Lightning Arc component to create short arcs (also called sparks) between an emitter and a series of target entities. When an arc is emitted, the arc jumps between the center of the entity to which the Lightning Arc component is attached and the center of the target entity.

To enable the Lightning Arc component, you must enable the Lightning Arc gem. For more information, see Lightning Arc Gem.

Example

The Lightning Arc component is attached to the entity in the center, and the arc randomly jumps between three targets. This example uses the default lightning material in the Lightning Arc gem and the Tesla_core arc preset. For more information, see Customizing a Lightning Arc Preset.


                Add the Lightning Arc component to your entity to
                    create lightning arcs that jump between entities.

Lightning Arc Component Properties

The Lightning Arc component has the following properties:

Enabled

Specifies whether the Lightning Arc component emits arcs.

Default value: True

Targets

The collection of targets to which the Lightning Arc component emits arcs.

Default value: None

Material

The lightning arc material. This parameter does not require a specific type of material, but it's recommended that you use the Illum shader and a texture with opacity.

You can find the default files in the following directory: Gems\LightningArc\Assets\materials\effects

Default value: None

Arc Preset Name

The name of the arc preset in use; the arc preset is specified in the lightningarceffects.xml file. If you change any of the arc parameters in this file, this field changes to <Custom>.

You can find the available arc preset names in the following directory: Gems\LightningArc\Assets\libs\lightningarc\lightningarceffects.xml

Default value: Default

Refresh Presets

If you make changes to the lightningarceffects.xml file, click Refresh Presets to get the most recent arc preset names.

Arc Parameters

The Lightning Arc component has the following lightning options:

Lightning

Deviation

Amount of deviation applied to the arcs. Specify lower values to make the arc appear more smooth.

Default value: 0.2

Valid values: -∞ to ∞

Fuzziness

Amount of noise applied to the arcs.

Default value: 0.01

Valid values: -∞ to ∞

Velocity

Specify how fast an arc drifts upward after it is emitted.

Default value: 0.6

Valid values: -∞ to ∞

Branch

The Lightning Arc component has following branch options:

Max Level

Maximum number of branches that can spawn from an arc. For more information, see SetBranchMaxLevel.

Default value: 1

Valid values: 0 to ∞

Probability

Specifies how likely that a child branch spawns from an arc. For more information, see SetBranchProbability.

Default value: 2

Valid values: -∞ to ∞

Strike

The Lightning Arc component has following strike options:

Time Min

Minimum amount of time that an arc is kept alive.

Default: 0.35

Valid values: -∞ to ∞

Time Max

Maximum amount of time that an arc is kept alive.

Default: 0.35

Valid values: -∞ to ∞

Fade Out

Specifies how long it takes for an arc to fade out.

Default: 0.6

Valid values: -∞ to ∞

Segment Count

Number of segments in an arc. Specify more segments to make the arcs appear more winding.

Default: 6

Valid values: 1 to 100

Point Count

Number of points for each segment. Specify more points to increase the noise effect that is defined by the Fuzziness parameter.

Default: 5

Valid values: 1 to 100

Max Strike Count

Specify how many arcs can be alive at one time from this Lightning Arc component.

Default value: 6

Valid values: 0 to ∞

Beam

The Lightning Arc component has following beam options:

Size

The width of the arcs that the Lightning Arc component creates. The branches that spawn off the arc beam will have half this size.

Default: 0.2

Valid values: -∞ to ∞

Tex Tiling

Texture tiling based on the world size of the arc beam. For more information, see SetBeamTexTiling.

Default: 0.2

Valid values: -∞ to ∞

Tex Shift

Specify how fast to move through textures in the arc's animation. For more information, see SetBeamTexShift.

Default: 0.05

Valid values: -∞ to ∞

Tex Frames

Specify how many frames are in the arc's animation.

Default: 4

Valid values: -∞ to ∞

Tex FPS

Specify how many frames per second are in the arc's animation.

Default: 15

Valid values: -∞ to ∞

Timing

The Lightning Arc component has following timing options:

Delay

Time between emitted arcs, in seconds.

Default: 2

Valid values: 0 to 100

Delay Variation

Variation in time between emitted arcs. For more information, see SetDelayVariation.

Default: 0.5

Valid values: 0 to 100

EBus Request Bus Interface

Use the following request functions with the EBus interface to communicate with other components of your game. You can use this EBus to communicate to an entity with a Lightning Arc component attached. The EBus is available at game run time and editing and can be accessed from C++, Lua, and the Script Canvas editor.

For more information about using the event bus (EBus) interface, see Working with the Event Bus (EBus) System.

Enable

Enables the component to emit lightning arcs.

Parameters

None

Return

None

Scriptable

Yes

Disable

Disables lightning arc emission.

Parameters

None

Return

None

Scriptable

Yes

Toggle

Toggles lightning arc emission.

Parameters

None

Return

None

Scriptable

Yes

IsEnabled

Returns whether the Lightning Arc component emits lightning arcs.

Parameters

None

Return

Type: Boolean

Scriptable

Yes

SetTargets

Sets the target entities to which the Lightning Arc component emits arcs.

Parameters

AZStd::vector<AZ::EntityId>

Type: Vector of entity IDs.

Return

None

Scriptable

Yes

GetTargets

Returns the target entities to which the Lightning Arc component emits arcs.

Parameters

None

Return

AZStd::vector<AZ::EntityId>

Type: Vector of entity IDs.

Scriptable

Yes

SetDelay

Sets the time between emitted arcs, in seconds.

Parameters

Type: Double

Return

None

Scriptable

Yes

GetDelay

Returns the time between emitted arcs, in seconds.

Parameters

None

Return

Type: Double

Scriptable

Yes

SetDelayVariation

Sets the variation in time between emitted arcs.

Delay variation is a random range applied to the Delay parameter to calculate the time that the next arc emits.

The random variation is in the following range: [delay variation * 0.5, delay variation].

For example, if the delay is 2.0 and the delay variation is 1.0, the range of time between arc emissions is [2.5 and 3.0].

Parameters

Type: Double

Return

None

Scriptable

Yes

GetDelayVariation

Returns the variation in time between emitted arcs.

Parameters

None

Return

Type: Double

Scriptable

Yes

SetStrikeTimeMin

Sets the minimum amount of time that an arc is kept alive.

Parameters

Type: Float

Return

None

Scriptable

Yes

GetStrikeTimeMin

Returns the minimum amount of time that an arc is kept alive.

Parameters

None

Return

Type: Float

Scriptable

Yes

SetStrikeTimeMax

Sets the maximum amount of time that an arc is kept alive.

Parameters

Type: Float

Return

None

Scriptable

Yes

GetStrikeTimeMax

Returns the maximum amount of time that an arc is kept alive.

Parameters

None

Return

Type: Float

Scriptable

Yes

SetStrikeFadeOut

Sets how long it takes for an arc to fade out.

Note

Lumberyard completes this fade out internally by scaling the size to 0 rather than adjusting the transparency.

Parameters

Type: Float

Return

None

Scriptable

Yes

GetStrikeFadeOut

Returns how long it takes for an arc to fade out.

Parameters

None

Return

Type: Float

Scriptable

Yes

SetStrikeSegmentCount

Sets the number of segments in an arc.

Specify more segments to make the arcs appear more winding. A Lightning arc component must have a minimum of 1 segment. If you specify 0, a warning appears and 1 is used instead.

Parameters

Type: AZ::u32

Return

None

Scriptable

Yes

GetStrikeSegmentCount

Returns the number of segments in an arc.

Parameters

None

Return

Type: AZ::u32

Scriptable

Yes

SetStrikePointCount

Sets the number of points for each segment.

Note

Specify more points to increase the noise effect that is defined by the Fuzziness parameter. A Lightning arc component must have a minimum of 1 point. If you specify 0, a warning appears and 1 is used instead.

Parameters

Type: AZ::u32

Return

None

Scriptable

Yes

GetStrikePointCount

Returns the number of points for each segment in an arc.

Parameters

None

Return

Type: AZ::u32

Scriptable

Yes

SetLightningDeviation

Sets the amount of deviation applied to the arcs.

Note

Specify lower values to make the arc appear more smooth.

Parameters

Type: Float

Return

None

Scriptable

Yes

GetLightningDeviation

Returns the amount of deviation applied to the arcs.

Parameters

None

Return

Type: Float

Scriptable

Yes

SetLightningFuzziness

Sets the amount of noise applied to the arcs.

Parameters

Type: Float

Return

None

Scriptable

Yes

GetLightningFuzziness

Returns the amount of noise applied to the arcs.

Parameters

None

Return

Type: Float

Scriptable

Yes

SetLightningVelocity

Sets how fast an arc drifts upwards after it emits.

Parameters

Type: Float

Return

None

Scriptable

Yes

GetLightningVelocity

Returns how fast an arc drifts upwards after it emits.

Parameters

None

Return

Type: Float

Scriptable

Yes

SetBranchProbability

Sets how likely a branch spawns off of an arc.

A branch (or child arc) is an arc that is half the size and intensity of the parent arc. A branch has the same emission point and target as its parent.

  • A value of 0 means that branches do not spawn.

  • A value of 0.5 means there is a 50% chance of spawning a branch.

  • A value of 2.0 means there is a 100% chance of spawning two branches.

For more information about setting the maximum number of branches, see SetBranchMaxLevel.

Parameters

Type: Float

Return

None

Scriptable

Yes

GetBranchProbablity

Returns how likely a branch spawns off the parent arc.

Parameters

None

Return

Type: Float

Scriptable

Yes

SetBranchMaxLevel

Sets the maximum number of branches that can spawn off the parent arc.

  • A value of 0 means branches do not spawn, regardless of branch probability.

  • A value of 3 means that between 0 and 3 branches can spawn, depending on the branch probability.

Parameters

Type: AZ::u32

Return

None

Scriptable

Yes

GetBranchMaxLevel

Returns the maximum number of branches allowed to spawn off the parent arc.

Parameters

None

Return

Type: AZ::u32

Scriptable

Yes

SetMaxStrikeCount

Sets how many arcs can be alive at one time from this Lightning Arc component; this includes parent and branch arcs.

Parameters

Type: AZ::u32

Return

None

Scriptable

Yes

GetMaxStrikeCount

Returns the maximum number of arcs that can be alive at one time from this Lightning Arc component.

Parameters

None

Return

Type: AZ::u32

Scriptable

Yes

SetBeamSize

Sets the width of the generated arcs. Branch arcs be half this size.

Parameters

Type: Float

Return

None

Scriptable

Yes

GetBeamSize

Returns the width of the generated arcs.

Parameters

None

Return

Float

Scriptable

Yes

SetBeamTexTiling

Sets the texture tiling based on the world size of the arc beam.

  • A value of 2.0 means that the texture wraps around twice for each meter.

  • A value of 0.25 means that the texture wraps around four times for each meter.

Note

Only the U coordinate of the texture map is affected by this parameter.

Parameters

Type: Float

Return

None

Scriptable

Yes

GetBeamTexTiling

Returns the texture tiling parameter for the arc beam.

Parameters

None

Return

Type: Float

Scriptable

Yes

SetBeamTexShift

Sets how fast to move through textures in the arc's animation.

Note

The U value of the texture coordinate moves at this specified rate. The V value is automatically calculated to select the correct frame.

Parameters

Type: Float

Return

None

Scriptable

Yes

GetBeamTexShift

Returns how fast to move through textures in the arc's animation.

Parameters

None

Return

Type: Float

Scriptable

Yes

SetBeamTexFrames

Sets how many frames are in an arc's animation.

Parameters

Type: Float

Return

None

Scriptable

Yes

GetBeamTexFrames

Returns the number of frames in an arc's animation.

Parameters

None

Return

Type: Float

Scriptable

Yes

SetBeamTexFPS

Sets how many frames per second are in an arc's animation.

Parameters

Type: Float

Return

None

Scriptable

Yes

GetBeamTexFPS

Returns how many frames per second are in an arc's animation.

Parameters

None

Return

Type: Float

Scriptable

Yes

Request Bus Example Script

function example:OnActivate() -- Send some events to a LightningArcComponent attached to the same entity as this script LightningArcComponentRequestBus.Event.Toggle(self.entityId) LightningArcComponentRequestBus.Event.SetDelayVariation(self.entityId, 0.4) end

EBus Notification Bus Interface

Use the following notification functions with the Lightning Arc component notification EBus interface to communicate with other components of your game.

For more information about using the Event Bus (EBus) interface, see Working with the Event Bus (EBus) System.

OnSpark

Notifies an event that triggers when the specified component fires a spark.

Parameters

None

Return

None

Scriptable

Yes

Notification Bus Example Script

function example:OnActivate() -- Listen for lightning arc notifications on the same entity to which this script is attached self.lightningArcHandler = LightningArcComponentNotificationBus.Connect(self, self.entityId) end function example:OnSpark() Debug.Log("On Spark Triggered") end function example:OnDeactivate() self.lightningArcHandler:Disconnect() end