Skip to content
Eric Froemling edited this page Oct 11, 2022 · 120 revisions

Welcome to the Ballistica Wiki!

I'm going to attempt to keep this pretty freeform and open to the public, so please feel free to add your own docs here or improve existing ones. We'll see how that goes. I'll switch this to private if it gets abused, so please don't be that person.

If you're brand new to Ballistica, head over to the README for an introduction. Otherwise you're in the right place.


Black is the new Yapf

October 10, 2022

I love autoformatting. Ballistica has been using yapf to format its Python code for years and it has generally worked well. However, yesterday I discovered that yapf chokes on the new match statement in Python 3.10 which I was experimenting with for the first time. This puzzled me since Python 3.10 has been out for nearly a year now, which is plenty of time for tools to embrace new features, and it led me to looking into the state of Python auto-formatters. After doing some research, it seems that the yapf project is largely inactive and some might say dying, while black is looking extremely lively and healthy. I had looked at black back when I was originally setting up auto-formatting but went with yapf due to its large set of style options compared to black's 'uncompromising' lack of them. But in taking another look now, I find black's style quite acceptable and it does feel more 'human curated' and consistent compared to yapf's more fuzzy algorithms which usually look great but occasionally spit out bafflingly ugly results.

So we're using black now. But with a few caveats:

  • We're going with 80 char line lengths. Black defaults to 88 but since we want to be as usable as possible on mobile devices with tiny screens let's stick with 80, which is also a widely used standard. Note that I'm actually increasing this from 79 which we were using before and which is recommended by Pep-8, but I feel Pep-8's motivation for 79 vs 80 (editors showing marker glyphs in the last column) isn't a very common thing so let's splurge and use the full 80.
  • I'm also disabling black's 'string normalization' which converts all single quotes to double. I'm not ready to let go of my single quotes; I find them more elegant looking and readable personally. Maybe I will reconsider later.

To use the new formatting you shouldn't need to do anything aside from making sure black is installed. (pip install black). Ballistica build targets should nag you if it isn't. Then just run the standard stuff like make format or make preflight. You can also use efrotools.code.format_python_str() to explicitly run some code through formatting with our settings or efrotools.code.black_base_args() to get the command line args we use to invoke the tool.

Now back to trying out that match statement...

Cloud Console

September 18, 2022

The 1.7.7 update is now starting to roll out which adds support for the new devices page; specifically the console feature. This lets you see app output and run commands on any device where you are signed in with your V2 account. This should be a great help to modders using phones or other devices where it can be difficult to get at device/app logs any other way. It also can be of use to all modders in that it lets you write multi-line test code and easily run it repeatedly after relaunching the app. When combined with workspaces, this should start to allow pretty effective modding using nothing but a web browser. Next I plan to enable V2 account features for Google Play and other widely used account type and then I plan to write some modder tutorials using these tools. Stay tuned.

Discord Server

Aug 4, 2022

I've been getting a lot of requests for this, so at long last there is an official BombSquad/Ballistica Discord Server. Lots of modders and community members have joined already and I'll be hopping on periodically (including weekly scheduled office-hours time) so its a great resource to ask questions or share fun stuff you've made.

BombSquad 1.7 is Here!!!!

July 13, 2022

🚀 Here we go! (see the discussion)


July 1, 2022

The new 1.7 workspaces functionality is finally live. This includes both the simple web editing front end and the bacloud command line tool for interacting with them from a computer. Please holler if you run into any issues or have any feedback. My next priority will be getting 1.7 builds pushed out to Google Play, etc. so that people don't need to grab test builds to play with this stuff.

Workspaces Documentation

Python 3.10

June 1, 2022

To go along with the imminent 1.7 release, Ballistica has been upgraded from Python 3.9 to 3.10. This means we're using the latest and greatest available. I've also improved my back-end pipeline to be less dependent on OS Python versions, meaning we are free to upgrade Ballistica's Python version yearly in sync with Python itself instead of waiting for Ubuntu LTS updates or whatnot (though I expect we'll still wait a few months after new Python releases to allow tools support to mature/etc).

Accordingly, I'll be updating the getting started section with more information about installing Python versions outside of what comes with the OS. For example, homebrew for Mac currently still installs Python 3.9 by default but you'll need to install 3.10 to build Ballistica stuff.

Here is the list of what's new in Python 3.10. There's nothing super relevant to us, but there are a few things that could be fun to play with. Originally 3.10 would have meant we could remove all the from __future__ import annotations lines, but that change has been deferred.

On the type-checking side here is one nice syntax improvement: typing.Optional and typing.Union are no longer necessary.

Instead of code like this:

