Skip to content

Latest commit

 

History

History
364 lines (297 loc) · 15.7 KB

COMPILING.md

File metadata and controls

364 lines (297 loc) · 15.7 KB

How to Compile the Polyverse Environment

Tip

If you want some helpful info about the Gradle tasks (or the frameworks Polyverse uses), consider taking a look at PROJECT.md!

Prerequisites (REQUIRED)

  • A GitHub account to download the game's GitHub repository (only if you're using GitHub Desktop!).
  • A Java Development Kit (JDK), version 17 to compile the game's code.
  • The IntelliJ IDEA IDE.
  • Some basic knowledge of programming (especially with using Gradle) and how to navigate an IDE.

Tip

Although Eclipse is great for Java as well, we STRONGLY recommend IntelliJ IDEA, due to how beginner-friendly and well-integrated it is with Polyverse!

Step-by-Step Guide

Creating a GitHub Account

Note

If you already have a GitHub account, you can skip ahead to Step 4 - Installing the JDK!

  1. Head over to the GitHub website and click the Sign up button in the top-right corner of the page.

  2. Follow the on-screen prompts to create your account. You'll need to provide the following:

    • An email address. This will be used for account verification and notifications.
    • A password. Make sure it's strong and something you'll remember!
    • A username. This will be your public identity on GitHub.
    • After filling everything out, you'll be asked to solve a short verification puzzle to confirm you're not a bot.

Tip

You can change any of these details at any time after you create your account!

  1. Check your email inbox for a verification email from GitHub and click the link inside to verify your account. Once verified, you're all set!

Installing the JDK

Important

Polyverse requires JDK 17 specifically. Make sure you're not downloading a newer or older version, and that you're downloading the JDK (Java Development Kit) and not just the JRE (Java Runtime Environment). The JDK includes the compiler and tools needed to build the project!

  1. Head over to the Oracle JDK 17 download page and download the installer for your operating system. If you're unsure which file to pick, use the guide below:
    • Windows: Download the Windows x64 Installer (.exe) file.
    • macOS: Download the macOS x64 DMG Installer (.dmg) file. If you're on an Apple Silicon Mac (M1/M2/M3/M4), download the macOS Arm 64 DMG Installer instead.
    • Linux: You can use the .tar.gz archive from Oracle, but it's easier to install via your package manager (see below).

Tip

If you're on Linux, you can install OpenJDK 17 (which is functionally identical to Oracle JDK for our purposes) directly through your package manager:

Debian / Ubuntu 
sudo apt update && sudo apt install openjdk-17-jdk
Fedora / RHEL / CentOS 
sudo dnf install java-17-openjdk-devel
openSUSE 
sudo zypper install java-17-openjdk-devel
Arch Linux / Manjaro 
sudo pacman -S jdk17-openjdk

  1. Run the installer (on Windows/macOS) and follow the prompts. You generally don't need to change any of the default settings.

  2. After installation, open a new terminal and verify that Java is installed correctly by running:

java -version

You should see output that includes something like java version "17.x.x" or openjdk version "17.x.x". If you see a different major version number or get a "command not found" error, double-check your installation.

Important

Gradle needs the JAVA_HOME environment variable to find your JDK. Most installers set this automatically, but if you run into build errors later, you may need to set it manually:

  • Windows: Search for "Environment Variables" in the Start menu, click Environment Variables, then under System variables click New and set the name to JAVA_HOME and the value to your JDK installation path (e.g. C:\Program Files\Java\jdk-17).
  • macOS / Linux: Add the following line to your shell profile (~/.bashrc, ~/.zshrc, or similar): 
    export JAVA_HOME=/path/to/your/jdk-17
    Then run source ~/.bashrc (or whichever file you edited) to apply the change. On Linux, if you installed via a package manager, JAVA_HOME is usually set automatically. You can check with echo $JAVA_HOME.

Installing & Setting Up GitHub Desktop

  1. Visit the official GitHub Desktop website and download the app. Make sure to run the installer when it finishes downloading!

Tip

If you're on Linux, don't worry! You can install a community-made version using the instructions below for your distro:

Debian / Ubuntu

Add the repository key and source:

wget -qO - https://mirror.mwt.me/shiftkey-desktop/gpgkey | gpg --dearmor | sudo tee /usr/share/keyrings/mwt-desktop.gpg > /dev/null
sudo sh -c 'echo "deb [arch=amd64 signed-by=/usr/share/keyrings/mwt-desktop.gpg] https://mirror.mwt.me/shiftkey-desktop/deb/ any main" > /etc/apt/sources.list.d/mwt-desktop.list'

