Menu
Lumberyard
Developer Guide (Version 1.11)

Core Concepts of Lumberyard for Programmers

Before you start programming in Lumberyard, it is important to understand its key concepts: entities and components, EBuses, gems, modules, and slices.

Entities and Components

Lumberyard uses a lightweight entity/component model called the component entity system for both game objects and systems. Lumberyard entities are simply an ID and a container of components. They have no functionality associated with them. Lumberyard's component model is granular: It expects each component to provide independent functionality. It expects game objects to be made up of one or more entities with many components attached to each entity. Lumberyard components communicate with each other using a messaging system called EBuses (explained later). Lumberyard expects you to use EBuses instead of holding references to other entities or their components.

Lumberyard’s components have a simple lifecycle. When an entity is activated, it calls Activate() on all of its components. When the entity is deactivated, it calls Deactivate() on all of its components. In the Activate() function a component sets itself up, connects to EBuses, and allocates resources or requests assets. In the Deactivate() function, a component should release all resources and disconnect from all EBuses. Components should be completely dormant after deactivation, and they should be in more or less the same state that they are in after Init() is called. The Init() function is only called once and allows a component to initialize its internal state. Note that a component can be activated and deactivated many times before it is deleted. For example, it might be deactivated temporarily while it is being streamed out.

The remaining API operations of a component should be established by the EBus that it implements.

Components can depend on services. Such services usually have a one-to-one relationship with EBuses. If a component declares that it depends on (requires) a service, any entity that uses the component must also contain a component that provides the required services.

Components are always activated in order of their dependency. For this reason, a component can always assume that the services that it requires are available when the component is activated.

Entities are never allowed to be in a state in which one of their component dependencies is missing, even during authoring. In Lumberyard's editing tools, this means that components whose dependencies are missing are actually removed from the entity and stored in a temporary list. When all of the component's dependencies become available, the component is restored to the entity.

For more information about entities and components, see Programmer's Guide to Entities and Components.

EBuses

EBuses are Lumberyard's general-purpose messaging system. They dispatch notifications and receive requests.

Components commonly use EBuses in two ways: to dispatch events from a notification bus or to handle requests using a request bus. Some components provide one type of bus, and some components provide both types. You use the EBus class for both EBus types. Some components do not provide an EBus at all.

To interact with the engine or other components in Lumberyard, include the component or system's EBus or API header in your code. Then make calls to the exposed EBuses. With this approach you can replace enginelevel system APIs with implementations that you define in a gem. For example, you could replace Lumberyard's audio system with your own EBus handler. This would give you complete control over audio without having to recompile the engine.

For information about EBuses, see Event Bus (EBus).

Gems and AZ Modules

Lumberyard is designed to create applications that are small executables. A Lumberyard application has a simple application class (AZ::ComponentApplication). The application class reads a manifest (a gems.json file) and loads modules that provide functionality for your game. Lumberyard calls these modules gems. Lumberyard includes a variety of prebuilt gems that add functionality to the game engine, such as VR, cloud connectivity, and a new EmotionFX animation system. Cloud Gems are gems that add AWS cloud-connected functionality to your game. Lumberyard's goal is to have you pick a set of gems that match the requirements of your game and only compile what you need.

When you create a game, your game code and assets go into one or more gems. Each code gem contains an AZ::Module. An AZ module is a collection of C++ code built as a static or dynamic library (.lib or .dll file) that implements specific initialization functions. The AZ module is the interface that Lumberyard uses to extract the contents of your gem into the global environment. Each application has a single entity associated with it that is referred to as the system entity. AZ modules can add components to this entity before it is activated. Components that are added to the system entity are called system components. System components are often singleton/manager-type objects that aggregate or provide resources to game components or other systems. Like other entities, a system entity must have its dependencies present. You can assume that any systems that you depend on are booted and available when your system component is activated.

For more information, see Gems in the Amazon Lumberyard User Guide.

Slices

Slices are practical and powerful way to create units of content in Lumberyard and manage them. A slice is a collection of one or more entities. You can instantiate a slice as many times as you require. Many game engines use levels and/or sublevels for their content, but Lumberyard loads content into its engine in the form of slices. Because slices can inherit from each other and be nested, they are powerful tools for managing content.

Like most systems that use prefabs or archetypes, you can use inheritance to override properties in Lumberyard. However, you can use Lumberyard's slices to add or remove components or even entire entity hierarchies.

For more information, see Slices and Dynamic Slices.