Transitioning between the planets, and their screens, that make up the game is an important function as it allows the traversal between different levels in an easy manner whilst allowing all aspects of the game to access important information whenever using the GameState.

The transition between planets is facilitated using PlanetScreens which are outlined here.

In planetary transitioning, there are 2 major ways of causing this. Using a pre-existing transition method to handle all the state changes and updating for you or manually causing a transition and updating the state. Both of which are outlined below.

Note: Please note that the registering of the GameStateObserver into ServiceLocator and the creation of a GdxGame is included here in the example code for completeness but in most usage instances the Observer will already be registered, and the game will be parsed in as a parameter or attribute and as such are not required.

Pre-existing transition methods:

Space Map:

The space map is an interactive screen that displays all the planets in the game and their progression path in a clear and visually appealing way. This is the most visually appealing way to trigger a planet transition due to giving the full package of visual map, loading transitionary visuals, and triggering minigames the user must complete in their spaceship.

There are two ways to do this, either using the PlanetTravel, or manually transitioning to the appropriate screen.

PlanetTravel

This method uses the PlanetTravel class to handle the transitioning calls and is the preferred method.

GdxGame game = new GdxGame();
PlanetTravel travel = new PlanetTravel(game);
travel.beginFullTravel();

Screen Call

To do this is very simple just requiring the transitioning to this map screen as outlined below.

GdxGame game = new GdxGame();
game.setScreen(NAVIGATION_SCREEN);

Instant Planetary Travelling:

This method instantly travels to the next planet in the sequence, appropriately updating the game states and cleanup.

GdxGame game = new GdxGame();
PlanetTravel travel = new PlanetTravel(game);
travel.beginInstantTravel();

Returning to the current planet

This method simply returns to the current planet the player was just on and loads its state back in from the save file, just like they never left.

GdxGame game = new GdxGame();
PlanetTravel travel = new PlanetTravel(game);
travel.returnToCurrent();

Return Button:

The final pre-existing way is to utilise a return button component that will simply return the player back to the planet they were on last.

To do this two components are simply added to the UI entity of the displayed screen for the user to press. Being MainGameActions and ReturnToPlanetDisplay.

Below is example code that simply creates a UI entity with these two components however they can just be added directly onto the existing UI entity.

 private void createUI() {
        Stage stage = ServiceLocator.getRenderService().getStage();

        Entity ui = new Entity();
        ui.addComponent(new MainGameActions(this.game, stage))
                .addComponent(new ReturnToPlanetDisplay())
                // ...... Additional components for UI
        ServiceLocator.getEntityService().register(ui);
    }

Manual Planet Transition.

Other than using the pre-existing methods, you can also forcefully cause a planetary transition manually by getting the screens and updating the game state yourself. These steps are outlined below for a full planetary transition. (Further information of the GameState aspect of transitioning is further below or here).

The instance of requiring to call this is quite rare and should only occur if you want to explicitly break the gameplay travel chain for a reason, otherwise PlanetTravel should be used. A full suite of examples are provided for full functionality, such as transitioning back to a previous planet but this is already covered by the PlanetTravel and that should be used instead.

Full planetary transitioning.

Most accesses of the PlanetScreen will be due to a need to return from the currently displayed screen back to a planet for the player to interact with. As such outlined below are the two key transitions that can be manually triggered to return to the current planet the player was just on or to go to the next planet the player can access.

Transition back to the planet:

Most commonly a transition back to the current planet the player was using will occur be it from a cut-away screen or minigame. Below is the procedure to return to this current planet and continue gameplay.

GdxGame game = new GdxGame(); 
String currentPlanetName = (String) ServiceLocator.getGameStateObserverService().getStateData("currentPlanet");
PlanetScreen currentPlanet = PlanetScreen(game, currentPlanetName);
game.setScreen(currentPlanet); // Return back to planet

Transition to the next planet:

The other primary planetary transition is to advance to the next planet/level in the game.

GdxGame game = new GdxGame();
String currentPlanetName = (String) ServiceLocator.getGameStateObserverService().getStateData("currentPlanet");
PlanetScreen currentPlanet = PlanetScreen(game, currentPlanetName);
PlanetScreen nextPlanet = currentPlanet.getNextPlanet(); // Generate next planet in chain
ServiceLocator.getGameStateObserverService().trigger("updatePlanet", "currentPlanet", nextPlanet); // Save new planet in state
currentPlanet.clear(); // Cause a disposal of old planets data
game.setScreen(nextPlanet); // Display new planet

Planet State Storage

The GameState is simply designed to store the name of the planet the player is currently one as well as the next in the sequence, as such this name should then be used to create the appropriate PlanetScreen, and if a save file exists, it will be loaded in and the game will continue from the state.

Storing the current planet:

The current planet the player is to be stored inside the GameState to be easily accessed across all screens. As such it is important to ensure the current planet stored is correct and up to date.

ServiceLocator.registerGameStateObserver(new GameStateObserver());
GdxGame game = new GdxGame();
PlanetScreen currentPlanet = new PlanetScreen(game, "Earth");
String currentPlanetName = currentPlanet.name;
ServiceLocator.getGameStateObserverService().trigger("updatePlanet", "currentPlanet", currentPlanetName); //Update current planet in GameState

Retrieving the current planet:

In most instances, the current planet will already be appropriately updated in the GameState and it can be accessed whenever required to return back to the planet screen.

String currentPlanetName = (String) ServiceLocator.getGameStateObserverService().getStateData("currentPlanet");
PlanetScreen currentPlanet = PlanetScreen(game, currentPlanetName);

UML