Menu
Lumberyard
Developer Guide (Version 1.11)

Gameplay Bus

The gameplay bus alerts gameplay systems that an event has occurred. You can use the bus to send contextual messages between the visual scripting, scripting, and code parts of your game in a generic and extensible way.

The gameplay bus passes an AZStd::any, a class that uses type erasure to hold any C++ reflected type or any Lua primitive except for tables (string, number, Boolean, etc.). It includes mechanisms for type safety to ensure that it returns the same type that it is passed. In Lua, the type can be inspected if it has been exposed to the behavior context through the typeid() function, which uses the AZ_RTTI system.

Example

Copy
function MyComponent:OnEventBegin(param) if typeid(param) == typeid(Uuid) then -- param is a Uuid elseif typeid(param) == typeid(Vector3) then -- param is a Vector3 end end

GameplayNotificationId

The GameplayNotificationId is the type used as the ID for the gameplay bus. Its syntax is as follows.

Copy
GameplayNotificationId(const AZ::EntityId& entityChannel, AZ::Crc32 actionNameCrc)

The entityChannel and actionNameCrc parameters create a unique bus ID. You can use this ID to communicate with the bus.

entityChannel

When you write your events, choose the ID of an entity channel that makes sense in the context of your game. Components are automatically aware of the following two entity IDs, which you can use for channels. These IDs do not require an entity reference.

  1. The component's own entity ID. To obtain it, call GetEntityId().

  2. The default AZ::EntityId().

To communicate directly to a specific entity, use GetEntityId(). To communicate indirectly to a generic audience, use AZ::EntityId().

actionNameCrc

You can pass the actionNameCrc parameter as a string or as the AZ::Crc32 of that string when you construct the ID. This parameter should be the name of the event that gives context to the event data.

GameplayNotifications

The GameplayNotifications class contains the gameplay bus type traits. It establishes the GameplayNotificationId as the bus ID. It defines the following events.

Copy
void OnEventBegin(const AZStd::any& value)
Copy
void OnEventUpdate(const AZStd::any& value)
Copy
void OnEventEnd(cosnt AZStd::any& value)

GameplayEventHandlerNode

You can use GameplayEventHandlerNode to control the flow of gamplay events.

Input Ports

The following table describes the flow graph nodes for handling a gameplay event.

Input Port Description
ChannelId The channel on which to send your event. For information on choosing a channel, see GameplayNotificationId.
EventName The name of the event that you want to handle. For information on available events, see GameplayNotifications.
Enable

Calls the BusConnect method and connects to GameplayNotificationBus. When the node connects, it begins handling events that are received when the flowgraph updates.

Note

If you send multiple events in a flowgraph update, only the last event is used.

Disable Calls BusDisconnect, disconnects from GameplayNotificationBus, and stops the handling of events.

Output Ports

The output ports for the GameplayEventHandlerNode are the same as those for the GameplayNotifications class (OnEventBegin, OnEventUpdate, and OnEventEnd).

GameplayEventHandlerNode Flow Graph Example

The following image shows how the flow graph might be used be to change the position of (move) an entity.


          GameplayEventHandlerNode Flow Graph Example

GameplayEventSenderNode

You can use GameplayEventSenderNode to sent gameplay events.

Input Ports

The following table describes the flow graph nodes for sending a gameplay event.

Input Port Description
Activate Causes a gameplay event to be sent.
ChannelId The channel on which to send your event. For information on choosing a channel, see GameplayNotificationId.
SendEventValue Stores the AZStd::any value for delivery with the event.
EventName The name of the event that you want to handle. For information on choosing a channel, see GameplayNotificationId.
EventType Specifies the event. The options are OnEventBegin, OnEventUpdating, and OnEventEnd. These events are defined in the GameplayNotfications class.

GameplayEventSenderNode Flow Graph Example

The following image shows how the flow graph might be used to send an event when an entity enters lava.


          GameplayEventSenderNode Flow Graph Example

Script Examples

The Lua script examples in this section illustrate the use of GameplayNotificationBus to control what happens when an entity enters and then exits lava.

1. The following example implements the OnActivate function when the entity enters lava.

Copy
local InLavaBehavior ={ Properties = { }, } function InLavaBehavior:OnActivate() local gameplayId = GameplayNotificationId(self.entityId, "InLava") self.gameplayBus = GameplayNotificationBus.CreateHandler(self, inputBusId) end

2. The following example implements the OnEventBegin function to start an animation associated with the event.

Copy
function InLavaBehavior:OnEventBegin(floatValue) local animInfo = AnimatedLayer("LavaHotFootDance", 0, true, 1.0, 0.0); SimpleAnimationComponentRequestBus.Event.StartAnimation(self.entityId, animInfo) -- tell our flow graph HUD to transition the screen effect to "In Lava" local gameplayId = GameplayNotificationId(EntityId(), "TransitionScreenEffect") GameplayNotificationBus.Event.OnEventBegin(gameplayId, "In Lava") end

3. The following example implements the OnEventUpdating function to update a health component regarding the status of the entity.

Copy
function InLavaBehavior:OnEventUpdating(floatValue) -- alert the health component (this gameplay component is an example only) that we are taking damage, it can handle any death transitions HealthComponentBus.Event.TakeDamage(self.entityId, floatValue) end

4. The following example implements the OnEventEnd function to end the animation and return status to normal.

Copy
function InLavaBehavior:OnEventEnd(floatValue) local animInfo = AnimatedLayer("Idle", 0, true, 1.0, 0.0); SimpleAnimationComponentRequestBus.Event.StartAnimation(self.entityId, animInfo) -- tell our flow graph HUD to transition the screen effect to "Normal" local gameplayId = GameplayNotificationId(EntityId(), "TransitionScreenEffect") GameplayNotificationBus.Event.OnEventBegin(gameplayId, "Normal") end

5. The following example implements the OnDeactivate function to disconnect from the gameplay bus.

Copy
function InLavaBehavior:OnDeactivate() self.gameplayBus:Disconnect() end return InLavaBehavior