Planet Screens

In the game, each planet acts as its own independent level that gets traversed through as the player progresses. As such each planet level should be encapsulated into its own, separate, state that is independent of all other levels.

This helps ensure that only appropriate textures and services are utilised for each planet rather than shared across all game areas even when not necessary. It also allows for the grouping of different game areas together into their own state rather than them all being together on the same screen even when they are not related to each other.

To achieve this each Planet acts as its own screen instance that contains all the state information, services, textures, game areas, and renderer entirely independent of all other planets and their own game areas allowing compartmentalisation and modularity.

The PlanetScreen is based upon the MainGameScreen with a few key feature changes and QOL tweaks to make generating the different planet screens and their game areas simple whilst also allowing other screens to easily transition around to planets through the GameStateObserver.

Creating a planet screen:

The creation of a planet screen is designed to be as simple as possible with only two parameters being required to give. These are the GdxGame and the name of the planet. The names of planets are outlined inside the screen functionality (setGameArea, detailed below) but if the given name is invalid the default base planet will be created instead.

Note: Please note that the PlanetScreen still needs to be set as the current screen after its creation.

GdxGame game = new GdxGame(); // Game that is being used (usually passed in as a parameter).
PlanetScreen planet = new PlanetScreen(game, "Earth");
game.setScreen(planet); // Display screen

Generating the next planet:

A key and important feature of navigating the screens for each planet is determining which screen is the next planet in the sequence. In order to facilitate this the PlanetScreen has a method that returns the next planet screen for usage called getNextPlanet().

Note: This method does not transition into this new planet screen or begin asset loading when called, the screen must be set when required.

GdxGame game = new GdxGame(); // Game that is being used (usually passed in as a parameter).
String planetName = "Earth";
PlanetScreen currentPlanet = new PlanetScreen(game, planetName);
PlanetScreen nextPlanet = currentPlanet.getNextPlanet();
game.setScreen(nextPlanet); // Load in assets, and display screen and primary game area.

If the name of the next planet is known then it can be directly created using its name without using a reference to the previous planet screen

GdxGame game = new GdxGame(); // Game that is being used (usually passed in as a parameter).
String nextPlanetName = "Verdant Oasis";
PlanetScreen nextPlanet = new PlanetScreen(game, nextPlanetName);
game.setScreen(nextPlanet); // Load in assets, and display screen and primary game area.

Creating planet data from name:

Once a planet screen has been created the given planet name is then used to generate additional data surrounding its state including its game areas and next planet. The planet's game areas are created based on the configuration files for the given level (planet) name.

Each planet can support multiple game areas but at a minimum must have a main_area that acts as the initial entry point into the planet. The areaNames correspond to the area directories as part of the level configs. This is outlined further here which outlines loading configuration files and what everything represents.

Note: Each Planet must have a main_area game area to act as the first initial screen unless explicitly changed.

There are multiple under-the-hood helper methods that streamline this process even further to generate the corresponding directories for config files and handling save loads, therefore only requiring the config file to specify the specific names of the areas.

Multiple Game Areas and Planets Example

The setup of a new planet and its corresponding game areas is quite simple merely requiring the generateGameAreas() lookup method to be extended to insert additional planets into the chain using the helper generation method.

Below is an example of two new planets with the name "Mars" and "Jupiter" which are after "Earth" and contain example configuration files and multiple corresponding game areas. So the new chain goes Earth -> Mars -> Jupiter -> Default.

Note: Mars and Jupiter config files do not exist and are simply examples of usage.

levels/earth/level.json

{
  "areaNames": [
    "main_area"
  ],
  "nextPlanet": "mars"
}

levels/mars/level.json

{
  "areaNames": [
    "main_area"
    "caves"
  ],
  "nextPlanet": "jupiter"
}

levels/jupiter/level.json

{
  "areaNames": [
    "main_area",
    "mountain_1",
    "mountain_2"
  ]
}

Changing displayed game area

The switching of the current displayed GameArea is a simple feat merely requiring a method call to the new areas name on the PlanetScreen. This name is the name given in the level.json config file and can be used anywhere that has access to the GdxGame.

Defining a Planet Screen

Below is an example of doing this for a created planet screen that represents to example planet Mars: This is used if you have a direct reference to the desired planet you wish to target.

GdxGame game = new GdxGame(); // Game that is being used (usually passed in as a parameter).
String planetName = "Mars";
PlanetScreen currentPlanet = new PlanetScreen(game, planetName);
currentPlanet.setCurrentArea("caves");

The currently displayed planet

In most instances you will not have a reference to the current planet, it is trivial however to change the displayed area of the currently shown PlanetScreen through the GdxGame.

An example is shown below by getting the current planet screen.

GdxGame game = new GdxGame(); // Game that is being used (usually passed in as a parameter).
game.getScreen().setCurrentArea("caves");

Transitioning between planets either using the Space Map, return button, or manually whilst storing their state is outlined here.

UML