Menu
Lumberyard
C++ API Reference (Version 1.10)

Classes | Public Member Functions | Public Attributes | List of all members
AZ::BehaviorContext Class Reference

Open 3D Engine (O3DE), the successor to Lumberyard, is now available in Developer Preview. Download O3DE or visit the AWS Game Tech blog to learn more.

BehaviorContext is an object that contains information about classes, methods, properties, constants, enums, and EBuses to enable Lumberyard to interact with objects during run time. More...

Inherits AZ::ReflectContext .

Classes

struct ClassReflection
This structure is built up while you call ClassReflection functions to reflect a class's information to the behavior context. More...
struct EBusReflection
This structure is built up while you call EBusReflection functions to reflect an EBus 's information to the behavior context. More...

Public Member Functions

BehaviorContext ()
Initializes a behavior context object. More...
~BehaviorContext ()
A destructor. More...
template<class Function >
GlobalMethodInfo Method (const char *name, Function f, BehaviorValues *defaultValues=nullptr, const char *dbgDesc=nullptr)
Reflects a global method to the behavior context. More...
template<class Function , class = AZStd::enable_if_t<AZStd::function_traits<Function>::num_args != 0>>
GlobalMethodInfo Method (const char *name, Function f, AZStd::array< AZStd::string, AZStd::function_traits< Function >::num_args > argNames, BehaviorValues *defaultValues=nullptr, const char *dbgDesc=nullptr)
Reflects a global method with arguments to the behavior context. More...
template<class Getter , class Setter >
GlobalPropertyInfo Property (const char *name, Getter getter, Setter setter)
Reflects a global property to the behavior context. More...
template<int Value>
BehaviorContext * Enum (const char *name)
Reflects global enum data to the behavior context. More...
template<class Getter >
BehaviorContext * Constant (const char *name, Getter getter)
Reflects a global constant to the behavior context. More...
template<class T >
ClassReflection < T > Class (const char *name=nullptr)
Reflects a class to the behavior context and enables you to attach classwide attributes. More...
template<class T >
EBusReflection < T > EBus (const char *name)
Reflects an EBus to the behavior context. More...
- Public Member Functions inherited from AZ::ReflectContext
ReflectContext ()
Initializes a reflection context instance. More...
virtual ~ReflectContext ()
An empty destructor. More...
void EnableRemoveReflection ()
Sets the behavior such that calls to this context remove reflection for types passed to it. More...
void DisableRemoveReflection ()
Sets the behavior such that calls to this context add reflection for types passed to it. More...
bool IsRemovingReflection () const
Indicates whether calls to this context remove reflection for types passed to it. More...

Public Attributes

AZStd::unordered_map< AZStd::string, BehaviorMethod * > m_methods
A map of all methods that are reflected to the behavior context. More...
AZStd::unordered_map< AZStd::string, BehaviorProperty * > m_properties
A map of all properties that are reflected to the behavior context. More...
AZStd::unordered_map< AZStd::string, BehaviorClass * > m_classes
A map of all classes that are reflected to the behavior context. More...
AZStd::unordered_map< AZStd::string, BehaviorEBus * > m_ebuses
A map of all EBuses that are reflected to the behavior context. More...

Detailed Description

BehaviorContext is an object that contains information about classes, methods, properties, constants, enums, and EBuses to enable Lumberyard to interact with objects during run time.

The behavior context enables scripts (such as Lua scripts) to change the state of objects during a game.

To make classes, methods, properties, constants, and EBuses accessible to scripts, you must reflect them to the global behavior context. To do this, you add code to a component's implementation of the Reflect() function. You use the Reflect() function to reflect information to the SerializeContext and EditContext also.

The following example shows how to implement a component's Reflect() function to provide information to the behavior context. You call various functions to add methods, properties, constants, enums, and EBuses to the behavior context. Immediately following each of these, you can use a builder pattern to apply optional attributes with the form -> Attribute ("attributeName", attributeValue); .

