Gameplay Bus

This topic references tools and features that are legacy. If you want to use legacy tools in Lumberyard Editor, disable the CryEntity Removal gem using the Project Configurator or the command line. To learn more about legacy features, see the Lumberyard Legacy 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.

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

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.

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

This function takes the entityChannel, actionNameCrc, and payloadType parameters and creates a unique ID that you can use 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.

payloadType

Use the payloadType parameter to specify the type that is sent or received. This parameter is required starting in Lumberyard version 1.12.

GameplayNotifications

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

void OnEventBegin(const AZStd::any& value)

void OnEventUpdate(const AZStd::any& value)

void OnEventEnd(cosnt AZStd::any& value)

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.

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.

function InLavaBehavior:OnEventBegin(floatValue)
    local animInfo = AnimatedLayer("LavaHotFootDance", 0, true, 1.0, 0.0);
    SimpleAnimationComponentRequestBus.Event.StartAnimation(self.entityId, animInfo)

    -- tell the 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.

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.

function InLavaBehavior:OnEventEnd(floatValue)
    local animInfo = AnimatedLayer("Idle", 0, true, 1.0, 0.0);
    SimpleAnimationComponentRequestBus.Event.StartAnimation(self.entityId, animInfo)

    -- tell the 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.

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