Skip to content

README.md

Latest commit

 

History

History
156 lines (109 loc) · 5.43 KB

README.md

File metadata and controls

156 lines (109 loc) · 5.43 KB

Developer Setup Guide

Before Getting Started

  • Install JDK 21 (project is using this Java version)
  • Install IDE (IDEA is better supported, YMMV with Eclipse)

Mac

Windows

  • Set up WSL (see WSL installation guide), this will give you a command line that can be used to run docker, gradle and the code check scripts
  • Open git folder, e.g., C:\Users\<user>\git\triplea, in WSL via explorer Shift+Right click and option Open Linux shell here
  • Install/upgrade GitHub CLI

Install:

sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-key C99B11DEB97541F0
sudo apt-add-repository https://cli.github.com/packages
sudo apt update
sudo apt install gh

Upgrade:

sudo apt update
sudo apt upgrade gh
  • Login to your GitHub account (e.g. via HTTPS > Credentials > Login with a web browser, copy URL to open window in browser and copy one-time code for device connection)
gh auth login
image
  • Sync changes in your IDE with WSL
git status
  • Declare repository triplea-game/triplea as your default to create PR to with WSL
gh repo set-default triplea-game/triplea
  • (if wanted) declare start path for WSL by adjusting .bashrc or .zshrc inside WSL by adding at the end cd ~/projects/my-repo
nano ~/.bashrc

Getting Started

If you are new to Open Source & GitHub:

Compile and launch TripleA (CLI)

# Build & Launch TripleA Game-Client
./gradlew :game-app:game-headed:run

# Run all build checks
./verify

# Run formatting
./gradlew spotlessApply

# Runs all tests
./gradlew test

# Run tests for a (sub)project
./gradlew :game-app:game-core:test

# Run a specific test
./gradlew :game-app:game-core:test --tests games.strategy.triplea.UnitUtilsTest

# Runs a specific test method
./gradlew :game-app:game-core:test --tests games.strategy.triplea.UnitUtilsTest.multipleTransportedUnitsAreTransferred

# Run specific tests using wildcard (be sure to use quotes around wildcard)
./gradlew :game-app:game-core:test --tests 'games.strategy.triplea.UnitUtilsTest.*Units*'

To run tests even if there are no changes from the previous build, use the --rerun-tasks option:

./gradlew --rerun-tasks :game-app:game-core:test

Run Formatting

We use 'Google Java Format', be sure to install the plugin in your IDE to properly format from IDE.

To apply formatting via CLI:

./gradlew spotlessApply

Code Conventions (Style Guide)

See: reference/code-conventions

Lobby / Server Development

Look for the corresponding readmes, check: https://github.com/triplea-game

Pitfalls and Pain Points to be aware of

Save-Game Compatibility

  • Do not rename private fields or delete private fields of anything that extends GameDataComponent
  • Do not move class files (change package) of anything that extends GameDataComponent

The above are to protect save game compatibility. Game saves are done via Java object serialization. The serialized data is binary and written to file. Changing any object that was serialized to a game data file will prevent the save games from loading.

Network Compatibility

'@RemoteMethod' indicates methods invoked over network. The API of these methods may not change.

FAQ - common problems

Game crashes after splash screen displayed

This can be caused by missing resource files, such as images or icons.

The Gradle task run for game-headed will download and unzip game assets into the game-headed project's directory /build/assests. This directory will then be processed as a main resource, by the task :game-app:game-headed:processResources, in order to be packaged in the resulting project jar. When the game starts, it expects to find the folder assets at the root of the classpath, so to load files use the class loader's method getResourceAsStream(). Since this is a resource file packaged in the library jar produced by this project, the working dir should not influence how assets are loaded.

In short:

  • Check that ./gradlew downloadAssets has been run and there is a folder build/assets present; and that the contents have been copied to build/resources/main/assets (Gradle should handle this automatically as necessary).

How do I view log files after the .exe crashes?

Navigate to the TripleA install directory and launch the jar manually using:

java -jar bin/game-headed-<SOME_VERSION_NUMBER>.jar

And you should see the log printed to the console.