Python Overview

Overview

Ballistica consists of two layers; a low level layer written in C++ and a high level layer written in Python. Things such as rendering and physics calculations happen in the low level layer, and things such as game and ui logic happen in the Python layer. For modding purposes, the Python layer is the only really relevant one (at least for now).

Ballistica vs. Original BombSquad

This is a high level list of some of the tech changes in Ballistica vs the original BombSquad scripting layer. For detailed changes you can look at the ChangeLog, though admittedly not all Ballistica changes made it in there. In future incremental updates that list should hopefully be more exhaustive.

• Ballistica uses a modern version of Python (3.7 at the time of this writing), whereas the old code was using the (now end-of-life) 2.7 version. There are some incompatible differences between Python 2 and Python 3 to be aware of such as the print() statement and reworked string types. Python's 2-to-3 transition has been going on for many years and there is plenty of information available about porting code. Moving to modern Python gives us lots of fun new toys to play with, including a better super(), data classes, enums, f-strings, and type hints. One thing to keep in mind is that, going forward, all Ballistica platforms will be targeting a single recent version of Python (currently 3.7), and so all code can target the exact feature-set from that version; no need to worry about backward compatibility.
• Ballistica has incorporated static typing into all of its Python code. This is currently being done with Mypy, though different or additional systems could be adopted in the future. Static typing can make code in a large project easier to write, more robust, and less prone to breakage, especially in cases such as ours where APIs are evolving over time. There are a number of useful tips in the Knowledge Nuggets page related to Mypy and type checking.
• Ballistica has adopted common code standards for Python such as Pep-8 which should allow us to more cleanly interoperate with the rest of the Python world and more easily take advantage of linters, auto-formatters, and other tools. See the Python section of the Coding Style Guide for specifics. I apologize for the annoyance of having to rewrite lots of thisTypeOfThing() as this_type_of_thing(), but if you take some time and familiarize yourself with the type-checking setup and get creative with search-and-replace then it shouldn't be too painful of a process I hope.
• Ballistica's APIs have been reshuffled a bit and split into several Python packages containing a hierarchy of smaller, more maintainable modules. See the Python Package Overview section below for details.

Python Package Overview

In original BombSquad, game scripts were contained in a single flat directory of (often very large) Python modules. There were getting to be a lot of these, and some of them had grown in size over time to become extremely unwieldy, so a reorganization was in order. They have now been split into much smaller, more manageable modules and organized into several Packages. These are described below.

• ba

  The core Ballistica package. This encapsulates core engine functionality and base types. It is documented here. The goal for this package is to contain only foundational pieces that should never need to be touched by modders and that everything else should be in 'bastd' (this reorganization is still a work in progress).

• bastd

  The Ballistica Standard Library. This contains all UIs, game types, actor types, etc. for the current BombSquad game. By replacing or augmenting this library, one should be able to create mods or completely new games (this reorganization is still a work in progress).

• bacommon

  This package contains types and values shared between the Ballistica client app and various server components. Modders generally should not need to touch this.

• efro

  This package contains core functionality that is shared among all of my own projects. It is noteworthy in that it is made available not only to the built game, but also to the project build-tools. Any code in here should be well hardened and covered by unit-testing since a lot depends on it. Please consult me before making changes or additions here.

• efrotools

  This package contains functionality shared among build-tools in all of my projects. It is only used for tools and not available from the game itself, so not as much care needs to be taken with it compared to the 'efro' package.