Getting Started

Project Structure

• assets: Contains supporting assets that aren't directly loaded by the game. This can include wiki images, documentation, texture files, etc.
• source: Contains the source code of the game following the libGDX project layout.

Running the Game

The game uses the Gradle build tool. Open the source directory with IntelliJ or another IDE with Gradle support to automatically install dependencies. Alternatively, Gradle will install dependencies when you first run the game.

From IntelliJ

A pre-setup Intellij project is provided which contains tasks to run and test the game.

1. Create a new directory .idea under source/, so that the path of this folder is game-engine/source/.idea/

2. Copy the contents of .idea.template into .idea. You should now have the path game-engine/source/.idea/workspace.xml

3. Open the source directory in IntelliJ as an existing project. Say yes to importing Gradle settings.

4. Under project settings (File > Project Structure > Project), select version 17 as the project SDK and language level.

5. Run or edit the game using the provided build tasks.

From command-line

Alternatively from a terminal inside the source directory, you can run:

• ./gradlew run to run the game.
• ./gradlew test to run the unit tests.
• ./gradlew build to build a release version of the game.
• ./gradlew clean to delete the generated output directory.

If Gradle is globally installed on your system, you can use substitute ./gradlew with gradle.

Windows

Substitute ./gradlew with .\gradlew. The .\ is required for PowerShell or in IntelliJ's terminal, it is optional for a Command Prompt.

macOS

On macOS or Mac OS X, the application needs to use the JVM argument XstartOnFirstThread. The source/desktop/build.gradle file includes a test to determine if you are running on macOS or Mac OS X and then initialises the JVM arguments to include XstartOnFirstThread. This allows Gradle to correctly launch the game on most platforms.

Without the XstartOnFirstThread JVM argument on macOS, the game may launch but not display the game window or it may generate a Java error message. The MacOS Setup Guide discusses this issue in more detail. It also discusses a similar issue with running the libGDX TexturePacker GUI to generate sprite sheets on macOS.

To run the game's DesktopLauncher from IntelliJ on macOS, you need to add the XstartOnFirstThread JVM argument to its Run/Debug Configuration. Select the source\desktop\src\com\deco2800\game\desktop\DesktopLauncher.java file in IntelliJ and then select the "Run -> Edit Configurations..." menu item. If the VM options text field is not visible, press Alt+V to display it. Enter -XstartOnFirstThread into the VM options text field. Click on the OK or Apply buttons to save your changes.

Game Introduction

The example game provided is called Box Boy. It is a simple game with a player that runs around a forest filled with ghosts. The following sections will give a light overview on how the game is put together.

Screens and Game Areas

The game is composed of a number of screens and can only display one screen at a time. Within Box Boy there are 3 screens:

• Main Menu Screen: /screens/MainGameScreen.java
• Main Game Screen: /screens/MainMenuScreen.java
• Settings Screen: /screens/SettingsScreen.java

The screens are managed by GDX Game: /GdxGame.java, which makes it easy to move between them like a state machine.

When you run the game, you'll first come to the Main Menu Screen. From here you'll see the main menu, where the 'Settings' button will take you to the Settings Screen, and the 'Start' button will take you to the Main Game Screen.

Screens can also contain game areas which makes it easy to create different levels or areas within a screen. An example in the game of this is in the Main Game Screen, which currently has a Forest Game Area. The Forest Game Area is a good place to get started within the code: /areas/ForestGameArea.java.

Screen are responsible for initiating important game services, drawing the background and UI, rendering the entities and handling input. When using game areas, some of the screen's responsibilities can be delegated to the game areas.

In the game, the Main Game Screen intialises important services such as the Physics Service, Input Service, Entity Service, etc., as well as loads assets and creates the UI for the screen. The Forest Game Area is then responsible for loading game area-specific assets, drawing the background tiles, drawing game area-specific UI, creating the trees, player and ghosts, and playing the background music.

Learn more about screens and game areas in Game Screens.

Entities

There are a number of entities within the game including the trees, player and ghosts.

Learn more about entities in Entity Component System (ECS).