LITIENGINE

https://litiengine.com/docs/
Admin
LITIENGINE is a free, open-source 2D Java game engine that provides infrastructure for creating...
Tokens:74,109
Snippets:1,107
Trust Score:8.7
Update:5 months ago
Show doc for...
Tokens:
Raw
### Basic Game Setup

Source: https://litiengine.com/docs/getting-started/api-quick-reference

A common pattern for setting up a new LitiEngine game, including initialization and starting the game loop.

```APIDOC
## Common Patterns - Basic Game Setup
```java
public static void main(String[] args) {
  Game.info().setName("My Game");
  Game.init(args);
  Resources.load("game.litidata");
  Game.world().loadEnvironment("level1");
  Game.start();
}
```
```

--------------------------------

### Basic Game Setup and Initialization

Source: https://litiengine.com/docs/getting-started/api-quick-reference

Standard entry point for a LitiEngine game, setting the game name, initializing the engine, loading resources, loading the initial environment, and starting the game loop.

```java
public static void main(String[] args) {
  Game.info().setName("My Game");
  Game.init(args);
  Resources.load("game.litidata");
  Game.world().loadEnvironment("level1");
  Game.start();
}
```

--------------------------------

### Initialize and Start LITIENGINE Game

Source: https://litiengine.com/docs/getting-started/run-the-game

Use this snippet to initialize the Game infrastructure with command-line arguments and start the game. This will spawn an empty window.

```java
import de.gurkenlabs.litiengine.Game;

public class Program {

  public static void main(String[] args) {
    Game.init(args);
    Game.start();
  }
}
```

--------------------------------

### Game Initialization and Start

Source: https://litiengine.com/docs/game-api

This snippet shows the basic steps to initialize and start the LITIENGINE game from the application's entry point.

```APIDOC
## Game Initialization and Start

### Description
Initializes the LITIENGINE game with provided arguments and starts the game loop.

### Method
Static method call

### Endpoint
N/A (Java static method)

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
```java
public static void main(String[] args) {
  Game.init(args);
  Game.start();
}
```

### Response
#### Success Response (N/A)
N/A

#### Response Example
N/A
```

--------------------------------

### Initialize and Start the Game

Source: https://litiengine.com/docs/game-api

This is the entry point for launching a LITIENGINE game. It initializes the game infrastructure and then starts the game loop.

```java
public static void main(String[] args) {
  Game.init(args);
  Game.start();
}
```

--------------------------------

### Start Ball Method

Source: https://litiengine.com/docs/tutorials/creating-an-arkanoid-clone

Initializes and starts the ball's movement. Sets its angle, velocity, acceleration, and state to INGAME.

```java
private static void startBall() {
  Ball.instance().setAngle(180);
  Ball.instance().setVelocity(GAMESPEED);
  Ball.instance().setAcceleration(500);
  Ball.setState(Ball.BallState.INGAME);
}
```

--------------------------------

### Initialize and Start Game Lifecycle

Source: https://litiengine.com/docs/getting-started/api-quick-reference

Use these methods to initialize the LITIENGINE, start the game loop, and terminate the game. You can also set the game's name and version.

```java
Game.init(args);                           // Initialize engine
Game.start();                              // Start game loop
Game.exit();                               // Terminate game

Game.info().setName("My Game");            // Set game name
Game.info().setVersion("v1.0.0");          // Set version
```

--------------------------------

### Initialize Game Window Setup

Source: https://litiengine.com/docs/game-api/game-window

Configure game information and initialize the game engine. The window icon can be set after initialization.

```java
public static void main(String[] args) {
  // Set game info first (used for window title)
  Game.info().setName("My Game");
  Game.info().setVersion("v1.0.0");

  Game.init(args);

  // Set window icon after initialization
  Game.window().setIcon(Resources.images().get("icon.png"));

  Game.start();
}
```

--------------------------------

### Example Sprite Info File Structure

Source: https://litiengine.com/docs/resource-management/sprite-info-files

This example demonstrates the structure of a sprite info file, including comments and various entries for different sprite types.

```text
#mobs
gnome1_walk.png,16,16
gnome1-dead.png,16,13
civilian1-walk.png,16,32
civilian2-walk.png,16,32
civilian3-walk.png,16,32

#clown
clown-walk-down.png,18,34
clown-walk-up.png,18,34
clown-cakethrow-preparation-down.png,20,34
clown-cakethrow-preparation-up.png,20,34
clown-victory.png,18,45;200,120,200,200,200,120,120,300,120,4000,200,200

#props
prop-tent1-intact.png,83,60
prop-car1-intact.png,43,20
prop-car2-intact.png,43,20
prop-bookshelf1-intact.png,32,16
prop-bed1-intact.png,16,8

#misc
arrow-throw.png,8,8
arrow-throw-red.png,8,8
projectile-cake.png,8,6
nose.png,5,9
```

--------------------------------

### Check Gradle Version

Source: https://litiengine.com/docs/tutorials/modifying-example-projects

Verify that Gradle is installed and accessible by checking its version. This command is essential for confirming your Gradle setup.

```bash
gradle -v
```

--------------------------------

### Configuration Properties

Source: https://litiengine.com/docs/getting-started/api-quick-reference

Example configuration properties for graphics, frame rate, and client settings.

```APIDOC
## Configuration
```properties
# config.properties
gfx_fullscreen=false
gfx_enableResolutionScale=true
cl_maxFps=60
cl_showGameMetrics=true
client_updaterate=60
```
```

--------------------------------

### Example Configuration File Excerpt

Source: https://litiengine.com/docs/configuration

This excerpt shows typical key-value pairs found in a LITIENGINE game's config.properties file for various settings.

