Python Overview
Ballistica consists of two layers; a low level 'native' layer written mostly 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 high level layer. For modding purposes, the high level Python layer is generally the only relevant one (at least for now).
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 is built around the latest Python 3.x releases, 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.8) at a given time, and so all code can target the exact feature-set from that version; no need to worry about backward or forward compatibility. When Ballistica's Python version changes, its API Version will be incremented as well, so code can be revisited at that time to make any needed changes for the new Python version. This should only happen once every few years.
- Ballistica has incorporated static typing into all of its Python code. Our type checking is currently being handled by 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. Static typing is purely to aid in development; it has no effect at runtime and is completely optional in your own mod code. I would highly recommend adopting it, however, as the Ballistica APIs will be in flux for a while and this will make it much easier for you to respond to these changes.
- 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()asthis_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.
In original BombSquad, game scripts were contained in a single flat directory of 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.
Project dependencies. A given component should only import/use components below it.
-
The Ballistica Standard Library. This is only available at runtime, and contains most all UIs, game types, actor types, and other components for the current incarnation of BombSquad. One should be able to create mods or completely new games by replacing or augmenting this package. (Note: this reorganization is still a work in progress so that is not entirely the case yet)
-
The core runtime Ballistica package. This encapsulates engine functionality and base types, and acts as a wrapper to the low-level C++ layer. 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. (Note: this reorganization is still a work in progress so that is not entirely the case yet)
-
This package contains types and values accessible at runtime but also by server or tool components. Modders generally should not need to touch this package.
-
This package contains functionality only used in builds/tests/etc. It is not present at runtime so can be a little less clean and organized than those components. Tools functionality that is specific to the Ballistica project should go here (anything containing specific paths, names, etc.) and tools functionality that is more general can go into the efrotools package instead.
-
This package contains functionality that might be useful by build-tools across multiple projects, not just Ballistica. Like batools, it is not present at runtime so can be a bit less clean and organized, though perhaps a bit more so than batools code due to its cross-project nature. Code placed here should never contain any ballistica-specific names or paths; that code should live in batools.
-
This package contains core functionality usable by all components (both runtime and tools), as well as other projects. 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.