Developer Guide Version 1 - d3bqhfbip4ze4a.cloudfront.net · that is likely to cause confusion among customers, or in any manner that disparages or discredits Amazon. All other trademarks

LumberyardDeveloper Guide

Version 1.8

Lumberyard Developer Guide

Lumberyard: Developer GuideCopyright © 2017 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.

Amazon's trademarks and trade dress may not be used in connection with any product or service that is not Amazon's, in any mannerthat is likely to cause confusion among customers, or in any manner that disparages or discredits Amazon. All other trademarks notowned by Amazon are the property of their respective owners, who may or may not be affiliated with, connected to, or sponsored byAmazon.


Table of ContentsLumberyard for Programmers ............................................................................................................... 1AI ..................................................................................................................................................... 3

AI System Concepts ................................................................................................................... 3AI System Overview ........................................................................................................... 4Pathfinding Costs ............................................................................................................... 7Sensory Models ................................................................................................................ 10Flight ............................................................................................................................... 15AI C++ Class Hierarchy ..................................................................................................... 16AI System Concept Examples ............................................................................................. 16

AI Bubbles System ................................................................................................................... 18Message Display Types ..................................................................................................... 18Specifying Notification Display Types ................................................................................... 19

AI Tactical Point System ............................................................................................................ 20Tactical Point System Overview .......................................................................................... 21TPS Query Execution Flow ................................................................................................ 22TPS Querying with C++ ..................................................................................................... 22TPS Querying with Lua ...................................................................................................... 24TPS Query Language Reference ......................................................................................... 25Point Generation and Evaluation ......................................................................................... 28Integration with the Modular Behavior Tree System ................................................................ 30Future Plans and Possibilities ............................................................................................. 30

Navigation Q & A ..................................................................................................................... 31Big Triangles and Small Links Between Them ....................................................................... 31Path Following .................................................................................................................. 32Auto-Disabling .................................................................................................................. 32

Path Following .......................................................................................................................... 32Goalop "Followpath" .......................................................................................................... 32COPTrace::ExecuteTrace and COPTrace::Execute ................................................................ 33COPTrace::Execute2D ....................................................................................................... 33

Movement System .................................................................................................................... 33Using the Movement System .............................................................................................. 34Potential Improvements ...................................................................................................... 34

Auto-Disable ............................................................................................................................. 35Global auto-disable ........................................................................................................... 35Per-AI auto-disable ........................................................................................................... 35

AI Scripting .............................................................................................................................. 35Communication System ..................................................................................................... 36Factions ........................................................................................................................... 42Modular Behavior Tree ...................................................................................................... 43Refpoints ......................................................................................................................... 85Signals ............................................................................................................................ 86

Animation ........................................................................................................................................ 97Animation Overview .................................................................................................................. 97

Linear Animations ............................................................................................................. 97Interactive Animations ........................................................................................................ 98Scripted Animations .......................................................................................................... 99

Animation Events .................................................................................................................... 100Marking Up Animations with Events ................................................................................... 100Receiving Animation Events in the Game Code ................................................................... 100

Limb IK Technical ................................................................................................................... 100Setting Up ...................................................................................................................... 100Using LimbIK from Code .................................................................................................. 100

Animation Streaming ................................................................................................................ 101Animation Data ............................................................................................................... 101

Version 1.8iii


Animation Header Data .................................................................................................... 101Animation Controller Data ................................................................................................. 101

Animation Debugging ............................................................................................................... 103Layered Transition Queue Debugging ................................................................................ 103CommandBuffer Debugging .............................................................................................. 107Warning Level ................................................................................................................ 108

Fall and Play .......................................................................................................................... 108Time in the Animation System .................................................................................................. 109

Segmentation ................................................................................................................. 110Playback Speed .............................................................................................................. 111Segmented Parametric Animation ...................................................................................... 111Animation with Only One Key ........................................................................................... 111Direction of Time ............................................................................................................ 112Time within Controllers ..................................................................................................... 112

Asset Builder API ............................................................................................................................ 113Builder Modules ...................................................................................................................... 113Creating a Builder Module ........................................................................................................ 113

Main Entry Point ............................................................................................................. 114Lifecycle Component ....................................................................................................... 114Creating a Builder ........................................................................................................... 116

Message Loggging .................................................................................................................. 119AZ Code Generator ......................................................................................................................... 120

Workflow Summary ................................................................................................................. 121Waf ....................................................................................................................................... 121Clang .................................................................................................................................... 121Intermediate JSON Data .......................................................................................................... 121AZ Code Generator and Python ................................................................................................ 122Template Drivers and Template Rendering ................................................................................. 123Generated Files ...................................................................................................................... 123AZ Code Generator Integration with Waf .................................................................................... 124

Basic Integration ............................................................................................................. 125Advanced Integration ....................................................................................................... 125Input Files ...................................................................................................................... 126Template Drivers ............................................................................................................. 126Command Line Parameters .............................................................................................. 126Waf Specific Options ....................................................................................................... 127

AZ Code Generator Parameters ................................................................................................ 127Waf Parameters .............................................................................................................. 127Clang Compilation Parameters .......................................................................................... 127Intermediate Data ............................................................................................................ 128Front End ....................................................................................................................... 128AZ Code Generator Parameter List .................................................................................... 128

Code Generation Templates ..................................................................................................... 130Simple Example .............................................................................................................. 131Complex Example ........................................................................................................... 131Template Data ................................................................................................................ 132

Template Drivers ..................................................................................................................... 133Specifying Drivers in Waf ................................................................................................. 133Creating a Template Driver in Python ................................................................................. 133Minimal Template Driver ................................................................................................... 135Rendering Templates ....................................................................................................... 136Configuring Automatic Build Injection ................................................................................. 136Preprocessing Intermediate Data ....................................................................................... 136