Then install:

sudo apt update && sudo apt install github-desktop
Fedora / RHEL / CentOS

Add the repository key and source:

sudo rpm --import https://mirror.mwt.me/shiftkey-desktop/gpgkey
sudo sh -c 'echo -e "[mwt-desktop]\nname=GitHub Desktop\nbaseurl=https://mirror.mwt.me/shiftkey-desktop/rpm\nenabled=1\ngpgcheck=1\nrepo_gpgcheck=1\ngpgkey=https://mirror.mwt.me/shiftkey-desktop/gpgkey" > /etc/yum.repos.d/mwt-desktop.repo'

Then install:

sudo dnf install github-desktop
openSUSE

Add the repository key and source:

sudo rpm --import https://mirror.mwt.me/shiftkey-desktop/gpgkey
sudo sh -c 'echo -e "[mwt-desktop]\nname=GitHub Desktop\nbaseurl=https://mirror.mwt.me/shiftkey-desktop/rpm\nenabled=1\ngpgcheck=1\nrepo_gpgcheck=1\ngpgkey=https://mirror.mwt.me/shiftkey-desktop/gpgkey" > /etc/zypp/repos.d/mwt-desktop.repo'

Then install:

sudo zypper ref && sudo zypper in github-desktop
Arch Linux / Manjaro

Install from the AUR using an AUR helper such as yay or paru:

yay -S github-desktop-bin

Or if you use paru:

paru -S github-desktop-bin

  1. When GitHub Desktop is done installing, open the app. You'll be prompted to sign in. Click the Sign in to GitHub.com button and log in with the GitHub account you created earlier. Your browser will open and ask you to authorize the app; click Authorize desktop to continue.

  2. After signing in, GitHub Desktop will ask you to configure your Git identity. Make sure your name and email are correct (these will appear on any commits you make!). When you're happy with the settings, click Finish to complete the setup.

