Banner

libGDX 入门部署手册

2026-10-09

环境要求

  • JDK 11 或更高版本，用于编译和运行项目
  • Gradle 8.x，通常由项目自带的 Gradle Wrapper 管理
  • Android Studio / IntelliJ IDEA，推荐 Android Studio Chipmunk 2021.2.1 及以上版本
  • Android SDK，仅开发 Android 端时需要
  • Xcode / RoboVM，仅开发 iOS 端时需要
  • Chrome / Firefox，仅调试 Web 端时需要

注意：旧版 gdx-setup.jar 在某些环境下需要 JDK 8 运行，但 libGDX 1.13.0 之后推荐使用 gdx-liftoff 生成项目，它更现代，也更兼容当前 JDK 版本。

安装项目生成工具

推荐方式：gdx-liftoff

下载最新 gdx-liftoff jar 后运行：

java -jar gdx-liftoff-latest.jar

它会提供项目模板、平台选择、扩展配置、Kotlin/Scala 支持等功能。

旧方式：gdx-setup

java -jar gdx-setup.jar

如果你仍使用 gdx-setup，建议确认当前版本是否仍需要 JDK 8，避免生成器启动失败。

创建项目

在生成工具中填写：

  • Name：项目名称
  • Package：包名，例如 com.example.game
  • Game Class：主游戏类，例如 MyGame
  • Destination：项目输出目录
  • Platforms：选择 Desktop、Android、iOS、HTML
  • Extensions：按需选择 Box2D、Freetype、Controllers 等

生成后，用 Android Studio 或 IntelliJ IDEA 打开项目根目录。

项目结构

my-game/
├── core/          # 跨平台游戏逻辑
├── desktop/       # LWJGL3 桌面启动器
├── android/       # Android 启动器
├── ios/           # iOS 启动器
├── html/          # Web/GWT 启动器
├── assets/        # 图片、音频、字体等资源
├── build.gradle
├── settings.gradle
└── gradlew

assets/ 现在通常放在项目根目录，所有平台模块共享。

开发时主要修改 core/src，各平台模块只负责启动窗口、生命周期桥接和平台配置。

常用命令

# 桌面端运行
./gradlew desktop:run

# Android 安装并运行
./gradlew android:installDebug android:run

# Web 端开发模式
./gradlew html:superDev

# iOS 模拟器运行
./gradlew ios:launchIPhoneSimulator

# 清理构建
./gradlew clean

如果在 IDE 中开发，也可以直接运行 desktop 模块的 DesktopLauncher 主类。

最小组件示例

core/src/.../MyGame.java：

package com.example.game;

import com.badlogic.gdx.ApplicationAdapter;
import com.badlogic.gdx.Gdx;
import com.badlogic.gdx.graphics.GL20;
import com.badlogic.gdx.graphics.Texture;
import com.badlogic.gdx.graphics.g2d.SpriteBatch;

public class MyGame extends ApplicationAdapter {

    private SpriteBatch batch;
    private Texture texture;

    @Override
    public void create() {
        batch = new SpriteBatch();
        texture = new Texture(Gdx.files.internal("badlogic.jpg"));
    }

    @Override
    public void render() {
        Gdx.gl.glClear(GL20.GL_COLOR_BUFFER_BIT);
        batch.begin();
        batch.draw(texture, 100, 100);
        batch.end();
    }

    @Override
    public void dispose() {
        batch.dispose();
        texture.dispose();
    }
}

desktop/src/.../DesktopLauncher.java：

package com.example.game;

import com.badlogic.gdx.backends.lwjgl3.Lwjgl3Application;
import com.badlogic.gdx.backends.lwjgl3.Lwjgl3ApplicationConfiguration;

public class DesktopLauncher {
    public static void main(String[] args) {
        Lwjgl3ApplicationConfiguration config = new Lwjgl3ApplicationConfiguration();
        config.setTitle("My Game");
        config.setWindowedMode(800, 600);
        new Lwjgl3Application(new MyGame(), config);
    }
}

打包发布

Desktop

./gradlew desktop:dist

产物通常在：

desktop/build/libs/

Android

./gradlew android:assembleRelease

产物位置：

android/build/outputs/apk/release/

正式上架前需要配置签名。

Web

./gradlew html:dist

产物位置：

html/build/dist/

可直接部署到 Nginx、Cloudflare Pages、Vercel 等静态托管服务。

iOS

iOS 打包依赖 RoboVM / MobiVM，需要在 macOS 上配置证书和描述文件，再通过 Xcode 或 Gradle 任务构建。

常见问题

依赖下载慢

在 build.gradle 或生成器高级设置中配置国内 Maven 镜像，例如阿里云公共仓库。

Gradle 同步失败

检查 JDK 版本是否为 11+，Android SDK 是否安装 Build-Tools，Gradle Wrapper 是否正常。

资源找不到

确保文件放在根目录 assets/ 下，并通过：

Gdx.files.internal("image.png")

加载。

桌面端黑屏

检查 assets/ 路径是否正确，图片是否已加入模块资源目录，以及 dispose() 是否误释放了仍在使用的资源。

Android 构建失败

确认 gradle.properties 中包含：

android.useAndroidX=true

并安装对应版本的 Android SDK Build-Tools。


8
libGDX
桌面端/安卓/HTML5/苹果系统 Java游戏开发框架
2026-10-09
10
目录