Menu
Lumberyard
User Guide (Version 1.14)

Visual Components

You can add one visual component to an element: Image, Particle Emitter, or Text.

Image

You can use an Image component to add a color tint or texture to an element.

To see in-game examples of completed canvases with Image components

  1. In Lumberyard Editor, in the Samples Project, open the UiFeatures level.

  2. Press Ctrl+G to play the game, and then choose Components, Visual Components, Image.

    You can view examples of image types such as sliced, stretched, fixed, tiled, stretched to fit, and stretched to fill.

  3. Press Esc to exit the game.

To view these same canvases in the UI Editor, navigate to the lumberyard_version\dev\Gems\LyShineExamples\Assets\UI\Canvases\LyShineExamples\Comp\Image directory.

You can open the following canvases:

  • ColorTest.uicanvas

  • ImageTypes.uicanvas

Use the Properties pane of the UI Editor to configure the following settings for the Image component.

Image Settings

Name Description
SpriteType

Select one of the following:

  • Sprite/Texture asset – Image displays the asset specified for Sprite path.

  • Render target – Image displays the render target specified in Render target name.

Sprite path

Click the browse () icon and select a suitable file.

Click the open-in (arrow) icon next to Sprite path to open the Sprite Editor.

Render target name

Type a name of a render target and press Enter.

Index

The sprite sheet image index that will be rendered by the component.

Color

Click the color swatch to select a different color.

Displays only if the SpriteType is Sprite/Texture asset, and the image has been configured as a sprite sheet using the Sprite Editor.

Alpha

Use the slider to choose an alpha value between 0 and 1.

Image type

Select one of the following:

  • Stretched – Stretches the texture with the element without maintaining aspect ratio.

  • Sliced – Treats the texture as a 9-sliced sprite.

  • Fixed – Makes the texture pixel perfect.

  • Tiled – Tiles the texture to fill the element.

  • Stretched to Fit – Scales to fit while maintaining aspect ratio.

  • Stretched to Fill – Scales to fill while maintaining aspect ratio.

Blend Mode

Select one of the following:

  • Normal – Uses alpha to interpolate colors between elements.

  • Add – Blends colors between elements by adding (lightening) color values together.

  • Screen – Blends colors using inverse source color resulting in a lighter color.

  • Darken – Chooses the darker color channel when blending between elements.

  • Lighten – Chooses the lighter color channel value when blending between elements.

Fill Type

Select one of the following:

  • None – Displays the entire image.

  • Linear – Uses Fill Amount value to fill the image linearly from one edge to the opposite edge.

  • Radial – Uses Fill Amount value to fill the image radially 360 degrees around the center of the image.

  • Radial Corner – Uses Fill Amount value to fill the image radially 90 degrees around a corner of the image.

  • Radial Edge – Uses Fill Amount value to fill the image radially 180 degrees around the midpoint of an edge of the image.

Fill Amount

The amount of the image to be filled, from 0.00 to 1.00.

Fill Start Angle

The start angle for the fill, measured in degrees clockwise from vertical.

Corner Fill Origin

The starting corner from which the image is filled.

Select one of the following:

  • Top Left

  • Top Right

  • Bottom Left

  • Bottom Right

Edge Fill Origin

The edge from which the image is filled about (radial corner) or from (linear).

Select one of the following:

  • Left

  • Top

  • Right

  • Bottom

Fill Clockwise

If selected, the image is radially filled clockwise about the fill center.

Fill Center

If selected, the center segment of a slice-resized sprite is visible.

Particle Emitter

You can use a Particle Emitter component to emit two dimensional particles from an element.

To see in-game examples of completed canvases with a Particle Emitter component

  1. In Lumberyard Editor, in the Samples Project, open the UiFeatures level.

  2. Press Ctrl+G to play the game, and then choose Components, Visual Components, Particle Emitter.

    You can view particle emitter examples that create a variety of spark effects and trail effects.

  3. Press Esc to exit the game.

