Getting Started

This repository contains not only sources for the game, but also an environment for automatically downloading and running prebuilt game binaries, type-checking and formatting code, and other handy functionality. This page helps you get started with all of that.

Note: The engine now supports Workspaces which let you mod the game using nothing but a web-browser or text editor. This can be a nice place to start if you're new to Ballistica or don't feel like setting up a full development environment just yet.

Preparing Your Environment

You will need an up-to-date Mac, Windows, or Linux machine to work with Ballistica. On Android, you will need a high speed phone with 3 gb of free space. You will also need a basic understanding of a Unix command line. Per-platform details as follows:

Mac

You should be running the latest macOS and XCode releases, as that's what I am building/testing against.
Development versions of the game link against libraries from Homebrew, so you will need that too.
- Use the instructions at https://brew.sh for a standard homebrew install; this will live at /opt/homebrew on Apple Silicon and /usr/local on Intel.
- Make sure homebrew binaries are available in your PATH. (running which brew should show you a valid binary path).
To install necessary dependencies, run brew install libogg libvorbis sdl2 python@3.12 cmake

Linux

Linux prefab binaries are currently built on Ubuntu 22.04 for x86-64 and arm64, so you will probably need that or something newer/similar.
You will need Python 3.12 (specifically, python3.12 needs to be in your PATH). This may be available by default on new Ubuntu versions, or you can get it on older Ubuntus by installing the deadsnakes ppa. You can also build Python from source or try pyenv.
To install necessary project dependencies on Ubuntu, run sudo apt install python3-pip python3.12-dev python3.12-venv libopenal-dev libsdl2-dev libvorbis-dev cmake clang-format rsync. Other Linux distros may vary. And if you only plan to work with script and not compile the low level binary then you can skip a few of those (sdl2, verbs, make).

Windows

The workflow in Windows involves the same Unix tools as on Mac & Linux, but run through Windows Subsystem for Linux which is available in Windows 10 or newer. Follow the instructions to install WSL, and then install the Ubuntu 22.04 LTS distro. You should now be able to bring up a Linux terminal from Windows and run Unix commands such as ls.
Note that as of Windows 10 build 2004 (released spring 2020) WSL version 2 is available which runs significantly faster for our purposes. Follow your instructions here to upgrade your setup if you'd like (though everything should still work under WSL 1).
To install necessary dependencies, run sudo apt install python3-pip python3.12 python3.12-venv cmake clang-format rsync
Depending on your version of Ubuntu you may need to add the deadsnakes ppa to get access to Python 3.12. See Linux notes above since this is essentially the same.

Android

Warning: I (Eric) have not tried this workflow; this info may be out of date.

Download Termux from GitHub or F-Droid (Playstore builds for termux are deprecated). Open Termux and type apt update && apt upgrade.
For Non-rooted phones:
- After this type pkg install proot && pkg install proot-distro, after this type proot-distro install ubuntu.
- Now type proot-distro login ubuntu. This will be your workspace.
- Now type apt-get install software-properties-common. Now type add-apt-repository ppa:deadsnakes/ppa.
- Now type apt update && apt dist-upgrade && apt install python3-pip libopenal-dev libsdl2-dev libvorbis-dev cmake git rsync
For Rooted Phones:
- After this type apt-get install software-properties-common. Now type add-apt-repository ppa:deadsnakes/ppa.
- Now type sudo apt update && sudo apt dist-upgrade && sudo apt install python3-pip libopenal-dev libsdl2-dev libvorbis-dev cmake git rsync.
Note: at this time, there are no 'prefab' targets to build Android versions of the game (this may be added in time), but most other pipeline functionality such as formatting and checking code should work.

Note about Python Virtual Environments

Previously, working with the project involved installing a number of Python packages via pip, and there were instructions here for setting up a Python virtual environment to insulate these installations from the OS Python installation. As of the projects's upgrade to Python 3.12 in April 2024, this is no longer necessary. The project itself maintains a virtual environment (in <project-root>/.venv) and uses that for all its needs. This should make your life easier.
Note: running make help will create the .venv for you

Wrapping Up

At this point, no matter the platform, you should have a working Unix terminal, and typing which python3.12 should show you the path to a working Python binary.
Clone the Ballistica repo: git clone https://github.com/efroemling/ballistica.git (or with ssh: git clone git@github.com:efroemling/ballistica.git)
Now cd ballistica to jump into the project root. Some tools and commands expect to be run from the project root, so it is generally a good idea to do so if you are unsure.
You should now be ready to go 👍.

Basics

Most high level functionality is contained in the Makefile at the project root. Run make help or simply make to print a list of available targets that can be run along with short descriptions for them.

Building/Running

To run the game, type make prefab-gui-debug. This should download any required asset files and prebuilt binaries for the current platform and then build and launch the game.
You can edit game scripts under assets/src/ba_data/python and then run the same command again to see your changes.
You can use targets such as prefab-gui-debug-build to build the game without running it.
To build for a platform other than the one you are running on, you can use targets such as prefab-windows-x86-gui-debug-build. Run make help or look at the Makefile to see all the options under the 'Prefab' section.
Debug builds contain extra code to check for errors, so it is a good idea to use them while editing scripts. They run significantly slower than release builds, however. To run an optimized, full-speed version of the game, do: make prefab-gui-release.
On Windows, Mac, and Linux, you can compile most of the game from source instead of using prebuilt binaries if you'd like. See this post for details.

Formatting

Type make format to run auto-formatting on all code in the project. This can take a while the first time but should be much faster on subsequent runs (it only visits files that have changed since the last run).

Checking

Type make check to run all type-checks and lint-checks on your code. This may take a while the first time you run it but should be faster on subsequent runs. You can also run checks individually via commands such as make mypy or make pylint (run make help and look at the "Checking" section to see what is available)
All Python code in Ballistica is set up to use Mypy, which adds type-checking to Python code. Type checking is completely optional and you are free to ignore it for your own mods, but any code submitted to the Ballistica project must be type checked. I have found it makes the codebase much more maintainable and less fragile overall. Mypy tends to run very fast, so running make mypy often while working can be handy (or working with an editor/IDE that has it integrated).
All Python code in Ballistica is also set to use Pylint, which helps enforce good coding standards and provides some additional type safety via its own introspection. Like Mypy, this is completely optional for your own mods but any code being submitted upstream to Ballistica must pass Pylint inspections.

Testing

Type make test to run unit tests. This involves executing code in the project to make sure it behaves as expected. Currently this is limited to testing certain low-level Python classes, but may be expanded over time to test things such as game scripts, powerups, UIs, etc. In general you shouldn't need to worry about this for now.

Updating

Type make update to update the project structure for any changes you have made. This includes updating asset lists, Makefiles, and other project files for the current state of the project tree. It is a good idea to do this any time you add, remove, or rename any files anywhere in the repo. If you are banging your head against the wall trying to figure out why importing your shiny new Python module from within the running engine is failing, you probably forgot to do do a make update.

Preflighting

Type make preflight to preflight the project. This essentially is the same as formatting, updating, and then running checks and tests. This is a good final step to perform before pushing commits, minimizing the likelihood that your commits will fail CI testing when they hit the GitHub server.

Other Environments

Aside from the 'full' ballistica development environment described above, other limited development environments may be available depending on your platform. The following are examples (feel free to add to this is you have a workflow that works for you)