Note
Although reflection to the behavior context is done within a component's Reflect() function, component classes do not generally reflect their own information to the behavior context. They typically only reflect items that they interact with, such as EBuses.
class MyComponent
{
void MyComponent::Reflect( AZ::ReflectContext * context) // Static function
{
AZ::BehaviorContext * behaviorContext = azrtti_cast < AZ::BehaviorContext *>(context);
if (behaviorContext)
{
// Reflect global constants, enums, properties, and methods
behaviorContext-> Constant ( "GlobalConstName" , BehaviorConstant (globalConstValue))
->Attribute( "attributeName" , attributeValue);
behaviorContext-> Enum <ENUM_VALUE>( "ENUM_VALUE" )
-> Attribute ( "attributeName" , attributeValue);
behaviorContext-> Property ( "globalData" ,&GetGlobalData, &SetGlobalData)
->Attribute( "attributeName" , attributeValue);
behaviorContext-> Method ( "GlobalMethod" ,&GlobalMethod, nullptr , "Debug description." )
->Attribute( "attributeName" , attributeValue);
// Reflect EBuses
behaviorContext-> EBus <MyComponentRequestBus>( "MyComponentRequestBus" )
->Event( "MyComponentRequestBus" , &MyComponentRequestBus::Events::MyRequestEvent);
behaviorContext-> EBus <MyComponentNotificationBus>( "MyComponentNotificationBus" )
->Handler<MyComponentNotificationBusHandler>();
// Reflect class constants, enums, properties, and methods.
// Component classes typically do not reflect their own class members; they reflect
// items that they interact with, like EBuses. However, components occasionally reflect
// members of another class.
behaviorContext-> Class <MyOtherClass>()
-> Attribute ( "attributeName" , attributeValue);
->Constructor< int >()
-> Attribute ( "attributeName" , attributeValue);
->Property( "memberData" , &MyOtherClass::GetData(), &MyOtherClass::SetData)
->Attribute( "attributeName" , attributeValue);
->Constant( "memberConst" , BehaviorConstant (constValue))
->Attribute( "attributeName" , attributeValue);
->Enum<MyOtherClass::ENUM_VALUE>( "ENUM_VALUE" )
-> Attribute ( "attributeName" , attributeValue);
->Method( "MemberMethod" ,& Method , nullptr , "Debug description." )
->Attribute( "attributeName" , attributeValue);
}
}
};

For more information about reflecting components to the behavior context, see Behavior Context in the Lumberyard User Guide .

To see real examples of reflecting to the behavior context, browse the Reflect() implementations for components in lumberyard-root\dev\Gems\LmbrCentral\Code\Source .

Reflecting Global Properties, Constants, Enums, and Methods

This section shows how to reflect global properties, constants, enums, and methods to the behavior context.

Global Properties

A property is data that is represented by a getter and setter function. To reflect global properties, you use the BehaviorContext::Property() function.

// Global property with a getter and setter function.
behaviorContext-> Property ( "globalData" ,&GlobalDataGetter, &GlobalDataSetter)
->Attribute( "attributeName" , attributeValue);
// Global property with getter and setter lambda functions.
behaviorContext-> Property ( "globalData" ,[]() { return g_globalDataValue; }, []( int value) { g_globalDataValue = value;})
-> Attribute ( "attributeName" , attributeValue);
// Global property from a value with helper macro.
behaviorContext-> Property ( "globalData" , BehaviorValueProperty (&g_globalDataValue))
->Attribute( "attributeName" , attributeValue);
// Global read-only property with a getter function.
behaviorContext-> Property ( "globalReadOnlyProp" , &GlobalDataGetter, nullptr );
->Attribute( "attributeName" , attributeValue);
// Global read-only property with a lambda function.
behaviorContext-> Property ( "globalReadOnlyProp" , []() { return g_globalDataValue; }, nullptr )
-> Attribute ( "attributeName" , attributeValue);
// Global read-only property with a value and a helper macro.
behaviorContext-> Property ( "globalReadOnlyProp" , BehaviorValueGetter (&g_globalDataValue), nullptr )
->Attribute( "attributeName" , attributeValue);
// Write only is the same as read only but with the setter enabled and the getter set to nullptr.