Custom Code Generator Annotations ......................................................................................... 137Reference Annotations ..................................................................................................... 137Helper Macros ................................................................................................................ 137Example Annotations ....................................................................................................... 138

Version 1.8iv


Waf Debugging with AZ Code Generator .................................................................................... 141Prerequisites .................................................................................................................. 142Identifying and Configuring Debug Output ........................................................................... 142Setting Up PyCharm for Debugging Waf ............................................................................. 142

Template Driver Debugging ...................................................................................................... 143Debugging the AZ Code Generator Utility ................................................................................... 144

Prerequisites .................................................................................................................. 144Debugging the AZ Code Generator Utility from the Waf build ................................................. 145Setting Visual Studio Debug Arguments ............................................................................ 145Setting Xcode Debug Arguments ...................................................................................... 146

Intermediate JSON Data Format ................................................................................................ 146AZ Modules (Preview) ...................................................................................................................... 148

Comparing AZ Modules to Legacy Modules ............................................................................... 148A Self-Aware Method of Initialization ................................................................................. 149

Relationship with the AZ Framework ......................................................................................... 150Smarter Singletons ................................................................................................................. 150Current Lumberyard AZ Modules .............................................................................................. 150

LmbrCentral .................................................................................................................. 150LmbrCentralEditor .......................................................................................................... 150

Parts of an AZ Module, Explained ............................................................................................. 150The Module Class ........................................................................................................... 151The EBus ....................................................................................................................... 152The System Component Class .......................................................................................... 153Calling the Module from External Code .............................................................................. 155

System Components ................................................................................................................ 155Smart Initialization Order .................................................................................................. 155Easily Configurable Components ....................................................................................... 156Writing System Components ............................................................................................. 156Required System Components .......................................................................................... 157

Gems and AZ Modules ............................................................................................................ 157Structure of a Gem ......................................................................................................... 157Waf Integration ............................................................................................................... 158Gems Built as AZ Modules ............................................................................................... 158

Creating an AZ Module That Is Not a Gem ................................................................................. 158A. Start with a Gem ........................................................................................................ 158B. Modify the AZ Module Declaration ................................................................................. 159C. Remove CryEngine References (Optional) ..................................................................... 159D. Modify the Wscript and Waf Spec Files .......................................................................... 160E. Configure Your Project to Load the New Module ............................................................. 160F. Add the Module's Public Interfaces to Your Project's Include Paths ..................................... 161

Configuring System Entities ...................................................................................................... 161Application Descriptor Files ............................................................................................. 162

The AZ Bootstrapping Process .................................................................................................. 163Cloud Canvas ................................................................................................................................. 165

Features ................................................................................................................................ 165Example Uses ........................................................................................................................ 165Tools ..................................................................................................................................... 166Knowledge Prerequisites .......................................................................................................... 166Cloud Canvas Overview ........................................................................................................... 167

Prerequisites ................................................................................................................. 167AWS, Cloud Canvas, and Lumberyard .............................................................................. 167Amazon Web Services Supported by Cloud Canvas ............................................................. 168Understanding Cloud Canvas Resource Manager ................................................................. 169Cloud Gems Overview ..................................................................................................... 172Pricing ........................................................................................................................... 173Tutorial: Getting Started with Cloud Canvas ........................................................................ 173Don't Die Sample Project ................................................................................................. 182

Version 1.8v


Cloud Canvas Game Play Design and Engineering Guide ............................................................. 187Cloud Canvas Tools in Lumberyard Editor .......................................................................... 187Managing Cloud Canvas Profiles ....................................................................................... 188Using Resource Manager in Game Design .......................................................................... 188Cloud Gems ................................................................................................................... 189Cloud Canvas Flow Graph Node Reference ........................................................................ 200

Cloud Canvas Software Engineering Guide ................................................................................. 219Resource Manager in Depth ............................................................................................. 219Cloud Gems Framework ................................................................................................... 255

Administering Cloud Canvas ..................................................................................................... 286Setting Up a Project to Use Resource Manager ................................................................... 286Working with Deployments ............................................................................................... 288Understanding the Resource Manager Security System ........................................................ 293

Using the Cloud Canvas Command Line .................................................................................... 299Syntax ........................................................................................................................... 299Configuration .................................................................................................................. 299Common Arguments ........................................................................................................ 300Command Summary ........................................................................................................ 300Commands ..................................................................................................................... 301

Component Entity System ................................................................................................................ 316Programmer's Guide to Entities and Components ......................................................................... 316

Creating a Component ..................................................................................................... 317Registering Your Component ............................................................................................ 319Reflecting a Component for Serialization and Editing ............................................................ 319Defining and Using Component Services ............................................................................ 324Editor Components .......................................................................................................... 325Creating System Components ........................................................................................... 328Components and EBuses ................................................................................................. 329Tick Bus and Components ............................................................................................... 333Exposing Custom Components to Track View for Animation ................................................... 334Components and EBuses: Best Practices ........................................................................... 337

Behavior Context ..................................................................................................................... 339Reflection API ................................................................................................................. 339Example ........................................................................................................................ 342

Slices and Dynamic Slices ....................................................................................................... 344Anatomy of a Slice .......................................................................................................... 344Working with Dynamic Slices ............................................................................................ 344Instantiating Dynamic Slices ............................................................................................. 345

Controller Devices and Game Input ................................................................................................... 346Action Maps ........................................................................................................................... 346

Initializing the Action Map Manager .................................................................................... 346Receiving Actions During Runtime ..................................................................................... 346

CryInput ................................................................................................................................. 347IInput ............................................................................................................................. 347IInputEventListener .......................................................................................................... 347SInputEvent .................................................................................................................... 347IInputDevice ................................................................................................................... 347