```properties
cl_country=US
cl_language=en
cl_maxFps=60
cl_showGameMetrics=true
cl_updaterate=60
sfx_musicVolume=0.5
sfx_soundVolume=0.5
gfx_enableResolutionScale=true
gfx_fullscreen=false
gfx_graphicQuality=VERYHIGH
...
```

--------------------------------

### Game Configuration Properties

Source: https://litiengine.com/docs/getting-started/api-quick-reference

Example configuration properties for graphics, fullscreen, resolution scaling, FPS limits, and client update rates.

```properties
# config.properties
gfx_fullscreen=false
gfx_enableResolutionScale=true
cl_maxFps=60
cl_showGameMetrics=true
client_updaterate=60
```

--------------------------------

### Example Spritesheet Names

Source: https://litiengine.com/docs/control-entities/animation-controller

These examples illustrate the spritesheet naming convention for different entity states and directions.

```text
gurknukem-idle-left.png
gurknukem-walk-left.png
gurknukem-dead.png
```

--------------------------------

### Game Lifecycle

Source: https://litiengine.com/docs/getting-started/api-quick-reference

Essential methods for initializing, starting, and exiting the game, as well as setting game metadata.

```APIDOC
## Game Lifecycle
```java
Game.init(args);                           // Initialize engine
Game.start();                              // Start game loop
Game.exit();                               // Terminate game

Game.info().setName("My Game");            // Set game name
Game.info().setVersion("v1.0.0");          // Set version
```
```

--------------------------------

### Clone LITIENGINE Project

Source: https://litiengine.com/docs/player-input/keyboard-input

To begin working with keyboard input, clone the LITIENGINE example project from GitHub. This provides a base for your game development.

```bash
git clone https://github.com/gurkenlabs/litiengine-gurk-nukem.git
```

--------------------------------

### Example Logging Configuration

Source: https://litiengine.com/docs/configuration

Configure LITIENGINE's logging behavior by defining handlers, levels, formatters, and file output settings in a logging.properties file.

```properties
handlers=java.util.logging.FileHandler, java.util.logging.ConsoleHandler

java.util.logging.ConsoleHandler.level=WARNING
java.util.logging.ConsoleHandler.formatter=java.util.logging.SimpleFormatter

java.util.logging.FileHandler.level=WARNING
java.util.logging.FileHandler.pattern=game.log
java.util.logging.FileHandler.formatter=java.util.logging.SimpleFormatter
java.util.logging.FileHandler.append=true
java.util.logging.FileHandler.limit = 50000
java.util.logging.FileHandler.count = 1
```

--------------------------------

### Initialize and Run LITIENGINE Game

Source: https://litiengine.com/docs/tutorials/creating-a-platformer

Sets up game metadata, initializes the game engine, loads resources, and starts the game loop. Ensure 'icon.png' and 'game.litidata' exist in your project.

```java
public class Program {
  public static void main(String[] args) {
    // set meta information about the game
    Game.info().setName("GURK NUKEM");
    Game.info().setSubTitle("");
    Game.info().setVersion("v0.0.1");
    Game.info().setWebsite("https://github.com/gurkenlabs/litiengine-gurk-nukem");
    Game.info().setDescription("An example 2D platformer with shooter elements made in the LITIENGINE");

    // init the game infrastructure
    Game.init(args);

    // set the icon for the game (this has to be done after initialization because the ScreenManager will not be present otherwise)
    Game.window().setIcon(Resources.images().get("icon.png"));
    Game.graphics().setBaseRenderScale(4f);

    // load data from the utiLITI game file
    Resources.load("game.litidata");

    // load the first level (resources for the map were implicitly loaded from the game file)
    Game.world().loadEnvironment("level1");
    Game.start();
  }
}
```

--------------------------------

### Keyboard Input Listener for Ball Start

Source: https://litiengine.com/docs/tutorials/creating-an-arkanoid-clone

Adds a listener to the keyboard input to start the ball's movement when the space key is pressed. Ensures the game is in the correct state.

```java
Input.keyboard().onKeyPressed(e -> {
  if (e.getKeyCode() == KeyEvent.VK_SPACE) {
    if (GameHandler.getState() == GameState.INGAME && Ball.getState() == Ball.BallState.IDLE) {
      startBall();
    }
  }
});
```

--------------------------------

### Accessing the Game Window

Source: https://litiengine.com/docs/game-api/game-window

This snippet shows how to get an instance of the GameWindow class to manage window properties.

```APIDOC
## Accessing the Game Window

The `Game.window()` method provides access to the `GameWindow` class, which manages the window that hosts your game’s rendering component. Use it to control window properties like title, icon, resolution, cursor, and display mode.
```java
// Access the game window
GameWindow window = Game.window();
```
```

--------------------------------

### Create a Menu Screen

Source: https://litiengine.com/docs/user-interface/creating-menus

Extend the Screen class to create a new menu screen. Override prepare() for pre-render setup, render() for drawing, and initializeComponents() for adding GUI elements.

```java
public class MenuScreen extends Screen {
  public MenuScreen() {
    super("MENU");
  }

  @Override
  public void prepare() {
    // This method will be called right before the screen is displayed
    super.prepare();
  }

  @Override
  public void render(Graphics2D g) {
    // This method is called on every tick and lets you draw shapes, text, images etc. explicitly.
    // Calling super.render(g) also renders all GuiComponents in this.getComponents()
    super.render(g);
  }

  @Override
  protected void initializeComponents() {
    // This method is called once by the Screen's constructor. Use it to initialize the GuiComponents that will be contained by this screen. 
    // Don't forget to call this.getComponents().add(GuiComponent c) so that the components will actually be rendered.
    super.initializeComponents();
  }
}
```

--------------------------------

### Toggle Fullscreen at Runtime

