如果你在独立游戏开发这条路上已经摸索了一段时间可能会发现一个有趣的现象很多教程和讨论都集中在 Unity 或 Godot 这类“所见即所得”的引擎上。它们强大、生态繁荣但对于一个想从底层理解游戏是如何“画”出来、如何“动”起来的开发者来说有时会感觉隔着一层玻璃——你操作的是编辑器而不是代码本身。最近我重新捡起了 LibGDX 这个老牌 Java 游戏开发框架用它来启动一个新的小项目。这个过程让我意识到LibGDX 的价值远不止于“一个能写跨平台游戏的库”。它更像是一把精密的螺丝刀让你亲手拧紧游戏世界的每一个齿轮。你不会被拖拽组件和预制体界面包围而是直面SpriteBatch、OrthographicCamera和ApplicationListener。这种“裸奔”式的开发体验对于想夯实图形、输入、音频等基础概念的开发者来说是一种极佳的锻炼。它不帮你做太多决定而是把控制权完全交还给你。这第一期的内容我们不急于做出一个完整的游戏而是先解决一个最实际的问题如何从一个空文件夹开始搭建一个干净、可维护、且能顺畅跨平台桌面、安卓的 LibGDX 开发环境。这听起来像是老生常谈但我见过太多项目在第一步就埋下了混乱的种子——依赖冲突、构建脚本冗长、桌面测试与移动端打包流程割裂。我们将用一个现代、简洁的方式搞定这一切。1. 为什么从 LibGDX 开始理解“框架”与“引擎”的思维差异在深入命令行之前有必要先厘清一个根本问题我们选择的到底是一个什么样的工具这决定了后续整个工作流的心态。Unity/Unreal/Godot 等是“游戏引擎”。它们提供了一套完整的、高度集成化的解决方案包括编辑器、物理系统、渲染管线、资源管理、脚本系统等。你主要的工作环境是一个可视化编辑器通过组装和配置各种组件Component或节点Node来构建游戏。引擎帮你处理了巨量的底层细节让你能快速原型化和迭代。代价是你对底层机制的理解可能变得模糊并且项目结构、构建流程很大程度上被引擎的既定规则所塑造。LibGDX 是一个“游戏开发框架”。它本质上是一组精心设计的、模块化的 Java 库。它没有中心化的编辑器你的“编辑器”就是 IDE如 IntelliJ IDEA 或 VS Code。它提供了绘制图形、播放声音、处理输入、管理文件 I/O 等基础功能但如何组织你的游戏循环、状态管理、实体系统、场景图完全由你决定。它给你的是砖块、水泥和工具至于房子怎么盖盖成什么风格是你自己的事。这种差异带来的核心影响是控制度你对内存、渲染批次、线程、资产加载拥有更精细的控制。学习曲线初期你需要自己处理更多“家务事”比如窗口创建、视口适配、资产的生命周期管理但这能让你更扎实地理解游戏运行原理。项目结构你的项目结构就是标准的 Gradle/Maven 多模块项目结构清晰、透明易于与通用的 Java 开发工具链集成。包体大小去除了庞大编辑器运行时的开销最终产出的 APK 或 Jar 包通常更小。所以选择 LibGDX你选择的其实是一条“理解优先于产出”的路径。它适合那些不满足于黑盒操作希望看清并掌控每一个环节的开发者。接下来我们就从零开始亲手搭建这个透明的“工作台”。2. 放弃传统安装器使用官方 CLI 工具进行精准项目生成过去LibGDX 官网推荐一个叫做gdx-setup.jar的 GUI 工具来生成项目。虽然它还能用但我们现在有更优雅、可脚本化的选择——官方命令行工具CLI。这是项目健康的第一步用一个可重复、可版本化的命令替代手动点击的 GUI。2.1 环境准备确保 JDK 与 SDK 就位首先确保你的机器上有以下环境JDK 17 或 21LibGDX 目前兼容这些 LTS 版本。建议使用 JDK 21 以获得更好的性能。安装后在终端运行java -version确认。Android SDK如果你需要开发安卓版本。最简单的方式是安装 Android Studio它会帮你管理 SDK。安装后需要设置ANDROID_HOME环境变量指向你的 SDK 路径例如C:\Users\YourName\AppData\Local\Android\Sdk或/Users/YourName/Library/Android/sdk并将$ANDROID_HOME/tools和$ANDROID_HOME/platform-tools加入PATH。2.2 生成项目一条命令创建结构化工程打开终端命令行执行以下命令来安装或运行 LibGDX CLI 工具并生成项目# 方式一直接使用最新版CLI推荐 java -jar gdx-cli.jar # 通常更简单的做法是使用官方提供的在线生成命令它会下载CLI并执行 # 访问 https://libgdx.com/wiki/start/project-generation 获取最新命令 # 示例命令结构如下具体参数见下文 java -jar gdx-cli.jar \ --dir MyGame \ --name my-game \ --package com.mygame \ --mainClass MyGame \ --sdkPath $ANDROID_HOME \ --excludeModules ios,html \ --java关键参数解析--dir项目根目录名称。--name项目名称小写用连字符用于子模块和包名生成。--package你的游戏基础包名遵循 Java 反向域名规范。--mainClass桌面端主类的类名。--sdkPath指向你的ANDROID_HOME路径这是生成安卓模块所必需的。--excludeModules这里我们排除了ios(需要macOS和Xcode) 和html(GWT支持)专注于桌面和安卓。你可以根据需要调整。--java使用 Java 语言而非 Kotlin。如果你熟悉 Kotlin可以使用--kotlin。执行成功后你会得到一个名为MyGame或你指定的名称的文件夹其内部结构是标准的多模块 Gradle 项目MyGame/ ├── build.gradle.kts // 根项目构建脚本 ├── settings.gradle.kts // 模块定义 ├── gradle.properties // 全局属性如JVM参数 ├── core/ // **核心游戏逻辑模块** │ ├── build.gradle.kts │ └── src/main/java/com/mygame/ │ └── MyGame.java // 核心游戏入口类 ├── desktop/ // 桌面Windows/macOS/Linux启动模块 │ ├── build.gradle.kts │ └── src/main/java/com/mygame/desktop/ │ └── DesktopLauncher.java // 桌面启动器 └── android/ // 安卓启动模块 ├── build.gradle.kts ├── AndroidManifest.xml ├── assets/ // 安卓资源目录 └── src/main/java/com/mygame/android/ └── AndroidLauncher.java // 安卓启动器这个结构清晰地区分了“游戏内容”core和“平台外壳”desktop,android。core模块包含所有平台共享的游戏代码而desktop和android模块只负责初始化对应平台的窗口、上下文并启动core里的游戏。3. 深入构建脚本理解 Gradle 如何管理依赖与构建生成的项目使用Gradle Kotlin DSL(*.gradle.kts) 作为构建系统。相比旧的 Groovy DSL它更类型安全、易于阅读。我们不需要成为 Gradle 专家但理解几个关键文件能让你在后续添加依赖或调整构建时心中有数。3.1 根目录的build.gradle.kts定义公共配置这个文件主要做两件事声明所有子模块的通用依赖版本号。这确保了core、desktop、android模块使用的 LibGDX 版本一致。配置所有项目的通用任务或属性。打开它你会看到类似这样的allprojects配置块它定义了所有模块共享的仓库和 LibGDX 版本allprojects { // ... val gdxVersion: String by project val roboVMVersion: String by project // 通常已排除 val box2DLightsVersion: String by project val ashleyVersion: String by project val aiVersion: String by project repositories { mavenLocal() mavenCentral() google() maven { url uri(https://oss.sonatype.org/content/repositories/snapshots/) } } }版本号实际定义在根目录的gradle.properties文件中。这是集中管理版本的最佳实践。3.2core/build.gradle.kts声明游戏核心依赖这是最重要的模块。它的依赖项会被desktop和android模块自动继承通过api与implementation配置。你在这里添加的库所有平台都能使用。dependencies { api(com.badlogicgames.gdx:gdx:$gdxVersion) // 你可以在这里添加其他核心依赖例如 // api(com.badlogicgames.ashley:ashley:$ashleyVersion) // 实体组件系统 // api(com.badlogicgames.box2dlights:box2dlights:$box2DLightsVersion) // Box2D 灯光 }关键原则将纯粹的、与平台无关的游戏逻辑库如 Ashley ECS, Box2D依赖放在core模块。将平台特定的库如桌面特定的 UI 工具、安卓特定的广告 SDK放在对应的平台模块。3.3desktop/build.gradle.kts与android/build.gradle.kts平台特定配置desktop模块依赖core模块并添加gdx-backend-lwjgl3和gdx-platform依赖后者包含了 natives 本地库用于 LWJGL3 后端。android模块依赖core模块并添加gdx-backend-android依赖。它的构建脚本更复杂包含了安卓特有的配置如compileSdk、minSdk、targetSdk版本以及应用 ID (applicationId) 等。请务必根据你的目标用户群仔细设置minSdk版本例如minSdk 24对应 Android 7.0能覆盖绝大多数设备。3.4 首次构建与导入 IDE在项目根目录打开终端运行以下命令来下载所有依赖并确保构建成功# 在项目根目录执行 ./gradlew build # Windows 用户使用 gradlew.bat # gradlew build这个过程可能会花费几分钟Gradle 会下载所有声明的依赖。成功后你就可以将项目导入 IDE 了。IntelliJ IDEA (推荐)直接打开项目根文件夹IDEA 会自动识别为 Gradle 项目并导入。VS Code安装 “Extension Pack for Java” 和 “Gradle for Java” 扩展然后打开根文件夹。导入后你可以在desktop/src/main/java/.../DesktopLauncher中找到主类并运行应该能看到一个经典的 LibGDX 红色背景窗口。4. 从“Hello World”到可维护的起点搭建基础游戏结构运行成功只是第一步。默认生成的代码只是一个最小示例。为了长期开发我们需要建立一个更健壮的基础结构。这比急于画第一个精灵更重要。4.1 重构游戏入口建立清晰的阶段管理默认的MyGame类直接实现了ApplicationListener把所有逻辑堆在一个类里。我们将其改造成一个简单的状态管理器。首先在core模块中创建几个包来组织代码例如com.mygame.screen游戏屏幕、com.mygame.manager资源管理器等。然后创建一个GameScreen接口或抽象类以及一个具体的MainMenuScreen// 在 core 模块中 package com.mygame.screen; import com.badlogic.gdx.Screen; public class MainMenuScreen implements Screen { Override public void show() { // 屏幕显示时调用用于初始化资源 } Override public void render(float delta) { // 清除屏幕并绘制主菜单 Gdx.gl.glClearColor(0.2f, 0.2f, 0.2f, 1); Gdx.gl.glClear(GL20.GL_COLOR_BUFFER_BIT); // 这里未来会加入 SpriteBatch 绘制菜单UI } // ... 其他方法hide, pause, resume, dispose暂时留空或简单实现 }接着修改你的主游戏类例如MyGame让它继承com.badlogic.gdx.Game类。Game类已经实现了ApplicationListener并内置了简单的屏幕管理功能。package com.mygame; import com.badlogic.gdx.Game; import com.mygame.screen.MainMenuScreen; public class MyGame extends Game { Override public void create() { // 游戏启动时设置第一个屏幕 setScreen(new MainMenuScreen()); } Override public void render() { // 将渲染委托给当前活跃的 Screen super.render(); } Override public void dispose() { // 游戏退出时确保当前屏幕的资源也被释放 if (screen ! null) screen.dispose(); } }现在你的游戏就有了一个清晰的屏幕流雏形。你可以通过setScreen(new AnotherScreen())在不同游戏状态主菜单、游戏进行中、设置、游戏结束间切换。4.2 资产管理与生命周期在render方法里硬编码颜色或直接加载纹理是灾难的开始。我们需要一个资产管理器。LibGDX 提供了AssetManager类。创建一个AssetManager的单例或通过依赖注入方式在游戏启动时初始化并在各个Screen中共享使用。// 一个简单的资产管理类示例 package com.mygame.manager; import com.badlogic.gdx.assets.AssetManager; import com.badlogic.gdx.graphics.Texture; import com.badlogic.gdx.graphics.g2d.BitmapFont; public class Assets { public static final AssetManager manager new AssetManager(); // 定义资产路径常量 public static final String PLAYER_TEXTURE images/player.png; public static final String UI_FONT fonts/ui_font.fnt; public static void load() { manager.load(PLAYER_TEXTURE, Texture.class); manager.load(UI_FONT, BitmapFont.class); // ... 加载其他资产 } public static void dispose() { manager.dispose(); } }在LoadingScreen你可以创建它中调用Assets.manager.update()来渐进式加载资产并显示进度条。加载完成后再切换到MainMenuScreen。4.3 视口Viewport配置应对多种分辨率这是移动端开发的关键。不要直接使用固定的像素坐标。LibGDX 提供了多种Viewport如FitViewport,FillViewport,ScreenViewport来处理不同宽高比和分辨率。在你的Screen的show()或resize()方法中配置视口public class GameScreen implements Screen { private OrthographicCamera camera; private Viewport viewport; private SpriteBatch batch; Override public void show() { camera new OrthographicCamera(); // 使用 FitViewport虚拟世界大小为 16:9 的 800x450 // 它会在任何屏幕上保持比例两侧可能有黑边 viewport new FitViewport(800, 450, camera); batch new SpriteBatch(); } Override public void render(float delta) { // 应用视口 viewport.apply(); batch.setProjectionMatrix(camera.combined); // ... 使用 batch 绘制坐标基于虚拟世界 (800x450) } Override public void resize(int width, int height) { // 当窗口大小改变时更新视口 viewport.update(width, height, true); // true 表示同时更新相机居中 } }这样你的游戏逻辑就可以基于一个固定的虚拟坐标系如 800x450进行开发Viewport会负责将其适配到任何实际的屏幕尺寸上。5. 开发、调试与发布建立高效的工作流环境搭建好基础结构也建立了最后我们来规划日常的开发流程。5.1 桌面端快速迭代桌面模块是你的主要开发环境。在 IDE 中直接运行DesktopLauncher它启动快调试方便可以设置断点、查看变量。你应该将大部分逻辑开发和调试工作放在这里。技巧你可以修改DesktopLauncher的启动参数例如初始窗口大小Lwjgl3ApplicationConfiguration config new Lwjgl3ApplicationConfiguration(); config.setTitle(My Game); config.setWindowedMode(1200, 675); // 16:9 比例方便测试 config.setForegroundFPS(60); new Lwjgl3Application(new MyGame(), config);5.2 安卓端真机测试当桌面端功能稳定后就需要在真机上测试触控、性能和多分辨率适配。连接设备用 USB 线连接安卓手机并开启“开发者选项”和“USB调试”。运行项目在 IDE 中选择android模块下的AndroidLauncher作为运行配置然后执行。Gradle 会自动构建 APK 并安装到设备上。查看日志使用adb logcat命令或 IDE 内置的 Logcat 工具查看运行时日志这对于调试崩溃和性能问题至关重要。注意首次构建安卓版本可能较慢因为需要下载 Gradle 的安卓插件和构建工具。确保网络通畅。5.3 常见问题排查链路当你遇到问题时遵循从简到繁的排查顺序现象确认是在桌面端还是安卓端是启动崩溃还是运行时错误错误信息是什么检查日志桌面端查看 IDE 控制台安卓端使用adb logcat | grep -i “libgdx”或 IDE 的 Logcat 过滤。资产路径问题这是最常见的问题之一。确保资产文件图片、声音放在正确的位置桌面端通常放在android/assets/目录下因为桌面模块通过core模块访问资产而core在运行时从 classpath 或文件系统加载默认会指向android/assets的路径结构。更稳妥的做法是在桌面启动器 (DesktopLauncher) 中通过config.setPreferencesConfig(...)或重写Files模块的路径处理来明确资产目录。安卓端必须放在android/assets/目录下。使用Gdx.files.internal(“path/to/asset.png”)来加载内部资产。依赖冲突如果你引入了第三方库可能会发生版本冲突。使用./gradlew :core:dependencies命令查看core模块的依赖树检查是否有重复或冲突的库。内存与性能在桌面端使用 JVM 参数如-Xmx1g增加堆内存。在安卓端注意纹理尺寸最好是2的幂次方及时调用dispose()释放资源并使用TextureAtlas合并小图以减少渲染批次。5.4 发布准备对于桌面端使用./gradlew :desktop:dist命令它会在desktop/build/libs/下生成可执行的 Jar 文件及其依赖。对于安卓端使用./gradlew :android:assembleRelease命令生成发布版 APK。在此之前你需要配置签名密钥signingConfigs并在android/build.gradle.kts中正确设置buildTypes。至此你已经拥有了一个结构清晰、构建可靠、便于跨平台开发和调试的 LibGDX 项目基础。这个基础就像一副坚固的骨架后续无论是添加复杂的游戏逻辑、引入实体组件系统ECS、集成物理引擎还是设计 UI 和关卡都可以在这个骨架上稳健地生长。记住在独立游戏开发中前期在工程化和结构上多花一点时间会在后期为你避免数不清的麻烦和重构。下一期我们可以深入聊聊如何利用这个基础实现一个简单的玩家控制和精灵动画系统。