Setting Up Controls and Action Maps ......................................................................................... 348Action Maps ................................................................................................................... 349Action Filters .................................................................................................................. 350Controller Layouts ........................................................................................................... 350Working with Action Maps During Runtime .......................................................................... 351Default Controller Mapping ............................................................................................... 351Key Naming Conventions ................................................................................................. 352

CryCommon ................................................................................................................................... 355CryExtension .......................................................................................................................... 355

Composites .................................................................................................................... 356

Version 1.8vi


Shared and raw interface pointers ..................................................................................... 356GUIDs ........................................................................................................................... 356ICryUnknown .................................................................................................................. 357ICryFactory ..................................................................................................................... 358ICryFactoryRegistry ......................................................................................................... 358Additional Extensions ....................................................................................................... 359Glue Code Macros .......................................................................................................... 361CryExtension Samples ..................................................................................................... 366Using Extensions ............................................................................................................ 367Implementing Extensions Using the Framework ................................................................... 369

CryString ................................................................................................................................ 378How to Use Strings as Key Values for STL Containers ......................................................... 378Further Usage Tips ......................................................................................................... 378

ICrySizer ................................................................................................................................ 379How to use the ICrySizer interface .................................................................................... 379

Serialization Library ................................................................................................................. 379Tutorial .......................................................................................................................... 379Use Cases ..................................................................................................................... 382

Demo and Video Capture ................................................................................................................. 390Capturing Video and Audio ....................................................................................................... 390

Preparation ..................................................................................................................... 390Video Settings ................................................................................................................ 390Starting and Ending the Video Recording ............................................................................ 392Audio Settings ................................................................................................................ 392Configuration Files .......................................................................................................... 393

Recording Time Demos ............................................................................................................ 394Overview ........................................................................................................................ 394Recording Controls .......................................................................................................... 394Related Console Variables ............................................................................................... 394

Entity System ................................................................................................................................. 396Entity Property Prefixes ............................................................................................................ 396Creating a New Entity Class ..................................................................................................... 397Entity Pool System .................................................................................................................. 399

Editor Usage .................................................................................................................. 399Static versus Dynamic Entities .......................................................................................... 400Entity Pool Definitions ...................................................................................................... 400Entity Pool Creation ......................................................................................................... 402Creating and Destroying Static Entities with Pools ................................................................ 402Creating and Destroying Dynamic Entities with Pools ............................................................ 405Serialization .................................................................................................................... 405Listener/Event Registration ............................................................................................... 406Debugging Utilities .......................................................................................................... 407

Entity ID Explained .................................................................................................................. 408Adding Usable Support on an Entity .......................................................................................... 408

Overview ........................................................................................................................ 408Preparing the Script ......................................................................................................... 409Implementing IsUsable ..................................................................................................... 409Implementing OnUsed ...................................................................................................... 409

Entity Scripting ........................................................................................................................ 409Structure of a Script Entity ................................................................................................ 409Using Entity State ........................................................................................................... 413Using Entity Slots ............................................................................................................ 414Linking Entities ............................................................................................................... 415Exposing an Entity to the Network ..................................................................................... 416

Event Bus (EBus) ........................................................................................................................... 419Bus Configurations .................................................................................................................. 419

Single Handler ............................................................................................................... 419

Version 1.8vii


Many Handlers ............................................................................................................... 420EBus with Addresses and a Single Handler ......................................................................... 421EBus with Addresses and Many Handlers ........................................................................... 423

Synchronous vs. Asynchronous ................................................................................................. 424Additional Features .................................................................................................................. 424Usage and Examples ............................................................................................................... 425

Declaring an EBus .......................................................................................................... 425EBus Configuration Options ............................................................................................. 426Implementing a Handler ................................................................................................... 427Sending Messages to an EBus ......................................................................................... 427Retrieving Return Values .................................................................................................. 428Return Values from Multiple Handlers ............................................................................... 428Asynchronous/Queued Buses ............................................................................................ 429

File Access .................................................................................................................................... 430CryPak File Archives ............................................................................................................... 430

Features ........................................................................................................................ 430Unicode and Absolute Path Handling ................................................................................. 430Layering ......................................................................................................................... 430Slashes ......................................................................................................................... 431Special Folder Handling ................................................................................................... 431Internals ......................................................................................................................... 431Creating a pak file using 7-Zip .......................................................................................... 431Dealing with Large Pak Files ............................................................................................ 431Accessing Files with CryPak ............................................................................................. 432

Tracking File Access ............................................................................................................... 438CVars ............................................................................................................................ 438Where invalid access is defined ........................................................................................ 438

Graphics and Rendering .................................................................................................................. 440Render Nodes ........................................................................................................................ 440

Creating a New Render Node ........................................................................................... 441TrueType Font Rendering ......................................................................................................... 444

Supported Features ......................................................................................................... 444Useful Console Commands .............................................................................................. 445

Generating Stars DAT File ....................................................................................................... 445File Format .................................................................................................................... 445

Anti-Aliasing and Supersampling ............................................................................................... 446Controlling Anti-Aliasing .................................................................................................... 446Controlling Supersampling ................................................................................................ 448

Lua Scripting .................................................................................................................................. 449Working with Lua Scripting ....................................................................................................... 449

Running Scripts .............................................................................................................. 449Reloading Scripts During Runtime ..................................................................................... 450Recommended Reading ................................................................................................... 450Lua Editor ...................................................................................................................... 450Using the Lua Remote Debugger ...................................................................................... 454Using the Lua XML Loader ............................................................................................... 455

