Getting Started

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

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.10 cmake
You will need python3.10 available in your PATH (try running which python3.10). It may not be there depending on what homebrew's default Python version is currently (try python3 --version to see what you have). See this post for a nondestructive way to get python3.10 into your path in that case (just substitute 3.10 for 3.8). In a nutshell, it involves brew install python@3.10 and then adding the following line to your .zshrc file:
- Intel: export PATH="/usr/local/opt/python@3.10/bin:$PATH"
- Apple Silicon: export PATH="/opt/homebrew/opt/python@3.10/bin/$PATH"

Linux

Linux prefab binaries are currently built on Ubuntu 20.04 for x86-64 and arm64, so you will probably need that or something newer/similar.
You will need Python 3.10 (specifically, python3.10 needs to be in your PATH). This version is available by default on Ubuntu 22 LTS. On earlier versions of Ubuntu you can use the deadsnakes ppa. You can also build Python from source or try pyenv.
- Note that if Python 3.10 wasn't the default for your OS it is highly recommended to set up a Python virtual environment to avoid errors. And there are benefits to doing so even if Python 3.10 is your default.
To install necessary dependencies on Ubuntu, run sudo apt install python3-pip python3.10-dev python3.10-venv libopenal-dev libsdl2-dev libvorbis-dev cmake clang-format. Other Linux distros may vary.

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.10 python3.10-venv cmake clang-format
If you are using an older Ubuntu you may need to add the deadsnakes ppa to get access to Python 3.10. See Linux notes above since this is essentially the same. It is also highly recommended to use a virtual environment in this case to avoid errors.

Android

Download Termux from Play Store. 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
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.
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.

OPTIONAL: Set up a Python virtual environment.

The engine and tools require installing a few Python packages, and working in a virtual environment means that these packages will be limited to that environment and won't affect your default Python install. It also helps prevent issues if you have installed Python 3.10 on a system that shipped with an older version of Python, since the virtual environment will prevent you from picking up old system-provided packages that may cause problems under 3.10.

This example uses venv but you could do the same thing with virtualenv if you prefer.
First, just for kicks, let's ask Python what packages it has installed. Run python3.10 -m pip list and check its output.
- Depending on your OS, you may see a lot of packages listed here. Using a virtual environment will let us start with a clean slate, which means we won't run into hard-to-debug package incompatibilities or old broken package versions.
- In some cases the list command may error. This can happen if you have installed Python3.10 on an older Ubuntu system for example. This is likely due to Python picking up system-provided packages that were designed for the OS' Python version but broken under 3.10. This is another reason for wanting a virtual environment: to avoid such errors.
First make sure venv is available. Run python3.10 -m venv -h and you should see some help text. If not, you may have to install some system package to get venv. On Ubuntu, for example, this would be sudo apt install python3.10-venv.
Once you're sure venv is installed, try creating a virtual environment in your home directory called '.pyba' (Python Ballistica). To do that, run python3.10 -m venv ~/.pyba.
Now, to use that virtual environment, run source ~/.pyba/bin/activate. When we do that we should see "(.pyba)" appear at the beginning of your shell prompt. That means the virtual environment is active. To deactivate it, simply run deactivate. That's really all there is to it. You can add those commands to your .bashrc/.zshrc/etc if you'd like that virtual environment to be active or you can manually activate it when working with Ballistica stuff.
Now, with the .pyba environment active, run python3.10 -m pip list once more. This time you should see a nice clean empty list. So now we can use pip to install exactly what we need and keep things clean and contained, and we can blow away .pyba anytime we want to start over.

Wrapping Up

At this point, no matter the platform, you should have a working Unix terminal, and typing which python3.10 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. Tools and commands should always be run from the project root unless they state otherwise.
Lastly, install Python modules used by the engine and tools. To list them, run tools/pcommand list_pip_reqs. To install them, run tools/pcommand install_pip_reqs. If you set up a virtual environment above, make sure it is active before doing this.
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 game scripts or other files so they are properly incorporated into subsequent builds. If you can't figure out why importing your shiny new Python module from within the game is failing, you probably forgot to do this.

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)