Menu
Lumberyard
User Guide (Version 1.14)

Spline

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

You can use the Spline component to create line and curves in Lumberyard Editor. A spline is a curve that connects two or more specific points. You can use the Spline component to animate objects along a spline, such as a road or river.

Spline Properties


                Default Spline component properties.

See the following Spline properties:

Name Description
Visible

The Spline component always appears in the viewport, even if the entity is not selected.

Spline Type

Interpolation type to use between vertices. The component supports the following spline types:

  • Linear

  • Bézier

  • Catmull-Rom

Default value: Linear

Vertices

Vertices that the spline uses, which is a Vector3. You can switch the spline type and use the same values for the vertices.

Note

Linear and Bézier splines must have a minimum of two vertices. Catmull-Rom splines must have a minimum of four vertices.

Closed

Lets you specify if a spline is a closed or open loop.

Default value: False

Granularity

Number of steps for each segment that are in the spline. A step is one of the many short lines that are arranged to approximate the shape of the curve. A segment is defined as the part of the spline between two vertices.

This property is available only for Bézier and Catmull-Rom spline types.

Default value: 8

Valid values: 2 to 64

Knot Parameterization

Adjusts the curvature and smoothness of the spline. Specify a value to support parameterization.

A value of 0 creates a standard Catmull-Rom spline. A value of 1 creates a chordal Catmull-Rom spline.

For more information, see Knot Parameterization examples.

This property is available only for the Catmull-Rom spline type.

Default value: 0

Valid values: 0 to 1

By default, a Spline component has four vertices that are spaced evenly in a line. The vertex positions are all stored in the local space of the entity.


            Default Spline component with the linear type.

Working with Spline Components

You can move the vertices in the local space of the entity along each axis. Each vertex has a planar, linear, and surface manipulator; combined, these are called the translation manipulator. You can use the translation manipulator to move the vertices.

To change the vertex positions for a spline

  • Do one of the following:

    • In the Spline component property window, change the vertex values.

    • Select a vertex on the component and then drag the blue, green, or red arrow to the position that you want.

    • Select a vertex on the component and then drag the yellow point to move the vertex. The yellow point is the surface manipulator.

Note

The manipulators follow the grid snap setting that you can specify in Lumberyard Editor toolbar. For more information, see Using the Top Toolbar.


                Select a vertex and a translation manipulator appears in the Spline
                    component.

Note

If the entity is scaled, the manipulators continue to behave correctly, but the scaling must be uniform, so that the x, y, and z scale values match.

You can also select multiple vertices.

To select multiple vertices on a spline

  • Hold Shift and then select the vertices that you want. Selected vertices appear yellow.

    
                        Select and move multiple vertices.

    Note

    Currently, you cannot click and draw a box around the vertices to select them.

You can also snap a vertex to another position on the terrain.

To snap a vertex to another position

  1. Select a vertex.

  2. Hold Shift+Ctrl and then click another position on the terrain. The vertex snaps to that position.

You can also add vertices to the spline.

To add a vertex to a spline

  1. Pause over a line, and hold Ctrl. A preview appears where you can add the vertex.

    
                        A green point appears where you can add a vertex to the Spline
                            component.
  2. Click to add the vertex to the spline.

    
                        Click to add a vertex to the spline. A translation manipulator
                            appears where you add the vertex.

You can also delete vertices from the spline.

To delete a vertex from the spline

  1. Hold Alt and pause on a vertex. The vertex appears gray.

    
                        Select the vertex that you want to delete; the vertex color turns
                            gray.
  2. Click the vertex to delete it. You can also select a vertex and press Delete.

    
                        The deleted vertex is removed from the spline.

If you change the spline type, the component is updated to represent the new interpolation method.

Example Bézier


                    The linear spline changes to a Bézier spline.

Example Catmull-Rom


                    The linear spline changes to a Catmull-Rom spline.

Note

The first and last vertices of a Catmull-Rom spline are only control points; they do not form part of the curve. A well-formed Catmull-Rom spline must have a minimum of four vertices. The spline does not render if there are fewer than four vertices.

The following examples show how Catmull-Rom splines change when you adjust the Knot Parameterization property.