Component Entity Lua Scripting Reference ................................................................................. 458Writing Lua Scripts for the Component Entity System ........................................................... 458Loading Canvases in Lua ................................................................................................. 466Lua API Reference .......................................................................................................... 467

Legacy Lua Scripting Reference ................................................................................................ 530Entity System Script Callbacks .......................................................................................... 531Game Rules Script Callbacks ............................................................................................ 532Common Lua Globals and Functions .................................................................................. 534EntityUtils Lua Functions .................................................................................................. 538Lua Vector and Math Functions ......................................................................................... 541Physics Lua Functions ..................................................................................................... 551

Version 1.8viii


Lua ScriptBind Reference ................................................................................................. 552Integrating Lua and C++ .................................................................................................. 753

Networking System .......................................................................................................................... 755Tutorial: Getting Started with Multiplayer .................................................................................... 755

Prerequisites .................................................................................................................. 755Step 1: Creating a Level and Adding a Sphere and a Box ..................................................... 756Step 2: Binding Sphere Transform Components to the Network .............................................. 757Step 3: Connecting a Client to the Server ........................................................................... 757Related Tasks and Tutorials ............................................................................................. 757Configuring the Multiplayer Sample for Amazon GameLift ...................................................... 758

Overview ................................................................................................................................ 759NetBinding ..................................................................................................................... 760GridMate ........................................................................................................................ 760Other GridMate Features .................................................................................................. 761CryNetwork Backward Compatibility (Deprecated) ................................................................ 761Networking Architecture .................................................................................................... 762Carrier ........................................................................................................................... 762Marshalling ..................................................................................................................... 766Sessions ........................................................................................................................ 770Replicas ......................................................................................................................... 778Replica Manager ............................................................................................................. 788

Using Lumberyard Networking ................................................................................................... 790Synchronizing Game State Using Components .................................................................... 791Synchronizing Game State Using Scripts ............................................................................ 796Using Encyrption ............................................................................................................. 796Controlling Bandwidth Usage ............................................................................................ 800Setting up a Lobby .......................................................................................................... 802Using Amazon GameLift ................................................................................................. 802Useful Console Commands .............................................................................................. 803

CryNetwork Backward Compatibility ........................................................................................... 804RMI Functions ................................................................................................................ 804Network Serialization and Aspects ..................................................................................... 807

Physics .......................................................................................................................................... 808Physics Scripting Guide ........................................................................................................... 808

Threading ....................................................................................................................... 808Physics Scripting Tips and Tricks ...................................................................................... 809Scripting with Physics Example ......................................................................................... 810

Geometries ............................................................................................................................. 810Geometry Management Functions ..................................................................................... 811

Physical Entities ...................................................................................................................... 812Creating and managing entities ......................................................................................... 812

Functions for Entity Structures .................................................................................................. 814Common Functions ......................................................................................................... 815Living Entity-Specific Functions ......................................................................................... 817Particle Entity-Specific Functions ....................................................................................... 818Articulated Entity-Specific Functions ................................................................................... 819Rope Entity-Specific Functions .......................................................................................... 820Soft Entity-Specific Functions ............................................................................................ 821

Collision Classes ..................................................................................................................... 822Setup ............................................................................................................................ 822Code ............................................................................................................................. 822Types ............................................................................................................................ 823Filtering the collision ........................................................................................................ 823Interface ........................................................................................................................ 824

Functions for World Entities ...................................................................................................... 824Advancing the Physical World Time State .......................................................................... 824Returning Entities with Overlapping Bounding Boxes ............................................................ 824

Version 1.8ix


Casting Rays in an Environment ....................................................................................... 826Creating Explosions ......................................................................................................... 826

Profiler ........................................................................................................................................... 828Profiler Tutorial ....................................................................................................................... 828

Registering Your Application ............................................................................................. 829Launching Profiler ........................................................................................................... 829Capturing Data ............................................................................................................... 829Inspecting Data ............................................................................................................... 830Playing Back Data ........................................................................................................... 830Exporting Data ................................................................................................................ 831

Creating and Using Annotations ................................................................................................ 831Using Annotations .......................................................................................................... 832Creating Annotations ...................................................................................................... 832Viewing Annotations in Trace Messages Profiler ................................................................. 833

Using Profiler for Networking .................................................................................................... 833Prerequisites ................................................................................................................. 833Carrier Profiler ................................................................................................................ 833Replica Activity Profiler .................................................................................................... 834

Using the Profiler for CPU Usage .............................................................................................. 836Understanding the Tree View ............................................................................................ 836Controlling the Display ..................................................................................................... 837

Using Profiler for VRAM ........................................................................................................... 838Notes ............................................................................................................................ 839Understanding the Captured Data ...................................................................................... 839Inspecting the Data ......................................................................................................... 839

Using GridHub ........................................................................................................................ 840Registering an Application in GridHub ................................................................................ 840Viewing and Configuring GridHub ..................................................................................... 841Troubleshooting GridHub .................................................................................................. 841

System .......................................................................................................................................... 843Memory Handling .................................................................................................................... 843

Hardware Memory Limitations ........................................................................................... 843Choosing a Platform to Target .......................................................................................... 843Budgets ......................................................................................................................... 844Allocation Strategy with Multiple Modules and Threads ......................................................... 844Caching Computational Data ............................................................................................. 844Compression .................................................................................................................. 844Disk Size ....................................................................................................................... 844Total Size ...................................................................................................................... 844Address Space ............................................................................................................... 845Bandwidth ...................................................................................................................... 845Latency .......................................................................................................................... 845Alignment ....................................................................................................................... 845Virtual Memory ............................................................................................................... 845Streaming ...................................................................................................................... 846