To view these same canvases in the UI Editor, navigate to the lumberyard_version\dev\Gems\LyShineExamples\Assets\UI\Canvases\LyShineExamples\Comp\ParticleEmitter directory.

You can open the following canvases:

  • ParticleEmitter.uicanvas

  • ParticleEmitterSparks.uicanvas

  • ParticleEmitterTrails.uicanvas

Use the Properties pane of the UI Editor to configure the following settings for the Particle Emitter component.

Emitter Settings

Name Description
Emit on activate Start emitting when the component is activated.
Hit particle count on activate Emit and process the average number of particles when the emitter starts emitting.
Infinite life time Make the lifetime of the emitter infinite.
Emitter life time Type the number of seconds during which the emitter is active. When the end of the lifetime is reached, the emitter stops emitting. This option is available when Infinite life time is not set.
Emit rate Type the number of particles to emit per second.
Emitter shape

Select one of the following:

  • Point – Particles are emitted from the emitter position.

  • Circle – Particles are emitted from within the circle that is contained by the element area.

  • Quad – Particles are emitted from within the quad that is contained by the element area.

Particle count limit Use the Active particle limit value to limit the number of active particles.
Active particles limit This option is available when Particle Count Limit is set. Type the maximum number of active particles. When the maximum number is reached, additional particles are emitted only after existing particles are removed. The maximum value is 9999.
Fixed random seed Specify a fixed random seed for the emitter. When not selected, a random seed is generated each time the emitter starts emitting.
Random seed This option is available when Fixed random seed is set. Type the numerical seed to use for the particle emitter when Fixed random seed is selected. The field accepts a maximum nine digit negative or positive integer.
Emit on edge This option is available when Emitter shape is Circle or Quad. Emit particles on the edge of the specified shape.
Emit inside distance This option is available when Emit on Edge is set. Type the distance inside the edge from which the particles are emitted.
Emit outside distance Type the distance outside the edge from which the particles are emitted.
Initial direction type

This option is available when Emitter shape is Circle or Quad. Select one of the following to specify how the initial direction is calculated:

  • Relative to emit angle – Use the value of emit angle as the direction along which to emit.

  • Relative to emitter center – Use the direction from the emitter center to the initial position as the direction along which to emit.

Emit angle Type the number of degrees vertical from which particles are emitted.
Emit angle variation Type a number or use the slider to specify, in degrees, the variation of the emit angle. Valid values are from 0 through 180. A value of 10 specifies a variation range of plus or minus 10 degrees.

Particle Settings

Name Description
Infinite life time Make the particle lifetime infinite.
Life time Type the number of seconds during which the emitted particles are initially active.
Life time variation Type the number of seconds that the lifetime of the emitted particles can vary.
Sprite pathname Click the ellipsis (...) to open the Pick Texture dialog box and select a sprite image file.
Animated sprite sheet This option is available when the selected sprite is a sprite sheet (has more than one cell). Select to change the sprite sheet cell index on each particle over time.
Loop sprite sheet animation This option is available when Animated sprite sheet is set. Select to loop the sprite sheet cell animation.
Random sprite sheet index This option is available when the selected sprite is a sprite sheet (has more than one cell). Select to randomly choose the initial sprite sheet cell index.
Sprite sheet index This option is available when the selected sprite is a sprite sheet (has more than one cell) and Random sprite sheet index is not set. Select the sprite sheet index that is used for the emitted particles.
Sprite sheet start frame This option is available when the selected sprite is a sprite sheet (has more than one cell) and Random sprite sheet index is set. Select the starting frame of the sprite sheet range that is used for sprite sheet animation or randomly choosing the index.
Sprite sheet end frame This option is available when the selected sprite is a sprite sheet (has more than one cell) and Random sprite sheet index is set. Sets the end frame of the sprite sheet range used for sprite sheet animation or randomly choosing the index.
Sprite sheet frame delay This option is available when Animated sprite sheet is set. Type the number of seconds of delay between each sprite sheet frame.
Blend mode