Example Knot Parameterization = 0


                    Knot Parameterization value is 0 for the Catmull-Rom
                        spline.

Example Knot Parameterization =1


                    Knot Parameterization value is 1 for the Catmull-Rom
                        spline.

Example Linear and Bézier Splines

The following examples are linear and Bézier splines with the same vertices, but with open and closed loops.


                    Example open and closed Linear and Bézier splines.

EBus Request Bus Interface

Use the following request functions with the SplineComponentRequestBus EBus interface to communicate with other components of your game. The Spline component also uses VertexContainer functions. For more information, see Vertex Containers.

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

Request Name Description Parameters Return Scriptable
GetSpline

Returns a constant pointer to the underlying spline type. You can use this function to query the spline against raycasts and positions. You can also request information, such as the length of the spline, its position, normal, and tangent at various points along the spline.

None

AZ::ConstSplinePtr Yes
ChangeSplineType

Changes the spline type. The AZ::u64value refers to the RTTI hash of the underlying spline type.

For example, AZ::LinearSpline::RTTI_Type().GetHash()).

AZ::u64 None Yes
SetClosed

Specify whether the spline forms a closed or open loop.

Boolean None Yes

Example

The following script uses the request bus interface.

local spline = SplineComponentRequestBus.Event.GetSpline(self.entityId); -- GetNearestAddressPosition local posSplineQueryResult = spline:GetNearestAddressPosition(Vector3(0, 0, 0)); posSplineQueryResult.splineAddress posSplineQueryResult.splineAddress.segmentIndex posSplineQueryResult.splineAddress.segmentFraction posSplineQueryResult.distanceSq -- GetNearestAddressRay local raySplineQueryResult = spline:GetNearestAddressRay(Vector3(10, -1, 0), Vector3(0, -1, 0)); raySplineQueryResult.splineAddress.segmentIndex raySplineQueryResult.splineAddress.segmentFraction raySplineQueryResult.distanceSq raySplineQueryResult.rayDistance local splineAddressFromDistance = spline:GetAddressByDistance(3.0); local splineAddressFromFraction = spline:GetAddressByFraction(0.75); -- Test SplineAddress Constructor (1 param) local splineAddress_1 = SplineAddress(2); -- Test SplineAddress Constructor (2 params) local splineAddress_2 = SplineAddress(1, 0); spline:GetPosition(splineAddress_1) spline:GetNormal(splineAddress_1) spline:GetTangent(splineAddress_1) spline:GetLength(splineAddress_1) spline:GetSplineLength() spline:GetSegmentLength(1) spline:GetSegmentCount() spline:GetSegmentGranularity() local aabb = spline:GetAabb(Transform:CreateIdentity()); local closed = spline:IsClosed(); local firstVertex = spline.vertexContainer[1]; local lastVertex = spline.vertexContainer[spline.vertexContainer:Size()]; -- Attention: You can use the bus interface directly, but here (at the moment at least) indexing will start from 0, not 1 as is the norm in Lua. Instead, you should use the functions directly on the VertexContainer, listed below SplineComponentRequestBus.Event.AddVertex(self.entityId, lastVertex + Vector3(1, 2, 3)); SplineComponentRequestBus.Event.UpdateVertex(self.entityId, 0, firstVertex + Vector3(1, 2, 3)); SplineComponentRequestBus.Event.InsertVertex(self.entityId, spline.vertexContainer:Size() - 1, lastVertex + Vector3(1, 2, 3)); SplineComponentRequestBus.Event.ClearVertices(self.entityId); SplineComponentRequestBus.Event.RemoveVertex(self.entityId, spline.vertexContainer:Size() - 1); -- Prefer these functions - indexing will start from 1 spline.vertexContainer:AddVertex(lastVertex + Vector3(1, 2, 3)); spline.vertexContainer:UpdateVertex(1, firstVertex + Vector3(1, 2, 3)); spline.vertexContainer:InsertVertex(spline.vertexContainer:Size(), lastVertex + Vector3(1, 2, 3)); spline.vertexContainer:ClearVertices(); spline.vertexContainer:RemoveVertex(spline.vertexContainer:Size());