Meta Tag System - efroemling/ballistica GitHub Wiki
Making the Engine Aware of Your Code
In pre-1.5 BombSquad, the engine would locate available games by importing every module present in the game's script directories and searching for functions in each such as bsGetAPIVersion() and bsGetGames(). While this worked, it was a bit wasteful and could lead to problems when trying to import out-of-date modules.
In Ballistica, a comment-based meta-tag system is used instead to inform the engine of a Python module's contents without requiring it to actually be imported. This means modules will only be imported if and when they are needed. This should help launch times and memory usage and generally make errors easier to isolate.
This difference, however, is an important consideration when modding. You can no longer rely on your module always being imported when the game launches. If you have code that needs to run at launch, you will need to reimplement it to run as a plugin.
API Version
Ballistica contains a numeric api-version value which is incremented whenever backwards-incompatible changes are introduced in its APIs. Python modules and packages must declare which api-version they were written against, and will only be discovered if the engine is running that same version. Whenever Ballistica's api-version changes, modules should be updated to take these changes into account and then their target api-versions should be set to once again match it.
The api-version of the running game can be found by looking at ba.app.api_version.
Note that this version will only be incremented once per 'official' release of the game; if you are working with the latest development builds here in the Ballistica project, you should keep an eye on the ChangeLog or Roadmap to stay aware of changes as they are introduced. Adding static typing to your own code is a good way to stay on top of these changes and be informed when something changes under you.
To specify which api-version your code targets, add the following line somewhere in your module (or in the top level __init__.py of a package):
# ba_meta require api 7
To determine what changed between api-versions, look up version/build numbers listed below in the ChangeLog:
- api 7: Corresponds to Ballistica 1.7.2 and newer.
- api 6: Corresponds to Ballistica 1.5 (build 20001)
Game Exports
To inform ballistica that your module/package defines a game type, insert this line above where you declare a ba.GameActivity subclass:
# ba_meta export game
class MyGame(ba.GameActivity):
"""My super awesome game type."""
Exported game types will be made available to the user when creating custom game playlists/etc.
Plugin Exports
To inform ballistica that your module/package defines a plugin, insert this line above where you declare a ba.Plugin subclass:
# ba_meta export plugin
class MyPlugin(ba.Plugin):
"""My super awesome plugin."""
Exported plugin types will show up in the plugins UI at Settings->Advanced->Plugins where they can be enabled/disabled by the user. Note that newly-discovered plugins are not enabled by default, but the user is informed that they were found so they can be enabled if desired.
Debugging
To see the complete set of metadata that was discovered at launch, look at the value of ba.app.meta.scanresults.
Also, check the game's output for any notices of incorrectly formatted ba_meta lines, etc.