Lifecycle Example

Screens and transitions offer a lot of different methods (show(), hide(), render(), etc.). It is not always easy to figure out, when each method is invoked and who calls whom. The following paragraphs detail what would happen in a normal game loop.

Our scenario: Imagine the game game is currently displaying screenA. Then, screenB is pushed using the transition transition, for example via a click listener:

myButtonInScreenA.addListener(new ClickListener() {              
    @Override
    public void clicked(InputEvent event, float x, float y) {
        game.getScreenManager().pushScreen(new ScreenB(), new BlendingTransition(batch, 1.5F));
    };
});

This call triggers the following things to happen internally:

• In the first render pass (game.render(delta)) after the call to pushScreen(...): ¹
  • the input handlers of screenA are unregistered
  • screenB.show()
  • screenB.resize(width, height)
  • transition.show()
  • transition.resize(width, height)
  • transition.render(delta, ...) - the transition is rendered (and is given textures of screenA.render(delta) and screenB.render(delta))
• From then on, in every render pass (game.render(delta)) the transition is rendered...
  • transition.render(delta, ...) (textures of screenA.render(delta) and screenB.render(delta) are given to the transition)
• ...until the transition is done:
  • transition.hide()²
  • screenA.hide()³
  • the input handlers of screenB are registered
  • a new transition is polled (it is checked whether there was another call to pushScreen() while the transition was going on⁴)
    • if there is no new transition queued: screenB.render(delta)
• And from then on, in every render pass (game.render(delta)) the new screen is rendered:
  • screenB.render(delta)

---

¹ Note 1:

After a screen was pushed, the actual change of the screen happens in the first game.render(...) call after that. This ensures that Screen#show() and Screen#hide() are only called on the rendering thread and thus the OpenGL context is available.

This also has the benefit, that the execution of a method isn't interrupted by pushing a screen. For example, the logging statement in this example is executed before screenB.show() is called:

myButtonInScreenA.addListener(new ClickListener() {              
    @Override
    public void clicked(InputEvent event, float x, float y) {
        game.getScreenManager().pushScreen(screenB, transition);
        Gdx.app.debug("ScreenA", "My button was clicked!");
    };
});

² Note 2:

If automatic disposing of transitions is enabled (ScreenManager#setAutoDispose(..., true)), transition.dispose() is called as well. Check out this page for more information.

³ Note 3:

If automatic disposing of screens is enabled (ScreenManager#setAutoDispose(true, ...)), screenA.dispose() is called as well. Check out this page for more information.

⁴ Note 4:

If there is a transition still going on while a new one is pushed, the new one is queued until the current one is finished.