Select one of the following:

  • Normal – Use alpha to interpolate colors between elements.

  • Add – Blend colors between elements by adding (lightening) color values together.

  • Screen – Use inverse source color to blend colors. Results in a lighter color.

  • Darken – Choose the darker color channel value when blending between elements.

  • Lighten – Choose the lighter color channel value when blending between elements.

Particle Movement

Name Description
Relative to emitter Move particles relative to the element to which the Particle Emitter component is attached. When this option is not selected, the element leaves a trail of particles as the emitter moves around the canvas.
Movement co-ordinate type

Select the type of coordinate space that is used for particle movement:

  • Cartesian

  • Polar

Speed This option is available when Movement co-ordinate type is set to Cartesian. Type a number that specifies the initial speed of the emitted particles when the emit direction is calculated.
Speed variation This option is available when Movement co-ordinate type is set to Cartesian. Type a number that specifies the variation in initial speed of the emitted particles when the emit direction is calculated.
Initial velocity This option is available when Movement co-ordinate type is set to Polar. Type X and Y values that specify the initial velocity of the emitted particles.
Initial velocity variation This option is available when Movement co-ordinate type is set to Polar. Type X and Y values that specify the variation in the initial velocity of the emitted particles.
Acceleration co-ordinate type

Select the type of coordinate space that is used for particle acceleration:

  • Cartesian

  • Polar

Acceleration Type X and Y values that specify the acceleration of each emitted particle.
Orientation velocity based Point the top of each particle toward the current velocity vector.
Initial orientation velocity based Point the top of each particle toward the initial velocity vector.
Initial rotation Type the number of degrees of the initial rotation clockwise from vertical.
Initial rotation variation Type the number of degrees in the variation of the initial rotation. A value of 10 specifies a variation range of plus or minus 10 degrees around the specified initial rotation.
Rotation speed Type the rotation speed in degrees clockwise per second.
Rotation speed variation Type the variation in rotation speed in degrees clockwise per second. A value of 10 specifies a variation range of plus or minus 10 degrees in the specified rotation speed.

Particle Size

Name Description
Lock aspect ratio Locks the width and height of the emitted particles into the current aspect ratio.
Pivot Type X and Y values that specify the pivot for the particles from (0,0) at the top left to (1,1) at the bottom right.
Size Type X and Y values that specify the size of each emitted particle.
Size variation Type X and Y values that specify the variation in size of each emitted particle.

Particle Color

Name Description
Color Type RGB values that specify the color of each emitted particle or click the white square to use the Select Color dialog box.
Color brightness variation Type a decimal number between 0 and 1 that specifies the variation in brightness of each emitted particle.
Color tint variation Type a decimal number between 0 and 1 that specifies the tint variation of each emitted particle.
Alpha Type a decimal number between 0 and 1 that specifies the alpha that is used for the emitted particles.

Timelines

Name Description
Speed multiplier Click the plus sign (+) to add keyframes that control a curve to multiply the particle speed over its lifetime.
Width multiplier

This option is available when Lock aspect ratio (in Particle Size) is not set.

Click the plus sign (+) to add keyframes that control a curve to multiply the particle width over its lifetime.

Height multiplier

This option is available when Lock aspect ratio (in Particle Size) is not set.

Click the plus sign (+) to add keyframes that control a curve to multiply the particle height over its lifetime.

Size multiplier Click the plus sign (+) to add keyframes that control a curve to multiply the particle size over its lifetime.
Color multiplier Click the plus sign (+) to add keyframes that control a curve to multiply the particle color over its lifetime.
Alpha multiplier Click the plus sign (+) to add keyframes that control a curve to multiply the particle alpha over its lifetime.
Time

Type a value between 0 and 1 that specifies when the keyframe occurs during the particle lifetime.

A value of 0 is the start of the particle lifetime and 1 is the end of the particle lifetime.

Multiplier

Specify a value from -100 through 100 to multiply against the value that this timeline controls.

For example, if the speed value is 50.0 and the speed multiplier for a specific keyframe is 2.0, then the value of speed at the specified keyframe is 100.

In tangent