Source: https://litiengine.com/docs/game-api/game-window

Toggle fullscreen mode at runtime using a keyboard shortcut. This example uses the F11 key.

```java
Input.keyboard().onKeyPressed(KeyEvent.VK_F11, e -> {
  Game.window().setFullscreen(!Game.window().isFullscreen());
});
```

--------------------------------

### CollisionEntity with Wall Example

Source: https://litiengine.com/docs/entity-framework/default-entity-types

Shows how to create a `Wall` entity that extends `CollisionEntity`. It configures collision properties using annotations, defining dimensions and enabling collision.

```java
@EntityInfo(width = 32, height = 32)
@CollisionInfo(collisionBoxWidth = 28, collisionBoxHeight = 28, collision = true)
public class Wall extends CollisionEntity {
  public Wall() {
    super("wall");
  }
}
```

--------------------------------

### Create and Configure a CheckBox

Source: https://litiengine.com/docs/user-interface/guicomponents-an-overview

Provides an example of creating a CheckBox component. It shows how to set the initial checked state and define a callback function that executes when the checkbox's state changes, such as adjusting game settings.

```java
CheckBox checkbox = new CheckBox("Enable Sound", true);
checkbox.onChecked(e -> {
  Game.audio().setSoundVolume(e.isChecked() ? 1.0f : 0.0f);
});
```

--------------------------------

### Example LITIENGINE Project Structure

Source: https://litiengine.com/docs/getting-started/project-structure

This is a common directory layout for a LITIENGINE game project. It includes folders for sprites, audio, maps, localization, and source code, along with configuration files.

```tree
game-project
└─── sprites
│   │─── sprite1.png
│   └─── ...
│─── audio
│   │─── sound1.ogg
│   └─── ...
│─── maps
│   │─── map1.tmx
│   │─── tileset.tsx
│   │─── tileset.png
│   └─── ...
│─── localization
│   │─── strings.properties
│   │─── strings_de_DE.properties
│   └─── ...
│─── src
│   └─── com
│        └─── mygame
│             │─── Program.java
│             └─── ...
│─── .classpath
│─── game.litidata
│─── config.properties
│─── build.gradle
│─── settings.gradle
└───...
```

--------------------------------

### Create Custom AStarMovementController

Source: https://litiengine.com/docs/control-entities/movement-controller

Implement a custom movement controller, such as AStarMovementController, for pathfinding. This example moves the entity towards the next waypoint in a given path.

```java
public class AStarMovementController extends MovementController<Creature> {

  private Queue<Point2D> path;

  public AStarMovementController(Creature entity) {
    super(entity);
  }

  @Override
  public void update() {
    if (path == null || path.isEmpty()) {
      return;
    }

    Point2D target = path.peek();
    if (getEntity().getLocation().distance(target) < 5) {
      path.poll();
      return;
    }

    // Move toward current waypoint
    double angle = getEntity().getAngleTo(target);
    Game.physics().move(getEntity(), angle, getEntity().getVelocity());
  }

  public void setPath(Queue<Point2D> path) {
    this.path = path;
  }
}
```

--------------------------------

### Implement a Custom LITIENGINE Screen

Source: https://litiengine.com/docs/game-api/screens

Provides an example of a custom screen implementation that extends the default GameScreen. This snippet shows how to set a screen name, override the render method for custom drawing, and use LITIENGINE's resources for fonts, colors, and text rendering.

```java
// a custom screen implementation that renders "Test text" on the screen
public class TestScreen extends GameScreen {
  public TestScreen() {
    super("TEST");
  }
  @Override
  public void render(final Graphics2D g) {
    super.render(g);
    g.setFont(Resources.fonts().get("customfont.ttf",32f));
    g.setColor(Color.RED);
    TextRenderer.render(g, "Test text", 100, 100);
  }
}
```

--------------------------------

### Create and Configure a Trigger via Code

Source: https://litiengine.com/docs/advanced/advanced-entity-knowledge/triggers

Instantiate a Trigger entity, set its position and dimensions, and add it to the game environment. This is the basic setup for using triggers programmatically.

```java
Trigger trigger = new Trigger("myTrigger", TriggerActivation.PROPAGATE);
trigger.setLocation(100, 100);
trigger.setWidth(64);
trigger.setHeight(64);

// Add to environment
Game.world().environment().add(trigger);
```

--------------------------------

### Control Entities with Gamepad Input

Source: https://litiengine.com/docs/player-input/gamepad-input

Create a controller to map gamepad analog stick input directly to entity movement. This example assumes an IMobileEntity with setDx/setDy methods.

```java
public class GamepadEntityController<T extends IMobileEntity> extends MovementController<T> {

  public GamepadEntityController(T entity) {
    super(entity);
    Input.gamepadManager().onPressed(Gamepad.Xbox.LEFT_STICK_X, x -> {
      this.setDx((float) x);
    });
    Input.gamepadManager().onPressed(Gamepad.Xbox.LEFT_STICK_Y, y -> {
      this.setDy((float) y);
    });
  }
}
```

--------------------------------

### Listen for Entity Added to Environment

Source: https://litiengine.com/docs/control-entities/messaging-system

Subscribe to events that are triggered when a new entity is added to the game environment. This can be used for entity registration or initial setup.

```java
// When entity is added to environment
Game.world().environment().onEntityAdded(e -> {
  System.out.println("Entity added: " + e.getEntity().getName());
});
```

--------------------------------

### Execute utiLITI on Windows

Source: https://litiengine.com/docs/utiliti-editor

Unzip the downloaded LITIENGINE SDK and run the executable file for the utiLITI editor on Windows.

```bash
utiliti-win/utiliti-vX.X.X.exe
```

--------------------------------

