Project Management¶

Game Resource Files (.litidata)¶

In LITIENGINE, all game assets, maps, blueprints, particle configurations, sounds, and script definitions are organized and bundled into a central game resource file (conventionally named with the .litidata extension).

A .litidata file is an XML-structured container that can either reference external assets or store base64-encoded compressed resources directly. This makes it effortless to package your entire game for distribution or version-control your assets cleanly.

What is stored inside .litidata?¶

• GUI Layouts: Declarative menus, panels, buttons, and HUD interfaces designed in the GUI Editor.
• Maps: All TMX map layouts, tile layer GID grids, and placed map objects.
• Tilesets: External and embedded TSX tilesets, Wang terrain definitions, tile animations, and custom tile collision shapes.
• Spritesheets: Image frame metrics, slice dimensions, and keyframe animation timing data.
• Emitters: Particle emitter configurations, physics properties, and color gradients.
• Blueprints: Reusable entity templates and pre-configured object blueprints.
• Sounds: Registered SFX and audio resources.
• Script Definitions: Declarations for game, environment, and entity scripts with their target bindings and @ScriptProperty parameter values.

For complete XML schema definitions, GZIP compression options, and the low-level ResourceBundle Java API, see the .litidata File Format reference.

Creating a New Project¶

utiLITI features a full Gradle Project Creation Wizard (CreateProjectDialog) that scaffolds a ready-to-run LITIENGINE game project on disk.

To open the wizard, select File -> New Project... from the menu bar or press Ctrl + N (Cmd + N on macOS).

Project Wizard Settings¶

Dynamic Version Fetching¶

The dialog connects asynchronously to Maven Central (MavenCentralVersions) to fetch all published engine versions. You can click the Reload button (Icons.RELOAD_16) to refresh available versions. If no internet connection is available, the wizard automatically falls back to the embedded default engine release.

Live Project Preview¶

The right panel of the dialog displays a real-time preview of:

• Project Structure: A live tree view showing the directory hierarchy and generated files.
• Generated Build Script: Live preview of the generated build.gradle or build.gradle.kts containing the required Maven repositories and dependencies.

Auto-Scaffolded Project Structure¶

When you click Create Project, utiLITI generates the complete project scaffold:

my-liti-game/
├── gradlew
├── gradlew.bat
├── gradle/
│   └── wrapper/
│       ├── gradle-wrapper.jar
│       └── gradle-wrapper.properties
├── gradle.properties        # Configured with org.gradle.jvmargs=-Xmx1g
├── settings.gradle[.kts]    # Declares rootProject.name
├── build.gradle[.kts]       # Declares Maven Central, LITIENGINE dependency, application plugin
├── .gitignore               # Ignores .gradle/, build/, out/, .idea/, *.iml
├── game.litidata            # Blank starter resource bundle
└── src/
    └── main/
        └── java/
            └── com/example/mylitigame/
                └── Main.java # Pre-configured entry point loading game.litidata

The generated Main.java contains the bootstrap code:

package com.example.mylitigame;

import de.gurkenlabs.litiengine.Game;
import de.gurkenlabs.litiengine.resources.Resources;

public class Main {
  public static void main(String[] args) {
    Game.info().setName("My LITI Game");
    Game.info().setVersion("1.0.0");
    Game.init(args);
    Resources.load("game.litidata");
    Game.start();
  }
}

Once created, utiLITI opens game.litidata automatically, and you can run or build your game immediately using ./gradlew run or utiLITI's built-in Run button (Shift + F10).

Opening, Saving & Reverting¶

Opening Projects¶

• File -> Open... (Ctrl + O): Browse and open an existing .litidata project.
• File -> Recent Projects: Quickly reopen recently edited projects.
• Drag-and-Drop: Drag a .litidata file from your operating system file manager directly into the utiLITI window.

Saving Changes¶

• Save Project (Ctrl + S): Writes all current map modifications, layer updates, and asset changes to the active .litidata file.
• Save As...: Saves the entire project bundle to a new .litidata destination path.
• Compress Resource File: In Resources -> Compress Resource File, toggle compression to drastically reduce .litidata bundle size when exporting.

Reverting¶

• File -> Revert: Discards all unsaved in-memory changes and reloads the project from the disk version.

Auto-Save & Crash Recovery¶

utiLITI includes a background Auto-Save Manager (AutoSaveManager) designed to protect your work against accidental closures or system crashes.

How Auto-Save Works¶

1. Periodic Background Saves: Every 5 minutes (or as configured in preferences), if changes have been made since the last manual save, utiLITI silently writes a snapshot of your project.
2. Backup Storage: Auto-save snapshots are stored alongside your project file with a .backup or .autosave suffix.
3. Recovery on Startup: If utiLITI detects an unexpected shutdown or finds a backup file that is newer than the saved project, it prompts you on startup to restore the auto-saved session.

Project Settings & Startup Restoration¶

In File -> Settings -> General:

• Reopen Last Project on Startup: When enabled, utiLITI automatically loads the most recently active .litidata project upon launch.
• Gradle Launch Arguments: Define JVM flags or task options used when launching or debugging the project from the editor.
• Log Level: Filter the console output verbosity (ALL, INFO, WARNING, SEVERE, OFF).

Loading Projects in Code¶

Once you have saved your .litidata file in utiLITI, loading it into your LITIENGINE game requires only one line of code:

import de.gurkenlabs.litiengine.Game;
import de.gurkenlabs.litiengine.resources.Resources;

public class MyGame {
  public static void main(String[] args) {
    Game.init(args);

    // Load the resource bundle created in utiLITI
    Resources.load("game.litidata");

    // Load the initial map and start the game
    Game.world().loadEnvironment("level1");
    Game.start();
  }
}