Global Constants

Constants are read-only properties. To reflect a global constant, you use the BehaviorContext::Constant() function. This function requires you to provide a getter function. If you don't have a getter function, you can provide a lambda or you can use the BehaviorConstant() helper macro to provide the correct form for you.

// Uses a getter function.
behaviorContext-> Constant ( "Constant" , someGetterFunction);
->Attribute( "attributeName" , attributeValue);
// Uses a lambda.
behaviorContext-> Constant ( "Constant" , []() { return constantValue; });
->Attribute( "attributeName" , attributeValue);
// Uses the BehaviorConstant() helper macro to provide the getter function form.
behaviorContext-> Constant ( "Constant" , BehaviorConstant (constantValue));
->Attribute( "attributeName" , attributeValue);

Global Enums

Enums are read-only properties. To reflect a global enum, you use the BehaviorContext::Enum() function.

behaviorContext-> Enum <ENUM_VALUE>( "ENUM_VALUE" );
->Attribute( "attributeName" , attributeValue);

Global Methods

To reflect a global method, you use the BehaviorContext::Method() function.

behaviorContext-> Method ( "GlobalMethod" ,&GlobalMethod, nullptr , "Debug description." )
->Attribute( "attributeName" , attributeValue);

Class Members

To reflect class members, you use the BehaviorContext::Class() function and then add elements using a syntax similar to the syntax for adding global items.

Note
This example is included for completeness. Component classes do not generally reflect their own information to the behavior context. They typically only reflect items that they interact with, such as EBuses.
behaviorContext-> Class <MyClass>()
-> Attribute ( "attributeName" , attributeValue);
->Constructor< int >()
-> Attribute ( "attributeName" , attributeValue);
->Property( "memberData" , &MyClass::GetData(), &MyClass::SetData)
->Attribute( "attributeName" , attributeValue);
->Constant( "memberConst" , BehaviorConstant (constValue))
->Attribute( "attributeName" , attributeValue);
->Enum<MyClass::ENUM_VALUE>( "ENUM_VALUE" )
-> Attribute ( "attributeName" , attributeValue);
->Method( "MemberMethod" ,& Method , nullptr , "Debug description." )
->Attribute( "attributeName" , attributeValue);

EBuses

A component can reflect its notification buses and request buses. A component's request bus handles requests from other components. Its notification bus sends notifications that are received by handlers that are monitoring the notification bus. You reflect buses to the behavior context so that scripts can interact with C++ components. For example, for the Light component to react to a script that turns a light on, the Light component's request bus needs to be notified when the script sends a TurnOnLight event. The behavior context handles this binding.

Reflecting your EBuses is not required, but we recommend reflecting all useful buses because it enables users to script complex behaviors.

To reflect a component's request bus, you use the BehaviorContext::EBus() function and then add events using the BehaviorContext::EBusReflection::Event() function in a builder pattern. You must call BehaviorContext::EBusReflection::Event() for any event that you want to be callable by scripts. The following example shows how to add an event.

behaviorContext-> EBus <MyComponentRequestBus>( "MyComponentRequestBus" )
->Event( "MyComponentRequestBus" , &MyComponentRequestBus::Events::MyRequestEvent);

To reflect a component's notification bus, you use the BehaviorContext::EBus() function and then use the BehaviorContext::EBusReflection::Handler() function in a builder pattern to add a handler class. You must also add code to the component to implement the handler class.

The following is an example of how you reflect a component's notification bus to the behavior context.

behaviorContext-> EBus <MyComponentNotificationBus>( "MyComponentNotificationBus" )
->Handler<MyComponentNotificationBusHandler>(); // Specifies a handler class that forwards the events
// to handlers created by the behavior context.
// You must implement this class.

