Package de.gurkenlabs.litiengine

Class Game

java.lang.Object
de.gurkenlabs.litiengine.Game
public final class Game extends Object

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 init(String...) and start() from your programs main(String[]) method.

Additionally, it provides an interface to hook up event listeners (e.g. GameListener or EnvironmentLoadedListener) for the most basic operations of a Game life cycle. 

See Also:

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final String
    COMMANDLINE_ARG_NOGUI
     
    static final String
    COMMANDLINE_ARG_RELEASE
     
    static final int
    EXIT_GAME_CLOSED
     
    static final int
    EXIT_GAME_CRASHED
     

  • Method Summary

    Modifier and Type
    Method
    Description
    static void
    addGameListener(GameListener listener)
    Adds the specified game listener to receive events about the basic game life-cycle.
    static void
    allowDebug(boolean allow)
    This flag indicates if the game currently supports debugging.
    static SoundEngine
    audio()
    Gets the engine's SoundEngine component that can be used to play sounds and music.
    Sound can be loaded and accessed using the Resources API and are managed by the
    Resources.sounds() resource container.
    static GameConfiguration
    config()
    Gets the game's runtime configuration.
    It contains default engine settings for the game client, graphics, audio, input and debugging.
    Additionally, it can be used to register and manage custom settings that are specific to your game.
    static void
    exit()
     
    static RenderEngine
    graphics()
    Gets the engine's RenderEngine component that is used to render Images, Shapes or Text with respect to the environment and the render scale and the Camera.
    static boolean
    hasStarted()
    Indicates whether the game has already been started.
    static void
    hideGUI(boolean noGui)
    This flag indicates whether the game should display the GameWindow or not.
    static GameInfo
    info()
    Gets the static meta information about this game.
    This can be used to define meta information about your game, like it's name, version or web site.

    It's also possible to provide additional custom information using the method group
    Game.getInfo().setValue("CUSTOM_STRING", "my-value").
    static void
    init(boolean initInSwingThread, String... args)
    Initializes the infrastructure of the LITIENGINE game.
    static void
    init(Runnable preInitialization, Runnable postInitialization, String... args)
     
    static void
    init(String... args)
    Initializes the infrastructure of the LITIENGINE game.
    static boolean
    isDebug()
    This flag globally controls the game's debugging state.
    static boolean
    isInNoGUIMode()
    Indicates whether the game should display the GameWindow or not.
    static Logger
    log()
    Gets the game's default logger instance that can be used to quickly log messages without the need to initialize custom logger instances.
    static IGameLoop
    loop()
    Gets the game's main loop that is used to execute and manage all game logic apart from input processing.
    You can attach any Updatable instance to this loop if you want to execute custom game logic that is executed at the configured max fps.
    static GameMetrics
    metrics()
    Gets basic client metrics about the game's runtime.
    static PhysicsEngine
    physics()
    Gets the engine's PhysicsEngine component that can be used to detect and resolve collision and move entities with respect to all collision entities on the environment.
    The boundaries of the loaded environment also pose a "non-walkable" area that will be taken into account when moving entities with this engine.
    static GameRandom
    random()
    Gets the game's pseudo-random generator that enhances the default Java Random implementation with helpful additions.
    static void
    removeGameListener(GameListener listener)
    Removes the specified game listener.
    static ScreenManager
    screens()
    Gets the game's ScreenManager that is responsible for organizing all Screens of your game and providing the currently active Screen that is used to render the current Environment.
    Screens are the containers that allow you to organize the visible contents of your game and are identified and addressed by a unique name.
    static void
    setInfo(GameInfo info)
    Sets the Game's basic information by the specified GameInfo instance.
    static void
    setInfo(String gameInfoFile)
    Sets the Game's basic information by loading the GameInfo from the specified path to an XML file.
    static void
    setInfo(URL gameInfoFile)
     
    static void
    setUncaughtExceptionHandler(Thread.UncaughtExceptionHandler uncaughtExceptionHandler)
    Sets an UncaughtExceptionHandler used to handle all unexpected exceptions happening in the game.
    static void
    start()
    Starts the GameLoops and other components.
    static GameTime
    time()
    Gets time information about the running game/environment.
    static TweenEngine
    tweens()
    Gets the game's Tween manager that holds all currently active Tween instances.
    static GameWindow
    window()
    Gets the game's window in which the RenderComponent lives.
    This class e.g.
    static GameWorld
    world()
    Gets the game's world which is a global environment manager that contains all Environments and provides the currently active Environment and Camera.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

  • Method Details

    • addGameListener

      public static void addGameListener(GameListener listener)
      Adds the specified game listener to receive events about the basic game life-cycle.
      Parameters:
      listener - The listener to add.

    • removeGameListener

      public static void removeGameListener(GameListener listener)
      Removes the specified game listener.
      Parameters:
      listener - The listener to remove.

    • allowDebug

      public static void allowDebug(boolean allow)
      This flag indicates if the game currently supports debugging. This should be set to false for release builds.

      The default value here is true and will allow debugging unless explicitly disabled by calling this method or providing the command line argument COMMANDLINE_ARG_RELEASE when running the game.

      Parameters:
      allow - If set to true, the game will be told to allow debugging.

    • hideGUI

      public static void hideGUI(boolean noGui)
      This flag indicates whether the game should display the GameWindow or not. This can only be set before the game has been initialized with the Game.init(String...) method. Afterwards it doesn't have an effect anymore. If enabled, the ScreenManager#setVisible(boolean) method won't be set to true and the RenderLoop won't be started. Also the Camera won't be updated.
      Parameters:
      noGui - If set to true, the GUI will be hidden.
      See Also:

    • isDebug

      public static boolean isDebug()
      This flag globally controls the game's debugging state. If enabled, debugging functionality (e.g. rendering collision boxes) can potentially be enabled in the configuration.
      Returns:
      True if debugging functionality is enabled; otherwise false.
      See Also:

    • isInNoGUIMode

      public static boolean isInNoGUIMode()
      Indicates whether the game should display the GameWindow or not.
      Returns:
      True if the game should display visual components; otherwise false.

    • hasStarted

      public static boolean hasStarted()
      Indicates whether the game has already been started.
      Returns:
      True if the game has been started; otherwise false.
      See Also:

    • info

      public static GameInfo info()
      Gets the static meta information about this game.
      This can be used to define meta information about your game, like it's name, version or web site.

      It's also possible to provide additional custom information using the method group
      Game.getInfo().setValue("CUSTOM_STRING", "my-value").
      Returns:
      The game's basic meta information.
      See Also:

    • config

      public static GameConfiguration config()
      Gets the game's runtime configuration.
      It contains default engine settings for the game client, graphics, audio, input and debugging.
      Additionally, it can be used to register and manage custom settings that are specific to your game.

      Elements of this configuration are also presented in a config.properties file in the game's root directory.
      This way its possible to adjust elements without having to recompile the game.

      Returns:
      The game's runtime configuration.
      See Also:

    • metrics

      public static GameMetrics metrics()
      Gets basic client metrics about the game's runtime. This includes information about network, the frames-per-second or the updates-per-second and the used memory.

      This information can be rendered by setting
      Game.config().client().setShowGameMetrics(boolean) to true or
      cl_showGameMetrics=true in the config.settings.

      Returns:
      Metrics about the game's runtime.
      See Also:

    • time

      public static GameTime time()
      Gets time information about the running game/environment.

      This allow to measure the time between actions, track how long something took, evaluate cooldowns or just get information about the played game time.

      Returns:
      The game's temporal information.
      See Also:

    • window

      public static GameWindow window()
      Gets the game's window in which the RenderComponent lives.
      This class e.g. provides the possibility to set a title, provide an icon, get information about the resolution or set a cursor.
      Returns:
      The window that hosts the game's RenderComponent.
      See Also:

    • audio

      public static SoundEngine audio()
      Gets the engine's SoundEngine component that can be used to play sounds and music.
      Sound can be loaded and accessed using the Resources API and are managed by the
      Resources.sounds() resource container.

      Upon playing a sound, the engine returns an SoundPlayback instance that can then be used to further control the audio line.

      Returns:
      The engine's SoundEngine component.
      See Also:

    • physics

      public static PhysicsEngine physics()
      Gets the engine's PhysicsEngine component that can be used to detect and resolve collision and move entities with respect to all collision entities on the environment.
      The boundaries of the loaded environment also pose a "non-walkable" area that will be taken into account when moving entities with this engine.

      It is also possible to manually register static collision Rectangles that can further restrict the game world.

      Returns:
      The engine's PhysicsEngine component.
      See Also:

    • graphics

      public static RenderEngine graphics()
      Gets the engine's RenderEngine component that is used to render Images, Shapes or Text with respect to the environment and the render scale and the Camera.

      In case you want to render something in a static manner that is unrelated to the environment, you can use the engine's different static Renderer implementations.

      Returns:
      The engine's RenderEngine component.
      See Also:

    • loop

      public static IGameLoop loop()
      Gets the game's main loop that is used to execute and manage all game logic apart from input processing.
      You can attach any Updatable instance to this loop if you want to execute custom game logic that is executed at the configured max fps.

      The game's loop also executes the rendering process on the GameFrame's RenderComponent.
      This internally renders the currently active screen which passes the Graphics2D object to all GuiComponents and the Environment for rendering.

      The LITIENGINE has two separate loops for game logic/rendering and input processing.
      This prevents them from interfering with each other and to be able to process player input independent of the game's framerate.

      Returns:
      The game's main loop.
      See Also:

    • log

      public static Logger log()
      Gets the game's default logger instance that can be used to quickly log messages without the need to initialize custom logger instances.
      Returns:
      The game's default logger instance.

    • random

      public static GameRandom random()
      Gets the game's pseudo-random generator that enhances the default Java Random implementation with helpful additions.
      Returns:
      The game's pseudo random generator.

    • screens

      public static ScreenManager screens()
      Gets the game's ScreenManager that is responsible for organizing all Screens of your game and providing the currently active Screen that is used to render the current Environment.
      Screens are the containers that allow you to organize the visible contents of your game and are identified and addressed by a unique name.

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

      Returns:
      The game's screen manager.
      See Also:

    • world

      public static GameWorld world()
      Gets the game's world which is a global environment manager that contains all Environments and provides the currently active Environment and Camera.

      The GameWorld returns the same instance for a particular map/mapName until the GameWorld.reset(String) method is called.

      Moreover, it provides the possibility to attach game logic via EnvironmentListeners to different events of the Envrionment's life cycle (e.g. loaded, initialized, ...).
      This is typically used to provide some per-level logic or to trigger general loading behavior.

      Returns:
      The game's environment manager.
      See Also:

    • tweens

      public static TweenEngine tweens()
      Gets the game's Tween manager that holds all currently active Tween instances.
      Returns:
      The game's Tween manager.

    • init

      public static void init(Runnable preInitialization, Runnable postInitialization, String... args)
      Parameters:
      preInitialization - a runnable used to prepare the game for initialization. This runnable will be started in the Swing Event Dispatch Thread.
      postInitialization - a runnable used to setup the game directly after initialization. This runnable will be started in the Swing Event Dispatch Thread.
      args - The arguments passed to the program's entry point.
      Throws:
      AWTError - if this method is called on the Swing Event Dispatcher thread

    • init

      public static void init(String... args)
      Initializes the infrastructure of the LITIENGINE game. The following tasks are carried out by this method:
      • load the GameConfiguration
      • handle the specified program parameters
      • configure the logging
      • set the programs Locale according to the configured values.
      • initialize and attach core components like the PhysicsEngine
      • initialize the ScreenManger
      • initialize the Input
      • initialize the GameLoop and RenderLoop
      • set a default Camera
      Parameters:
      args - The arguments passed to the programs entry point.

    • init

      public static void init(boolean initInSwingThread, String... args)
      Initializes the infrastructure of the LITIENGINE game.
      Parameters:
      initInSwingThread - used to determine if the game should be launched in the swing worker thread. This should be true in most circumstances, unless you're already in the swing worker thread, in which case you MUST supply false.
      args -
      See Also:

    • setUncaughtExceptionHandler

      public static void setUncaughtExceptionHandler(Thread.UncaughtExceptionHandler uncaughtExceptionHandler)
      Sets an UncaughtExceptionHandler used to handle all unexpected exceptions happening in the game.
      Parameters:
      uncaughtExceptionHandler - The handler to be used for uncaught exceptions.

    • start

      public static void start()

      Starts the GameLoops and other components. After this method is called, the engine will start to render contents of the current Screen of the ScreenManager, the SoundEngine will start to playback Sounds and the different input devices (e.g. Mouse, Keyboard) will start to process player input.

      When the Game has started up successfully, it'll callback to the registered GameListeners.

      See Also:

    • exit

      public static void exit()

    • setInfo

      public static void setInfo(GameInfo info)
      Sets the Game's basic information by the specified GameInfo instance.

      Typically, this should not be called manually because the Game already provides a GameInfo object which can be adjusted.
      If you just want to edit some of it's information, use the provided instance of info().

      Parameters:
      info - The GameInfo that contains the basic information for the game.
      See Also:

    • setInfo

      public static void setInfo(String gameInfoFile)
      Sets the Game's basic information by loading the GameInfo from the specified path to an XML file.
      Parameters:
      gameInfoFile - The path to the XML file that contains the serialized GameInfo.
      See Also:

    • setInfo

      public static void setInfo(URL gameInfoFile)