from typing import Union, Optional
possibly_str: Optional[str] = 'HELLO' if random.random() > 0.5 else None
assert isinstance(possibly_str, (str, type(None))
str_or_int: Union[str, int] = 'HELLO' if random.random() > 0.5 else 123

We can now do this:

possibly_str: str | None = 'HELLO' if random.random() > 0.5 else None
assert isinstance(possibly_str, str | None)
str_or_int: str | int = 'HELLO' if random.random() > 0.5 else 123

Please holler or submit corrections if you find anything broken, out-of-date docs, etc.

Python 3.9

October 23, 2021

Ballistica/Bombsquad 1.6.5 has been upgraded from Python 3.8 to 3.9. I will be switching to an Arm-based Mac as my primary development machine, and 3.9 is the first officially supported version there, so it seemed like a good time to update. 3.10 was just released but it is not very widely available yet so we'll get to that one later in its lifecycle.

Python 3.9 should be relatively easy to get on most platforms; on Ubuntu 20 (including WSL on Windows) do sudo apt update; sudo apt install python3.9-dev and on Mac homebrew setups do brew install python@3.9. See the getting started section for details.

Here is what's new in Python 3.9. For us, the most noticeable improvement will be simplified type annotations in many cases; the standard type objects can now be used instead of special ones from the typing module.

Instead of code like this:

from typing import Dict, Tuple
my_obj_vals: Dict[str, Tuple[int]] = {'obj1': (1, 2, 3)}

We can now do this:

my_obj_vals: dict[str, tuple[int]] = {'obj1': (1, 2, 3)}

Please holler or submit corrections if you find anything broken, out-of-date docs, etc.

Compiling on Windows

June 6, 2021

For a while it has been possible to compile most of the game from source on Linux and Mac, and I am happy to say that this is now also possible on Windows. See the documentation here. If you have any feedback or run into any issues, please contribute to the discussion here. Enjoy!

BombSquad 1.6!

May 5, 2021

1.6 builds of BombSquad are now starting to make their way to various platforms (as well as equivalent ballisticacore builds here). The big new feature is private hosting, which lets you spin up a game on a cloud server and share a simple code with friends to join it. This represents the first use of my new worldwide cloud-hosting setup I've been working on for many months, which will form the foundation for lots of fun stuff in upcoming versions (multiplayer tournaments, matchmaking, etc.) See the CHANGELOG for the full list of changes. As always, please holler if you run into any issues, and enjoy!

Native M1 Mac Support

November 25, 2020

Ballistica now supports native Arm-64 builds on the new M1 Macs (both via the 'Prefab' targets and building from source). See the updated getting started section for details. A full compile from source on an M1 takes approximately 19 seconds 😎.

C++ Layer Now (Mostly) Open Source

October 13, 2020

I finally took some time and got most of the engine C++ code up here, so it is now possible to build from sources instead of using only pre-built binaries. So if anyone would like to muck around with low level code such as the rendering or physics engines, it is now possible. See Native Layer Overview for details.

Python 3.8

August 1, 2020

Ballistica/Bombsquad 1.5.24 has been upgraded from Python 3.7 to 3.8, which is (at the time of this post) the newest version available. This is nowhere near as big of a change as the 2.7 -> 3.7 upgrade was (all Python code that worked in 3.7 should still work in 3.8), but it may require adjustments to your development environment if you don't have Python 3.8 available currently, as the build tools are very specific in looking for that exact version. I will try to keep Ballistica generally up to date with the latest Python version so this transition will happen once every year or two. I'll be updating the 'getting started' docs and any other places that mention Python 3.7, and please holler if you come across outdated information elsewhere. (or feel free to correct it yourself).

New Plugin System in 1.5.23

July 23, 2020

A common request since 1.5 has been the ability for mods to automatically execute at launch (1.4 would run everything in the mods folder at launch but 1.5 doesn't). So I'm happy to announce that as of 1.5.23 it is once again possible to run code at launch via the new 'plugin' system. Learn more.

BombSquad 1.5 Full Rollout

It's been a long process of bug fixing and polishing, but I'm happy to say that as of 1.5.22, I've flipped the switch to have Google Play deliver 1.5.x to 100% of users (no more 1.4). Please continue to report any bugs or rough edges and now we can move on to the fun stuff in 1.6+...

BombSquad 1.5 is Here!!!!

After several weeks of cleanup and testing, I'm happy to say that BombSquad 1.5, the first version of the game using this Ballistica codebase, is here.

Grab test builds at

As mentioned in the roadmap, the goal with 1.5 is to transition the existing game to the new architecture. Most of the exciting new features will be coming in the next few versions and building on this foundation. But for now, please holler if anything seems broken or functionally different from what it was in 1.4. The sooner we can work through any bugs the sooner we can move on to the fun stuff...


  • Update: generic Android test builds are also now available also (as of 1.5.6)
  • There is now open testing for the Google Play Android version. To opt-in to testing, go here or look for the 'Join beta' option in the Google Play store.
  • I will begin rolling these out slowly to Google Play, the Mac App Store, etc. soon in a staggered fashion.
  • These official BombSquad releases are basically identical to what you get if you run the current prefab Ballistica builds from here. The main difference is that things are named 'BombSquad' instead of 'BallisticaCore' and tournaments should be functional (tournament scores submitted from BallisticaCore builds are rejected).