The following is an example of the handler class that you write to forward notification events to handlers that are created by the behavior context. The AZ_EBUS_BEHAVIOR_BINDER helper macro sets up the class. You follow the macro with handler functions that use a Call() or CallResult() function to forward the events to handlers that are created by the behavior context.

class MyComponentNotificationBusHandler : public MyComponentNotificationBus::Handler , public AZ::BehaviorEBusHandler
{
public :
AZ_EBUS_BEHAVIOR_BINDER (MyComponentNotificationBusHandler,
"{UUID_OF_THE_HANDLER_CLASS}" ,
AZ::SystemAllocator,
OnEvent1,
OnEvent2);
// Handler for an event with no argument or return value.
void OnEvent1() override
{
Call(FN_OnEvent1); // Forward the event to the behavior context handler.
}
// Handler for an event with an input argument and a return value.
int OnEvent2( int value) override
{
int result = 0; // Set the default value for the result.
CallResult(result, FN_OnEvent2, value); // Forward the event to the behavior context handler.
return result; // Return the result as with any EBus event.
}
// Handler for an event with a container as an input argument and a return value.
int OnEvent3( const AZStd::vector<int>& values) override
{
int result = 0; // Set the default value for the result.
CallResult(result, FN_OnEvent3, values); // Forward the event to the behavior context handler.
return result; // Return the result as with any EBus event.
}
};

For other examples, see Behavior Context in the Lumberyard User Guide or browse the component implementations in lumberyard-root\dev\Gems\LmbrCentral\Code\Source .

Constructor & Destructor Documentation

◆ BehaviorContext()

AZ::BehaviorContext::BehaviorContext ( )

Initializes a behavior context object.

◆ ~BehaviorContext()

AZ::BehaviorContext::~BehaviorContext ( )

A destructor.

Member Function Documentation

◆ Class()

template<class T >
ClassReflection <T> AZ::BehaviorContext::Class ( const char * name = nullptr )

Reflects a class to the behavior context and enables you to attach classwide attributes.

Note
Component classes do not generally reflect their own information to the behavior context. They typically only reflect items that they interact with, such as EBuses (see BehaviorContext::EBus ).

To attach classwide attributes, follow the Class() call with one or more calls to the Attribute() function.

You then attach properties, methods, and other elements to the class as shown in the following example.

behaviorContext-> Class <MyClass>()
-> Attribute ( "attributeName" , attributeValue);
->Constructor< int >()
-> Attribute ( "attributeName" , attributeValue);
->Property( "memberData" , &MyClass::GetData(), &MyClass::SetData)
->Attribute( "attributeName" , attributeValue);
->Constant( "memberConst" , BehaviorConstant (constValue))
->Attribute( "attributeName" , attributeValue);
->Enum<MyClass::ENUM_VALUE>( "ENUM_VALUE" )
-> Attribute ( "attributeName" , attributeValue);
->Method( "MemberMethod" ,& Method , nullptr , "Debug description." )
->Attribute( "attributeName" , attributeValue);
Parameters
name The name of the class. If you don't provide this, it defaults to the type information obtained from RTTI.
Returns
A structure that is built up while you call ClassReflection functions to reflect a class's information to the behavior context.

◆ Constant()

template<class Getter >
BehaviorContext * AZ::BehaviorContext::Constant ( const char * name ,
Getter getter
)

Reflects a global constant to the behavior context.

The constant must be passed in using a getter function. If you don't have a getter function, you can provide a lambda or you can use the BehaviorConstant() helper macro.

You can attach one or more attributes to the constant by following Constant() with Attribute() in a builder pattern as shown in the following example.

// Uses a getter function.
behaviorContext-> Constant ( "Constant" , someGetterFunction);
->Attribute( "attributeName" , attributeValue);
// Uses a lambda.
behaviorContext-> Constant ( "Constant" , []() { return constantValue; });
->Attribute( "attributeName" , attributeValue);
// Uses the BehaviorConstant() helper macro to provide the getter function form.
behaviorContext-> Constant ( "Constant" , BehaviorConstant (constantValue));
->Attribute( "attributeName" , attributeValue);

