Ok, I recently 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.13 or newer. You can look at the bottom right corner of the main menu screen for the version number. At the time of this writing 1.3.13 has been released for OUYA and should be available for Mac within a few days.
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:
The result of this call is 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.*
*A small side-note for android versions (OUYA, etc): Be aware that files created or deleted via Python code may not be visible through Android File Transfer until you run bs.androidRefreshFiles() and reconnect to the device. You may need to do this once right off the bat in order to even see the “/sdcard/BombSquad” directory. In general, if you ever find yourself scratching your head wondering why something isn’t showing up in Android File Transfer, try doing a bs.androidRefreshFiles().
Now let’s run another command:
This will show you where all of BombSquad’s built-in scripts live, including all existing mini-games and object types. 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.13′ (or whatever version you are running) under your 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 edit them. As luck may have it, there’s a command to do just that:
import bsUtils bsUtils.createUserSystemScripts()
Run that command, then quit BombSquad (via the UI or by running bs.quit()) and re-launch it. Now if you run bs.getSystemScriptsDirectory() 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.13/’).
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.
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: most core BombSquad functionality lives here
- 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.3.13 directory, and then dive in there and find the bsTeamGame.py script. That’s what we’ll need to edit. On Mac you may need to use Android File Transfer to copy the file off the device, edit it, and then copy it back on.. There may be ways to just edit the files in-place, but 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.