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:

bs.Session

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.

bs.Activity

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.

bs.Node
bs.Texture
bs.Model
bs.CollideModel
bs.Sound

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.

bs.Timer

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.

bs.Actor

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:

bs.gameTimer(1000,bs.Call(myFunction,myArg1,myArg2))

this will run myFunction(myArg1,myArg2) after 1 second of game time.  Be sure to avoid this common mistake:

 bs.gameTimer(1000,myFunction(myArg1,myArg2))

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:

bs.gameTimer(99000,bs.Call(myActivity.handleTimeExpired))

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:

bs.gameTimer(99000,bs.WeakCall(myActivity.handleTimeExpired))

..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.

Internal functions/variables

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.

Avoid globals

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.