To reflect class member constants, use BehaviorContext::ClassReflection::Constant() .

Parameters
name The name of the constant.
getter A method that gets the value of the constant. You can use the BehaviorConstant() helper macro to convert a value to a function to use for this parameter.
Returns
A pointer to the updated behavior context.

◆ EBus()

template<class T >
EBusReflection <T> AZ::BehaviorContext::EBus ( const char * name )

Reflects an EBus to the behavior context.

The bus can be a request bus or a notification bus.

To reflect a component's request bus, you use the BehaviorContext::EBus() function and then use BehaviorContext::EBusReflection::Event() in a builder pattern to add events as shown in the following example.

behaviorContext-> EBus <MyComponentRequestBus>( "MyComponentRequestBus" )
->Event( "MyComponentRequestBus" , &MyComponentRequestBus::Events::MyRequestEvent);

To reflect a component's notification bus, you use the BehaviorContext::EBus() function and then use BehaviorContext::EBusReflection::Handler() in a builder pattern to add a handler class. You must also add code to the component to implement the handler class.

The following is an example of how you reflect a component's notification bus to the behavior context.

behaviorContext-> EBus <MyComponentNotificationBus>( "MyComponentNotificationBus" )
->Handler<MyComponentNotificationBusHandler>(); // Specifies a handler class that forwards
// the events to the behavior context.
// You must implement this class.

The following is an example of the handler class that you write to forward notification events to handlers that are created by the behavior context. The AZ_EBUS_BEHAVIOR_BINDER helper macro sets up the class. You follow the macro with handler functions that use a Call() or CallResult() function to forward the events to handlers that are created by the behavior context.

class MyComponentNotificationBusHandler : public MyComponentNotificationBus::Handler , public AZ::BehaviorEBusHandler
{
public :
AZ_EBUS_BEHAVIOR_BINDER (MyComponentNotificationBusHandler,
"{UUID_OF_THE_HANDLER_CLASS}" ,
AZ::SystemAllocator,
OnEvent1,
OnEvent2);
// Handler for an event with no argument or return value.
void OnEvent1() override
{
Call(FN_OnEvent1); // Forward the event to the behavior context handler.
}
// Handler for an event with an input argument and a return value.
int OnEvent2( int value) override
{
int result = 0; // Set the default value for the result.
CallResult(result, FN_OnEvent2, value); // Forward the event to the behavior context handler.
return result; // Return the result as with any EBus event.
}
// Handler for an event with a container as an input argument and a return value.
int OnEvent3( const AZStd::vector<int>& values) override
{
int result = 0; // Set the default value for the result.
CallResult(result, FN_OnEvent3, values); // Forward the event to the behavior context handler.
return result; // Return the result as with any EBus event.
}
};
Parameters
name The name of the EBus .
Returns
A structure that is built up while you call EBusReflection functions to reflect an EBus 's information to the behavior context.

◆ Enum()

template<int Value>
BehaviorContext * AZ::BehaviorContext::Enum ( const char * name )

Reflects global enum data to the behavior context.

All enums are treated as int .

You can attach one or more attributes to the enum by following Enum() with Attribute() in a builder pattern as shown in the following example.

behaviorContext-> Enum <ENUM_VALUE>( "ENUM_VALUE" )
-> Attribute ( "attributeName" , attributeValue);

To reflect class member enums, use BehaviorContext::ClassReflection::Enum() .

Template Parameters
Value The enum value that you are reflecting.
Parameters
name The name of the enum.
Returns
A pointer to the updated behavior context.

◆ Method() [1/2]

template<class Function >
GlobalMethodInfo AZ::BehaviorContext::Method ( const char * name ,
Function f ,
BehaviorValues * defaultValues = nullptr ,
const char * dbgDesc = nullptr
)

Reflects a global method to the behavior context.

Each method must have a unique name in the global scope.

You can attach one or more attributes to the method by following Method() with Attribute() in a builder pattern as shown in the following example.