### Initialize Window with Custom Settings

Source: https://litiengine.com/docs/game-api/game-window

Initialize the game and configure window appearance, including setting the icon, custom cursor, and render scale for a pixel art look.

```java
public static void main(String[] args) {
  Game.info().setName("My Game");
  Game.info().setVersion("v1.0.0");

  Game.init(args);

  // Configure window appearance
  Game.window().setIcon(Resources.images().get("icon.png"));
  Game.window().cursor().set(Resources.images().get("cursor.png"), 8, 8);

  // Set render scale for pixel art look
  Game.graphics().setBaseRenderScale(4f);

  Game.start();
}
```

--------------------------------

### Create Application Entry Point

Source: https://litiengine.com/docs/getting-started/run-the-game

A simple Java class with a static main method is required to serve as the application's entry point for the JVM. Keep this class minimal, focusing solely on game startup.

```java
public class Program {

  public static void main(String[] args) {
  }
}
```

--------------------------------

### Execute utiLITI on Linux/Mac

Source: https://litiengine.com/docs/utiliti-editor

Unzip the downloaded LITIENGINE SDK and run the JAR file for the utiLITI editor on Linux or macOS.

```bash
utiliti/utiliti-vX.X.X.jar
```

--------------------------------

### Control Entity Animations

Source: https://litiengine.com/docs/getting-started/api-quick-reference

Play animations on an entity and get the currently playing animation.

```java
entity.getAnimationController().play("walk");
entity.getAnimationController().getCurrentAnimation();
```

--------------------------------

### Getting Window Resolution

Source: https://litiengine.com/docs/game-api/game-window

This snippet explains how to retrieve the current resolution of the game window.

```APIDOC
### Getting Resolution

```java
// Get current window resolution
Dimension resolution = Game.window().getResolution();
int width = resolution.width;
int height = resolution.height;

// Get host screen resolution
Dimension screenResolution = Game.window().getHostScreenResolution();
```
```

--------------------------------

### Getting Mouse Location

Source: https://litiengine.com/docs/player-input/mouse-input

Retrieves the current position of the mouse cursor relative to the game window.

```APIDOC
## Getting Mouse Location

### Description
Retrieves the current position of the mouse cursor relative to the game window.

### Method
`Input.mouse().getLocation()`

### Returns
A `Point2D` object representing the mouse coordinates (x, y).

### Example
```java
// Get current mouse location (window coordinates)
Point2D location = Input.mouse().getLocation();
double x = location.getX();
double y = location.getY();
```

### Note
The coordinates are relative to the game window, not the game world. To get world coordinates, account for camera position.
```

--------------------------------

### Create Keyboard Input Directory and File

Source: https://litiengine.com/docs/player-input/keyboard-input

After cloning the project, create the necessary directory structure and Java file to implement custom keyboard input handling. This involves creating a 'de.gurkenlabs.litiengine.input' directory within the 'src' folder and a 'KeyboardEntityController.java' file inside it.

```java
Create KeyboardEntityController.java file inside the input folder.
```

--------------------------------

### Animation Control

Source: https://litiengine.com/docs/getting-started/api-quick-reference

Control entity animations, including playing animations and getting the current animation state.

```APIDOC
## Animation
```java
entity.getAnimationController().play("walk");
entity.getAnimationController().getCurrentAnimation();
```
```

--------------------------------

### Initialize Player with Input Controller

Source: https://litiengine.com/docs/tutorials/creating-an-arkanoid-clone

Set up the player's sprite and add a keyboard controller for left and right movement.

```java
private Player() { 
  super("vaus"); 
  KeyboardEntityController playerController = new KeyboardEntityController<>(this); 
  playerController.addLeftKey(KeyEvent.VK_LEFT); 
  playerController.addRightKey(KeyEvent.VK_RIGHT); 
  this.setController(IMovementController.class, playerController); 
}
```

--------------------------------

### Build and Run Project

Source: https://litiengine.com/docs/tutorials/modifying-example-projects

Use these Gradle commands to build and run the SERVUS BONUS project. Ensure './' is used to specify the local gridlew execution.

```bash
./gradlew build
./gradlew run
```

--------------------------------

### Accessing Gamepads

Source: https://litiengine.com/docs/player-input/gamepad-input

Retrieve the GamepadManager and lists of connected gamepads. You can get all connected gamepads or the currently active one.

```APIDOC
## Accessing Gamepads
```java
// Get the gamepad manager
GamepadManager manager = Input.gamepadManager();

// Get all connected gamepads
List<Gamepad> gamepads = Input.gamepads().getAll();

// Get the first connected gamepad
Gamepad gamepad = Input.gamepads().getCurrent();
```
```

--------------------------------

### Customize KeyboardEntityController Keys

Source: https://litiengine.com/docs/control-entities/movement-controller

Customize the keys used by KeyboardEntityController for movement. This example rebinds the default arrow keys to WASD.

```java
public class Player extends Creature {

  @Override
  protected IMovementController createMovementController() {
    KeyboardEntityController<Player> controller = new KeyboardEntityController<>(this);

    // Customize keys (default: arrow keys)
    controller.addUpKey(KeyEvent.VK_W);
    controller.addDownKey(KeyEvent.VK_S);
    controller.addLeftKey(KeyEvent.VK_A);
    controller.addRightKey(KeyEvent.VK_D);

    return controller;
  }
}
```

--------------------------------

### Custom Particle Behavior

Source: https://litiengine.com/docs/advanced/the-particle-system

Extend the `Particle` class to create custom particle behavior. This example implements a flickering effect.

