---
name: libgdx-development
description: >
  Comprehensive libGDX cross-platform game development knowledge base covering project generation
  via gdx-liftoff, the rendering pipeline, Scene2D and Ashley ECS architecture, Box2D physics,
  AssetManager lifecycle, Screen management, Tiled map integration, and multi-platform deployment
  to Desktop (LWJGL3), Android, iOS (RoboVM), and HTML5 (GWT/TeaVM). Includes libGDX 1.14.0
  breaking changes and Kotlin compatibility caveats.
  TRIGGER WHEN: building, implementing, writing, coding, creating, optimizing, or debugging libGDX games;
  scaffolding or starting new libGDX projects; migrating libGDX versions; choosing libGDX architecture patterns.
  DO NOT TRIGGER WHEN: the task is general Java/Kotlin work unrelated to libGDX, or the engine is
  not libGDX (jMonkey, KorGE, Godot, Unity).
---

# libGDX Cross-Platform Game Development

Knowledge base for building production-grade games with libGDX, the cross-platform Java/Kotlin game framework.

## When to Use

- Scaffolding a new libGDX project with gdx-liftoff
- Designing the Game/Screen structure and Scene2D + Ashley + Box2D integration
- Managing the rendering pipeline: SpriteBatch, TextureAtlas, viewports, cameras
- Handling AssetManager lifecycle and OpenGL resource disposal
- Targeting Desktop, Android, iOS, or HTML5 from a shared codebase
- Migrating to libGDX 1.14.0 and its breaking changes (`Pools` -> `PoolManager`, `JsonValue` case sensitivity)
- Debugging frame-rate drops, VRAM leaks, or input handling bugs

## Quick Start

For 80% of new libGDX projects, follow this path:

1. **Generate**: download latest `gdx-liftoff` JAR from https://github.com/libgdx/gdx-liftoff/releases, run with JDK 17 or later (Java 21 recommended)
2. **Configure** in gdx-liftoff: pick platforms (Desktop + Android typical), pick language (Kotlin if no HTML5 target, otherwise Java), pick extensions (Ashley, Box2D, FreeType, Controllers as needed)
3. **Open** the generated project in IntelliJ IDEA or Android Studio (do NOT use Eclipse for modern libGDX)
4. **Run** `:lwjgl3:run` Gradle task to launch the desktop module
5. **Architecture**: extend `Game`, create `MainMenuScreen` + `GameplayScreen`, use Scene2D for UI and Ashley for entities
6. **Assets**: pack sprites into `TextureAtlas` (2048x2048 POT), load via `AssetManager`, never load loose Textures per sprite
7. **Disposal**: every Texture, Sound, Music, Stage, Skin, BitmapFont, ShaderProgram MUST have an explicit `.dispose()` call

Then harden incrementally:
- GL thread blocking, push IO/compute to a worker thread via `Gdx.app.postRunnable`
- Screen lifecycle, set `Gdx.input.setInputProcessor` in `show()`, never in the constructor
- Memory leaks, audit static field references to Texture/AssetManager (forbidden on Android)
- Scene2D performance, set `Group.isTransform = false` on non-rotating Groups
- Ashley correctness, components with collections must implement `Poolable` and clear in `reset()`

## Reference Materials

- `references/setup-and-tooling.md`: gdx-liftoff workflow, Gradle multi-module layout, JDK and Kotlin versions, IDE setup, libGDX 1.14.0 changelog
- `references/rendering-and-performance.md`: SpriteBatch batching, TextureAtlas packing, viewports, GL thread rules, frame-budget profiling, vsync ceiling
- `references/architecture-patterns.md`: Game + Screen pattern, Scene2D + Ashley ECS combination, Box2D fixed timestep, 3D ModelBatch basics
- `references/asset-and-lifecycle.md`: AssetManager async loading, dispose discipline, Screen lifecycle, input processor management, screen transitions
- `references/deployment-platforms.md`: Desktop LWJGL3, Android (minSdk/targetSdk), iOS RoboVM constraints, HTML5 GWT vs TeaVM, packaging and signing

## Key Decision Points

| Decision | Default | Upgrade When |
|----------|---------|-------------|
| Generator | gdx-liftoff | Always (gdx-setup is deprecated) |
| Language | Kotlin (Java if HTML5 needed) | HTML5 target requires Java |
| JDK build target | Java 21 | Java 17 minimum; iOS source level capped at 8 |
| Architecture | Game + Screen + Scene2D | Add Ashley ECS for mid-size entity counts |
| Physics | Box2D fixed timestep (60 Hz) | Bullet for 3D |
| Asset loading | AssetManager async, pump update() per frame | Multiple update() per frame on loading screen |
| Texture strategy | TextureAtlas, POT, packed via TexturePacker | Never load loose Textures per sprite |
| Screen transitions | Reuse Screen instances or libgdx-screenmanager | Constructing new screens per transition is wasteful |
| Input handling | Set processor in show(), null in hide() | InputMultiplexer for Stage + custom processors |
| HTML5 backend | GWT | TeaVM if you need Kotlin or modern JS interop (still WIP for libGDX) |

## Behavioral Rules

- Never share Texture or AssetManager via static fields (Android lifecycle breaks them)
- Never call OpenGL or `Gdx.gl.*` from a non-render thread
- Never load loose Textures per sprite, always pack atlases
- Always dispose every OpenGL-backed resource on Screen.dispose() or Game.dispose()
- Always set `Gdx.input.setInputProcessor` in Screen.show(), null it in Screen.hide()
- Always set `Group.isTransform = false` on Scene2D Groups without rotation or scaling
- Always cache `ComponentMapper.getFor(...)` references in Ashley systems
- Always use a fixed timestep for Box2D, decoupled from render rate

## Source Anchors

- libgdx.com (canonical wiki and news)
- javadoc.io/doc/com.badlogicgames.gdx/gdx/latest (canonical API)
- github.com/libgdx/libgdx (source)
- github.com/libgdx/gdx-liftoff (project generator)