behaviorContext-> Method ( "GlobalMethod" , &GlobalMethod, nullptr , "Debug description." )
->Attribute( "attributeName" , attributeValue);

To reflect class member methods, use BehaviorContext::ClassReflection::Method() .

Parameters
name The name of the method.
f A reference to the method.
defaultValues (Optional) Default values, which help you call the reflected method with fewer arguments. Default values are used right to left.
dbgDesc (Optional) A description that is used for debugging.
Returns
A pointer to an internal structure that contains global method reflection information.

◆ Method() [2/2]

template<class Function , class = AZStd::enable_if_t<AZStd::function_traits<Function>::num_args != 0>>
GlobalMethodInfo AZ::BehaviorContext::Method ( const char * name ,
Function f ,
AZStd::array< AZStd::string, AZStd::function_traits< Function >::num_args > argNames ,
BehaviorValues * defaultValues = nullptr ,
const char * dbgDesc = nullptr
)

Reflects a global method with arguments to the behavior context.

Each method must have a unique name in the global scope.

You can attach one or more attributes to the method by following Method() with Attribute() in a builder pattern as shown in the following example.

behaviorContext-> Method ( "GlobalMethod" , &GlobalMethod, { "MyArg1" , "MyArg2" }, nullptr , "Debug description." )
-> Attribute ( "attributeName" , attributeValue);

To reflect class member methods, use BehaviorContext::ClassReflection::Method() .

Parameters
name The name of the method.
f A reference to the method.
argNames An array of argument names for the method.
defaultValues (Optional) Default values, which help you call the reflected method with fewer arguments. Default values are used right to left.
dbgDesc (Optional) A description that is used for debugging.
Returns
A pointer to an internal structure that contains global method reflection information.

◆ Property()

template<class Getter , class Setter >
GlobalPropertyInfo AZ::BehaviorContext::Property ( const char * name ,
Getter getter ,
Setter setter
)

Reflects a global property to the behavior context.

A property is data that is represented by a getter and setter function. If you don't have a getter or setter function, you can provide a lambda or you can use the BehaviorValueGetter() and BehaviorValueSetter() helper macros.

You can attach one or more attributes to the property by following Property() with Attribute() in a builder pattern as shown in the following example.

// Global property with a getter and setter function.
behaviorContext-> Property ( "globalData" ,&GlobalDataGetter, &GlobalDataSetter)
->Attribute( "attributeName" , attributeValue);
// Global property with getter and setter lambda functions.
behaviorContext-> Property ( "globalData" ,[]() { return g_globalDataValue; }, []( int value) { g_globalDataValue = value;})
-> Attribute ( "attributeName" , attributeValue);
// Global property from a value with helper macro.
behaviorContext-> Property ( "globalData" , BehaviorValueProperty (&g_globalDataValue))
->Attribute( "attributeName" , attributeValue);

For more examples, see the detailed description of BehaviorContext . To reflect class member properties, use BehaviorContext::ClassReflection::Property() .

Parameters
name A name for the property.
getter (Optional) A method that gets the value of a property. If you pass null for this parameter, the property is write only. (This is rare.)
setter (Optional) A function that sets the value of the property. If you pass null for this parameter, the property is read only.
Returns
A pointer to an internal structure that contains global property reflection information.

Member Data Documentation

◆ m_classes

AZStd::unordered_map<AZStd::string, BehaviorClass *> AZ::BehaviorContext::m_classes

A map of all classes that are reflected to the behavior context.

◆ m_ebuses

AZStd::unordered_map<AZStd::string, BehaviorEBus*> AZ::BehaviorContext::m_ebuses

A map of all EBuses that are reflected to the behavior context.

◆ m_methods

AZStd::unordered_map<AZStd::string, BehaviorMethod*> AZ::BehaviorContext::m_methods

A map of all methods that are reflected to the behavior context.

◆ m_properties

AZStd::unordered_map<AZStd::string, BehaviorProperty*> AZ::BehaviorContext::m_properties

A map of all properties that are reflected to the behavior context.

The documentation for this class was generated from the following file: