libGDX 跨平台游戏开发知识库，用于以 libGDX 这一跨平台 Java/Kotlin 游戏框架构建生产级游戏。
用途 适用于以下场景：使用 gdx-liftoff 脚手架创建新的 libGDX 项目；设计 Game/Screen 结构以及 Scene2D、Ashley、Box2D 的整合；管理渲染管线，包括 SpriteBatch、TextureAtlas、视口与相机；处理 AssetManager 生命周期与 OpenGL 资源释放；从共享代码库面向桌面、Android、iOS 或 HTML5；迁移到 libGDX 1.14.0 及其破坏性变更（Pools 改为 PoolManager、JsonValue 大小写敏感）；调试帧率下降、显存泄漏或输入处理缺陷。
快速开始 对于 80% 的新 libGDX 项目，可按以下路径操作：
- 生成：从 https://github.com/libgdx/gdx-liftoff/releases 下载最新的 gdx-liftoff JAR，使用 JDK 17 或更高版本运行（推荐 Java 21）。
- 在 gdx-liftoff 中配置：选择平台（通常为 Desktop + Android）、选择语言（若无 HTML5 目标则用 Kotlin，否则用 Java）、选择扩展（按需选择 Ashley、Box2D、FreeType、Controllers）。
- 在 IntelliJ IDEA 或 Android Studio 中打开生成的项目（现代 libGDX 不要使用 Eclipse）。
- 运行 :lwjgl3:run Gradle 任务以启动桌面模块。
- 架构：继承 Game，创建 MainMenuScreen 与 GameplayScreen，UI 使用 Scene2D，实体使用 Ashley。
- 资源：将精灵打包进 TextureAtlas（2048x2048 POT），通过 AssetManager 加载，切勿为每个精灵加载零散 Texture。
- 释放：每个 Texture、Sound、Music、Stage、Skin、BitmapFont、ShaderProgram 都必须显式调用 .dispose()。
随后逐步加固：
- GL 线程阻塞：通过 Gdx.app.postRunnable 将 IO/计算推送到工作线程。
- Screen 生命周期：在 show() 中设置 Gdx.input.setInputProcessor，切勿在构造函数中设置。
- 内存泄漏：审查对 Texture/AssetManager 的静态字段引用（在 Android 上禁止）。
- Scene2D 性能：对不旋转的 Group 设置 Group.isTransform = false。
- Ashley 正确性：包含集合的组件必须实现 Poolable 并在 reset() 中清空。
参考材料
- references/setup-and-tooling.md：gdx-liftoff 工作流、Gradle 多模块布局、JDK 与 Kotlin 版本、IDE 设置、libGDX 1.14.0 变更日志。
- references/rendering-and-performance.md：SpriteBatch 批处理、TextureAtlas 打包、视口、GL 线程规则、帧预算分析、vsync 上限。
- references/architecture-patterns.md：Game + Screen 模式、Scene2D + Ashley ECS 组合、Box2D 固定时间步、3D ModelBatch 基础。
- references/asset-and-lifecycle.md：AssetManager 异步加载、dispose 规范、Screen 生命周期、输入处理器管理、屏幕切换。
- references/deployment-platforms.md：桌面 LWJGL3、Android（minSdk/targetSdk）、iOS RoboVM 约束、HTML5 GWT 与 TeaVM、打包与签名。
关键决策点
- 生成器：默认 gdx-liftoff；始终使用（gdx-setup 已弃用）。
- 语言：默认 Kotlin（需要 HTML5 时用 Java）；HTML5 目标要求 Java。
- JDK 构建目标：默认 Java 21；最低 Java 17；iOS 源码级别上限为 8。
- 架构：默认 Game + Screen + Scene2D；中等实体数量时加入 Ashley ECS。
- 物理：默认 Box2D 固定时间步（60 Hz）；3D 使用 Bullet。
- 资源加载：默认 AssetManager 异步，每帧泵送 update()；加载屏幕可每帧多次 update()。
- 纹理策略：默认 TextureAtlas、POT、通过 TexturePacker 打包；切勿为每个精灵加载零散 Texture。
- 屏幕切换：复用 Screen 实例或使用 libgdx-screenmanager；每次切换都构造新 Screen 会造成浪费。
- 输入处理：在 show() 中设置处理器，在 hide() 中置空；Stage 与自定义处理器使用 InputMultiplexer。
- HTML5 后端：默认 GWT；若需要 Kotlin 或现代 JS 互操作则用 TeaVM（对 libGDX 仍处于 WIP 阶段）。
行为规则
- 切勿通过静态字段共享 Texture 或 AssetManager（Android 生命周期会破坏它们）。
- 切勿从非渲染线程调用 OpenGL 或 Gdx.gl.*。
- 切勿为每个精灵加载零散 Texture，始终打包图集。
- 始终在 Screen.dispose() 或 Game.dispose() 中释放每个由 OpenGL 支持的资源。
- 始终在 Screen.show() 中设置 Gdx.input.setInputProcessor，在 Screen.hide() 中置空。
- 始终对没有旋转或缩放的 Scene2D Group 设置 Group.isTransform = false。
- 始终在 Ashley 系统中缓存 ComponentMapper.getFor(...) 引用。
- 始终为 Box2D 使用固定时间步，与渲染速率解耦。
来源锚点
- libgdx.com（权威 wiki 与新闻）
- javadoc.io/doc/com.badlogicgames.gdx/gdx/latest（权威 API）
- github.com/libgdx/libgdx（源码）
- github.com/libgdx/gdx-liftoff（项目生成器）