Menu
Lumberyard
User Guide (Version 1.14)

Navigation

Component entity system is in preview release and is subject to change.

Use the Navigation component on an AI entity for pathfinding and pathfollowing functionality. The Navigation component supports AI and other game logic by accepting navigation commands and dispatching movement requests.

Example: Navigation Procedure

The following example demonstrates how you can use the Navigation component. You can find the assets used in this procedure in the Starter Game Sample project.

To use the Navigation component

  1. Create a navigation area.

  2. Create an entity named box, and then do the following:

    1. Add a Mesh component to the entity.

    2. For its Mesh asset, select an object in the StarterGame\Objects directory.

    3. Move the object to a corner of your navigation area.

  3. To add a character, in the Asset Browser, in the StarterGame\slices directory, drag playerslice.slice to your viewport and then move the character to a different corner of your navigation area.

  4. In the Entity Outliner, do the following:

    1. Expand PlayerSlice and select the Jack entity.

    2. Add a Navigation component to Jack.

    3. In the Navigation component's Agent Type, select MediumSizedCharacters.

    This tells the navigation system that this character follows navigation paths as a medium-sized character.

  5. Add a Lua Script component to Jack.

  6. For Script, add the following Lua script:

    Note

    To create a Lua script, copy and paste the following text into a text file, and then change the .txt extension to .lua. Place the file in your game project directory so that you can select it in your level.

    local navigationmoversimplified = >>>>>>> ly1.13 { -- Adds properties to the Entity Inspector for easy setup of initial values. Properties = { -- This is the target toward which you'll move MoveToEntity = {default=EntityId(), description="Entity to move to."}, } } function navigationmoversimplified:OnActivate() -- Move! self.requestId = NavigationComponentRequestBus.Event.FindPathToEntity(self.entityId, self.Properties.MoveToEntity) end return navigationmoversimplified
  7. In the Entity Inspector, in the Lua Script's MoveToEntity property, click the target icon and in the Entity Outliner, select box. The text box appears in the MoveToEntity box.

    This tells the Jack character to move toward the box.

  8. Divide the navigation mesh into separate chunks, leaving a path between them. To block the character from traveling to the box in a straight line, do

    one of the following:

    The following example setup uses a static object.

    
                        Character, box, and obstacle setup for navigation
  9. Press Ctrl+G to play the game. Without any player input, the Jack character should move toward the opening in the navigation mesh and then toward the box. Press Esc to quit.

    Note

    If Jack moves too slowly, specify a higher value in the Navigation component's Agent Speed property to increase his speed.

  10. You can also do the following:

    • Make a complex path using exclusion areas, static objects, and terrain modifications.

    • Modify the static object to block Jack's path completely. Note that he does not move toward the target, because there isn't a path.

Navigation Component Properties

The Navigation component has the following properties:

Agent Type

Specifies this AI's entity type for navigation purposes. Defining the agent type determines which navigation area the entity follows in a scenario where there are different navigation meshes for larger vehicles and smaller humanoid bots. These agent types are defined in the lumberyard_version\dev\your_project_name\Scripts\AI\Navigation.xml file.

To define an agent type on your navigation area, see the Navigation Area component.

Agent Speed

Sets the speed of the agent while navigating.

Default value: 1

Agent Radius

Sets the entity radius for navigation purposes. Independent of physics or other collision concerns, the pathfinder uses this value to move around an area with obstacles while cutting corners.

Default value: 4

Arrival Distance Threshold

Sets the minimum distance from an end point when an entity's movement stops and is considered complete.

Default value: 0.25

Repath Threshold

Sets the minimum distance from the previously known location before an entity's new path is calculated.

Default value: 1

Move Physically

Applies movement through physics. You must add a Character Physics component to the entity for this functionality to work. We recommend this method to apply movement to a character during pathfollowing because it handles uneven terrain and character limitations properly. If deselected, movement applies directly to the entity's transform.

Default value: true

EBus Request Bus Interface

Use the following request functions with the NavigationComponentRequestBus event bus (EBus) interface to communicate with other components of your game.

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

Finds a requested path configuration.

Parameters

request – Allows the issuer of the request to override one, all, or none of the pathfinding configuration defaults for this entity.

Return

A unique identifier for this pathfinding request.

Scriptable

No

Creates a pathfinding request to navigate toward the specified entity.

Parameters

EntityId – ID of the entity toward to which you want to navigate.

Return

A unique identifier for the pathfinding request.

Scriptable

Yes

Stops all pathfinding operations for the provided requestId. Use the ID to ensure that the request you want to cancel is the request that is currently processing. If the specified requestId is different from the ID of the current request, then the stop command is ignored.

Parameters

requestId – ID of the request to cancel.

Return

None

Scriptable

Yes

EBus Notification Bus Interface

Use the following notification functions with the NavigationComponentNotificationBus event bus (EBus) interface to communicate with other components of your game.

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

Indicates that the pathfinding request was sent to the navigation system.

Parameters

requestId – ID of the path search request.

Return

None

Scriptable

Yes

Indicates that a path was found for the indicated request.

Parameters

requestID – ID of the found request for the path search.

currentPath – The path calculated by the pathfinder.

Return

Flag that indicates whether or not to traverse this path.

Scriptable

No

Indicates that traversal for the indicated request has started.

Parameters

requestId – ID of the request for which traversal has started.

Return

None

Scriptable

Yes

Indicates that traversal for the indicated request is in progress.

Parameters

requestId – ID of the request for which traversal is in progress.

Return

None

Scriptable

Yes

Indicates that traversal for the indicated request completed successfully.

Parameters

requestId – ID of the request for which traversal has completed.

distanceRemaining – The remaining distance in the path.

Return

None

Scriptable

Yes

Indicates that traversal for the indicated request was canceled before completing successfully.

Parameters

requestId – ID of the request for which traversal was canceled.

Return

None

Scriptable

Yes