Game view - e-ucm/ead GitHub Wiki

What is the game view?

The game view encapsulates all the visual elements that are rendered onto the screen using LibGdx's stage.

Layered structure

What the game engine shows to the user is structured in layers. In this context a layer is just a way to "make things appear" following a specified order, as to control the Z position of elements by groups.

This is typical in games. Most games usually render stuff on top of the virtual world, like a HUD, text, etc.

Currently, the eAdventure game engine supports four layers:

  1. HUD. It is rendered on top of everything, all the time. It is meant to store the part of the HUD that never changes.
  2. SCENE. It is not meant to host any element, just a couple of sublayers:
  3. SCENE_HUD. Meant to host pieces of the HUD that may change depending on the scene. That sort of flexibility is interesting, but most of the games won't need to make use of it.
  4. SCENE_CONTENT. To host all elements (entities) that the current scene comprises. By default, when a new entity is loaded and added to the game, it is put into this layer. This one is rendererd behind the other three.

Implementation

GameView is the class that hosts most of the logic for the layers. It extends libgdx's WidgetGroup and it is the root element in the engine view hierarchy.

GameView treats each layer as a "special entity". They are special because they are not actually added to the game engine, so they cannot be removed by accident. Each layer is created and added to its parent layer (e.g. scene_content) or directly to GameView:

GameView (root view)
|
|------------------------
|                       |
HUD.group              SCENE.group
                        |
                        |--------------------
                        |                   |
                      SCENE_HUD.group     SCENE_CONTENT.group
                                            |
                                            |--------|--------|---------|......|
                                            E1.group E2.group E3.group         EN.group

Note: Ex means "whatever entity the scene has"

It may look strange that layers and entities are not directly added to the tree, but its groups instead. That's because EngineEntity cannot be added directly to libgdx stage - all the "visual" stuff its placed into its group field.

Entities can be added and removed to layers at will, but layer structure described above cannot be altered during gameplay.

Where are layers actually defined?

The class GameView does not actually store the definition and structure of layers described above (HUD, SCENE, etc.). This definition is actually placed into Layer. Layer contains an enum with the list of layers. Take into account that the order in the list matters. Layers are added to the view as they are defined in this enum, so they should appear on the list in reverse order as they must be drawn.

The string associated to each layer also matters. If a layer has to be attached to another layer (child), its name should start with the name of the parent, followed by an underscore (_). Example: scene_contents is a child of scene. Root layers cannot have underscores.

Public API

GameView basically offers two public methods for managing entities and layers:

  • addEntityToLayer: adds the given entity to the given layer. This function is typically used after an entity is loaded, so it can be displayed.
  • clearLayer: empties all entities in the desired layer, but the sublayers. Can work recursively.

The reader may miss a method for removing an entity from a layer. However, this is not necessary since it is done automatically when gameLoop.removeEntity(Entity entity) is called. See GameLoop for more information.