Streaming System ................................................................................................................... 846Low-level Streaming System ............................................................................................. 846Streaming and Levelcache Pak Files .................................................................................. 851Single Thread IO Access and Invalid File Access ................................................................. 853High Level Streaming Engine Usage .................................................................................. 853

Text Localization and Unicode Support ....................................................................................... 854Terminology .................................................................................................................... 854What encoding to use? .................................................................................................... 855How does this affect me when writing code? ....................................................................... 857How does this affect me when dealing with text assets? ........................................................ 858Utilities provided in CryCommon ........................................................................................ 858Further reading ............................................................................................................... 858

Version 1.8x


CryLog ................................................................................................................................... 859CryLog Logging Functionality ............................................................................................ 859Verbosity Level and Coloring ............................................................................................ 859Log Files ........................................................................................................................ 860Console Variables ........................................................................................................... 860

CryConsole ............................................................................................................................ 860Color coding ................................................................................................................... 860Dumping all console commands and variables ..................................................................... 861Console Variables ........................................................................................................... 861Adding New Console Commands ...................................................................................... 861Console Variable Groups ................................................................................................. 862Deferred execution of command line console commands ....................................................... 863CVar Tutorial .................................................................................................................. 864

Lumberyard Blog, Forums, and Feedback ........................................................................................... 867

Version 1.8xi


Lumberyard for Programmers

The Lumberyard Developer Guide is intended for programmers or anyone working directly with theLumberyard code.

This guide includes the following sections:

• AI (p. 3)

Describes a variety of AI features that process navigation and individual and group behaviors, anddescribes convenient tools such as a Visual AI debugger, behavior tree visual editor, and a visual flowgraph editor.

• Animation (p. 97)

Contains tools to create both linear (video) and interactive animation. Interactive animation conveys AIand avatar (player) behavior, with sequences dependent on player choices in gameplay.

• Asset Builder API (p. 113)

Use the asset builder API to develop a custom asset builder that can process any number of asset types,generate outputs, and return the results to the asset processor for further processing. A custom buildercan be especially useful in a large project that has custom asset types.

• AZ Code Generator (p. 120)

AZ Code Generator is a command line utility that generates source code (or any data or text) fromspecially tagged source code. You can use it when the structure of the intended code is known inadvance.

• AZ Modules (Preview) (p. 148)

AZ modules are new, Amazon-created code libraries that plug into Lumberyard games and tools. TheseAZ modules implement specific initialization functions. When a Lumberyard application starts, it loadseach AZ module and calls the corresponding

• Cloud Canvas (p. 165)

Cloud Canvas is Lumberyard's technology for connecting your game to Amazon Web Services. WithCloud Canvas, you can use AWS to implement cloud-hosted features and create asynchronousmultiplayer games. Using AWS means you no longer have to acquire, configure, or operate host serversto implement connected gameplay.

• Component Entity System (p. 316)

The component entity system is a new Amazon-created way of creating components that is superior to(and that will eventually replace) the legacy Entity System (p. 396).

Version 1.81


• Controller Devices and Game Input (p. 346)

Describes Lumberyard's support for input devices such as keyboards, mice, and joysticks, and showshow to set up controls and action maps.

• CryCommon (p. 355)

Describes game engine interfaces, including CryExtension, which you can use to refactor Lumberyardfeatures into extensions for ease of use; CryString, which is a custom reference-counted string class; anda serialization library, which separates user serialization code from actual storage format and makes iteasy to change formats.

• Demo and Video Capture (p. 390)

Describes how to use Lumberyard Editor or the Lumberyard standalone Launcher to recordbenchmarking videos and capture audio.

• Entity System (p. 396)

Describes the creation and management of entities, which are objects placed inside a level that playerscan interact with. This section contains topics such as creating a new entity class, entity pools, and entityscripting.

• Event Bus (EBus) (p. 419)

Event buses are Lumberyard's general purpose system for dispatching messages. EBuses minimize harddependencies between systems, are event-driven (which eliminates polling), handle concurrency well,and enable predictability by providing support for the ordering of handlers on a given bus.

• File Access (p. 430)

Describes how to compress game content files and how to track invalid file reads that can potentially stallthe performance of a game.

• Graphics and Rendering (p. 440)

Lumberyard's shading core uses the same physical parameters that are used in high end film renderingpipelines. This section covers render nodes, true type font rendering, and the star data used in skyrendering. It also describes how to control anti-aliasing so that you can produce graphics from very sharpimages to softer blurred images.

• Lua Scripting (p. 449)

Lua is Lumberyard's scripting language. This section contains a Lua scripting reference and providestopics on Lua script usage, Lua and C++ integration, the Lua remote debugger, and the Lua XML Loader.

• Networking System (p. 755)

Describes GridMate, Lumberyard's networking subsystem, and contains topics on multiplayer setup, thesession service, controlling bandwidth usage, and synchronizing game state using the GridMate replicaframework.

• Physics (p. 808)

Describes the Lumberyard physics system and how to interact with the physics engine. This sectionshows you how to create a physical world object, fill the world with geometries and physical entities, andcontrol the entities with the functions described.

• Profiler (p. 828)

Profiler is a Lumberyard tool that can capture, save, and analyze network, CPU, and VRAM usagestatistics. You can used the saved data to analyze network usage frame by frame, fix problems in the useof network bandwidth, and optimize the performance of your game.

• System (p. 843)

Contains topics on memory handling, streaming, localization, logging, and console tools.

Version 1.82

Lumberyard Developer GuideAI System Concepts

AI

This section describes the AI system. It includes a general overview of key concepts, describes systemcomponents, and provides an AI scripting manual.

This section includes the following topics:

• AI System Concepts (p. 3)

• AI Bubbles System (p. 18)

• AI Tactical Point System (p. 20)

• Navigation Q & A (p. 31)

