Common Tasks, EBuses, and Handlers - Lumberyard User Guide

Common Tasks, EBuses, and Handlers

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 following are some common game programming tasks and the EBuses and handlers that you can use to implement them.

Detect Mouse, Keyboard, or Other Button Events

Bus AZ::InputEventNotificationBus
Events OnPressed, OnHeld, OnReleased
File InputEventBus.h

Use these events to detect when mouse, keyboard, or other buttons are pressed, held, or released.

Detect Entity or Component Readiness

Bus LmbrCentral::MeshComponentNotificationBus
Events OnMeshCreated, OnMeshDestroyed
File MeshComponentBus.h

Even after an entity has been created and its components have been activated, visual data might not be fully loaded. The OnMeshCreated event occurs when the mesh creation is complete. This is useful if you want to access the underlying ICharacterInstance and ISkeletonAnim members in order to play animations. More generally, it is useful to declare a component or entity as "alive" or game ready, whatever that might mean for your application.

Detect When a Member Joins or Leaves a Session

Bus GridMate::SessionEventBus
Events OnMemberJoined, OnMemberLeaving
File Session.h

You can use the SessionEventBus to detect when a member joins or leaves a network session. For documentation on this EBus, see Reacting to Session Events in the Using Lumberyard Networking.

Get and Set Physics Characteristics

Bus LmbrCentral::PhysicsComponentRequestBus
Methods AddImpulse, GetMass, SetMass, GetVelocity, SetVelocity, etc.
File PhysicsComponentBus.h

The PhysicsComponentRequestBus contains useful methods for getting or setting the physical characteristics of objects like mass, density, velocity, and water damping. For an example of using a pointer directly to the underlying handler for better access to functions such as GetVelocity, see Direct Access to EBus Handlers.

Get Notifications for Animation Events

Bus LmbrCentral::CharacterAnimationNotificationBus
Event OnAnimationEvent
File CharacterAnimationBus.h

If you have set up animations in the .animevents file in Geppetto, an OnAnimationEvent event is called for each animation event during animation playback. You can monitor this to get notifications for animation events. The string configured for the animation event in Geppetto is held in the LmbrCentral::AnimationEvent::m_animName variable.

Get or Set the Location of an Entity in the World

Bus AZ::TransformBus
Methods GetWorldX, SetWorldX, GetWorldY, SetWorldY, etc.
File TransformBus.h

The TransformBus contains many useful methods for getting or setting where in the world the entity is, such as xyz axis locations. For an example of using a pointer directly to the entity's transform for more optimal access to functions such as GetBasisY (the entity's forward vector), see Direct Access to EBus Handlers.

Manually Play Animations

Bus LmbrCentral::SkinnedMeshComponentRequestBus
Method GetCharacterInstance
File SkinnedMeshComponent.h

To play animations manually, use the ISkeletonAnim in the character instance. To get the ISkeletonAnim from the ICharacterInstance, use ICharacterInstance::GetISkeletonAnim().

Use an EBus from Another Component

Bus AZ::EntityBus
Events OnEntityActivated, OnEntityDeactivated
File EntityBus.h

The OnEntityActivated and OnEntityDeactivated events are called after all of an entity's components have had their Activate() or Deactivate() function called. These events can be useful if you want your component to use an EBus that another component has already set up in its Activate() function.

Use Tick Events

Bus AZ::TickBus
Event OnTick
File TickBus.h

A tick is a unit of time generated by the component application. The OnTick event signals that the application has issued a tick and is called each frame. By default, handlers receive events based on the order in which the components are initialized, but you can override this. For more information, see Tick Bus and Components.