Controls the in tangent for the current keyframe. Select one of the following:

  • Ease In

  • Linear

  • Step

Out tangent

Controls the out tangent for the current keyframe. Select one of the following:

  • Ease In

  • Linear

  • Step

Ease In

Specifies a gradual approach of a curve to a flat tangent.

For example, a keyframe that specifies Ease In for In tangent and Ease Out for Out tangent looks like the flattened tangent of an x3 (x cubed) curve at its origin.

Ease Out

Specifies a gradual retreat of a curve from a flat tangent.

For example, a keyframe that specifies Ease In for In tangent and Ease Out for Out tangent looks like the flattened tangent of an x3 (x cubed) curve at its origin.

Linear Specifies that the curve moves linearly from the keyframe towards the next or previous keyframe.
Step Specifies that the curve jumps from the current keyframe value to the next or previous keyframe value.

Text

You can use a Text component to add a text string to an element.

To see in-game examples of completed canvases with text components

  1. In Lumberyard Editor, in the Samples Project, open the UiFeatures level.

  2. Press Ctrl+G to play the game, and then choose Components, Visual Components, Text. The level has examples of text alignment, color and alpha, styling markup, overflow and wrapping, and character and line spacing.

  3. Press Esc to exit the game.

To view the same canvases in the UI Editor, navigate to the lumberyard_version\dev\Gems\LyShineExamples\Assets\UI\Canvases\LyShineExamples\Comp\Text directory.

You can open the following canvases:

  • Alignment.uicanvas – Examples of aligning the text within its element rectangle.

  • ColorAlpha.uicanvas – Examples of setting different colors and transparency levels.

  • Markup.uicanvas – Examples of customizing the appearance of text using different styles, colors, and font within a single string.

  • OverflowWrap.uicanvas – Examples of different wrap and overflow options.

  • Text.uicanvas – Examples of different wrap and overflow options.

Use the Properties pane of the UI Editor to configure the following settings for the Text component.

Text Settings

Name Description
Text

Type the preferred text string and press Enter. You can also apply text styling markup.

Color

Click the color swatch to select a different color.

Alpha

Use the slider to choose an alpha value between 0 and 1.

Font path

Click the button and select a font .font file. For more information, see Adding New Fonts.

Font size

Type a font size and press Enter.

Font effect

Select an effect from the list. The available font effects are dictated by the font .font file.

Horizontal text alignment

Select Left, Center, or Right to align the text with respect to the element's left and right borders.

Vertical text alignment

Select Top, Center, or Bottom to align the text with respect to the element's top and bottom borders.

Overflow mode

Select Overflow to allow the text to display beyond the edges of the element.

Select Clip text to hide, or clip, any text that flows beyond the element's edges.

Wrap text

Select No wrap to prevent text from wrapping to subsequent lines.

Select Wrap text to allow text to be broken into separate lines.

Text Styling Markup

You can customize the appearance of the text in your game UI with bold and italic styling, multiple text colors, and multiple fonts in a single text string. You type specific tags directly into the Font box, along with your string. The simple markup language is loosely based on HTML.

To use the text styling markup feature, you must use a font family *.fontfamily asset file in the Font path setting (rather than an individual .font asset file). For more information about adding font families to your projects, see Implementing New Fonts.

To use text styling markup

  1. In the UI Editor, add a Text component to an element on your canvas (or modify an existing component).

  2. With the element selected, in the Properties pane, set the Font path property to a *.fontfamily file.

  3. Type a string with markup styling in the Text box. See the next section for examples.

Tags and Attributes

Example

You can use the following tags and attributes when styling text with markup:

Bold tag: <b>

                                        Example that uses a Text
                                            component to add bold in the
                                                UI Editor.
Italic tag: <i>

                                        Example that uses a Text
                                            component to add italics in the
                                                UI Editor.
Font color tag: <font color>

                                        Example that uses a Text
                                            component to add font color in the
                                                UI Editor.
Font face tag: <font face>

                                        Example that uses a Text
                                            component to add different fonts in the
                                                UI Editor.

On this page: