Ok, I just completed the BombSquad 1.3.13 update, and now we can really start to have some fun.

In this update I added the ability to create your own scripts or override all of the game’s internal ones, so you can mod and tweak the game to your heart’s content without having to root your device or damage your install.

To get started, make sure you’ve run tutorial 1 so you know how to issue commands to the game.  Also make sure that you’re running BombSquad version 1.3.22 or newer.  You can look at the bottom right corner of the main menu screen for the version number.

First, a bit of context:

Conceptually, BombSquad is divided into two layers.  The first, low-level layer, the engine, is written in high-performance c/c++ code and handles things like rendering, physics, and input.  Changing to this requires re-compiling the game binary.  On top of this there is a higher level scripting layer which drives the engine.  All actual game logic happens in this layer, such as: ‘give team X a point when Y does Z’ …or ‘set player X’s hit points to Y’.   This logic is all written into Python scripts stored with the game, so by adding our own or editing the internal ones we can completely change the game.

To get started, issue the following command in a BombSquad shell:

env = bs.getEnvironment()
print env['userScriptsDirectory']

The string you see printed where you can place python scripts to have the game pick them up. On OUYA this should be ‘/sdcard/BombSquad’, which you can easily get at via file browsers such as ‘Android File Transfer’ on Mac.*

Now let’s look at another path:

print env['systemScriptsDirectory']

This will show you where all of BombSquad’s built-in scripts live, including all existing mini-games and object types.  Unfortunately you can’t modify anything in this directory without rooting your device or changing file permissions, but you don’t actually *need* to modify anything here.  When BombSquad launches, if it finds a directory named ‘sys/1.3.23’ (or whatever version you are running) under its user-scripts directory, it will use that as its system-scripts directory in place of it’s internal one.  ..So you just need to make a copy of BombSquad’s system scripts at that location to be able to modify them.   As luck may have it, there’s a command to do just that:

import bsUtils
bsUtils.createUserSystemScripts()

ta-da!

Run that command, then quit BombSquad (via the UI or by running bs.quit()) and re-launch it. Now if you print bs.getEnvironment()[‘systemScriptsDirectory’] once more you should see that it’s now pointing to a path within your user-scripts dir (something like ‘/sdcard/BombSquad/sys/1.3.23/’).

Let’s be doubly sure by taking a look at one of BombSquad’s internal python modules. Run the following:

import bs
print bs.__file__

the ‘__file__’ attribute on any Python module shows where it came from, so if everything’s in order you should see that bs was loaded from that same new location.

One last note before we start making changes:
In the course of tinkering with BombSquad’s scripts it’s possible to break the game or leave it in a messed up state where it won’t even launch successfully (due to syntax errors, infinite loops, etc). Don’t panic when this happens. As a failsafe you can just force-kill the app (or restart the device if that’s easier), temporarily move or rename your custom copy of the system scripts, and then relaunch BombSquad to get back to a ‘vanilla’ version. There’s also a bsUtils.deleteUserSystemScripts() function that will clear out that directory for you.

Note that BombSquad will print all errors and other info to the log on android and to stdout on other platforms, so you may be able to debug problems that way. (‘adb logcat’ on android, launching via terminal on OSX, etc).

With that important safety-message out of the way, we’re ready to start messing around. Feel free to take a look around the system scripts to see how things are put together. Here are a few of BombSquad’s built-in modules and their uses:

• bs.py: this pulls in bits of various modules to create BombSquad’s core API
• bsUI.py: user-interface bits (windows, dialogs, etc) are found here
• bsSpaz.py: the player character is defined here as well as variations of it (bots, etc)
• bsDeathMatch.py: this is an example of a mini-game. More on these later.

To keep this tutorial from getting too long, for now we’re just going to change something simple; let’s change teams-mode from a best-of-7 series to a best-of-5.
To do this, make sure you’ve got your sys/1.x.x directory, and then dive in there and find the bsTeamGame.py script.  That’s what we’ll need to edit.  Note that on Android platforms you may need to copy this file off the device, edit it, and copy it back on using something like “Android File Transfer”.  I’ll leave that as an exercise for the user.

Now look for the following line in bsTeamGame.py (currently its around line 711).

self._seriesLength = 7

..and change it to this:

self._seriesLength = 5
bs.screenMessage("SETTING CUSTOM SERIES LENGTH OF "+str(self._seriesLength))

Save the file, copy it back to your android device if necessary, and re-launch the game.
Now when you start a Teams game you should see the above message and your series should go to 5 games instead of 7.  Ta-da!

…Of course, if we wanted to make this a ‘proper’ option we could expose it via the GUI instead of hard-coding it like this, but that’s beyond the scope of this exercise.

Well, that’s all for this installment. Enjoy tinkering. Next time we’ll get into creating some new scripts from scratch.