• Path Following (p. 32)

• Movement System (p. 33)

• Auto-Disable (p. 35)

• AI Scripting (p. 35)

AI System ConceptsKey features of the AI system include the following:

Navigation

• Navigation with little or no assistance from the designers

• Multi-layer navigation (flying, swimming, zero-gravity) or simple 2D navigation

• Smart objects for special navigation and interactions

Individual AI

• Easy-to-use static and dynamic covers (such as behind movable vehicles)

• Dynamic tactical points (such as cover points, ambush points, patrol waypoints)

Version 1.83

Lumberyard Developer GuideAI System Overview

• Behavior trees, to select behaviors based on values of Boolean variables

• Customizable perception (such as vision, sound, memory, sixth sense)

Group and Global AI

• Group behavior trees, to define group tactics

• Formations, to move AI characters in some orderly fashion

• Factions (such as friends, neutrals, enemies)

• Visual flow graphs of game logic, with macro-nodes for reused sub-flow graphs

MMO-ready

• Support for streaming big maps

User-friendly

• Visual AI debugger to log signals, behavior changes, goal changes, user comments

• Behavior tree visual editor

• Visual flow graph editor and debugger (with visual flow propagation and break points)

This section includes the following topics:

• AI System Overview (p. 4)

• Pathfinding Costs (p. 7)

• Sensory Models (p. 10)

• Flight (p. 15)

• AI C++ Class Hierarchy (p. 16)

• AI System Concept Examples (p. 16)

AI System OverviewThis section outlines basic concepts related to the AI system.

Navigation

• Default navigation system

• Triangulation

• 2D terrain-based navigation

• Uses cylindrical objects (such as trees) and forbidden areas

• Navigation modifiers

• Human waypoints – Need to be place manually but connections can be generated automatically

• Flight – Information about navigable volumes for flying entities

• Volume – General volume navigation, such as for oceans

• Multi-layer navigation system

• Smart object system: allows AI agents to move in special ways

• AI territories & waves

• Control number of active AI agents (through flow graph logic)

Version 1.84


• Activate, deactivate, and spawn all AI agents assigned to a territory using a single FG node

• AI waves can be attached to AI territories and allow independent AI activations

• AI waves automatically handle entity pool issues for assigned AI agents, such as loading/unloading

In general, a search is time-sliced to use 0.5 ms per AI frame (configured using the console variableai_PathfinderUpdateTime). Options for pathfinding techniques include high priority, straight, and partial.Updates for human waypoints are heavy but time-sliced. The navigation graph is optimized but needsmemory. Navigation data is generated offline in Editor. With multi-layer navigation, the navigation mesh isregenerated when the designer modifies the map.

Decision Making

• Behavior selection system – Uses behavior trees to select AI behaviors

• Cover system – Provides AI agents with static and dynamic covers

• Smart object system – Allows AI agents to interact with their environment

• Interest system – Allows AI agents to perform intelligent actions when not alerted

Tactical

• Tactical point system (TPS) – Allows AI agents to ask intelligent questions about their environment (suchas where to hide or where to attack)

• Faction system – Determines levels of hostility between AI agents

• Group coordination system – Uses coordination selection trees to select group behaviors

• Formation system – Allows AI agents to move in formations

• Cluster detector – detects clusters of points in space and subdivides them into separate groupings thatsatisfy specific properties (using a modified K-mean algorithm); used with AISquadManager to groupdifferent AI agents into dynamic squads

World-Interfacing

• Signals – To trigger events and/or change behaviors

• Perception system

• Perception handler (legacy, usually per game)

• Target track system – Uses configurable ADSR envelopes to represent incoming stimuli

• Communication system – Allows AI agents to play sound/voice/animation events

Development Environment

The design and development environment includes the following components:

• Game object model – Entity, movement controller, extensions

• Actor & vehicle system – Health, camera, IK, weapons, animation, etc.

• Flow graph – Visual definition of game logic

• AI debug renderer – HUD, geometric primitives, text labels, graphs, etc.

• Editor

• AI entities – Properties, flow graphs, scripts

Version 1.85


• Entity archetypes – Templates for properties of individual AI agents

• AI shapes – AI territories, AI paths, forbidden areas

• Navigation – Navigation modifiers used instead of triangulation

• Cover surfaces – CoverSurface anchors to indicate where cover should be

• Visual AI debugger – Recording AI signals, active behaviors, goals, stimuli, etc.

• Scripting with Lua

• Entity definitions (including entity flow graph nodes)

• AI behavior definitions

• Group behavior definitions

• Library or shared Lua code (game rules, basic entities)

• Blackboards to share information globally or among groups

• Examples of AI functionality available in Lua:

• AI.Signal

• AI.FindObjectOfType

• AI.GetAttentionTargetType (Visual, Memory, Sound, None)

• AI.GetAttentionTargetAIType (Actor, Grenade, Car, etc.)

• AI.GetRefPointPosition

• AI.DistanceToGenericShape

• AI.SetBehaviorVariable (to change behavior)

• AI.CanMelee

