#3 - libgdx Tutorial: scene2d

Libgdx version used on this post: 0.9.2 (download)

All we have by now is a splash screen that displays an static image. Wouldn't it be nice to add some fading effect on this image? Things like these improve the user experience a lot, so soon we'll deal with that. As we build our graphical user interface, we need to handle things like selecting options, cliking on buttons, giving focus to an input widget and so on so forth. Can you imagine doing that with images inside image atlases? You're lucky today. There is a very cool feature of libgdx called scene2d that basically provides useful abstractions for rendering 2D components. Let's understand it better!

As of libgdx 0.9.6 some of the classes used on this post were modified or removed. You may want to read the post #13 after reading this post, which covers those changes.

About scene2d

Scene2d is a module of libgdx that eases the management and rendering of 2D components, which are called Actors. These actors live on a tree structure inside a container called Stage. They keep track of many rendering attributes, such as position relative to the parent, color, visibility, dimensions, scale and rotation factors and more. They are also responsible for hit detection.

Examples of actors would be: buttons, text fields, images, enemy targets, coins, the ship we'll fly, shots and so on. We'll use scene2d a lot in our game. Also, it's possible to apply actions on the actors, like translate, rotate, scale and fade actions. If needed, you can also write your own action, but we'll get to that later.

I'll try and summarize the main concepts of scene2d below:

• Actor - A 2D component that knows how to draw itself.
• Group - An actor that contains other actors.
• Stage - An engine that requests the actors to be drawn and handles user interaction by distributing touch events to the actors.
• Action - A function that modifies the actors' properties over time.

The following UML diagram shows it graphically:

Using scene2d

The first thing to do is setup a Stage where the actors will act. A nice place for it to live is within a screen (each screen with its own stage). These are the steps for managing the stage in our game:

1. Create a Stage instance on the constructor of AbstractScreen class
2. Resize its viewport when the screen is resized
3. Call the Stage's act and draw methods within the screen's render method
4. Dispose the stage within the screen's dispose method

For further details, please have a look at the source code of the AbstractScreen class. Now, everything we have to do is add actors to the stage. Our actors should override methods like act() and draw(), which are automatically invoked by the stage on the appropriate time.

Modifying the Splash screen

We want the splash image to be an actor so that we can do cool things with it. Instead of extending the Actor class, we can just use the Image (com.badlogic.gdx.scenes.scene2d.ui.Image) actor that comes with scene2d. We still have to load the texture and the texture region. We should also tell the image how to be drawn, and that it should take all the screen size. Have a look at the source code for the modified SplashScreen class to see how it's done.

Regarding that "actions" object inside SplashScreen.resize(), that's the coolest thing we can do with scene2d. Each actor can be animated by actions. What we do with our splash image is to add a set of the following actions:

1. Fade-in in 0.75 seconds
2. Wait for 1.75 sconds
3. Fade-out in 0.75 seconds

We want also to move on to the next screen when the action is completed, so all we have to do is add a completion listener to the "actions" object. Note that we didn't need to override the screen's render method on the splash screen, because the splash image is an actor that was added to the stage, and the stage is the one in charge of rendering it.

More about actions

The three actions we used on the splash image ship with libgdx. That is:

• Fade-in action: com.badlogic.gdx.scenes.scene2d.actions.FadeIn
• Fade-out action: com.badlogic.gdx.scenes.scene2d.actions.FadeOut
• Delay action: com.badlogic.gdx.scenes.scene2d.actions.Delay

I suggest you take some time to check all the available actions inside the package com.badlogic.gdx.scenes.scene2d.actions, but basically there are two types of them:

• Concrete actions - Actions that modifies the actors directly (FadeIn, FadeOut, MoveBy, RotateBy, ScaleTo, etc).
• Support actions - Actions that group or organize other actions in specific ways (Delay, Sequence, Parallel, Repeat, Forever, etc).

Every action comes with a factory method named "$" that takes the required parameters for it to work properly. If you want to create a FadeIn action that lasts 2 seconds, you can just write:

FadeIn fadeInAction = FadeIn.$(2f);

The delay action has a different factory method. The following code creates the FadeOut action 5 seconds delayed.

FadeOut fadeOutAction = FadeOut.$(2f);
Delay delayAction = Delay.$(fadeOutAction, 5f);

In order to have the complete effect we want, we need to join both actions:

Sequence sAction = Sequence.$(fadeInAction, delayAction);

And finally, add the action to the actor:

actor.action(sAction);

Piece of cake, isn't it? The last thing about actions I should not forget, is that you can also add interpolators to them. That means your action can start slow and them accelerate gradually, for instance. Interpolators define the rate of change for a given animation. In libgdx they also come with the "$" factory method, so you can easily create them.

Domain model

A domain model describes the entities, their attributes, roles and relationships for a given domain of interest. Most of our business logic will stay on the domain entities, because in software engineering it's a nice idea to isolate the business logic. It makes the code straightforward to other programmers, and even to ourselves later on. It also helps when switching technologies. Say we want to switch from 2D to 3D graphics. If the business logic is isolated, the impact of this change will be kept to a minimum.

With the help of scene2d we can achieve this objective rather easy, as each of the drawable domain entities can map to a scene2d actor. That's how we'll separate the business code from the presentation code. So the next task for us is to define our domain model. In order to make it simple, we're not going to implement a full clone of Tyrian, but just the main aspects of it. After analysing the game for some time, I came up with the following diagram:

You can check the complete source code for the domain model here.

Conclusion

This post was an introduction to scene2d. We saw how easy it is to use it, and how to extend it with custom functionality. We added a fade effect to the splash image and now it looks like a real splash image. Finally, we implemented the domain model for our game in an isolatted manner. The tag for this post on the Subversion is here. Thanks for reading!