```java
public class SparkParticle extends Particle {

  public SparkParticle() {
    super();
    this.setWidth(4);
    this.setHeight(4);
    this.setColor(Color.YELLOW);
  }

  @Override
  public void update(float updateRatio) {
    super.update(updateRatio);

    // Custom behavior: flicker
    if (Game.random().nextFloat() > 0.5f) {
      this.setVisible(!this.isVisible());
    }
  }
}
```

--------------------------------

### Get Game Version with Info Component

Source: https://litiengine.com/docs/game-api

Retrieves the current version of the LITIENGINE. This is a meta component for accessing game information.

```java
System.out.println("Game version is: " + Game.info().getVersion());
```

--------------------------------

### Initialize Game Logic with LITIENGINE

Source: https://litiengine.com/docs/tutorials/creating-a-platformer

Set up global game logic such as camera, gravity, and entity spawning. This class should be called from the main method to initialize the game.

```java
public final class GurkNukemLogic {

  private GurkNukemLogic() {
  }

  /**
  * Initializes the game logic for the GURK NUKEM game.
  */
  public static void init() {
    // we'll use a camera in our game that is locked to the location of the player
    Camera camera = new PositionLockCamera(Player.instance());
    camera.setClampToMap(true);
    Game.world().setCamera(camera);

    // set a basic gravity for all levels.
    Game.world().setGravity(120);

    // add default game logic for when a level was loaded
    Game.world().onLoaded(e -> {
      // spawn the player instance on the spawn point with the name "enter"
      Spawnpoint enter = e.getSpawnpoint("enter");
      if (enter != null) {
        enter.spawn(Player.instance());
      }
    });
  }
}
```

--------------------------------

### Play Sounds and Music with LITIENGINE

Source: https://litiengine.com/docs/game-api/sound-engine

Demonstrates various ways to play sounds and music using the LITIENGINE Game.audio() methods. Includes playing sounds at specific coordinates, relative to an entity, and playing background music. Also shows how to use SoundPlayback to listen for sound events.

```java
Sound mySound = Resources.sounds().get("my-sound.ogg");

// play the sound
Game.audio().playSound(mySound);

// play the sound at environment location (50/50)
Game.audio().playSound(mySound, 50, 50);

// play the sound at location of an entity
Game.audio().playSound(mySound, myEntity);

// play background music
Game.audio().playMusic(Resources.sounds().get("my-music.ogg"));

// use the SoundPlayback to react to events
SoundPlayback playback = Game.audio().playSound(mySound);
playback.addSoundPlaybackListener(new SoundPlaybackListener() {

  @Override
  public void finished(SoundEvent event) {
  }
  @Override
  public void cancelled(SoundEvent event) {
  }
});
```

--------------------------------

### Create and Configure a Button

Source: https://litiengine.com/docs/user-interface/guicomponents-an-overview

Illustrates the creation of a Button component. It demonstrates setting the button's text and defining an action to be performed when the button is clicked, such as changing the game screen.

```java
Button button = new Button("Start Game");
button.onClicked(e -> {
  Game.screens().display("GAME");
});
```

--------------------------------

### Render Engine Operations

Source: https://litiengine.com/docs/game-api/render-engine

Examples of how to use the RenderEngine to draw text and shapes. The RenderEngine translates environment coordinates to screen coordinates.

```APIDOC
## Render Engine - Game.graphics()

### Description
The 2D `RenderEngine` is used to render texts, shapes, images and entities at their location in the `Environment` and with respect to the `Camera`‘s location and zoom. Notice that the location lies within the coordinate space of the current `Environment`. The `RenderEngine` will translate the coordinates to a location on the screen.

### Method
`Game.graphics()`

### Endpoints
- `renderText(g, text, x, y)`: Renders the specified text at the given environment coordinates.
- `renderShape(g, shape)`: Renders the specified shape at its defined coordinates.

### Parameters
#### `renderText` Parameters
- **g** (`Graphics2D`) - The graphics context.
- **text** (String) - The text to render.
- **x** (float) - The environment X-coordinate.
- **y** (float) - The environment Y-coordinate.

#### `renderShape` Parameters
- **g** (`Graphics2D`) - The graphics context.
- **shape** (`java.awt.geom.Rectangle2D`) - The shape to render.

### Request Example
```java
// render "my text" at the environment location (50/100)
Game.graphics().renderText(g, "my text", 50, 100);

// render "my text" at the location of an entity
Game.graphics().renderText(g, "my text", myEntity.getX(), myEntity.getY());

// render a rectangle (50x50 px) at the environment location (50/100)
Rectangle2D rect = new Rectangle2D.Double(50, 100, 50, 50);
Game.graphics().renderShape(g, rect);
```

### Note
Rendering an `Entity` explicitly over the `RenderEngine` should never be necessary as long as the Entity was added to the game’s current `Environment`. The rendering process of the current `Environment` takes care of drawing all the entities and implicitly calls these methods on the `RenderEngine`.
```

--------------------------------

### Set Particle Color and Opacity

Source: https://litiengine.com/docs/advanced/the-particle-system

Define the starting and ending colors for particles, and control their fade-in/fade-out behavior using alpha values.

```java
emitter.getData().setStartColor(Color.ORANGE);
emitter.getData().setEndColor(Color.RED);

emitter.getData().setMinStartAlpha(1.0f);
emitter.getData().setMaxStartAlpha(1.0f);
emitter.getData().setMinEndAlpha(0.0f);
emitter.getData().setMaxEndAlpha(0.0f);
```

--------------------------------

### Create and Configure a DropdownListField

Source: https://litiengine.com/docs/user-interface/guicomponents-an-overview

Instantiate a dropdown list with provided options. Set up a callback to process the selected item.

```java
DropdownListField<String> dropdown = new DropdownListField<>(options);
dropdown.onChange(e -> {
  String selected = dropdown.getSelectedObject();
});
```

--------------------------------

