LITIENGINE Documentation

LITIENGINE is a free and open source Java 2D Game Engine designed for tile-based 2D games. Key features include:

• Infrastructure: GameLoop, Configuration, Resource Management, and Logging.
• 2D Render Engine: GUI Components, Spritesheet Animations, Ambient Lighting, and Particle Systems.
• 2D Sound Engine: Support for .wav, .mp3, and .ogg formats.
• 2D Physics Engine
• Map Support: Tile Maps in .tmx format (compatible with Tiled Editor).
• Input: Player input via Gamepad, Keyboard, and Mouse.
• Entity Framework

To maintain visual consistency and automatic edge/corner transitions, always prioritize Wang terrains over manual GID editing.

• Preferred Method: Use paint_terrain or paint-terrain to resolve tile corner/edge transitions and neighbor GIDs across grid regions.
• Discovery: Call list_terrains or list-terrains first to find available Wang terrain sets (e.g., ground, grass, stone, walls, paths) and their auto-tiling rulesets.
• Fallback: Use plain tile editing (edit_tiles, fill_tiles, or set_tile) only for non-terrain decorative standalone tiles or when no matching Wang terrain set exists in the project tileset.

# 1. Discover available terrain sets
list-terrains

# 2. Use terrain painting for automatic transitions
paint-terrain <terrain_set> <region>

When authoring or modifying maps, follow a staged workflow to ensure gameplay stability before adding visual clutter. This prevents the need for massive structural changes later in the process.

1. Big: Gameplay Structure

   • Define the entrance, goal, critical path, major rooms, gates, encounters, transitions, and collision topology.
   • Rule: Do not place decorative clutter until core gameplay questions are resolved.

2. Medium: Spatial Identity

   • Establish walls, doors, major furniture, machinery, structural lighting, cover, and landmarks.
   • Ensure the environment reads clearly while supporting game mechanics.

3. Small: Detail & Atmosphere

   • Add floor variation, wall details, debris, small props, particles, atmospheric lighting, and overlay details.
   • Rule: Details must reinforce composition, navigation, or atmosphere; avoid random noise.

To enable gamepad support, your application must be launched with the --enable-native-access=ALL-UNNAMED flag. This grants Input4j access to the Foreign Function & Memory API.

While Java 25 allows unauthorized native access with a warning by default, using --illegal-native-access=deny or future Java releases will reject it if this flag is not provided.

java --enable-native-access=ALL-UNNAMED -jar your-game.jar

A map that renders correctly may still be physically impossible to complete. After any structural change to walls, collision, doors, walkable floor, spawns, objectives, or exit triggers, you must validate playability.

1. Call analyze_playability: Pass the actual player collider width, height, and clearance.
2. Handle Failures: If the status is status: FAIL, you must correct all unreachable required targets before proceeding with gameplay placement or marking the map as complete.
3. Visual Inspection: Use render_playability to inspect computed collision, reachable, and unreachable cells. Do not rely solely on visual floor tiles or apparent wall gaps to infer access.

LITIENGINE is hosted on Maven Central. To use it in your project, add mavenCentral() to your repositories and include the de.gurkenlabs:litiengine dependency.

Note on Java Version: LITIENGINE requires Java 25 or later. Versions 22, 23, and 24 are no longer supported.

### Groovy syntax
```groovy
repositories {
    mavenCentral()
}

dependencies {
  implementation 'de.gurkenlabs:litiengine:0.8.0'
}

Kotlin Syntax

repositories {
    mavenCentral()
}

dependencies {
  implementation("de.gurkenlabs:litiengine:0.8.0")
}

When defining custom properties in XML tilemaps, you must use one of the following supported type identifiers. These types determine how the LITIENGINE XML parser interprets the property values.

Supported types:

• string: Textual data.
• float: Floating-point numbers.
• int: Integer numbers.
• bool: Boolean values.
• file: File paths or references.
• color: Color representations.
• object: Complex objects.