I’m happy to announce BombSquad’s third official platform: Amazon Fire TV.
The game runs quite nicely on this little guy; I was able to crank the quality to high and add anti-aliasing and a few other bells and whistles. It supports GameCircle leaderboards and achievements, and I even got the remote usable as a controller.
I finally got around to putting together a little trailer for BombSquad… I apparently didn’t get the memo that this sort of things is generally done *before* a game is released
I’ll probably keep tweaking it over time, so let me know if you have any thoughts on it…
The awesome folks over at Duxter have been helping me put together a rather nifty BombSquad portal, and today we’re officially kicking it off with a prize giveaway; (everyone loves prizes!) Check it out:
There’s a lot of cool functionality in there already, and I’m excited about integrating the portal more tightly with BombSquad going forward with things like live high score lists, character/stats tracking, etc.. So hop on board and let’s see where this thing can go.
Ok; enough with the expositional stuff already… today we’re going to make an actual, playable, (hopefully) enjoyable mini-game.
It’s called ‘Meteor Shower’, and it’s pretty simple. You run around a platform as bombs fall from the sky at an ever increasing rate. The last team/player alive wins.
Here’s a video of me testing it:
To play, simply download the following file and stick it in BombSquad’s user-scripts dir. Poke the “Settings”->”Advanced”->”Show-Mods-Folder” button if you forgot where that is. You can then launch BombSquad, create a new teams or free-for-all playlist, and you should be able to add a ‘Meteor Shower’ game to it.
..And that’s it… To see what’s going on, just open the file and take a look at the code. I’ve commented it so you should be able to follow along. If you’re brave, take a stab at modifying it; see if you can change where or when the bombs fall, or change it to use a different map. Good luck!
This episode is just a brain-dump of basic scripting types and concepts, intended to be used as a reference guide. We’ll get back to writing code next episide. Anyway, let’s dive right in:
Classes to Be Familiar With:
Represents the entire set of games you are playing, and is in charge of swapping in activities for games, score-screens, etc. Current session types include Co-op, Teams, and Free-for-All.
An activity represents a single sub-unit of a session, of which one is current at a time (though multiple can exist briefly during transitions). Examples of activities include mini-games and score-screens.
These are BombSquad’s low level building blocks. At the most basic level, a BombSquad game script creates and manipulates these to construct a game experience.
Timers are used to run code at some point in the future, either once or in a repeating fashion. If the timer object dies (due to its reference count falling to zero) the timer will be cancelled, so make sure to store it as a field on your game/actor/etc if you want to keep it running.
If you want to create a single-shot timer that can’t be cancelled, you can use the bs.gameTimer() or bs.realTimer() functions.
Actors are a high-level building block implemented purely in Python. They generally encompass one or more nodes and handle message passing with other actors. Some example actors include bsSpaz.Spaz which is the standard character class and bsBomb.Bomb which is the standard explosive unit.
Concepts & Guidelines to Keep in Mind:
Reference counts, WeakRefs, and Activities
There are a few key concepts related to Python garbage collection to keep in mind when working in BombSquad. CPython, which BombSquad uses, has two methods for garbage-collection; in most cases objects are simply cleaned up when their reference-counts drop to zero, but there is also a fancier garbage-collector that runs periodically to clean up cases such as cyclical references. (Object A referencing object B which also references A). Be aware that BombSquad disables this second type of garbage collection to avoid hitches (though it does explicitly run it periodically at ‘safe’ times such as between games). Because of this, you should make sure to avoid dependency loops in your code, using weak-references or other methods as necessary.
A good way to debug references is to add a __del__() method to your objects containing a simple print statement. If you never see this print, your object is still alive because there’s a reference to it out there somewhere.
On a related note, be aware that BombSquad Activities are told to begin *only* after the previous Activity has been cleaned up, so you should be very careful about holding strong references to Activities. If you’re writing a Mini-Game and it gets ‘stuck’ after it ends, this is probably the problem. Familiarize yourself with weakref.ref and bs.WeakCall to help combat this.
bs.Call and bs.WeakCall
bs.Call is a convenient way to wrap up a Python callable along with arguments/keywords into a single callable object. This can be handy to pass to timers or other things that take callables as arguments. Example:
this will run myFunction(myArg1,myArg2) after 1 second of game time. Be sure to avoid this common mistake:
The above code is calling myFunction *immediately* and passing the result to bs.gameTimer, which is most likely not what you want.
Bound methods and references
One important concept to keep in mind is that a bound method of an instance is actually a little object containing a reference to the instance (“self”) as well as to the method to call, so if you pass a bound method as a callback you’re going to keep that object instance alive, which is something you may not want.
Example: avoid things like this:
In this example the timer is going to hold onto the bound method (myActivity.handleTimeExpired) for 99 seconds, thus keeping a reference to myActivity, thus keeping it from being garbage collected and preventing another activity from starting for that 99 seconds. Doh.
The proper thing to do here would be to use bs.WeakCall. This is just like Call, except if given a bound-method it will only keep a weak-reference to the instance, allowing it to be garbage-collected if its ref-count hits zero. (in which case calling it results in a no-op).
So the correct code would be:
..in this new code we won’t inadvertently keep myActivity alive, but it’ll still get its handleTimeExpired method called in 99 seconds if its still around.
Please keep in mind that functions, classes, and variables starting with an underscore (‘_’) should be considered ‘private’ to BombSquad and not used, as they are subject to change at any time. Actually this is a general coding convention in Python; not just with BombSquad. If you need functionally that is not available via a public class or function, please email me and we’ll arrange something.
This restriction may be eased in the future, but currently all nodes/textures/materials/etc become invalidated between sessions, so make sure to create and store these as part of your game/actor/etc; not in a global fashion.
Tutorial 3 was pretty long-winded, so if you made it through that it’s time for something simpler. Today we’re gonna write our very first mini-game.
This mini-game we’ll be making doesn’t actually do anything; it just ends after 5 seconds and gives all teams a score of 0, so the game comes out a draw. That’s ok though; the point is to show what a bare-bones mini-game looks like; we’ll make it fancier in a later tutorial.
When BombSquad gathers its list of mini-games, it simply scans through all modules in its user and system scripts directories looking for ones that define a ‘getGames()’ function.. so to add a game we simply have to write a module that provides that function.
Create a file named HelloWorldGame.py (or whatever you want to call it), paste the following code in, and drop it into BombSquad’s user-scripts directory. You can use the ‘Show Mods Folder’ button in Settings->Advanced if you’ve forgotten where this is. (‘mods folder’ is just another term for the user scripts directory).
import bs # how BombSquad knows we exist def getGames(): return [HelloWorldGame] class HelloWorldGame(bs.TeamGameActivity): @classmethod def getName(cls): return 'Hello World Game' @classmethod def getDescription(cls,sessionType): return 'Just a test game.' def onBegin(self): bs.TeamGameActivity.onBegin(self) # game's starting - let's just set a timer to end it in 5 seconds bs.screenMessage("Hello World! Ending in 5 seconds...") self._endGameTimer = bs.Timer(5000,bs.WeakCall(self.endGame)) def endGame(self): # game's over - set a score for each team and tell our activity to finish ourResults = bs.TeamGameResults() for team in self.teams: ourResults.setTeamScore(team,0) self.end(results=ourResults)
Now, to try out your shiny new mini-game, launch BombSquad, create a new game list, and add a game to it. You should see ‘Hello World Game’ in the list of available game types. When you run the game you should just see it print its message and end.
If you’d like documentation on any of these classes or methods, take a look at the BombSquad Python API Docs.
Well, that’s it for this tutorial.. next time we’ll start to add logic to our game to make it actually worth playing… stay tuned. (or if you’re impatient, you can look through BombSquad’s system scripts directory at all the built-in mini-games as reference)
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:
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()
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.
Hi again folks.
Today we’re doing something simple but useful: turning off BombSquad’s player limits. I’ve gotten asked how to do this a fair amount so I thought it’d be worthwhile writing it down.
I built BombSquad’s engine to support *any* number of local players, but I decided to put in limits of 4 for co-op and 8 for teams/free-for-all so that I could ensure everything works cleanly with those numbers. Removing the limits and playing with more than that should work fine but is not officially supported, so please don’t be upset if you see little problems like player lists running off the edge of the screen or if your OUYA/Mac explodes from the insanity of it all and burns your house down.
Ok let’s get started.
First off, make sure you’ve gone through tutorial #1 so you know how to issue python commands to BombSquad.
Now simply run the following commands:
config = bs.getConfig() config['Coop Game Max Players'] = 999
config['Team Game Max Players'] = 999 config['Free-for-All Max Players'] = 999 bs.writeConfig()
If you entered everything correctly you shouldn’t see any errors …and we’re done. We just stored a few values in BombSquad’s config dictionary and told BombSquad to write its config to disk. Now you can gather up 3o or so friends, install BombSquad-Remote on their phones, and have the biggest BombSquad battle in history.
Here‘s a dorky video I made a few years ago while developing the game showing my personal record of 24 gamepads in one game. If you can top that, you have my eternal respect.
Well, that’s it for this round. Tune in next time and we’ll do something fancier like starting to build a new mini-game.
Alright let’s do this. Its time to mod the squad.
In this first tutorial we’re going to learn how to issue commands to BombSquad as it is running, which is very useful for modding and tinkering purposes.
What you’ll need:
- BombSquad version 1.3.15 or newer (the version number is visible at the bottom right of the screen when you launch the game) Grab an update from the Mac/OUYA/etc app store if you’re out of date.
- Python scripting knowledge. BombSquad’s game logic is written in Python, so you’ll need to be familiar with the language. It’s pretty nifty and useful outside of the game too; go to python.org to learn about it. BombSquad uses Python 2.7.
Option 1: The In-Game Console
If you are running BombSquad on Mac, Windows, or Linux, you can simply press backquote (`) or F2 to bring down the system console which will let you issue Python commands directly to the game. This is convenient, though functionality is a bit basic at the moment (no copy/paste, etc). For that reason you may still want to opt for option 2 even on these OSs.
Option 2: Telnet
The second option for talking to BombSquad is via a telnet client from your Mac/PC/etc. This is handy when you’re running BombSquad on a machine without a keyboard attached, such as an OUYA. Macs and Linux machines should have command-line telnet clients installed already; on Windows you may have to download a client such as ‘Putty’. Note that BombSquad’s telnet support is pretty rudimentary, so you may need to configure your client to connect in the most simple way possible to avoid strange errors.
Telnet Step 1: Find the game host’s IP address
We’ll need to know where to connect our telnet client to. If you’re running BombSquad on an OUYA, go to MANAGE->SYSTEM->CONSOLE INFO to find its IP Address. If you’re running BombSquad on the same machine you’ll be telneting from, you can just use ‘localhost’ as your address.
Telnet Step 2: Connect
Make sure BombSquad is running on your OUYA/Mac/etc, and then open a terminal on your computer and type the following to connect to the game, replacing ‘192.168.1.5’ with the address you found in the previous step:
telnet 192.168.1.5 43250
This will attempt to establish a telnet connection to the game on port 43250. If this works, you should see a message pop up on your BombSquad game asking if you want to allow the telnet client to connect. Hit ‘Allow’.
You should now see a prompt such as this:
Ok, you’re connected; now say hello.
At this point you can enter python commands for the game to run. As an example, type the following and hit return:
This will print a list of everything in the ‘bs’ module, which contains bombsquad’s core functionality. To learn more about something, you can use the builtin Python help. For instance, type the following to learn about the ‘bs.screenMessage’ function:
As you can see via help, this function lets us print stuff to the screen. Let’s give it a whirl by typing the following:
When you hit return you should see that message pop up in BombSquad. Ta-da!
And that’s it for our first tutorial. In the next tutorial we’ll build on that by looking at BombSquad’s internal scripts and starting to modify them for our nefarious purposes. Cheers!