### Game Loop Control

Source: https://litiengine.com/docs/getting-started/api-quick-reference

Manage the game loop, including registering updates, getting timing information, and controlling tick rate.

```APIDOC
## Game Loop
```java
Game.loop().attach(updateable);           // Register for updates
Game.loop().detach(updateable);           // Unregister
Game.loop().getDeltaTime();               // Ms since last tick
Game.loop().getTicks();                   // Total ticks
Game.loop().getTickRate();                // Ticks per second
Game.loop().setTickRate(30);              // Change tick rate
Game.loop().execute(60, () -> {...});     // Execute after 60 ticks
```
```

--------------------------------

### Add and Display Custom Screens in LITIENGINE

Source: https://litiengine.com/docs/game-api/screens

Demonstrates how to add custom screen implementations to the ScreenManager and how to display a specific screen by its name. Also shows how to retrieve and print the name of the currently active screen.

```java
// add some custom screens to the ScreenManager
Game.screens().add(new MenuScreen());
Game.screens().add(new IngameScreen());
Game.screens().add(new EndOfLevelScreen());

// display the screen with the name "MENU"
Game.screens().display("MENU");

// print the name of the currently active screen
System.out.println("Currently active screen: " + Game.screens().current().getName());
```

--------------------------------

### Control Camera Viewport

Source: https://litiengine.com/docs/getting-started/api-quick-reference

Access the game camera, set its focus to an entity, adjust zoom level, and get the current viewport.

```java
Game.world().camera();
camera.setFocus(entity);
camera.setZoom(2f);
camera.getViewport();
```

--------------------------------

### Get Host Screen Resolution

Source: https://litiengine.com/docs/game-api/game-window

Obtain the resolution of the screen on which the game window is currently displayed. This can differ from the window's resolution.

```java
// Get host screen resolution
Dimension screenResolution = Game.window().getHostScreenResolution();
```

--------------------------------

### Configure Default Fullscreen Mode

Source: https://litiengine.com/docs/game-api/game-window

Configure the default fullscreen mode in `config.properties`.

```properties
gfx_fullscreen=false
```

--------------------------------

### Get Current Window Resolution

Source: https://litiengine.com/docs/game-api/game-window

Retrieve the current width and height of the game window. This is useful for UI scaling or layout adjustments.

```java
// Get current window resolution
Dimension resolution = Game.window().getResolution();
int width = resolution.width;
int height = resolution.height;
```

--------------------------------

### Manage Game Environment and Entities

Source: https://litiengine.com/docs/game-api/game-world

Demonstrates loading an environment, adding, retrieving, and removing entities. Use these methods to interact with the game world.

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

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

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

```java
// remove the entity by its name
Game.world().environment().remove("my-entity");
```

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

--------------------------------

### Initialize Player Input Bindings

Source: https://litiengine.com/docs/tutorials/creating-a-platformer

Sets up keyboard bindings for player actions. Use this to define custom key presses for game events, such as exiting the game with the ESCAPE key.

```java
public final class PlayerInput {

  private PlayerInput() {
  }

  public static void init() {
    // make the game exit upon pressing ESCAPE (by default there is no such key binding and the window needs to be shutdown otherwise, e.g. ALT-F4 on Windows)
    Input.keyboard().onKeyPressed(KeyEvent.VK_ESCAPE, e -> System.exit(0));
  }
}
```

--------------------------------

### Fire Custom Controller Events

Source: https://litiengine.com/docs/control-entities/entity-controllers

Controllers can define and fire custom events to notify listeners. This example shows firing an attack event.

```java
public class CombatController extends EntityController<Creature> {

  public void attack() {
    // Perform attack
    fireAttackEvent();
  }

  private void fireAttackEvent() {
    // Notify listeners
    getEntity().getListeners().forEach(l -> l.onAttack());
  }
}
```

--------------------------------

### Create Custom MapObjectLoader

Source: https://litiengine.com/docs/tile-maps/map-objects

Extend MapObjectLoader to define custom entity types and their loading logic. Register the custom loader before starting the game.

```java
public class MyEntityLoader extends MapObjectLoader {

  public MyEntityLoader() {
    super("MY_ENTITY_TYPE");
  }

  @Override
  public Collection<IEntity> load(Environment environment, IMapObject mapObject) {
    Collection<IEntity> entities = new ArrayList<>();

    MyEntity entity = new MyEntity();
    entity.setLocation(mapObject.getLocation());
    entity.setWidth(mapObject.getWidth());
    entity.setHeight(mapObject.getHeight());

    entities.add(entity);
    return entities;
  }
}

// Register before Game.start()
Environment.registerMapObjectLoader(new MyEntityLoader());
```

--------------------------------

### Game Lifecycle Event Listeners

Source: https://litiengine.com/docs/game-api

Register event listeners to handle basic game lifecycle operations like initialization, start, and termination.

```APIDOC
## Game Lifecycle Event Listeners

### Description
Allows registration of listeners to react to key events in the game's lifecycle, such as initialization, starting, and termination.

### Method
Static method call

### Endpoint
N/A (Java static method)

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
```java
Game.addGameListener(new GameListener() {
  @Override
  public void initialized(String... args) {
    // do sth when game is initialized
  }
  @Override
  public void started() {
    // do sth when game started
  }

  @Override
  public void terminated() {
    // do sth when game terminated
  }
});
```

### Response
#### Success Response (N/A)
N/A

#### Response Example
N/A
```

--------------------------------

### Set up .bashrc for WSL Display

Source: https://litiengine.com/docs/tutorials/modifying-example-projects

For WSL users, add this export command to your ~/.bashrc file to enable floating window displays.

```bash
vi ~/.bashrc
export DISPLAY=0:0
```