Cloning the Repository

  1. Go back to your browser and (on the official home page for Polyverse's repository), click the green <> Code button and select Open with GitHub Desktop. You should see a prompt asking if you want to clone the game's code.

Green Code Button Location

Note

If you're on Linux, cloning through the GitHub website won't work. Although most Linux distros already have Git installed, you can check if you have it by running the command git --version. If you get an error saying the command doesn't exist, then you will have to install it onto your system:

  • Debian / Ubuntu: sudo apt install git
  • Fedora / RHEL / CentOS: sudo dnf install git
  • openSUSE: sudo zypper install git
  • Arch Linux / Manjaro: sudo pacman -S git

You can install Polyverse through Git with the following command (make sure you're running it in the folder you want it to be located in!):

git clone https://github.com/stringdotjar/Polyverse.git optional/path/to/clone/into/
  1. Click the blue Clone button and wait for the game's code to download.

Tip

We recommend putting the game's code in a place where you'll easily remember where it's at, such as your Documents\GitHub folder if you're on Windows!

Installing IntelliJ IDEA

  1. Head over to the IntelliJ IDEA download page and download the Community Edition. It's completely free and has everything you need to work on Polyverse.

Tip

The download page defaults to showing the Ultimate edition at the top, which is a paid product. Scroll down past it to find the Community Edition section, or look for a tab/toggle to switch editions.

  1. Run the installer and follow the on-screen prompts:
    • Windows: Run the downloaded .exe installer. During setup, you'll be asked about a few optional settings:
      • Check Add "Open Folder as Project" to your context menu. This makes it easy to open project folders directly from File Explorer.
      • Check Add launchers dir to the PATH so you can launch IntelliJ from the terminal.
      • Check the .java and .gradle file associations if you'd like IntelliJ to be the default app for those file types.
    • macOS: Open the downloaded .dmg file and drag the IntelliJ IDEA icon into your Applications folder.

Tip

If you're on Linux, there are several ways to install IntelliJ IDEA Community Edition:

Snap (Ubuntu and most distros)

Snap comes pre-installed on Ubuntu. If your distro supports it, this is the easiest method:

sudo snap install intellij-idea-community --classic
Flatpak

If your distro uses Flatpak (e.g. Fedora, Linux Mint):

flatpak install flathub com.jetbrains.IntelliJ-IDEA-Community
Arch Linux / Manjaro 
sudo pacman -S intellij-idea-community-edition
JetBrains Toolbox (all distros)

The JetBrains Toolbox App is a manager that lets you install, update, and manage all JetBrains IDEs from one place. Download the .tar.gz from the link above, extract it, and run the jetbrains-toolbox binary inside. From the Toolbox, you can then install IntelliJ IDEA Community Edition with a single click.

  1. Launch IntelliJ IDEA for the first time. You'll be greeted with a welcome screen where you can tweak the initial settings:
    • Theme: Choose between a light or dark UI theme.
    • Plugins: You can skip this for now. No extra plugins are needed to work on Polyverse.
    • Click Start using IntelliJ IDEA (or Continue) when you're done.

Building & Running

  1. From the IntelliJ welcome screen, click Open and navigate to the game's folder that you cloned earlier. Select the folder and open it.

Important

When you open the game's folder, your IDE will most likely start running Gradle tasks. Don't worry, this is normal and expected! IntelliJ needs to import the project, download dependencies, and index your files. This can take about one to a few minutes depending on your internet speed and hardware. Let it finish before trying to do anything else.

  1. When the tasks are finished, you can now run the game's code! You can do so by running the applicable task depending on the platform.
    • For example, you can run the desktop version by executing the task lwjgl3:run.

Setting Up for Android

Note

This section is completely optional. You only need to follow these steps if you want to build and run Polyverse on an Android device or emulator. If you're only interested in the desktop version, you can safely skip this!

Building for Android requires the Android SDK to be installed on your machine. To make this process easier, Polyverse includes a setup script at setup/android_setup.sh that handles most of the heavy lifting for you.

What the Script Does

The setup script will automatically:

  • Download the Android SDK Command-Line Tools for your operating system.
  • Install them to ~/android-sdk (your home directory).
  • Accept all required SDK licenses on your behalf.
  • Install the essential packages needed to build the project (platform-tools, platforms;android-34, and build-tools;34.0.0).

Prerequisites

Before running the script, make sure you have curl and unzip installed on your system. Most systems already have these, but if not, you can install them through your package manager:

  • Debian / Ubuntu: sudo apt install curl unzip
  • Fedora / RHEL / CentOS: sudo dnf install curl unzip
  • openSUSE: sudo zypper install curl unzip
  • Arch Linux / Manjaro: sudo pacman -S curl unzip

Running the Script

Open a terminal, navigate to the root of the Polyverse project folder, and run:

bash setup/android_setup.sh

Tip

If you're on Windows, you can run this script through Git Bash (which comes bundled with Git for Windows) or through WSL (Windows Subsystem for Linux). Simply open Git Bash or your WSL terminal, navigate to the project folder, and run the command above.

The script will take a few minutes to download and install everything. When it finishes, you'll see a SETUP COMPLETE! message.

Setting Up Environment Variables

After the script completes, you'll need to set the ANDROID_HOME environment variable and add the SDK tools to your PATH so that Gradle can find the Android SDK when building.

  • Windows: Search for "Environment Variables" in the Start menu, click Environment Variables, then under System variables:

    1. Click New and set the name to ANDROID_HOME and the value to the SDK installation path (e.g. C:\Users\YourName\android-sdk).
    2. Find the Path variable, click Edit, and add two new entries:
      • %ANDROID_HOME%\cmdline-tools\latest\bin
      • %ANDROID_HOME%\platform-tools

  • macOS / Linux: Add the following lines to your shell profile (~/.bashrc, ~/.zshrc, or similar):

export ANDROID_HOME="$HOME/android-sdk"
export PATH="$ANDROID_HOME/cmdline-tools/latest/bin:$ANDROID_HOME/platform-tools:$PATH"

Then run source ~/.bashrc (or whichever file you edited) to apply the changes.

Configuring the Project

Gradle needs to know where your Android SDK is located. Create a file called local.properties in the root of the Polyverse project folder (if it doesn't already exist) and add the following line:

sdk.dir=/home/YourName/android-sdk

Replace the path with wherever the SDK was installed. On Windows, use forward slashes or escaped backslashes (e.g. sdk.dir=C:/Users/YourName/android-sdk).

Important

The local.properties file is specific to your machine and should not be committed to the repository. It's already included in the project's .gitignore, so Git will ignore it automatically.

Building the Android Version

Once everything is set up, you can build and install the Android version of Polyverse by running the Gradle task android:installDebug from IntelliJ. Make sure you have an Android device connected via USB (with USB debugging enabled) or an Android emulator running before executing the task.