Skip to main content

​
Overview

This guide will help you run Space Birds on your local machine within minutes. Space Birds is built with libGDX and supports both desktop and Android platforms.
Make sure you’ve completed the Installation steps before proceeding.

​
Running on Desktop

The fastest way to play Space Birds is using the LWJGL3 desktop backend.
1

Navigate to project directory

cd SpaceEscape_AULA
2

Run the desktop version

./gradlew lwjgl3:run
On Windows:
gradlew.bat lwjgl3:run
The game window will open automatically and start from the assets directory.
3

Start playing

The game will launch in a new window. Use the controls to navigate and play Space Birds.
The lwjgl3:run task automatically sets the working directory to the assets folder and includes platform-specific JVM arguments (like -XstartOnFirstThread on macOS).

​
Running from JAR

Alternatively, you can build and run from a JAR file:
1

Build the JAR

./gradlew lwjgl3:jar
2

Run the JAR

java -jar lwjgl3/build/libs/SpaceEscape_AULA-1.0.0.jar
JAR files are portable and can be shared with others who have Java installed. The JAR includes all necessary dependencies.

​
Running on Android

To test Space Birds on an Android device or emulator:
1

Set up Android SDK

Ensure your Android SDK is configured:
export ANDROID_SDK_ROOT=/path/to/android-sdk
Or create local.properties:
sdk.dir=/path/to/android-sdk
2

Connect device or start emulator

Physical Device:
  • Enable USB debugging on your Android device
  • Connect via USB
  • Verify connection: adb devices
Emulator:
  • Launch an Android emulator from Android Studio
  • Ensure the emulator is running: adb devices
3

Install and run on device

./gradlew android:installDebug android:run
This will:
  1. Build the debug APK
  2. Install it on your connected device/emulator
  3. Launch the game automatically
The Android device must be running Android 5.0 (API Level 21) or higher.

​
Alternative: Build and Install APK Manually

1

Build the APK

./gradlew android:assembleDebug
The APK will be at: android/build/outputs/apk/debug/android-debug.apk
2

Install the APK

adb install android/build/outputs/apk/debug/android-debug.apk
3

Launch the game

adb shell am start -n com.pmm.games/com.pmm.games.android.AndroidLauncher

​
First Gameplay Session

Once Space Birds is running, here’s what to expect:
1

Game launches

The game window opens displaying the Space Birds interface with the libGDX logo.
2

Main menu

Navigate the main menu to start a new game or adjust settings.
3

Start playing

Begin your space adventure! Control your bird through space, avoiding obstacles and collecting points.

​
Development Workflow

For rapid development and testing:

​
Hot Reload Workflow

1

Keep the game running

Start the desktop version:
./gradlew lwjgl3:run
2

Make code changes

Edit your source files in core/src/ or platform-specific directories.
3

Recompile and restart

Stop the game (Ctrl+C) and run again:
./gradlew lwjgl3:run

​
Asset Changes

Asset files in the assets/ directory are automatically picked up:
  • Images, sounds, and other resources can be modified while developing
  • The desktop version runs from the assets directory by default
  • No rebuild needed for asset-only changes (just restart the game)

​
Platform-Specific Notes

​
Linux Desktop

The game runs on Linux x64, ARM32, and ARM64 architectures:
./gradlew lwjgl3:run
Native libraries for all architectures are included in the build.

​
Troubleshooting

​
Game Won’t Start

Desktop: 
# Ensure Java is installed
java -version

# Clean and rebuild
./gradlew clean lwjgl3:run
Android: 
# Check device connection
adb devices

# Check logs
adb logcat | grep pmm.games

​
Performance Issues

  • Desktop: Ensure you have sufficient RAM (1GB+ recommended)
  • Android: Test on a device with at least Android 5.0 (API 21)
  • Close other applications to free up resources

​
Build Errors

# Refresh dependencies
./gradlew clean build --refresh-dependencies

# Use offline mode if network issues
./gradlew lwjgl3:run --offline

​
macOS: “App is damaged and can’t be opened”

If running a built JAR, remove the quarantine attribute: 
xattr -cr SpaceEscape_AULA-1.0.0.jar

​
Next Steps

Now that Space Birds is running:
  • Explore the game mechanics and controls
  • Review the source code in core/src/ to understand the architecture
  • Check out the Architecture Guide to learn about the project structure
  • Start customizing the game with your own assets and logic
For continuous development, keep ./gradlew lwjgl3:run running and make changes to see them in action quickly.

Build docs developers (and LLMs) love

Get started for freeTalk to us