Quickstart

Before you can start using libgdx-screenmanager, you need to add it as a dependency. Check out this page for instructions.

After that, there are three simple steps involved in using libgdx-screenmanager:

1. Your game has to extend ManagedGame.
2. All screen have to inherit from ManagedScreen.
3. New screens can be pushed like this: game.getScreenManager().pushScreen(screen, transition). If no transition should be used, just call pushScreen(screen, null).

In practice, this is how a game class could look like:

public class MyGdxGame extends ManagedGame<ManagedScreen, ScreenTransition> {

	@Override
	public final void create() {
		super.create();

		// Do some basic stuff
		this.batch = new SpriteBatch();

		// Push the first screen using a blending transition
		this.screenManager.pushScreen(new GreenScreen(), new BlendingScreenTransition(batch, 1F));

		Gdx.app.debug("Game", "Initialization finished.");
	}

}

A full example can be found here.

There are a couple of additional things you should be aware of when using libgdx-screenmanager:

• If you are planning on using FrameBuffers inside of a screen, please take a look here. Please be aware, that some libraries (such as box2d-lights, for example) use framebuffers internally, so there are additional steps involved to get libgdx-screenmanager working with them. This page details what you have to do to get some of the more popular libraries running with libgdx-screenmanager.
• Screens and transitions can be reused as often as you like, just push them again. If your screens are single-use, i.e. they should be disposed after they were shown once, you can use ScreenManager#setAutoDispose. Check out this page for more information.
• If you are using viewports in your screens (as you should!), be sure to apply them first. Also, if you're using the same SpriteBatch as some of your transitions, don't forget to set the projection matrix:

  public class GreenScreen extends ManagedScreen {
  
  	// ...
  
  	@Override
  	public void render(float delta) {
  		viewport.apply();
  		batch.setProjectionMatrix(viewport.getCamera().combined); 
  
  		// Render your stuff
  		batch.begin();
  		/* [...] */
  		batch.end();
  	}
  
  	@Override
  	public void resize(int width, int height) {
  		viewport.update(width, height, true);
  	}
  }

Additional Features

libgdx-screenmanager offers a few additional features, that you can use in your game:

Automatic Input Processor Registration

Input processors should be added in a screen via #addInputProcessor(...). This has the advantage that they are automatically registered/unregistered when the screen is shown/hidden. This also means that there is no need to use any InputMultiplexers yourself, as this is all done automatically behind the scenes. If you rely on this behaviour, don't use Gdx.input.setInputProcessor(...) yourself!

public class BlueScreen extends ManagedScreen {

	public BlueScreen() {
   		// ... 
   		this.addInputProcessor(new InputAdapter() { // this input processor is automatically registered & unregistered
   			@Override
   			public boolean touchDown(int screenX, int screenY, int pointer, int button) {
   				screenManager.pushScreen(new GreenScreen(), null);
   				return true;
   			}
   		});
   	}

}

Convenient Screen Clearing

ManagedScreens do not need to call Gdx.gl.glClearColor(0, 0, 0, 0);in their render() method. The screens (i.e. their color and depth buffers) are automatically cleared by the screen manager. To set a specific color, override getClearColor():

public class BlueScreen extends ManagedScreen {

   	@Override
   	public void render(float delta) {
   		//  The screen is automatically cleared with a white color beforehand
   		// ...
   	}

   	@Override
   	public Color getClearColor() {
   		return Color.WHITE;
   	}

}

To disable screen clearing, return null in getClearColor(). This can improve performance, but might have unforeseen consequences during transitions when the screens are transparent.