Gaia Sky - Open source 3D Universe platform

Gaia Sky is a real-time 3D Universe application that runs on Linux, Windows and macOS. It is developed within the framework of ESA's Gaia mission to chart more than 1 billion stars.

A part of Gaia Sky is described in the paper Gaia Sky: Navigating the Gaia Catalog.

To get the latest up-to-date and most complete information,

• Visit our home page
• Read the official documentation (PDF version)
• Submit a bug or a feature request
• Follow development news at @gaiasky.bsky.social or #GaiaSky@mastodon

---

1. Overview and Stack

Gaia Sky is a 3D universe platform built using the following technologies:

• Language: Java
• Frameworks: libGDX (core 3D engine), Ashley (entity-component system), LWJGL 3 (desktop backend).
• Package Manager/Build Tool: Gradle.
• Scripting Interface: Python (via Py4J).
• VR Support: OpenXR.

2. Requirements

2.1 Hardware

Component	Minimum requirement
Operating system	Linux / Windows 10+ / macOS
Architecture	x86_64, ARM (only Apple silicon through compat layer)
CPU	Intel Core i5 3rd Generation. 4+ cores recommended
GPU	Support for OpenGL 3.3 (4.2 recommended), 1 GB VRAM
Memory	4+ GB RAM (depends on loaded datasets)
Hard drive	1+ GB of free disk space (depends on downloaded datasets)

2.2 Software

• Java Development Kit (JDK): Gaia Sky is developed on the most recent JDK version. We recommend using at least the latest LTS version (JDK 25+).
• Git: To clone the repository.
• Python (Optional): For external scripting.

3. Setup and Run

3.1 Installation from Source

Clone the Gaia Sky repository:

git clone https://codeberg.org/gaiasky/gaiasky.git
cd gaiasky

3.2 Running Gaia Sky

On Linux and macOS: Using the provided wrapper script:

./gaiasky

Or directly with Gradle:

./gradlew core:run

On Windows: Open PowerShell and run:

.\gradlew.bat core:run

3.3 CLI Arguments

Run ./gaiasky -h to find out about launch arguments. If running with Gradle, use the --args flag:

./gradlew core:run --args='-h'

3.4 Gaia Sky VR

Gaia Sky VR works with OpenXR-enabled runtimes. To run in VR:

# Windows
gradlew.bat core:run --args='-vr'
# Linux
./gradlew core:run --args='-vr'

4. Scripts and Project Structure

4.1 Key Scripts

• gaiasky: A bash script to run Gaia Sky with Gradle.
• gradlew / gradlew.bat: The Gradle wrapper for building and running.
• makefile: Primarily for Linux/Debian packaging and installation.
  • make install: Installs Gaia Sky to /opt/gaiasky.
• justfile: Contains commands for Monado-service (OpenXR) management on Linux.

4.2 Project Structure

• core/: Contains the main Java source code and assets.
  • src/gaiasky/: Root of the Java package structure.
  • src/gaiasky/desktop/GaiaSkyDesktop.java: Main entry point for the desktop application.
  • scripts/: Scripts and utilities to create releases and manipulate datasets.
• assets/: Textures, shaders, data, scripts, and internationalization files.
• gradle/: Gradle wrapper and configuration.

5. Environment Variables

• JAVA_HOME: Should point to your JDK installation.
• XDG_DATA_HOME, LOCALAPPDATA: Used to determine where to store data.
• GS: Points to the gaiasky project directory.

6. Tests

Run the test suite using Gradle:

./gradlew core:test

7. Documentation and Help

• User Manual
• Gaia Sky VR Docs
• DeepWiki Technical Docs

8. License

This software is published and distributed under the Mozilla Public License 2.0 (MPL 2.0). See the LICENSE.md file for details.

---

Contributing

Find information about contributing in CONTRIBUTING.md.

Acknowledgements

See ACKNOWLEDGEMENTS.md, AUTHORS.md, and CONTRIBUTORS.md.