libgdx-development

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)