• AI.RecComment (make comment for Visual AI Debugger

• Scripting with XML

• Behavior/coordination trees

• AI communications

• Items (e.g., weapons)

• Entity system

• Spatial queries – GetPhysicalEntitiesInBox()

• AI agents and vehicles are entities in the Entity system

• To spawn an entity, its Entity class is required – Can be defined either using the .ent file in Game\Entities OR through a C++ call to RegisterFactory() in game code

• An entity pool can be used to limit the number of active AI agents per each specified Entity class.

• AI Debugger and AI Debug Draw

• Use AI Debugger to track multiple features, including active behavior, signal received, attention target,comments, etc.

• ai_DebugDraw

• 1 – Basic info on AI agents (selected by ai_DrawAgentStats)

• 74 – All of the navigation graph (can be slow)

• 79 – Parts of the navigation graph around the player

• ai_statsTarget – Detailed info for the specified AI

• ai_DebugTargetTracksAgent – Perception information on the specified AI

• ai_Recorder_Auto – Record AI activity in Editor game mode for AI Debugger

• ai_DebugTacticalPoints – Debug TPS queries

• ai_DrawPath – Draw the path of the specified AI (optionally specify "all" for all AI agents)

• ai_DrawPathFollower – Draw the actual path being followed

• ai_DrawSmartObjects – Display smart objects and their classes and attributes

• ai_DebugDrawEnabledActors – List currently enabled AI agents.

Version 1.86

Lumberyard Developer GuidePathfinding Costs

Execution Context

• AI update is called every frame, but are fully updated only at ~10Hz

• Some AI subsystems use independent time-slicing (pathfinding, tactical point, dynamic waypointsupdating, smart object, interest, and dead bodies removal)

• Some services can be called synchronously from game code (such as tactical point system (TPS)queries)

Pathfinding CostsFor agents to behave in a believable way, they need to find paths that are appropriate for their currentstate. Sometimes these paths will take the most direct route; other times they will be longer paths tomaximize use of roads, cover, or other properties of the environment. The current system needs to beextended to support this. The pathfinding system uses A* to find minimal-cost paths.

The cost of a path is given by the sum of the costs of the links that make up that path. Currently the costtraversing a link in the navigation graph is normally simply the physical (3D) length of that link. However,the A* implementation makes it easy for the requester to modify these distance-based costs with simplecode changes to extend the current system . For example, the cost of traveling between two road nodescan be scaled by a factor of 0.1 so that road-traveling agents have a strong preference for finding road-based paths.

The cost of a path link connecting two graph nodes should be determined by two sets of properties:

• Link properties, including the path's length.

• Pathfinding agent properties in relation to link properties. For example, a stealthy agent might evaluate alink passing through trees as a lower cost-per-unit-length than one passing along a road. However, thesame agent might reach a different conclusion when leading a convoy containing vehicles.

In general, the cost of a link is determined by the product of these two factors: the link-length multiplied by arelative cost-per-unit-length. The latter is what needs to be determined.

Problem: Calculating Costs at Run TimeWe want to use the same navigation graph for different kinds of agents. This means that link cost should becalculated at run time by combining the inherent link properties with the agent properties.

Link properties

Associate these properties with each link:

Link.Length

Length of the link (in meters).

Link.Resistance

The link's resistance to traversal. A road would be close to 0, off-road would be larger, water deepenough to require swimming might be close to 1.

Link.Exposure

How exposed the link is. Trees and dense vegetation would be close to 0, low vegetation would belarger, and a road/open space would be close to 1.

Link.DeepWaterFraction

Fraction of the link that contains deep water (e.g., > 1.5m).

Version 1.87


Link.DestinationDanger

Additional "danger value" associated with the destination node. A dead body might be 1. This valuecan be stored in the destination node itself to save memory.

Agent properties

Associate these properties with each agent (normally set when the agent is created):

Agent.CanTraverseTriangular

True/false indicator determining if the agent can traverse triangular nodes.

Agent.CanTraverseWaypoint

True/false indicator determining if the agent can traverse waypoint nodes.

Associate these properties with an agent if relevant for the link type:

Agent.CanSwim

True/false indicator determining if the agent can swim.

Pathfinder request properties

Associate these properties with each agent pathfinder request:

Agent.TriangularResistanceFactor

Extra link cost factor when the link is of type Triangular and its resistance is 1.

Agent.WaypointResistanceFactor

Extra link cost factor when the link is of type Waypoint and its resistance is 1.

Agent.RoadResistanceFactor

Extra link cost factor when the link is of type Road and its resistance is 1.

Associate these properties with an agent pathfinder request if relevant for the link type (note: if a path linkhas different start/end node types, the result is obtained by averaging):

Agent.SwimResistanceFactor

Extra link cost factor when the link deep water fraction is 1.

Agent.ExposureFactor

Extra link cost factor when the link's exposure is 1.

Agent.DangerCost

Extra link cost when the link danger value is 1.

All link properties, except for Link.DestinationDanger, are calculated when the triangulation is generated.Link.DestinationDanger is initially set to 0 and then calculated as the game runs. For example, whenevera character dies, each link going into the death node will have its DestinationdangerCost incremented by1. This will cause an agent with Agent.DangerCost = 100 to prefer paths up to 100m longer (assuming noother path cost differences) in order to avoid this death node. These link modifications need to be serializedto support load/save.

Version 1.88


In addition, extra costs can be calculated at run time. For example, an extra cost associated with exposurecould be added when an agent wishes to find a path that avoids the player; this can be done by usingraycasts in the A* callback that calculates costs.

When determining pathfinding costs, there are two problems that need to be solved:

• How should the link properties be calculated?

• How should the link and agent properties be combined to give a numerical cost for traversing each graphlink?

Keep in mind that link properties represent the average nature of the environment over the length of thelink. If the region has not been triangulated reasonably finely, this may negatively impact the quality ofpathfinding results. If the impact is significant, it may be necessary to add additional triangulation points.

An additional issue to consider: should pathfinding differentiate between variable visibility conditions, suchas night vs. day or fog vs. clear weather? This would involve splitting the link exposure into terms derivedfrom physical cover and shadow cover. Given the number of links involved, adding too much information ofthis type to each link should be considered carefully. A simpler solution might be to have stealthy agents beless likely to request a stealthy path in these conditions, or to set the agent's ExposureFactor lower.

Solution

Calculating link properties

Because link resistance is only dependant on the actual type of nodes involved in the link, it can be storedin a lookup table. Here's an example set of resistance values for each node type:

Node type Resistance

Triangular-no-water 0.5

Triangular-water 1.0

Waypoint 0.6

Road 0

Flight/Volume 0

Note

• Consider adding a separate resistance for Flight/Volume in underwater terrain.

• For links between nodes of different types, the resistance values can be averaged.

The Link.Exposure value, which is stored in the link, is determined by the environment properties sampledover the length of the link. For triangular, waypoint and volume navigation regions, this can be done byfiring rays from points along the link. (This is done by using IPhysicalWorld::RayWorldIntersection andchecking for HIT_COVER | HIT_SOFT_COVER with COVER_OBJECT_TYPES.) It does not make senseto try to get a really accurate value, because in practice the beautified path will not follow the link directly.

Combining link and agent properties

Link cost must account for intersections between link properties and agent properties. For example: if a linkis marked as containing deep water and the agent cannot swim, the link should be treated as impassable.

Version 1.89

Lumberyard Developer GuideSensory Models

A factor representing the extra costs associated with travel resistance and exposure will be calculated, andthe total link cost should be set as follows:

Cost = Link.DestinationDanger * Agent.DangerCost + (1 + Factor) * Link.Length

where

Factor = Agent.[link-type]ResistanceFactor * Link. [link-type]Resistance + Agent.ExposureFactor * Link.Exposure

Consider this scenario: with no exposure/destination costs, and assuming that road links haveLink.Resistance {{0}} while off-road links have Link.Resistance {{0.5}}, then in order to make roadtravel ten times more attractive than off-road (such as if the agent is a car), the agent could haveAgent.TriangularResistanceFactor set to {{(10-1)/0.5}} (or 18) and Agent.RoadResistanceFactor set to 0.

If the agent is a human character that always moves at about the same speed whether or not it is on or offa road, then it could have both Agent.TriangularResistanceFactor and Agent.RoadResistanceFactor set to0.

Assuming the agent can traverse deep water or is not affected by water (such as a hovercraft),Agent.SwimResistanceFactor could be set to 0. For a human agent, this factor might be set to a value ashigh as 3.0, so that the agent will take significant detours to avoid swimming across a river.

Sensory Models

OverviewThis topic describes the modelling and principal operation of the sensors implemented in the Lumberyard AIsystem. These include the visual sensors, sound sensors, and a general-purpose signalling mechanism.

Sensory information is processed during a full update of each enemy (the actual time that a sensory eventwas received is asynchronous). These sensors are the only interface the enemy has with the outsideworld, and provide the data that the enemy will use to assess their situation and select potential targets. Allsensors are completely configurable, and they can be turned on/off at run-time for any individual enemy.

VisionThe visual sensory model is the heart of the AI system. It is an enemy's most important sense. The model isdesigned to simulate vision as realistically as possible, while still maintaining a low execution cost, using acombination of compromises and optimizations.

During a full update for an individual enemy, the system traverses all potential targets from the enemy’spoint of view and runs each one through a visibility determination routine. All targets that survive thisfiltering procedure are placed in a visibility list that is maintained until the next full update. For a target topersist as "visible" it must pass the visibility test in each full update. Targets that change from visible tonot visible during an update are moved to a memory targets list. If a previously visible target becomesvisible again, it is moved from the memory target list back to the visibility list. Memory targets have anexpiration time to simulate the enemy "forgetting" the target; this time interval is determined by severalfactors, including the threat index of the target and the length of time it was visible. Visible targets are giventhe highest priority and will become the current attention target even if there is another target with a higherthreat index. This approach simulates the natural tendency of humans to act based on what they see fasterthan on what they remember (or hear).

Visibility DeterminationThe visibility determination routine determines whether a target is considered visible to an enemy. It is runagainst each of the enemy's potential targets during a full update.

Version 1.810

Lumberyard Developer GuideSensory Models

Identifying Targets

Visibility determination can be very CPU intensive; to mitigate this cost, only potential targets are evaluatedfor visibility. There is a mechanism to register any AI object as an object that should be included in thevisibility determination (including user-defined objects). This includes objects such as the grenades inLumberyard, flashlights, etc. There are also special objects called attributes, which will be discussed inmore detail later in this topic.

To be considered a potential target, an AI object must be:

• currently active

• of a different species than the enemy (enemies don't need to keep track of members of their own team)

In addition, the visibility determination test is performed automatically against the player, even if the playeris of the same species as the enemy. This rule ensures that the player is accurately specified as an objecttype and is always taken into account when checking visibility.

The game developer can also designate certain AI object types for visibility determination. These user-defined types are added to a list maintained by the AI system identifying object types to be included in thevisibility check. Objects can be freely added to and removed from this list, even from script. To include anobject in the list, specify an assessment multiplier to the desired object type. For example, refer to the fileaiconfig.lua, which can be found in the /scripts directory. For more about assessment multipliers, seethe topics on threat assessment.

Checking Visibility

Each potential target identified is evaluated for visibility using a series of tests. In situations where theplayer is facing a single species, no visibility determination is performed between AI enemy objects, onlyagainst the player.Key measures determining visibility include:

Sight-range test

This check is done first, as it is fast and cheap to filter out all AI objects that are outside the enemy's sightrange. This is done by comparing the distance between enemy and target against the enemy's sight rangevalue.

enemy sight range

Floating point value that determines how far the enemy can see (in meters); the value represents theradius of a sphere with the enemy at the center.

Field-of-vi

Documents

Developer Guide Version 1 - d3bqhfbip4ze4a.cloudfront.net · that is likely to cause confusion among customers, or in any manner that disparages or discredits Amazon. All other trademarks