--------------------------------

### Register Game Lifecycle Event Listeners

Source: https://litiengine.com/docs/game-api

Add listeners to the Game class to react to key lifecycle events such as initialization, starting, and termination.

```java
Game.addGameListener(new GameListener() {
  @Override
  public void initialized(String... args) {
    // do sth when game is initialized
  }
  @Override
  public void started() {
    // do sth when game started
  }

  @Override
  public void terminated() {
    // do sth when game terminated
  }
});
```

--------------------------------

### Enable Debug Metrics in LITIENGINE

Source: https://litiengine.com/docs/advanced/performance-optimization

Shows how to enable the display of FPS and tick rate in the game. This can be done programmatically or via the config.properties file.

```java
Game.config().debug().setShowGameMetrics(true);
```

```properties
cl_showGameMetrics=true
```

--------------------------------

### Register Custom MapObjectLoader

Source: https://litiengine.com/docs/control-entities/behavior-controller

Registers the custom PathMapObjectLoader with the environment before starting the game. This ensures that 'PATH' objects defined in the map are correctly processed.

```java
Environment.registerMapObjectLoader(new PathMapObjectLoader());
```

--------------------------------

### Smoke Effect Configuration

Source: https://litiengine.com/docs/advanced/the-particle-system

Configure particle properties for a smoke effect, including velocity, start color, end color, and alpha fade-out.

```java
emitter.getData().setVelocityYMin(-30);
emitter.getData().setVelocityYMax(-15);
emitter.getData().setStartColor(Color.DARK_GRAY);
emitter.getData().setEndColor(Color.LIGHT_GRAY);
emitter.getData().setMinStartAlpha(0.8f);
emitter.getData().setMaxEndAlpha(0.0f);
```

--------------------------------

### Configure Gradle Build for LitiEngine Game

Source: https://litiengine.com/docs/deployment

This Gradle script configures the build process for a LitiEngine game, including setting up the launch4j plugin for Windows executables, defining source sets, managing dependencies, and configuring JAR packaging. It also specifies JVM options and includes native libraries and resources for different platforms.

```gradle
plugins {
  id 'edu.sc.seis.launch4j' version '2.4.4'
}

apply plugin: 'java'
apply plugin: 'eclipse'
apply plugin: 'maven'

archivesBaseName = "mygame"
version = "v1.0.2"
targetCompatibility = "1.8.0"

sourceSets {
  main.java.srcDir "src"
  main.java.srcDir "resources"
  main.java.srcDir "sounds"
  main.java.srcDir "maps"
  main.java.srcDir "localization"

  main.resources.includes = ["game.litidata"]
}

repositories {
   mavenCentral()
}

dependencies {
 compile project(':litiengine')
}

compileJava.options.encoding = 'UTF-8'

jar {
  from {
    configurations.runtime.collect {
      it.isDirectory() ? it : zipTree(it)
    }
    configurations.compile.collect {
      it.isDirectory() ? it : zipTree(it)
    }
  }  {
     exclude 'META-INF/services/**'
  }

  // make sure to only include service providers from the litiengine when directly referencing the project
  from ("${project(':litiengine').projectDir}/resources/") {
    include 'META-INF/services/**'
  }

  from('resources') 
  {
    include '**/*'
    exclude 'sprites/*'
  }

  from('sounds') { include '**/*' }
  exclude '**/*.dll'
  exclude '**/*.jnilib'
  exclude '**/*.dylib'
  exclude '**/*.so'
  exclude 'junit**/**'

  from 'game.litidata'

  manifest {
    attributes 'Class-Path': ".",
               'Main-Class': "de.gurkenlabs.mygame.MyGame"
  }
}

launch4j {
  mainClassName = 'de.gurkenlabs.mygame.MyGame'
  icon = 'icon.ico'
  outputDir = 'libs'
  outfile = archivesBaseName +'.exe'
  companyName = 'gurkenlabs.de'
  version = '1.0.2'
  textVersion = '1.0.2'
  copyright = '2020 gurkenlabs.de'
  bundledJrePath = 'jre'
  jvmOptions = ['-Xms256m', '-Xmx1024m']
  cmdLine = '-release'
}

task copyNativeLibs(type: Copy) {
  def litiengineLibs ='../litiengine/build/libs'
  def buildFolder = new File(buildDir, 'libs')

  from(litiengineLibs) {
   include '**/*'
   exclude '**/*.jar'
   exclude '**/*.zip'
   exclude 'LICENSE'
   exclude 'lib/**'
  }

  from('/dist/){
    include 'icon.ico'
    include 'config.properties'
    include 'steam_appid.txt'
    include 'jre/**'
  }

  into buildFolder
}

build.dependsOn copyNativeLibs

task distZipWindow(type: Zip) {
   group 'build'
   from 'build/libs/'
   include '*.exe'
   include '*.dll'
   include 'config.properties'
   include 'jre/**'

   archiveName archivesBaseName + '-' + version + '-win.zip'
   exclude archiveName
   exclude 'jinput-dx8_64.dll'
   exclude 'jinput-raw_64.dll'
   exclude 'steam_api64.dll'
   exclude 'steamworks4j64.dll'
   destinationDir(file('build/libs/'))
}

task distZipLinux(type: Zip) {
   group 'build'
   from 'build/libs/'
   include '*.jar'
   include '*.so'
   include 'config.properties'

   archiveName archivesBaseName + '-' + version + '-linux.zip'
   exclude archiveName
   destinationDir(file('build/libs/'))
}

task distZipOSX(type: Zip) {
   group 'build'
   from 'build/libs/'
   include '*.jar'
   include '*.jnilib'
   include '*.dylib'

   include 'config.properties'

   archiveName archivesBaseName + '-' + version + '-osx.zip'
   exclude archiveName
   destinationDir(file('build/libs/'))
}

tasks.withType(JavaCompile) {
    options.encoding = 'UTF-8'
}

```

