Getting Started (2) – Learning the Basics

Tutorial - Getting Started With The LITIengine (Part 2) - Learning the Basics

This part of the series will be a theoretical chapter about the LITIengine Basics. It introduces you to the most important components and concepts that you should understand before working with the LITIengine.

  1. Setup a LITIengine Game Project
  2. Learning the Basics (this article)
  3. Configuring the Game
  4. Loading a .tmx Map
  5. Working with Entities

This Tutorial series will guide you through the basic steps of how to create your first “Hello World” Game with the LITIengine. We’ll use Eclipse as an example IDE to help you better understand some steps of this process. At the end of this series, we’ll have a running Game with a controllable Player.


The Game class

de.gurkenlabs.litieLITIengine Component Gamengine.Game

The Game class is without any doubt one of the classes that you will call a lot when creating a game with the LITIengine. It is designed to be the static container that provides access to all important aspects of the engine, e.g. it holds the GameInfo, the RenderEngine, the SoundEngine and many other major components.

We designed the API such that all important parts that make up the game are directly accessible via the Game class in a static manner. To be a little bit more technical, it is essentially a collection of core Singleton instances.

This class will also be your starting point when setting up a new LITIengine project. In order to launch your game,  you need to at least call Game.init(String...) and Game.start() from your programs main(String[]) method.

Additionally, it provides an interface to hook up event listeners for the most basic operations of a Game life cycle.

Example usages:

Game.init();
Game.start();

Game.addTerminatedListener(() -> 
{
  // do sth when game is shut down
});

System.out.println("Game version is: " + Game.getInfo().getVersion());

Game.getSoundEngine().playSound(Sound.get("test.ogg"));

Introduction to Screens

LITIengine Component Screende.gurkenlabs.litiengine.gui.screens.Screen

de.gurkenlabs.litiengine.gui.screens.ScreenManager

Screens are the containers that allow you to organize the visible contents of your game. They render the game’s Environment and are considered the parent of all GUI components you want to display in a particular state of your game. The screen itself inherits from GuiComponent and thereby provides support to define an Appearance and listen to all kinds of Input events (e.g. onMouseMoved(…)). Everything that should be visible to the player needs to be rendered to the currently active screen.

Screens are identified and addressed by a unique name. The ScreenManager holds instances of all available screen and handles whenever a different Screen should be shown to the player. It provides the currently active Screen for the Game’s RenderComponent which calls the Screen.render(Graphics2D) method on every tick of the RenderLoop. Overwriting this method provides the ability to define a customized render pipeline that suits the need of a particular Screen implementation. With the GameScreen, the LITIengine provides a simple default Screen implementation that renders the current Environment and all its GuiComponents.

  • Examples: Menu Screen, Credits Screen, Game Screen, Inventory Screen

Example usages:

Game.getScreenManager().addScreen(new MenuScreen());
Game.getScreenManager().addScreen(new IngameScreen());
Game.getScreenManager().addScreen(new EndOfLevelScreen());

Game.getScreenManager().displayScreen("MENU");

System.out.println("Currently active screen: " + Game.getScreenManager().getCurrentScreen().getName());

public class TestScreen extends GameScreen {
  public TestScreen() {
    super("TEST");
  }

  @Override
  public void render(final Graphics2D g) {
    super.render(g);

    g.setFont(FontLoader.load("customfont.ttf").deriveFont(32f));
    g.setColor(Color.RED);
    RenderEngine.drawText(g, "Test text", 100, 100);
  }
}

Introduction to the Environment

LITIengine Component Environmentde.gurkenlabs.litiengine.environment.Environment

Every game engine needs a container that holds all the visual and non-visual things that will, in the end, make up the game world. This container is called Environment in the LITIengine. Only one Environment is loaded at a time and the Game holds the currently active Environment. Every time you want to position something within the two-dimensional space of your game, you can do so by adding it to the Environment. When the active Screen calls the Environment.render(Graphics2D) method, it’s internal Rendering Pipeline is executed which will render everything that was previously added/loaded to the environment. There are different render types (BACKGROUND, OVERLAY, …) that define in which order the objects will be rendered, but more on that topic in a later tutorial.

It’s important to point out, that the Environment is related to exactly one Map and that the LITIengine provides an interface to load MapObjects to the environment. The implementations that take care of this task are called MapObjectLoaders. They basically translate the information form the .tmx map format to objects that can be managed by the LITIengine.

Example usages:

// set the active environment on the game
Game.loadEnvironment(new Environment("level-1.tmx"));

// add an entity to the environment
Game.getEnvironment().add(new MyEntity("my-entity"));

// retrieve the entity from the enviroment by its name
IEntity entity = Game.getEnvironment().get("my-entity");
MyEntity myEntity = Game.getEnvironment().get(MyEntity.class, "my-entity");

// remove the entity by its name
Game.getEnvironment().remove("my-entity");

// add a entity listener to the current environment of the game
Game.getEnvironment().addEntityListener(new EnvironmentEntityAdapter(){
  @Override
  public void entityAdded(IEntity entity) {
    // do sth when entities are added
  }
});

So much for the theoretical basics. Hope you learned something today 🙂 In the next part of the tutorial series, we’ll learn how to configure the engine to suit your game’s requirements.

Until then, have a great one!