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.

April 23, 2024

As part of the upcoming 1.7.34 update, the project has officially been upgraded to use Python 3.12. Anyone who's been around for a while knows the drill: make sure you've got a python3.12 available on your path/etc. and you should be able to build the latest version. You may need to do a make clean or freshly clone the repo if you run into problems.

One thing that you won't have to do this time, however, is reinstall a bunch of Pip packages. One fun feature that I added to correspond with the Python 3.12 update is a project-managed Python virtual-environment. This means that the project will no longer pester you to install a bunch of Pip stuff like mypy, pylint, etc. It now simply does so itself and keeps it wrapped up in its own private little virtual-environment (in .venv if you're curious). This should make it easier to get up and running and make things more consistent for people.

June 22, 2023

The BombSquad 1.7.20 update is rolling out to all Google Play users as of today. Even though the version number makes it look like a minor update, it contains some very substantial changes under the hood which form a foundation for features coming in 1.8. If you have written any mods, you will need to update them, as the api-version has been bumped from 7 to 8.

Basically, 1.7.20 splits the game/engine out into independent versioned 'feature-sets'. This means if you are writing gameplay code, you will pull in the things you need from a 'bascenev1' (Ballistica Scene Version 1) package, or if you are writing UI code you might use 'bauiv1' (Ballistica User Interface Version 1). Previously all of this stuff lived under the single 'ba' module.

So basically, to update mods, you will need to replace your usage of 'ba' or 'bastd' with the new feature-set packages. Yes, this is annoying, but the upside is that once things are using the new system it should be easier to keep them from breaking in the future, as we can add new feature-sets such as 'bascenev2' to evolve the api forward while leaving the older apis untouched. To see an example of updating a game script from api 7 to 8, check out this demo in a recent 'Coffee With Eric' episode. Also scan through the changelog and hop on the Ballistica Discord if you have any questions or hit any bugs.

There are lots more architecture improvements in this update, including 'App-Modes', the 'Spinoff' project system, and an update to Python 3.11. Stay tuned for more details on all of these... now onward to 1.8!

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...

September 18, 2022

The 1.7.7 update is now starting to roll out which adds support for the new ballistica.net 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.

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.

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

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.

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.

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!

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!

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 😎.

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.

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).

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.

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+...

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 https://files.ballistica.net/bombsquad/builds/

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...

Notes:

• 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).