--------------------------------

### Fire Effect Configuration

Source: https://litiengine.com/docs/advanced/the-particle-system

Configure particle properties to simulate a fire effect, including velocity, start color, end color, and scale.

```java
emitter.getData().setVelocityYMin(-80);
emitter.getData().setVelocityYMax(-40);
emitter.getData().setStartColor(Color.YELLOW);
emitter.getData().setEndColor(Color.RED);
emitter.getData().setMinStartScale(1.5f);
emitter.getData().setMaxEndScale(0.2f);
```

--------------------------------

### Get Mouse Location

Source: https://litiengine.com/docs/player-input/mouse-input

Retrieves the current mouse coordinates relative to the game window. For world coordinates, camera offset must be considered.

```java
Point2D location = Input.mouse().getLocation();
double x = location.getX();
double y = location.getY();
```

--------------------------------

### Configure Composite Build with Local LITIENGINE Repository

Source: https://litiengine.com/docs/getting-started/get-litiengine

Set up a composite build in your project's settings.gradle file to use a local clone of the LITIENGINE repository. This allows testing local engine changes without deploying artifacts.

```gradle
includeBuild ("../litiengine"){
    dependencySubstitution {
        substitute module('de.gurkenlabs:litiengine') using project(':litiengine')
    }
}
```

--------------------------------

### Create and Add LightSource Entity

Source: https://litiengine.com/docs/advanced/dynamic-lighting

Create a `LightSource` entity programmatically, set its location, intensity, color, and shape, then add it to the game environment.

```java
LightSource torch = new LightSource();
torch.setLocation(100, 100);
torch.setIntensity(150);           // Light radius
torch.setColor(Color.ORANGE);      // Light color
torch.setShape(LightSource.ELLIPSE); // Light shape

// Add to environment
Game.world().environment().add(torch);
```

--------------------------------

### Handle Entity Movement Events

Source: https://litiengine.com/docs/control-entities/movement-controller

Listen for movement events to react when an entity changes its position. This example logs the entity's new location.

```java
// When entity moves
entity.onMoved(e -> {
  System.out.println("Entity moved to: " + entity.getLocation());
});
```

--------------------------------

### Build a Java Project with Gradle

Source: https://litiengine.com/docs/tutorials/modifying-example-projects

Execute the Gradle build command to compile your Java project, run tests, and create a JAR file. This is a fundamental step in the build process.

```gradle
gradle build
```

--------------------------------

### Create and Configure a TextFieldComponent

Source: https://litiengine.com/docs/user-interface/guicomponents-an-overview

Instantiate a text field and set its initial text. Define a callback to capture text changes.

```java
TextFieldComponent textField = new TextFieldComponent();
textField.setText("Enter name...");
textField.onTextChanged(e -> {
  playerName = textField.getText();
});
```

--------------------------------

### Manually Trigger Update Method

Source: https://litiengine.com/docs/tutorials/creating-an-arkanoid-clone

Manually call the update() method. This can be a workaround if music playback is not starting automatically, typically called from the prepare() method.

```java
update();
```

--------------------------------

### Create and Configure a Slider

Source: https://litiengine.com/docs/user-interface/guicomponents-an-overview

Initialize a slider with a min, max, and step value. Set its initial value and define a callback for when the value changes.

```java
Slider slider = new Slider(0, 100, 1);
slider.setValue(50);
slider.onChange(e -> {
  int volume = (int) slider.getCurrentValue();
  Game.audio().setMusicVolume(volume / 100f);
});
```

--------------------------------

### Create and Configure a ListField

Source: https://litiengine.com/docs/user-interface/guicomponents-an-overview

Initialize a list field with a collection of items. Define a callback to handle item selection changes.

```java
ListField<String> list = new ListField<>(Arrays.asList("Option 1", "Option 2", "Option 3"));
list.onChange(e -> {
  String selected = list.getSelectedObject();
});
```

--------------------------------

### Grant Execution Permission to Gradlew

Source: https://litiengine.com/docs/tutorials/modifying-example-projects

Make the gradlew script executable. This is necessary to run build and run commands without a local Gradle installation.

```bash
sudo chmod 775 ./gradlew
```

--------------------------------

### Create and Configure a Label

Source: https://litiengine.com/docs/user-interface/guicomponents-an-overview

Shows how to create a Label component to display text. It includes setting the initial text and applying a custom font and color. This is useful for displaying scores, messages, or other static information.

```java
Label label = new Label("Score: 0");
label.setFont(Resources.fonts().get("gamefont.ttf", 24f));
label.setForeground(Color.WHITE);
```

--------------------------------

### Window Configuration Options

Source: https://litiengine.com/docs/game-api/game-window

Key window-related settings that can be configured in `config.properties`.

```properties
# Enable/disable resolution scaling
gfx_enableResolutionScale=true

# Start in fullscreen mode
gfx_fullscreen=false

# Maximum FPS (0 = unlimited, syncs to monitor if vsync enabled)
cl_maxFps=60

# Show game metrics (FPS, UPS) in corner
cl_showGameMetrics=false
```

--------------------------------

### Get Block Points and Remove Block

Source: https://litiengine.com/docs/tutorials/creating-an-arkanoid-clone

Retrieve points for a destroyed block based on its spritesheet name and remove it from the game environment. Ensure Block.getPointsOfBlock() is correctly implemented.

```java
int points = Block.getPointsOfBlock(hitObject.getSpritesheetName()); 
GameHandler.increasePoints(points); Game.world().environment().remove(hitObject);
```
Tokens:
Raw