BombSquad Python API

last updated on 2016-09-06 for BombSquad version 1.4.99 build 14255

This page documents the Python classes and functions in the 'bs' module, which are the ones most relevant to modding BombSquad. If you come across something you feel should be included here or could be better explained, please let me know. Happy modding!


Classes by Category:

Game Flow Classes:

General Utility Classes:

Bot Classes:

Media Classes:

Message Classes:

Misc:

User Interface Classes:


Functions by Category:

Game Flow Functions:

Media Functions:

User Interface Functions:

General Utility Functions:


bs.Activity

<top level class>

category: Game Flow Classes

Units wrangled by a bs.Session. Examples of Activities include games, score-screens, cutscenes, etc. A bs.Session has one 'current' Activity at any time, though their existence can overlap during transitions.

Attributes:

players, settings, teams

players

The list of bs.Players in the activity. This gets populated just before onBegin() is called and is updated automatically as players join or leave the game.

settings

The settings dict passed in when the activity was made.

teams

The list of bs.Teams in the activity. This gets populated just before onBegin() is called and is updated automatically as players join or leave the game. (at least in free-for-all mode where every player gets their own team; in teams mode there are always 2 teams regardless of the player count).

Methods:

<constructor>, continueOrEndGame(), end(), getSession(), handleMessage(), hasBegun(), hasEnded(), hasTransitionedIn(), isFinalized(), isTransitioningOut(), isWaitingForContinue(), onBegin(), onContinue(), onFinalize(), onPlayerJoin(), onPlayerLeave(), onTeamJoin(), onTeamLeave(), onTransitionIn(), onTransitionOut()

<constructor>

bs.Activity(self, settings={})

Creates an activity in the current bs.Session. The activity will not be actually run until bs.Session.setActivity() is called. 'settings' should be a dict of key/value pairs specific to the activity.

Activities should preload as much of their media/etc as possible in their constructor, but none of it should actually be used until they are transitioned in.

continueOrEndGame()

continueOrEndGame(self)

If continues are allowed, prompts the player to purchase a continue and calls either endGame or continueGame depending on the result

end()

end(self, results=None, delay=0, force=False)

Commences activity shutdown and delivers results to the bs.Session. 'delay' is the time delay before the activity actually ends (in milliseconds). Further calls to end() will be ignored up until this time, unless 'force' is True, in which case the new results will replace the old.

getSession()

getSession(self)

Returns the bs.Session this activity belongs to. If the session no longer exists, returns None.

handleMessage()

handleMessage(self, m)

General message handling; can be passed any message object.

hasBegun()

hasBegun(self)

Returns whether onBegin() has been called for this activity.

hasEnded()

hasEnded(self)

Returns whether end() has been called for this activity.

hasTransitionedIn()

hasTransitionedIn(self)

Returns whether onTransitionIn() has been called for this activity.

isFinalized()

isFinalized(self)

The activity is set as finalized when shutting down. At this point no new nodes, timers, etc should be made, run, etc, and the activity should be considered to be a 'zombie'.

isTransitioningOut()

isTransitioningOut(self)

Returns whether onTransitionOut() has been called for this activity.

isWaitingForContinue()

isWaitingForContinue(self)

(no docs)

onBegin()

onBegin(self)

Called once the previous bs.Activity has finished transitioning out. At this point the activity's initial players and teams are filled in and it should begin its actual game logic.

onContinue()

onContinue(self)

This is called if a game supports and offers a continue and the player accepts. In this case the player should be given an extra life or whatever is relevant to keep the game going.

onFinalize()

onFinalize(self)

Called when your activity is being finalized. If your activity has created anything explicitly that may be retaining a strong reference to the activity and preventing it from dying, you should tear that down here. From this point on your activity's sole purpose in life is to hit zero references and die so the next activity can begin.

onPlayerJoin()

onPlayerJoin(self, player)

Called for all new bs.Players (including the initial set of them).

onPlayerLeave()

onPlayerLeave(self, player)

Called when a player is leaving the activity.

onTeamJoin()

onTeamJoin(self, team)

Called when a new bs.Team enters the activity (including the initial set of them).

onTeamLeave()

onTeamLeave(self, team)

Called when a bs.Team leaves the activity.

onTransitionIn()

onTransitionIn(self)

Called when your activity is first becoming visible; It should fade in backgrounds, start playing music, etc. It does not yet have access to bs.Players or bs.Teams, however, until bs.Activity.onBegin() is called; they are still owned by the previous activity up until this point.

onTransitionOut()

onTransitionOut(self)

Called when your activity starts transitioning out and a new activity is on the way in. Note that this may happen at any time even if finish() has not been called.


bs.Actor

<top level class>

category: Game Flow Classes

Actors are high level organizational entities that generally manage one or more bs.Nodes, bits of game media, etc, along with the associated logic to wrangle them.

If bs.Nodes represent cells, think of bs.Actors as organs. Some example actors include bs.Bomb, bs.Flag, and bs.Spaz.

One key feature of actors is that they generally 'die' (killing off or transitioning out their nodes) when the last python reference to them disappears, so you can use logic such as:

# create a flag in our activity
self.flag = bs.Flag(position=(0,10,0))
# later, destroy the flag..
# (provided nothing else is holding a reference to it)
self.flag = None

This is in contrast to the behavior of the more low level bs.Nodes, which are always explicitly created and destroyed regardless of how many python references to them exist.

Another key feature of bs.Actor is its handleMessage() method, which takes a single arbitrary object as an argument. This provides a safe way to communicate between bs.Actor, bs.Activity, bs.Session, and any other object providing a handleMessage() method. The most universally handled message type for actors is the bs.DieMessage.

# another way to kill the flag from the example above:
# we can safely call this on any bombsquad type with a 'handleMessage' method.
# (though its not guaranteed to always have a meaningful effect)
self.flag.handleMessage(bs.DieMessage())

Methods:

<constructor>, autoRetain(), exists(), getActivity(), handleMessage(), isAlive(), isFinalized(), onFinalize()

<constructor>

bs.Actor(self)

Instantiates an actor in the current bs.Activity.

autoRetain()

autoRetain(self)

Automatically keeps this bs.Actor in existence by storing a reference to it with the bs.Activity it was created in. The reference is released once the actor no longer exists (see bs.Actor.exists()) or when the Activity is finalized. This can be a convenient alternative to storing references explicitly just to keep a bs.Actor from dying. For convenience, this method returns the bs.Actor it is called with, enabling chained statements such as: myFlag = bs.Flag().autoRetain()

exists()

exists(self)

Returns True if the actor is still visible or present in some way. Note that a dying character should still return True here as long as their corpse exists; this is about presence, not being 'alive'.

If this returns False, it is assumed the actor can be completely deleted without affecting the game; this call is often used when 'pruning' lists of actors.

The default implementation of this method returns 'node.exists()' if the actor has a 'node' attr; otherwise True.

getActivity()

getActivity(self, exceptionOnNone=True)

Return the bs.Activity this Actor is associated with. If the activity no longer exists, returns None.

handleMessage()

handleMessage(self, m)

General message handling; can be passed any message object.

isAlive()

isAlive(self)

Returns whether the Actor is 'alive'. What this means is up to the actor. It is not a requirement for actors to be able to die; just that they report whether they are alive or not.

isFinalized()

isFinalized(self)

Returns whether the actor has been finalized. (see bs.Actor.onFinalize())

onFinalize()

onFinalize(self)

onFinalize is called for each remaining bs.Actor when its bs.Activity is shutting down. Actors can use this opportunity to clear callbacks or other references which have the potential of keeping the bs.Activity alive inadvertantly.

Once an actor has been finalized (see bs.Actor.isFinalized()) it should no longer perform any game-object manipulation (creating, modifying, or deleting nodes, media, timers, etc.) Attempts to do so will likely in errors.


bs.Blast

inherits from: bs.Actor

category: Game Flow Classes

An explosion, as generated by a bs.Bomb.

Methods Inherited:

autoRetain(), exists(), getActivity(), isAlive(), isFinalized(), onFinalize()

Methods Defined or Overridden:

<constructor>, handleMessage()

<constructor>

bs.Blast(self, position=(0, 1, 0), velocity=(0, 0, 0), blastRadius=2.0, blastType='normal', sourcePlayer=None, hitType='explosion', hitSubType='normal')

Instantiate with given values.

handleMessage()

handleMessage(self, m)

General message handling; can be passed any message object.


bs.Bomb

inherits from: bs.Actor

category: Game Flow Classes

A bomb and its variants such as land-mines and tnt-boxes.

Methods Inherited:

autoRetain(), exists(), getActivity(), isAlive(), isFinalized()

Methods Defined or Overridden:

<constructor>, addExplodeCallback(), arm(), explode(), getFactory(), getSourcePlayer(), handleMessage(), onFinalize()

<constructor>

bs.Bomb(self, position=(0, 1, 0), velocity=(0, 0, 0), bombType='normal', blastRadius=2.0, sourcePlayer=None, owner=None)

Create a new Bomb.

bombType can be 'ice','impact','landMine','normal','sticky', or 'tnt'. Note that for impact or landMine bombs you have to call arm() before they will go off.

addExplodeCallback()

addExplodeCallback(self, call)

Add a call to be run when the bomb has exploded. The bomb and the new blast object are passed as arguments.

arm()

arm(self)

Arms land-mines and impact-bombs so that they will explode on impact.

explode()

explode(self)

Blows up the bomb if it has not yet done so.

getFactory()

<class method>

getFactory(cls)

Returns a shared bs.BombFactory object, creating it if necessary.

getSourcePlayer()

getSourcePlayer(self)

Returns a bs.Player representing the source of this bomb.

handleMessage()

handleMessage(self, m)

General message handling; can be passed any message object.

onFinalize()

onFinalize(self)

onFinalize is called for each remaining bs.Actor when its bs.Activity is shutting down. Actors can use this opportunity to clear callbacks or other references which have the potential of keeping the bs.Activity alive inadvertantly.

Once an actor has been finalized (see bs.Actor.isFinalized()) it should no longer perform any game-object manipulation (creating, modifying, or deleting nodes, media, timers, etc.) Attempts to do so will likely in errors.


bs.BomberBot

inherits from: bs.SpazBot, bs.Spaz, bs.Actor

category: Bot Classes

A bot that throws regular bombs and occasionally punches.

Attributes Inherited:

node

Methods:

<all methods inherited from bs.SpazBot>


bs.BomberBotLame

inherits from: bs.BomberBot, bs.SpazBot, bs.Spaz, bs.Actor

category: Bot Classes

A less aggressive yellow version of bs.BomberBot.

Attributes Inherited:

node

Methods:

<all methods inherited from bs.BomberBot>


bs.BomberBotPro

inherits from: bs.BomberBot, bs.SpazBot, bs.Spaz, bs.Actor

category: Bot Classes

A more aggressive red version of bs.BomberBot.

Attributes Inherited:

node

Methods:

<all methods inherited from bs.BomberBot>


bs.BomberBotProShielded

inherits from: bs.BomberBotPro, bs.BomberBot, bs.SpazBot, bs.Spaz, bs.Actor

category: Bot Classes

A more aggressive red version of bs.BomberBot who starts with shields.

Attributes Inherited:

node

Methods:

<all methods inherited from bs.BomberBotPro>


bs.BomberBotProStatic

inherits from: bs.BomberBotPro, bs.BomberBot, bs.SpazBot, bs.Spaz, bs.Actor

category: Bot Classes

A more aggressive red version of bs.BomberBot who generally stays in one place.

Attributes Inherited:

node

Methods:

<all methods inherited from bs.BomberBotPro>


bs.BomberBotProStaticShielded

inherits from: bs.BomberBotProShielded, bs.BomberBotPro, bs.BomberBot, bs.SpazBot, bs.Spaz, bs.Actor

category: Bot Classes

A more aggressive red version of bs.BomberBot who starts with shields and who generally stays in one place.

Attributes Inherited:

node

Methods:

<all methods inherited from bs.BomberBotProShielded>


bs.BomberBotStatic

inherits from: bs.BomberBot, bs.SpazBot, bs.Spaz, bs.Actor

category: Bot Classes

A version of bs.BomberBot who generally stays in one place.

Attributes Inherited:

node

Methods:

<all methods inherited from bs.BomberBot>


bs.BomberBotStaticLame

inherits from: bs.BomberBotLame, bs.BomberBot, bs.SpazBot, bs.Spaz, bs.Actor

category: Bot Classes

A less aggressive yellow version of bs.BomberBot who generally stays in one place.

Attributes Inherited:

node

Methods:

<all methods inherited from bs.BomberBotLame>


bs.BombFactory

<top level class>

category: Game Flow Classes

Wraps up media and other resources used by bs.Bombs A single instance of this is shared between all bombs and can be retrieved via bs.Bomb.getFactory().

Attributes:

activateSound, blastMaterial, bombMaterial, bombModel, debrisFallSound, dinkSounds, explodeSounds, freezeSound, fuseSound, hissSound, iceTex, impactBlastMaterial, impactBombModel, impactLitTex, impactTex, landMineBlastMaterial, landMineLitTex, landMineNoExplodeMaterial, landMineTex, landMinModel, normalSoundMaterial, regularTex, rollSound, stickyBombModel, stickyImpactSound, stickyMaterial, stickyTex, tntModel, tntTex, warnSound, woodDebrisFallSound

activateSound

A bs.Sound for an activating impact bomb.

blastMaterial

A bs.Material applied to bomb blast geometry which triggers impact events with what it touches.

bombMaterial

A bs.Material applied to all bombs.

bombModel

The bs.Model of a standard or ice bomb.

debrisFallSound

The bs.Sound for random falling debris after an explosion.

dinkSounds

A tuple of bs.Sounds for when bombs hit the ground.

explodeSounds

A tuple of bs.Sounds for explosions.

freezeSound

A bs.Sound of an ice bomb freezing something.

fuseSound

A bs.Sound of a burning fuse.

hissSound

The bs.Sound for the hiss sound an ice bomb makes.

iceTex

The bs.Texture for ice bombs.

impactBlastMaterial

A bs.Material applied to activated impact-bombs that causes them to exlode on impact.

impactBombModel

The bs.Model of an impact-bomb.

impactLitTex

The bs.Texture for impact bombs with lights lit.

impactTex

The bs.Texture for impact bombs.

landMineBlastMaterial

A bs.Material applied to activated land-mines that causes them to exlode on impact.

landMineLitTex

The bs.Texture for land-mines with the light lit.

landMineNoExplodeMaterial

A bs.Material that keeps land-mines from blowing up. Applied to land-mines when they are created to allow land-mines to touch without exploding.

landMineTex

The bs.Texture for land-mines.

landMinModel

The bs.Model of a land-mine.

normalSoundMaterial

A bs.Material that generates standard bomb noises on impacts, etc.

regularTex

The bs.Texture for regular bombs.

rollSound

bs.Sound for a rolling bomb.

stickyBombModel

The bs.Model of a sticky-bomb.

stickyImpactSound

The bs.Sound for a squish made by a sticky bomb hitting something.

stickyMaterial

A bs.Material that makes 'splat' sounds and makes collisions softer.

stickyTex

The bs.Texture for sticky bombs.

tntModel

The bs.Model of a tnt box.

tntTex

The bs.Texture for tnt boxes.

warnSound

A bs.Sound for an impact bomb about to explode due to time-out.

woodDebrisFallSound

A bs.Sound for random wood debris falling after an explosion.

Methods:

<constructor>, getRandomExplodeSound()

<constructor>

bs.BombFactory(self)

Instantiate a BombFactory. You shouldn't need to do this; call bs.Bomb.getFactory() to get a shared instance.

getRandomExplodeSound()

getRandomExplodeSound(self)

Return a random explosion bs.Sound from the factory.


bs.BotSet

<top level class>

category: Bot Classes

A container/controller for one or more bs.SpazBots.

Methods:

<constructor>, addBot(), celebrate(), clear(), finalCelebrate(), getLivingBots(), haveLivingBots(), spawnBot(), startMoving(), stopMoving()

<constructor>

bs.BotSet(self)

Create a bot-set.

addBot()

addBot(self, bot)

Add a bs.SpazBot instance to the set.

celebrate()

celebrate(self, duration)

Tell all living bots in the set to celebrate momentarily while continuing onward with their evil bot activities.

clear()

clear(self)

Immediately clear out any bots in the set.

finalCelebrate()

finalCelebrate(self)

Tell all bots in the set to stop what they were doing and just jump around and celebrate. Use this when the bots have won a game.

getLivingBots()

getLivingBots(self)

Returns the living bots in the set.

haveLivingBots()

haveLivingBots(self)

Returns whether any bots in the set are alive or in the process of spawning.

spawnBot()

spawnBot(self, botType, pos, spawnTime=3000, onSpawnCall=None)

(no docs)

startMoving()

startMoving(self)

(no docs)

stopMoving()

stopMoving(self)

Tell all bots to stop moving and stops updating their AI. Useful when players have won and you want the enemy bots to just stand and look bewildered.


bs.BunnyBot

inherits from: bs.SpazBot, bs.Spaz, bs.Actor

category: Bot Classes

A speedy attacking melee bot.

Attributes Inherited:

node

Methods:

<all methods inherited from bs.SpazBot>


bs.Call

<top level class>

category: General Utility Classes

Wraps a callable and arguments into a single callable object. The callable is strong-referenced so it won't die until this object does. Note that a bound method (ex: myObj.doSomething) contains a reference to the 'self' object, so you will be keeping that object alive too. Use bs.WeakCall if you want to pass a callback without keeping things alive.

Methods:

<constructor>

bs.Call(self, *args, **keywds)

Instantiate a Call; pass a callable as the first arg, followed by any number of arguments or keywords.

# example: wrap a method call with 1 positional and 1 keyword arg
myCallable = bs.Call(myObj.doStuff,argVal,namedArg=anotherVal)
# now we have a single callable to run that whole mess
# this is the same as calling myObj.doStuff(argVal,namedArg=anotherVal)
myCallable()

bs.ChickBot

inherits from: bs.SpazBot, bs.Spaz, bs.Actor

category: Bot Classes

A slow moving bot with impact bombs.

Attributes Inherited:

node

Methods:

<all methods inherited from bs.SpazBot>


bs.ChickBotPro

inherits from: bs.ChickBot, bs.SpazBot, bs.Spaz, bs.Actor

category: Bot Classes

A more aggressive red version of bs.ChickBot.

Attributes Inherited:

node

Methods:

<all methods inherited from bs.ChickBot>


bs.ChickBotProShielded

inherits from: bs.ChickBotPro, bs.ChickBot, bs.SpazBot, bs.Spaz, bs.Actor

category: Bot Classes

A more aggressive red version of bs.ChickBot who starts with shields.

Attributes Inherited:

node

Methods:

<all methods inherited from bs.ChickBotPro>


bs.ChickBotStatic

inherits from: bs.ChickBot, bs.SpazBot, bs.Spaz, bs.Actor

category: Bot Classes

A bs.ChickBot who generally stays in one place.

Attributes Inherited:

node

Methods:

<all methods inherited from bs.ChickBot>


bs.CollideModel

<top level class>

category: Media Classes

A reference to a collide-model. Use bs.getCollideModel() to instantiate one.


bs.Context

<top level class>

category: General Utility Classes

A BombSquad Context. Many operations such as bs.newNode(), bs.getTexture(), etc. operate implicitly on the current context. Each bs.Activity has its own Context and objects within that activity (nodes, media, etc) can only interact with other objects from that context.

In general, as a modder, you should not need to worry about contexts, since timers and other callbacks will take care of saving and restoring the context automatically, but there may be rare cases where you need to deal with them, such as when loading media in for use in the UI (there is a special 'UI' context for all interface-related functionality)

When instantiating a bs.Context instance, a single argument is passed, which must be one of the following strings/objects:

'empty': Gives an empty context; it can be handy to run code here to ensure it does no loading of media, creation of nodes, etc.

'current': Sets the context object to the current context.

'UI': Sets to the UI context. UI functions as well as loading of media to be used in said functions must happen in the UI context.

a bs.Activity object: Gives the context for the provided activity. Most all code run during a game happens in the activity's context.

a bs.Session object: Gives the context for the provided session. Generally a user should not need to run anything here.

Usage:

Contexts are generally used with the python 'with' statement, which sets the context as current on entry and resets it to the previous value on exit.

# example: load a few textures into the UI context (for use in widgets, etc)
with bs.Context('UI'):
   myTex1 = bs.getTexture('fooTex1')
   myTex2 = bs.getTexture('fooTex1')

bs.ContextCall

<top level class>

category: General Utility Classes

A ContextCall wraps a callable object along with a reference to the current context (see bs.Context); it handles restoring the context when run and automatically clears itself to a no-op if the context starts shutting down (finalizing).

Generally, as a user, you should not need to use this directly; all standard BombSquad callbacks such as timers, materials, UI functions, etc. use this 'under the hood' so you don't have to worry about it. The only time it may be necessary is if you are implementing your own callbacks, such as a worker thread that does some action and then calls some callback when done. By wrapping said callback in one of these, you can ensure that you will not inadvertantly be keeping the current activity alive or running code in a torn-down (finalized) context.

You can also use bs.WeakCall for similar functionality, but ContextCall has the added bonus that it will not run with a finalized context, whereas bs.WeakCall simply looks at whether the target object still exists.

# example A: code like this can inadvertantly prevent our activity (self) from
# ending until the operation completes, since the bound method we're passing
# (self.doSomething) contains a strong-reference to self).
startSomeReallyLongAction(callbackWhenDone=self.doSomething)
# example B: in this case our activity (self) can still die properly;
# the callback will clear itself when the activity starts shutting down,
# becoming a harmless no-op and releasing the reference to our activity.
startSomeReallyLongAction(callbackWhenDone=bs.ContextCall(self.doSomething))

bs.CoopGameActivity

inherits from: bs.GameActivity, bs.Activity

category: Game Flow Classes

Base class for cooperative-mode games.

Attributes Inherited:

players, settings, teams

Methods Inherited:

<constructor>, cameraFlash(), continueOrEndGame(), createConfigUI(), end(), endGame(), filterGameName(), getConfigDescriptionLocalized(), getConfigDisplayString(), getDescription(), getDescriptionDisplayString(), getDisplayString(), getInstanceDescription(), getInstanceDisplayString(), getInstanceNameLocalized(), getInstanceScoreBoardDescription(), getInstanceScoreBoardDisplayString(), getInstanceScoreBoardNameLocalized(), getMap(), getName(), getResolvedScoreInfo(), getScoreInfo(), getSession(), getSettings(), getSupportedMaps(), getTeamDisplayString(), handleMessage(), hasBegun(), hasEnded(), hasTransitionedIn(), isFinalized(), isTransitioningOut(), isWaitingForContinue(), onContinue(), onFinalize(), onPlayerJoin(), onPlayerLeave(), onTeamJoin(), onTeamLeave(), onTransitionIn(), onTransitionOut(), projectFlagStand(), respawnPlayer(), setupStandardPowerupDrops(), setupStandardTimeLimit(), showInfo(), showScoreBoardInfo(), showZoomMessage(), spawnPlayer(), spawnPlayerIfExists()

Methods Defined or Overridden:

celebrate(), fadeToRed(), onBegin(), setupLowLifeWarningSound(), spawnPlayerSpaz(), supportsSessionType()

celebrate()

celebrate(self, duration)

Tells all existing player-controlled characters to celebrate; can be useful in co-op games when the good guys score or complete a wave.

fadeToRed()

fadeToRed(self)

Fades the screen to red; useful when the good guys have lost.

onBegin()

onBegin(self)

Called once the previous bs.Activity has finished transitioning out. At this point the activity's initial players and teams are filled in and it should begin its actual game logic.

setupLowLifeWarningSound()

setupLowLifeWarningSound(self)

Sets up the activity to play a beeping noise whenever any players are close to death.

spawnPlayerSpaz()

spawnPlayerSpaz(self, player, position, angle=None)

Spawn and wire up a standard player spaz

supportsSessionType()

<class method>

supportsSessionType(cls, sessionType)

Return whether this game type can be played in the provided bs.Session subtype.


bs.CoopSession

inherits from: bs.Session

category: Game Flow Classes

A bs.Session which runs cooperative-mode games. These generally consist of 1-4 players against the computer and include functionality such as high score lists.

Attributes Inherited:

players, teams

Methods Inherited:

end(), getActivity(), handleMessage(), onPlayerRequest(), onTeamJoin(), onTeamLeave(), setActivity()

Methods Defined or Overridden:

<constructor>, getCustomMenuEntries(), onActivityEnd(), onPlayerLeave(), restart()

<constructor>

bs.CoopSession(self)

Instantiate a co-op mode session.

getCustomMenuEntries()

getCustomMenuEntries(self)

Subclasses can override this to provide custom menu entries. The returned value should be a list of dicts, each containing a 'label' and 'call' entry, with 'label' being the text for the entry (translated) and 'call' being the callable to trigger if the entry is pressed.

onActivityEnd()

onActivityEnd(self, activity, results)

Method override for co-op sessions; jumps between co-op games and score screens.

onPlayerLeave()

onPlayerLeave(self, player)

Called when a previously-accepted bs.Player leaves the session.

restart()

restart(self)

Restarts the current game activity.


bs.DieMessage

<top level class>

category: Message Classes

Tells an object to die. Most bs.Actors respond to this.

Attributes:

how, immediate

how

The particular reason for death; 'fall', 'impact', 'leftGame', etc. This can be examined for scoring or other purposes.

immediate

If this is set to True, the actor should disappear immediately. This is for 'removing' stuff from the game moreso than 'killing' it. If False, the actor should die a 'normal' death and can take its time with lingering corpses, sound effects, etc.

Methods:

<constructor>

bs.DieMessage(self, immediate=False, how='generic')

Instantiate with the given values.


bs.DropMessage

<top level class>

category: Message Classes

Tells an object that it has dropped whatever it was holding.


bs.DroppedMessage

<top level class>

category: Message Classes

Tells an object that it has been dropped.

Attributes:

node

The bs.Node doing the dropping.

Methods:

<constructor>

bs.DroppedMessage(self, node)

Instantiate with a given bs.Node.


bs.Flag

inherits from: bs.Actor

category: Game Flow Classes

A flag; used in games such as capture-the-flag or king-of-the-hill. Can be stationary or carry-able by players.

Methods Inherited:

autoRetain(), exists(), getActivity(), isAlive(), isFinalized(), onFinalize()

Methods Defined or Overridden:

<constructor>, getFactory(), handleMessage(), setScoreText()

<constructor>

bs.Flag(self, position=(0, 1, 0), color=(1, 1, 1), materials=[], touchable=True, droppedTimeout=None)

Instantiate a flag.

If 'touchable' is False, the flag will only touch terrain; useful for things like king-of-the-hill where players should not be moving the flag around.

'materials is a list of extra bs.Materials to apply to the flag.

If 'droppedTimeout' is provided (in seconds), the flag will die after remaining untouched for that long once it has been moved from its initial position.

getFactory()

<class method>

getFactory(cls)

Returns a shared bs.FlagFactory object, creating it if necessary.

handleMessage()

handleMessage(self, m)

General message handling; can be passed any message object.

setScoreText()

setScoreText(self, text)

Utility func to show a message over the flag; handy for scores.


bs.FlagDeathMessage

<top level class>

category: Message Classes

A bs.Flag has died.

Attributes:

flag

The bs.Flag that died.

Methods:

<constructor>

bs.FlagDeathMessage(self, flag)

Instantiate with given values.


bs.FlagDroppedMessage

<top level class>

category: Message Classes

A bs.Flag has been dropped.

Attributes:

flag, node

flag

The bs.Flag that was dropped.

node

The bs.Node that was holding it.

Methods:

<constructor>

bs.FlagDroppedMessage(self, flag, node)

Instantiate with given values.


bs.FlagFactory

<top level class>

category: Game Flow Classes

Wraps up media and other resources used by bs.Flags. A single instance of this is shared between all flags and can be retrieved via bs.Flag.getFactory().

Attributes:

flagMaterial, flagTexture, impactSound, noHitMaterial, skidSound

flagMaterial

The bs.Material applied to all bs.Flags.

flagTexture

The bs.Texture for flags.

impactSound

The bs.Sound used when a bs.Flag hits the ground.

noHitMaterial

A bs.Material that prevents contact with most objects; applied to 'non-touchable' flags.

skidSound

The bs.Sound used when a bs.Flag skids along the ground.

Methods:

<constructor>

bs.FlagFactory(self)

Instantiate a FlagFactory. You shouldn't need to do this; call bs.Flag.getFactory() to get a shared instance.


bs.FlagPickedUpMessage

<top level class>

category: Message Classes

A bs.Flag has been picked up.

Attributes:

flag, node

flag

The bs.Flag that has been picked up.

node

The bs.Node doing the picking up.

Methods:

<constructor>

bs.FlagPickedUpMessage(self, flag, node)

Instantiate with given values.


bs.FreeForAllSession

inherits from: bs.TeamBaseSession, bs.Session

category: Game Flow Classes

bs.Session type for free-for-all mode games.

Attributes Inherited:

players, teams

Methods Inherited:

announceGameResults(), end(), getActivity(), getCustomMenuEntries(), getGameNumber(), getMaxPlayers(), getNextGameDescription(), handleMessage(), onActivityEnd(), onPlayerLeave(), onPlayerRequest(), onTeamJoin(), onTeamLeave(), setActivity()

Methods Defined or Overridden:

<constructor>

bs.FreeForAllSession(self)

Sets up playlists and launches a bs.Activity to accept joiners.


bs.FreezeMessage

<top level class>

category: Message Classes

Tells an object to become frozen (as in the effects of an ice bs.Bomb).


bs.GameActivity

inherits from: bs.Activity

category: Game Flow Classes

Common base class for all game activities; whether of the free-for-all, co-op, or teams variety.

Attributes Inherited:

players, settings, teams

Methods Inherited:

continueOrEndGame(), end(), getSession(), hasBegun(), hasEnded(), hasTransitionedIn(), isFinalized(), isTransitioningOut(), isWaitingForContinue(), onFinalize(), onTeamJoin(), onTeamLeave(), onTransitionOut()

Methods Defined or Overridden:

<constructor>, cameraFlash(), createConfigUI(), endGame(), filterGameName(), getConfigDescriptionLocalized(), getConfigDisplayString(), getDescription(), getDescriptionDisplayString(), getDisplayString(), getInstanceDescription(), getInstanceDisplayString(), getInstanceNameLocalized(), getInstanceScoreBoardDescription(), getInstanceScoreBoardDisplayString(), getInstanceScoreBoardNameLocalized(), getMap(), getName(), getResolvedScoreInfo(), getScoreInfo(), getSettings(), getSupportedMaps(), getTeamDisplayString(), handleMessage(), onBegin(), onContinue(), onPlayerJoin(), onPlayerLeave(), onTransitionIn(), projectFlagStand(), respawnPlayer(), setupStandardPowerupDrops(), setupStandardTimeLimit(), showInfo(), showScoreBoardInfo(), showZoomMessage(), spawnPlayer(), spawnPlayerIfExists(), spawnPlayerSpaz(), supportsSessionType()

<constructor>

bs.GameActivity(self, settings={})

Instantiates the activity and starts pre-loading the requested map.

cameraFlash()

cameraFlash(self, duration=999)

Create a strobing camera flash effect as seen when a team wins a game.

createConfigUI()

<class method>

createConfigUI(cls, sessionType, config, completionCall)

Launch a UI to configure settings for this game type under the given bs.Session type.

'config' should be an existing config dict (specifies 'edit' mode) or None (specifies 'add' mode).

'completionCall' will be called with a filled-out config dict on success or None on cancel.

Generally subclasses don't need to override this; if they override bs.GameActivity.getSettings() and bs.GameActivity.getSupportedMaps() they can just rely on the default implementation here which calls those functions.

endGame()

endGame(self)

Tells the game to wrap itself up and call bs.Activity.end() immediately. This method should be overridden by subclasses.

A game should always be prepared to end and deliver results, even if there is no 'winner' yet; this way things like the standard time-limit (bs.GameActivity.setupStandardTimeLimit()) will work with the game.

filterGameName()

<class method>

filterGameName(cls)

Given a game name, game type

getConfigDescriptionLocalized()

<class method>

getConfigDescriptionLocalized(cls, config)

Given a game config dict, return a short description for it. This is used when viewing game-lists or showing what game is up next in a series.

getConfigDisplayString()

<class method>

getConfigDisplayString(cls, config)

Given a game config dict, return a short description for it. This is used when viewing game-lists or showing what game is up next in a series.

getDescription()

<class method>

getDescription(cls, sessionType)

Subclasses should override this to return a description for this activity type (in English) within the context of the given bs.Session type.

getDescriptionDisplayString()

<class method>

getDescriptionDisplayString(cls, sessionType)

Return a translated version of getDescription(). Sub-classes should override getDescription(); not this.

getDisplayString()

<class method>

getDisplayString(cls, settings=None)

Return a descriptive name for this game/settings combo. Subclasses should override getName(); not this.

getInstanceDescription()

getInstanceDescription(self)

Returns a description for this particular game instance, in English. This is shown in the center of the screen below the game name at the start of a game. It should start with a capital letter and end with a period, and can be a bit more verbose than the version returned by getInstanceScoreBoardDescription().

Note that translation is applied by looking up the specific returned value as a key, so the number of returned variations should be limited; ideally just one or two. To include arbitrary values in the description, you can return a sequence of values in the following form instead of just a string:

# this will give us something like 'Score 3 goals.' in English
# and can properly translate to 'Anota 3 goles.' in Spanish.
# If we just returned the string 'Score 3 Goals' here, there would
# have to be a translation entry for each specific number. ew.
return ['Score ${ARG1} goals.', self.settings['Score to Win']]

This way the first string can be consistently translated, with any arg values then substituted into the result. ${ARG1} will be replaced with the first value, ${ARG2} with the second, etc.

getInstanceDisplayString()

getInstanceDisplayString(self)

Returns a name for this particular game instance.

getInstanceNameLocalized()

getInstanceNameLocalized(self)

Deprecated - use getInstanceDisplayString()

getInstanceScoreBoardDescription()

getInstanceScoreBoardDescription(self)

Returns a short description for this particular game instance, in English. This description is used above the game scoreboard in the corner of the screen, so it should be as concise as possible. It should be lowercase and should not contain periods or other punctuation.

Note that translation is applied by looking up the specific returned value as a key, so the number of returned variations should be limited; ideally just one or two. To include arbitrary values in the description, you can return a sequence of values in the following form instead of just a string:

# this will give us something like 'score 3 goals' in English
# and can properly translate to 'anota 3 goles' in Spanish.
# If we just returned the string 'score 3 goals' here, there would
# have to be a translation entry for each specific number. ew.
return ['score ${ARG1} goals', self.settings['Score to Win']]

This way the first string can be consistently translated, with any arg values then substituted into the result. ${ARG1} will be replaced with the first value, ${ARG2} with the second, etc.

getInstanceScoreBoardDisplayString()

getInstanceScoreBoardDisplayString(self)

Returns a name for this particular game instance, in English. This name is used above the game scoreboard in the corner of the screen, so it should be as concise as possible.

getInstanceScoreBoardNameLocalized()

getInstanceScoreBoardNameLocalized(self)

Deprecated - use getInstanceScoreBoardDisplayString

getMap()

getMap(self)

Returns the bs.Map in use for this activity.

getName()

<class method>

getName(cls)

Return a name for this game type in English.

getResolvedScoreInfo()

<class method>

getResolvedScoreInfo(cls)

Call this to return a game's score info with all missing values filled in with defaults. This should not be overridden; override getScoreInfo() instead.

getScoreInfo()

<class method>

getScoreInfo(cls)

Games should override this to provide info about their scoring setup. They should return a dict containing any of the following (missing values will be default):

'scoreName': a label shown to the user for scores; 'Score', 'Time Survived', etc. 'Score' is the default.

'lowerIsBetter': a boolean telling whether lower scores are preferable instead of higher (the default).

'noneIsWinner': specifies whether a score value of None is considered better than other scores or worse. Default is False.

'scoreType': can be 'seconds', 'milliseconds', or 'points'.

'scoreVersion': to change high-score lists used by a game without renaming the game, change this. Defaults to empty string.

getSettings()

<class method>

getSettings(cls, sessionType)

Called by the default bs.GameActivity.createConfigUI() implementation; should return a dict of config options to be presented to the user for the given bs.Session type.

The format for settings is a list of 2-member tuples consisting of a name and a dict of options.

Available Setting Options:

'default': This determines the default value as well as the type (int, float, or bool)

'minValue': Minimum value for int/float settings.

'maxValue': Maximum value for int/float settings.

'choices': A list of 2-member name/value tuples which the user can toggle through.

'increment': Value increment for int/float settings.

# example getSettings() implementation for a capture-the-flag game:
@classmethod
def getSettings(cls,sessionType):
    return [("Score to Win",{'default':3,
                             'minValue':1}),
            ("Flag Touch Return Time",{'default':0,
                                       'minValue':0,
                                       'increment':1}),
            ("Flag Idle Return Time",{'default':30,
                                      'minValue':5,
                                      'increment':5}),
            ("Time Limit",{'default':0,
                           'choices':[('None',0),
                                      ('1 Minute',60),
                                      ('2 Minutes',120),
                                      ('5 Minutes',300),
                                      ('10 Minutes',600),
                                      ('20 Minutes',1200)]}),
            ("Respawn Times",{'default':1.0,
                              'choices':[('Shorter',0.25),
                                         ('Short',0.5),
                                         ('Normal',1.0),
                                         ('Long',2.0),
                                         ('Longer',4.0)]}),
            ("Epic Mode",{'default':False})]

getSupportedMaps()

<class method>

getSupportedMaps(cls, sessionType)

Called by the default bs.GameActivity.createConfigUI() implementation; should return a list of map names valid for this game-type for the given bs.Session type.

getTeamDisplayString()

<class method>

getTeamDisplayString(cls, name)

Given a team name, returns a localized version of it.

handleMessage()

handleMessage(self, m)

General message handling; can be passed any message object.

onBegin()

onBegin(self)

Called once the previous bs.Activity has finished transitioning out. At this point the activity's initial players and teams are filled in and it should begin its actual game logic.

onContinue()

onContinue(self)

This is called if a game supports and offers a continue and the player accepts. In this case the player should be given an extra life or whatever is relevant to keep the game going.

onPlayerJoin()

onPlayerJoin(self, player)

Called for all new bs.Players (including the initial set of them).

onPlayerLeave()

onPlayerLeave(self, player)

Called when a player is leaving the activity.

onTransitionIn()

onTransitionIn(self, music=None)

Method override; optionally can be passed a 'music' string which is the suggested type of music to play during the game. Note that in some cases music may be overridden by the map or other factors, which is why you should pass it in here instead of simply playing it yourself.

projectFlagStand()

projectFlagStand(self, pos)

Projects a flag-stand onto the ground at the given position. Useful for games such as capture-the-flag to show where a movable flag originated from.

respawnPlayer()

respawnPlayer(self, player, respawnTime=None)

Given a bs.Player, sets up a standard respawn timer, along with the standard counter display, etc. At the end of the respawn period spawnPlayer() will be called if the Player still exists. An explicit 'respawnTime' can optionally be provided (in milliseconds).

setupStandardPowerupDrops()

setupStandardPowerupDrops(self, enableTNT=True)

Create standard powerup drops for the current map.

setupStandardTimeLimit()

setupStandardTimeLimit(self, duration)

Create a standard game time-limit given the provided duration in seconds. This will be displayed at the top of the screen. If the time-limit expires, endGame() will be called.

showInfo()

showInfo(self)

show the game description

showScoreBoardInfo()

showScoreBoardInfo(self)

Creates the game info display in the top left corner showing the name and short description of the game.

showZoomMessage()

showZoomMessage(self, message, color=(0.9, 0.4, 0.0), scale=0.8, duration=2000, trail=False)

Show the standard zooming text used to announce game names and winners.

spawnPlayer()

spawnPlayer(self, player)

Spawn *something* for the provided bs.Player. The default implementation simply calls spawnPlayerSpaz().

spawnPlayerIfExists()

spawnPlayerIfExists(self, player)

A utility method which calls self.spawnPlayer() *only* if the bs.Player provided still exists; handy for use in timers and whatnot.

There is no need to override this; just override spawnPlayer().

spawnPlayerSpaz()

spawnPlayerSpaz(self, player, position=(0, 0, 0), angle=None)

Create and wire up a bs.PlayerSpaz for the provide bs.Player.

supportsSessionType()

<class method>

supportsSessionType(cls, sessionType)

Return whether this game type can be played in the provided bs.Session subtype.


bs.HitMessage

<top level class>

category: Message Classes

Tells an object it has been hit in some way. This is used by punches, explosions, etc to convey their effect to a target.

Methods:

<constructor>

bs.HitMessage(self, srcNode=None, pos=Vector(0,0,0), velocity=Vector(0,0,0), magnitude=1.0, velocityMagnitude=0.0, radius=1.0, sourcePlayer=None, kickBack=1.0, flatDamage=None, hitType='generic', forceDirection=None, hitSubType='default')

Instantiate a message with various bits of information on the type of hit that occurred.


bs.ImpactDamageMessage

<top level class>

category: Message Classes

Tells an object that it has been jarred violently and may want to be damaged.

Attributes:

intensity

The intensity of the impact.

Methods:

<constructor>

bs.ImpactDamageMessage(self, intensity)

Instantiate a messages with a given intensity value.


bs.InputDevice

<top level class>

category: Game Flow Classes

Represents an input-device such as gamepad, touchscreen, or keyboard. For most modding purposes it should not be necessary to interact with this class; all player interaction should happen through the bs.Player class. This class is mostly just used for displaying or configuring assigned keys, buttons, etc.

Methods:

exists(), getAxisName(), getButtonName(), getID(), getInstanceNumber(), getName(), getPlayer(), getUniqueIdentifier(), isConnectedToRemotePlayer(), isRemoteClient(), removeRemotePlayerFromGame()

exists()

exists() -> bool

Returns whether the device still exists. Most functionality will fail on a nonexistant device.

getAxisName()

getAxisName() -> string

Given an axis ID, returns the name of the axis on this device.

getButtonName()

getButtonName() -> string

Given a button ID, returns the name of the key/button on this device.

getID()

getID() -> int

Returns the unique numeric ID for this input device.

getInstanceNumber()

getInstanceNumber() -> int

Returns the number of this device among devices of the same type.

getName()

getName() -> string

Returns the name of the device.

getPlayer()

getPlayer() -> bs.Player

Returns the bs.Player associated with this input-device, or None if there is none.

getUniqueIdentifier()

getIdentifier() -> string

Returns a string that can be used to uniquely identify a particular input-device, even among devices of the same type. (used for saving prefs, etc)

isConnectedToRemotePlayer()

isConnectedToRemotePlayer() -> bool

Returns whether or not this input-device is attached to a player on a remote host device.

isRemoteClient()

isRemoteClient() -> bool

Returns whether or not this input-device represents a remotely connected client.

removeRemotePlayerFromGame()

removeRemotePlayerFromGame() -> None

If this device is attached to a remote player, removes it from the game.


bs.Level

<top level class>

(no docs)

Methods:

<constructor>, getCampaign(), getComplete(), getDisplayString(), getGameType(), getHighScores(), getIndex(), getName(), getPreviewTex(), getPreviewTexName(), getRating(), getScoreVersionString(), getSettings(), setComplete(), setHighScores(), submitRating()

<constructor>

bs.Level(self, name, gameType, settings, previewTexName, displayName=None)

(no docs)

getCampaign()

getCampaign(self)

(no docs)

getComplete()

getComplete(self)

(no docs)

getDisplayString()

getDisplayString(self)

(no docs)

getGameType()

getGameType(self)

(no docs)

getHighScores()

getHighScores(self)

(no docs)

getIndex()

getIndex(self)

(no docs)

getName()

getName(self)

(no docs)

getPreviewTex()

getPreviewTex(self)

(no docs)

getPreviewTexName()

getPreviewTexName(self)

(no docs)

getRating()

getRating(self)

(no docs)

getScoreVersionString()

getScoreVersionString(self)

(no docs)

getSettings()

getSettings(self)

(no docs)

setComplete()

setComplete(self, val)

(no docs)

setHighScores()

setHighScores(self, highScores)

(no docs)

submitRating()

submitRating(self, rating)

(no docs)


bs.Lstr

<top level class>

category: General Utility Classes

Used to specify strings in a language-independent way. These should be used whenever possible in place of hard-coded strings so that in-game or UI elements show up correctly on all clients in their currently-active language.

To see available resource keys, look at any of the bsLanguage*.py files in the game or the translations pages at bombsquadgame.com/translate.

# EXAMPLE 1: specify a string from a resource path
myTextNode.text = bs.Lstr(resource='audioSettingsWindow.titleText')
# EXAMPLE 2: specify a translated string via a category and english value;
# if a translated value is available, it will be used; otherwise the english value will be.
# to see available translation categories, look under the 'translations' resource section.
myTextNode.text = bs.Lstr(translate=('gameDescriptions','Defeat all enemies'))
# EXAMPLE 3: specify a raw value and some substitutions.  Substitutions can be used
# with resource and translate modes as well.
myTextNode.text = bs.Lstr(value='${A} / ${B}', subs=[('${A}', str(score)), ('${B}', str(total))])
# EXAMPLE 4: Lstrs can be nested.  This example would display the resource at resPathA
# but replace ${NAME} with the value of the resource at resPathB
myTextNode.text = bs.Lstr(resource='resPathA', subs=[('${NAME}', bs.Lstr(resource='resPathB'))])

Methods:

<constructor>, evaluate(), isFlatValue()

<constructor>

bs.Lstr(self, *args, **keywds)

Instantiate a Lstr; pass a value for either 'resource', 'translate', or 'value'. (see Lstr help for examples). 'subs' can be a sequence of 2-member sequences consisting of values and replacements. 'fallback' can be a resource key that will be used if the main one is not present for the current language in place of falling back to the english value ('resource' mode only).

evaluate()

evaluate(self)

Evaluates the Lstr and returns a flat string in the current language. You should avoid doing this as much as possible and instead pass and store Lstr values.

isFlatValue()

isFlatValue(self)

Returns true if the Lstr is a simple string value with no translations, resources, or substitutions. In this case it is reasonable to replace it with a simple flattened string or do string manipulation on it.


bs.Map

inherits from: bs.Actor

category: Game Flow Classes

A collection of terrain nodes, metadata, and other functionality comprising a game map.

Methods Inherited:

autoRetain(), exists(), getActivity(), isAlive(), isFinalized(), onFinalize()

Methods Defined or Overridden:

<constructor>, getDefBoundBox(), getDefPoint(), getDefPoints(), getFFAStartPosition(), getFlagPosition(), getMusicType(), getName(), getPreviewTextureName(), getStartPosition(), handleMessage(), onPreload(), preload()

<constructor>

bs.Map(self, vrOverlayCenterOffset=None)

Instantiate a map.

getDefBoundBox()

getDefBoundBox(self, name)

Returns a 6 member bounds tuple or None if it is not defined.

getDefPoint()

getDefPoint(self, name)

Returns a single defined point or a default value in its absence.

getDefPoints()

getDefPoints(self, name)

Returns a list of points - as many sequential ones are defined (flag1, flag2, flag3), etc.

getFFAStartPosition()

getFFAStartPosition(self, players)

Returns a random starting position in one of the FFA spawn areas. If a list of bs.Players is provided; the returned points will be as far from these players as possible.

getFlagPosition()

getFlagPosition(self, teamIndex)

Return a flag position on the map for the given team index. Pass None to get the default flag point. (used for things such as king-of-the-hill)

getMusicType()

<class method>

getMusicType(cls)

Returns a particular music-type string that should be played on this map; or None if the default music should be used.

getName()

<class method>

getName(cls)

Return the unique name of this map, in English.

getPreviewTextureName()

<class method>

getPreviewTextureName(cls)

Return the name of the preview texture for this map.

getStartPosition()

getStartPosition(self, teamIndex)

Returns a random starting position in the map for the given team index.

handleMessage()

handleMessage(self, m)

General message handling; can be passed any message object.

onPreload()

<class method>

onPreload(cls)

Called when the map is being preloaded; it should load any media it requires to class attributes on itself.

preload()

<class method>

preload(cls, onDemand=False)

Preload map media. This runs the class's onPreload function if need be to get it ready to run. Preloading can be fired for a soon-to-be-needed map to speed its creation. This is a classmethod since it is not run on map instances but rather on the class as a whole before instances are made


bs.Material

<top level class>

category: Game Flow Classes

A material can affect physical characteristics, generate sounds, or trigger callback functions when collisions occur.

Materials are applied to 'parts', which are groups of one or more rigid bodies created as part of a bs.Node. Nodes can have any number of parts, each with its own set of materials. Generally materials are specified as array attributes on the Node. The 'spaz' node, for example, has various attributes such as 'materials', 'rollerMaterials', and 'punchMaterials', which correspond to the various parts it creates.

Use bs.Material() to instantiate a blank material, and then use its addActions() method to define what the material does.

Methods:

addActions(), getName()

addActions()

addActions(actions, conditions=None) -> None

Add one or more actions to the material, optionally with conditions.

Conditions:

Conditions are provided as tuples which can be combined to form boolean logic. A single condition might look like ('conditionName', condArg), or a more complex nested one might look like (('someCondition', condArg), 'or', ('anotherCondition', cond2Arg)).

'and', 'or', and 'xor' are available to chain together 2 conditions, as seen above.

Available Conditions:

('theyHaveMaterial', material) - does the part we're hitting have a given bs.Material?

('theyDontHaveMaterial', material) - does the part we're hitting not have a given bs.Material?

('evalColliding') - is 'collide' true at this point in material evaluation? (see the modifyPartCollision action)

('evalNotColliding') - is 'collide' false at this point in material evaluation? (see the modifyPartCollision action)

('weAreYoungerThan', age) - is our part younger than 'age' (in milliseconds)?

('weAreOlderThan', age) - is our part older than 'age' (in milliseconds)?

('theyAreYoungerThan', age) - is the part we're hitting younger than 'age' (in milliseconds)?

('theyAreOlderThan', age) - is the part we're hitting older than 'age' (in milliseconds)?

('theyAreSameNodeAsUs') - does the part we're hitting belong to the same bs.Node as us?

('theyAreDifferentNodeThanUs') - does the part we're hitting belong to a different bs.Node than us?

Actions:

In a similar manner, actions are specified as tuples. Multiple actions can be specified by providing a tuple of tuples.

Available Actions:

('call', when, callable) - calls the provided callable; 'when' can be either 'atConnect' or 'atDisconnect'. 'atConnect' means to fire when the two parts first come in contact; 'atDisconnect' means to fire once they cease being in contact.

('message', who, when, messageObj) - sends a message object; 'who' can be either 'ourNode' or 'theirNode', 'when' can be 'atConnect' or 'atDisconnect', and messageObj is the message object to send. This has the same effect as calling the node's handleMessage() method.

('modifyPartCollision', attr, value) - changes some characteristic of the physical collision that will occur between our part and their part. This change will remain in effect as long as the two parts remain overlapping. This means if you have a part with a material that turns 'collide' off against parts younger than 100ms, and it touches another part that is 50ms old, it will continue to not collide with that part until they separate, even if the 100ms threshold is passed. Options for attr/value are: 'physical' (boolean value; whether a *physical* response will occur at all), 'friction' (float value; how friction-y the physical response will be), 'collide' (boolean value; whether *any* collision will occur at all, including non-physical stuff like callbacks), 'useNodeCollide' (boolean value; whether to honor modifyNodeCollision overrides for this collision), 'stiffness' (float value, how springy the physical response is), 'damping' (float value, how damped the physical response is), 'bounce' (float value; how bouncy the physical response is).

('modifyNodeCollision', attr, value) - similar to modifyPartCollision, but operates at a node-level. collision attributes set here will remain in effect as long as *anything* from our part's node and their part's node overlap. A key use of this functionality is to prevent new nodes from colliding with eachother if they appear overlapped; if modifyPartCollision is used, only the individual parts that were overlapping would avoid contact, but other parts could still contact leaving the two nodes 'tangled up'. Using modifyNodeCollision ensures that the nodes must completely separate before they can start colliding. Currently the only attr available here is 'collide' (a boolean value).

('sound', sound, volume) - plays a bs.Sound when a collision occurs, at a given volume, regardless of the collision speed/etc.

('impactSound', sound, targetImpulse, volume) - plays a sound when a collision occurs, based on the speed of impact. Provide a bs.Sound, a target-impulse, and a volume.

('skidSound', sound, targetImpulse, volume) - plays a sound during a collision when parts are 'scraping' against eachother. Provide a bs.Sound, a target-impulse, and a volume.

('rollSound', sound, targetImpulse, volume) - plays a sound during a collision when parts are 'rolling' against eachother. Provide a bs.Sound, a target-impulse, and a volume.

# example 1: create a material that lets us ignore
# collisions against any nodes we touch in the first
# 100 ms of our existence; handy for preventing us from
# exploding outward if we spawn on top of another object:
m = bs.Material()
m.addActions(conditions=(('weAreYoungerThan',100),
                         'or',('theyAreYoungerThan',100)),
             actions=('modifyNodeCollision','collide',False))
# example 2: send a DieMessage to anything we touch, but cause
# no physical response.  This should cause any bs.Actor to drop dead:
m = bs.Material()
m.addActions(actions=(('modifyPartCollision','physical',False),
                      ('message','theirNode','atConnect',bs.DieMessage())))
# example 3: play some sounds when we're contacting the ground:
m = bs.Material()
m.addActions(conditions=('theyHaveMaterial',bs.getSharedObject('footingMaterial')),
             actions=(('impactSound',bs.getSound('metalHit'),2,5),
                      ('skidSound',bs.getSound('metalSkid'),2,5)))

getName()

Returns the material name. Name is only for debugging.


bs.MelBot

inherits from: bs.SpazBot, bs.Spaz, bs.Actor

category: Bot Classes

A crazy bot who runs and throws sticky bombs.

Attributes Inherited:

node

Methods:

<all methods inherited from bs.SpazBot>


bs.MelBotStatic

inherits from: bs.MelBot, bs.SpazBot, bs.Spaz, bs.Actor

category: Bot Classes

A crazy bot who throws sticky-bombs but generally stays in one place.

Attributes Inherited:

node

Methods:

<all methods inherited from bs.MelBot>


bs.Model

<top level class>

category: Media Classes

A reference to a model. Models are used for drawing. Use bs.getModel() to instantiate one.


bs.NinjaBot

inherits from: bs.SpazBot, bs.Spaz, bs.Actor

category: Bot Classes

A speedy attacking melee bot.

Attributes Inherited:

node

Methods:

<all methods inherited from bs.SpazBot>


bs.NinjaBotPro

inherits from: bs.NinjaBot, bs.SpazBot, bs.Spaz, bs.Actor

category: Bot Classes

A more aggressive red bs.NinjaBot.

Attributes Inherited:

node

Methods:

<all methods inherited from bs.NinjaBot>


bs.NinjaBotProShielded

inherits from: bs.NinjaBotPro, bs.NinjaBot, bs.SpazBot, bs.Spaz, bs.Actor

category: Bot Classes

A more aggressive red bs.NinjaBot who starts with shields.

Attributes Inherited:

node

Methods:

<all methods inherited from bs.NinjaBotPro>


bs.Node

<top level class>

category: Game Flow Classes

Nodes are the basic low-level building-block of a BombSquad game. At its core, a game is nothing more than a scene-graph of nodes with attributes getting set or interconnected over time.

A bs.Node instance should be thought of as a weak-reference to a game node; *not* the node itself.

This means a node's lifecycle is completely independent of how many bs.Node python references to it exist. To explicitly add a new node to the game, use bs.newNode(), and to explicitly delete one, use bs.Node.delete(). bs.Node.exists() can be used to determine if a bs.Node still points to a live node in the game. You can use bs.Node(None) to instantiate a NULL Node reference (sometimes used as attr values/etc).

Methods:

addDeathAction(), connectAttr(), delete(), exists(), getDelegate(), getName(), getNodeType(), handleMessage()

addDeathAction()

addDeathAction(action) -> None

Add a callable object to be called upon this node's death. Note that these actions are run just after the node dies, not before.

connectAttr()

connectAttr(srcAttr,dstNode,dstAttr) -> None

Connect one of this node's attributes to an attribute on another node. This will immediately set the target attribute's value to that of the source attribute, and will continue to do so once per step as long as the two nodes exist. The connection can be severed by setting the target attribute to any value or connecting another node attribute to it.

# example: create a locator and attach a light to it
light = bs.newNode('light')
loc = bs.newNode('locator',attrs={'position':(0,10,0)})
loc.connectAttr('position',light,'position')

delete()

delete(ignoreMissing=True) -> None

Delete the node. Ignores already-deleted nodes unless ignoreMissing is False, in which case an Exception is thrown.

exists()

Returns whether the node still exists. Most functionality will fail on a nonexistant node, so it's never a bad idea to check this.

getDelegate()

Returns the node's current delegate, which is the python object designated to handle the node's messages.

getName()

Return the name assigned to a node; used mainly for debugging

getNodeType()

Return the type of node referenced by this object as a string. (Note this is different from the Python type which is always bs.Node)

handleMessage()

handleMessage(...) -> None

General message handling; can be passed any message object.

All standard message objects are forwarded along to the bs.Node's delegate for handling (generally the bs.Actor that made the node).

bs.Nodes are unique, however, in that they can be passed a second form of message; 'node-messages'. These consist of a string type-name as a first argument along with the args specific to that type name as additional arguments. Node-messages communicate directly with the low-level node layer and are delivered simultaneously on all game clients, acting as an alternative to setting node attributes.


bs.NodeActor

inherits from: bs.Actor

category: Game Flow Classes

A simple bs.Actor which wraps around a single bs.Node and kills the node when told to die. This allows you to take advantage of standard actor behavior such as dying when no longer referenced, so you can do things like kill off a bunch of nodes simply by clearing a python list, etc.

Attributes:

node

The wrapped node.

Methods Inherited:

autoRetain(), exists(), getActivity(), isAlive(), isFinalized(), onFinalize()

Methods Defined or Overridden:

<constructor>, handleMessage()

<constructor>

bs.NodeActor(self, node)

Instantiate with a given bs.Node.

handleMessage()

handleMessage(self, m)

General message handling; can be passed any message object.


bs.OnScreenCountdown

inherits from: bs.Actor

category: Game Flow Classes

A Handy On-Screen Timer; useful for time-based games that count down to zero.

Methods Inherited:

autoRetain(), exists(), getActivity(), handleMessage(), isAlive(), isFinalized()

Methods Defined or Overridden:

<constructor>, onFinalize(), start()

<constructor>

bs.OnScreenCountdown(self, duration, endCall=None)

Duration is provided in seconds

onFinalize()

onFinalize(self)

onFinalize is called for each remaining bs.Actor when its bs.Activity is shutting down. Actors can use this opportunity to clear callbacks or other references which have the potential of keeping the bs.Activity alive inadvertantly.

Once an actor has been finalized (see bs.Actor.isFinalized()) it should no longer perform any game-object manipulation (creating, modifying, or deleting nodes, media, timers, etc.) Attempts to do so will likely in errors.

start()

start(self)

Starts the timer.


bs.OnScreenTimer

inherits from: bs.Actor

category: Game Flow Classes

A Handy On-Screen Timer. Useful for time-based games where time increases.

Methods Inherited:

autoRetain(), exists(), getActivity(), isAlive(), isFinalized(), onFinalize()

Methods Defined or Overridden:

<constructor>, getStartTime(), handleMessage(), hasStarted(), start(), stop()

<constructor>

bs.OnScreenTimer(self)

Instantiates an actor in the current bs.Activity.

getStartTime()

getStartTime(self)

Returns the game-time when start() was called

handleMessage()

handleMessage(self, m)

General message handling; can be passed any message object.

hasStarted()

hasStarted(self)

(no docs)

start()

start(self)

Starts the timer.

stop()

stop(self, endTime=None)

Ends the timer. If 'endTime' is not None, it is used when calculating the final display time; otherwise the current time is used


bs.OutOfBoundsMessage

<top level class>

category: Message Classes

Tells an object that it is out of bounds.


bs.PickedUpMessage

<top level class>

category: Message Classes

Tells an object that it has been picked up by something.

Attributes:

node

The bs.Node doing the picking up.

Methods:

<constructor>

bs.PickedUpMessage(self, node)

Instantiate with a given bs.Node.


bs.PickUpMessage

<top level class>

category: Message Classes

Tells an object that it has picked something up.

Attributes:

node

The bs.Node that is getting picked up.

Methods:

<constructor>

bs.PickUpMessage(self, node)

Instantiate with a given bs.Node.


bs.PirateBot

inherits from: bs.SpazBot, bs.Spaz, bs.Actor

category: Bot Classes

A bot who runs and explodes in 5 seconds.

Attributes Inherited:

node

Methods:

<all methods inherited from bs.SpazBot>


bs.PirateBotNoTimeLimit

inherits from: bs.PirateBot, bs.SpazBot, bs.Spaz, bs.Actor

category: Bot Classes

A bot who runs but does not explode on his own.

Attributes Inherited:

node

Methods:

<all methods inherited from bs.PirateBot>


bs.PirateBotShielded

inherits from: bs.PirateBot, bs.SpazBot, bs.Spaz, bs.Actor

category: Bot Classes

A bs.PirateBot who starts with shields.

Attributes Inherited:

node

Methods:

<all methods inherited from bs.PirateBot>


bs.Player

<top level class>

category: Game Flow Classes

A reference to a player in the game. These are created and managed internally and provided to your Session/Activity instances. You can use bs.Player(None) to instantiate an empty Player reference (sometimes used as attr values/etc). Be aware that, like bs.Nodes, bs.Player objects are 'weak' references under-the-hood; a player can leave the game at. any point. For this reason, you should make judicious use of the bs.Player.exists() method to ensure that a Player is still present if retaining references to one.

Attributes:

actor, character, color, gameData, highlight, sessionData

actor

The current bs.Actor associated with this player.

character

The character this player has selected in their profile. (string)

color

The base color for this player. In team games this will match the bs.Team's color.

gameData

A dict for use by the current bs.Activity for storing data associated with this player. This gets cleared for each new bs.Activity.

highlight

A secondary color for this player. This is used for minor highlights and accents to allow a player to stand apart from his teammates who may all share the same team (primary) color.

sessionData

A dict for use by the current bs.Session for storing data associated with this player. This persists for the duration of the session.

Methods:

assignInputCall(), exists(), getIcon(), getID(), getInputDevice(), getName(), getTeam(), isAlive(), removeFromGame(), resetInput(), setActor(), setName()

assignInputCall()

assignInputCall(type(s),call) -> None

Set the python callable to be run for one or more types of input. Valid type values are: 'jumpPress', 'jumpRelease', 'punchPress', 'punchRelease','bombPress', 'bombRelease', 'pickUpPress', 'pickUpRelease', 'upDown','leftRight','upPress', 'upRelease','downPress', 'downRelease', 'leftPress','leftRelease','rightPress', 'rightRelease', 'run', 'flyPress', 'flyRelease', 'startPress', 'startRelease'

exists()

exists() -> bool

Returns whether the player still exists. Most functionality will fail on a nonexistant player.

getIcon()

getIcon() -> dict

Returns the character's icon (images, colors, etc contained in a dict)

getID()

getID() -> int

Returns the unique numeric ID for this player.

getInputDevice()

getInputDevice() -> bs.InputDevice

Returns the player's input device. It may return None in cases such as remote players.

getName()

getName(long=False,icon=True) -> string

Returns the player's name. If icon is True, the long version of the name may include an icon.

getTeam()

getTeam() -> bs.Team

Returns the player's team.

isAlive()

isAlive() -> bool

Returns True if the player has a bs.Actor assigned and its isAlive() method return True. False is returned otherwise.

removeFromGame()

removeFromGame() -> None

Removes the player from the game.

resetInput()

resetInput() -> None

Clears out the player's assigned input actions.

setActor()

setActor(actor) -> None

Set the player's associated bs.Actor.

setName()

setName(name) -> None

Set the player's name to the provided string. A number will automatically be appended if the name is not unique from other players.


bs.PlayerScoredMessage

<top level class>

category: Message Classes

Informs a bs.Activity that a player scored.

Attributes:

score

The score value.

Methods:

<constructor>

bs.PlayerScoredMessage(self, score)

Instantiate with the given values


bs.PlayerSpaz

inherits from: bs.Spaz, bs.Actor

category: Game Flow Classes

A bs.Spaz subclass meant to be controlled by a bs.Player.

When a PlayerSpaz dies, it delivers a bs.PlayerSpazDeathMessage to the current bs.Activity. (unless the death was the result of the player leaving the game, in which case no message is sent)

When a PlayerSpaz is hurt, it delivers a bs.PlayerSpazHurtMessage to the current bs.Activity.

Attributes Inherited:

node

Methods Inherited:

addDroppedBombCallback(), autoRetain(), curse(), curseExplode(), dropBomb(), equipBoxingGloves(), equipShields(), exists(), getActivity(), getDeathPoints(), getFactory(), isAlive(), isFinalized(), onBombPress(), onBombRelease(), onFinalize(), onFlyPress(), onFlyRelease(), onJumpPress(), onJumpRelease(), onMove(), onMoveLeftRight(), onMoveUpDown(), onPickUpPress(), onPickUpRelease(), onPunchPress(), onPunchRelease(), onPunched(), onRun(), setBombCount(), setLandMineCount(), setScoreText(), shatter()

Methods Defined or Overridden:

<constructor>, connectControlsToPlayer(), disconnectControlsFromPlayer(), getPlayer(), handleMessage()

<constructor>

bs.PlayerSpaz(self, color=(1, 1, 1), highlight=(0.5, 0.5, 0.5), character='Spaz', player=None, powerupsExpire=True)

Create a spaz for the provided bs.Player. Note: this does not wire up any controls; you must call connectControlsToPlayer() to do so.

connectControlsToPlayer()

connectControlsToPlayer(self, enableJump=True, enablePunch=True, enablePickUp=True, enableBomb=True, enableRun=True, enableFly=True)

Wire this spaz up to the provided bs.Player. Full control of the character is given by default but can be selectively limited by passing False to specific arguments.

disconnectControlsFromPlayer()

disconnectControlsFromPlayer(self)

Completely sever any previously connected bs.Player from control of this spaz.

getPlayer()

getPlayer(self)

Return the bs.Player associated with this spaz. Note that while a valid player object will always be returned, there is no guarantee that the player is still in the game. Call bs.Player.exists() on the return value before doing anything with it.

handleMessage()

handleMessage(self, m)

General message handling; can be passed any message object.


bs.PlayerSpazDeathMessage

<top level class>

category: Message Classes

A bs.PlayerSpaz has died.

Attributes:

how, killed, killerPlayer, spaz

how

The particular type of death.

killed

If True, the spaz was killed; If False, they left the game or the round ended.

killerPlayer

The bs.Player that did the killing, or None.

spaz

The bs.PlayerSpaz that died.

Methods:

<constructor>

bs.PlayerSpazDeathMessage(self, spaz, wasKilled, killerPlayer, how)

Instantiate a message with the given values.


bs.PlayerSpazHurtMessage

<top level class>

category: Message Classes

A bs.PlayerSpaz was hurt.

Attributes:

spaz

The bs.PlayerSpaz that was hurt

Methods:

<constructor>

bs.PlayerSpazHurtMessage(self, spaz)

Instantiate with the given bs.Spaz value.


bs.PopupText

inherits from: bs.Actor

category: Game Flow Classes

A bit of text that pops up above a position to denote something special.

Methods Inherited:

autoRetain(), exists(), getActivity(), isAlive(), isFinalized(), onFinalize()

Methods Defined or Overridden:

<constructor>, handleMessage()

<constructor>

bs.PopupText(self, text, position=(0, 0, 0), color=(1, 1, 1, 1), randomOffset=0.5, offset=(0, 0, 0), scale=1.0)

Instantiate with given values.

randomOffset is the amount of random offset from the provided position that will be applied. This can help multiple achievements from overlapping too much.

handleMessage()

handleMessage(self, m)

General message handling; can be passed any message object.


bs.Powerup

inherits from: bs.Actor

category: Game Flow Classes

A powerup box. This will deliver a bs.PowerupMessage to anything that touches it which has the bs.PowerupFactory.powerupAcceptMaterial applied.

Attributes:

node, powerupType

node

The 'prop' bs.Node representing this box.

powerupType

The string powerup type. This can be 'tripleBombs', 'punch', 'iceBombs', 'impactBombs', 'landMines', 'stickyBombs', 'shield', 'health', or 'curse'.

Methods Inherited:

autoRetain(), exists(), getActivity(), isAlive(), isFinalized(), onFinalize()

Methods Defined or Overridden:

<constructor>, getFactory(), handleMessage()

<constructor>

bs.Powerup(self, position=(0, 1, 0), powerupType='tripleBombs', expire=True)

Create a powerup-box of the requested type at the requested position.

see bs.Powerup.powerupType for valid type strings.

getFactory()

<class method>

getFactory(cls)

Returns a shared bs.PowerupFactory object, creating it if necessary.

handleMessage()

handleMessage(self, m)

General message handling; can be passed any message object.


bs.PowerupAcceptMessage

<top level class>

category: Message Classes

Inform a bs.Powerup that it was accepted. This is generally sent in response to a bs.PowerupMessage to inform the box (or whoever granted it) that it can go away.


bs.PowerupFactory

<top level class>

category: Game Flow Classes

Wraps up media and other resources used by bs.Powerups. A single instance of this is shared between all powerups and can be retrieved via bs.Powerup.getFactory().

Attributes:

healthPowerupSound, model, modelSimple, powerdownSound, powerupAcceptMaterial, powerupMaterial, powerupSound, texBox, texCurse, texHealth, texIceBombs, texImpactBombs, texLandMines, texPunch, texShield, texStickyBombs

healthPowerupSound

bs.Sound played when a health powerup is accepted.

model

The bs.Model of the powerup box.

modelSimple

A simpler bs.Model of the powerup box, for use in shadows, etc.

powerdownSound

bs.Sound that can be used when powerups wear off.

powerupAcceptMaterial

Powerups will send a bs.PowerupMessage to anything they touch that has this bs.Material applied.

powerupMaterial

bs.Material applied to powerup boxes.

powerupSound

bs.Sound played when a powerup is accepted.

texBox

Triple-bomb powerup bs.Texture.

texCurse

Curse powerup bs.Texture.

texHealth

Health powerup bs.Texture.

texIceBombs

Ice bomb powerup bs.Texture.

texImpactBombs

Impact-bomb powerup bs.Texture.

texLandMines

Land-mine powerup bs.Texture.

texPunch

Punch powerup bs.Texture.

texShield

Shield powerup bs.Texture.

texStickyBombs

Sticky bomb powerup bs.Texture.

Methods:

<constructor>, getRandomPowerupType()

<constructor>

bs.PowerupFactory(self)

Instantiate a PowerupFactory. You shouldn't need to do this; call bs.Powerup.getFactory() to get a shared instance.

getRandomPowerupType()

getRandomPowerupType(self, forceType=None, excludeTypes=[])

Returns a random powerup type (string). See bs.Powerup.powerupType for available type values.

There are certain non-random aspects to this; a 'curse' powerup, for instance, is always followed by a 'health' powerup (to keep things interesting). Passing 'forceType' forces a given returned type while still properly interacting with the non-random aspects of the system (ie: forcing a 'curse' powerup will result in the next powerup being health).


bs.PowerupMessage

<top level class>

category: Message Classes

Tell something to get a powerup. This message is normally recieved by touching a bs.Powerup box.

Attributes:

powerupType, sourceNode

powerupType

The type of powerup to be granted (a string). See bs.Powerup.powerupType for available type values.

sourceNode

The node the powerup game from, or an empty bs.Node ref otherwise. If a powerup is accepted, a bs.PowerupAcceptMessage should be sent back to the sourceNode to inform it of the fact. This will generally cause the powerup box to make a sound and disappear or whatnot.

Methods:

<constructor>

bs.PowerupMessage(self, powerupType, sourceNode=<bs.Node object>)

Instantiate with given values. See bs.Powerup.powerupType for available type values.


bs.RespawnIcon

<top level class>

category: Game Flow Classes

An icon with a countdown that appears alongside the screen; used to indicate that a bs.Player is waiting to respawn.

Methods:

<constructor>

bs.RespawnIcon(self, player, respawnTime)

Instantiate with a given bs.Player and respawnTime (in milliseconds)


bs.ScoreBoard

<top level class>

category: Game Flow Classes

A display for player or team scores during the game.

Methods:

<constructor>, setTeamValue()

<constructor>

bs.ScoreBoard(self, label=None, scoreSplit=0.7)

Instantiate a score-board. Label can be something like 'points' and will show up on boards if provided.

setTeamValue()

setTeamValue(self, team, score, maxScore=None, countdown=False, flash=True, showValue=True)

Update the score-board display for the given team.


bs.Session

<top level class>

category: Game Flow Classes

A Session is the highest level control structure in the game. Types of sessions are bs.FreeForAllSession, bs.TeamsSession, and bs.CoopSession.

A Session is responsible for wrangling and transitioning between various bs.Activity instances such as mini-games and score-screens, and for maintaining state between them (players, teams, score tallies, etc).

Attributes:

players, teams

players

All bs.Players in the Session. Most things should use the player list in bs.Activity; not this.

teams

All the bs.Teams in the Session. Most things should use the team list in bs.Activity; not this.

Methods:

<constructor>, end(), getActivity(), getCustomMenuEntries(), handleMessage(), onActivityEnd(), onPlayerLeave(), onPlayerRequest(), onTeamJoin(), onTeamLeave(), setActivity()

<constructor>

bs.Session(self, teamNames=['Good Guys'], teamColors=[(0.6, 0.2, 1.0)], useTeamColors=True, minPlayers=1, maxPlayers=8, allowMidActivityJoins=True)

Instantiate a session with the provided info about teams and max players.

end()

end(self)

Initiates an end to the session and a return to the main menu. Note that this happens asynchronously, allowing the session and its activities to shut down gracefully.

getActivity()

getActivity(self)

Returns the current foreground activity for this session.

getCustomMenuEntries()

getCustomMenuEntries(self)

Subclasses can override this to provide custom menu entries. The returned value should be a list of dicts, each containing a 'label' and 'call' entry, with 'label' being the text for the entry (translated) and 'call' being the callable to trigger if the entry is pressed.

handleMessage()

handleMessage(self, m)

General message handling; can be passed any message object.

onActivityEnd()

onActivityEnd(self, activity, results)

Called when the current bs.Activity has ended. The session should look at the results and start another activity.

onPlayerLeave()

onPlayerLeave(self, player)

Called when a previously-accepted bs.Player leaves the session.

onPlayerRequest()

onPlayerRequest(self, player)

Called when a new bs.Player wants to join; should return True or False to accept/reject.

onTeamJoin()

onTeamJoin(self, team)

Called when a new bs.Team joins the session.

onTeamLeave()

onTeamLeave(self, team)

Called when a bs.Team is leaving the session.

setActivity()

setActivity(self, activity)

Assign a new current bs.Activity for the session. Note that this will not change the current context to the new Activity's. Code must be run in the new activity's methods (onTransitionIn, etc) to get it. (so you can't do session.setActivity(foo) and then bs.newNode() to add a node to foo)


bs.ShouldShatterMessage

<top level class>

category: Message Classes

Tells an object that it should shatter.


bs.Sound

<top level class>

category: Media Classes

A reference to a sound. Use bs.getSound() to instantiate one.


bs.Spaz

inherits from: bs.Actor

category: Game Flow Classes

Base class for various Spazzes. A Spaz is the standard little humanoid character in the game. It can be controlled by a player or by AI, and can have various different appearances. The name 'Spaz' is not to be confused with the 'Spaz' character in the game, which is just one of the skins available for instances of this class.

Attributes:

node

The 'spaz' bs.Node.

Methods Inherited:

autoRetain(), getActivity(), isFinalized()

Methods Defined or Overridden:

<constructor>, addDroppedBombCallback(), curse(), curseExplode(), dropBomb(), equipBoxingGloves(), equipShields(), exists(), getDeathPoints(), getFactory(), handleMessage(), isAlive(), onBombPress(), onBombRelease(), onFinalize(), onFlyPress(), onFlyRelease(), onJumpPress(), onJumpRelease(), onMove(), onMoveLeftRight(), onMoveUpDown(), onPickUpPress(), onPickUpRelease(), onPunched(), onPunchPress(), onPunchRelease(), onRun(), setBombCount(), setLandMineCount(), setScoreText(), shatter()

<constructor>

bs.Spaz(self, color=(1, 1, 1), highlight=(0.5, 0.5, 0.5), character='Spaz', sourcePlayer=None, startInvincible=True, canAcceptPowerups=True, powerupsExpire=False)

Create a new spaz with the requested color, character, etc.

addDroppedBombCallback()

addDroppedBombCallback(self, call)

Add a call to be run whenever this Spaz drops a bomb. The spaz and the newly-dropped bomb are passed as arguments.

curse()

curse(self)

Give this poor spaz a curse; he will explode in 5 seconds.

curseExplode()

curseExplode(self, sourcePlayer=None)

Explode the poor spaz as happens when a curse timer runs out.

dropBomb()

dropBomb(self)

Tell the spaz to drop one of his bombs, and returns the resulting bomb object. If the spaz has no bombs or is otherwise unable to drop a bomb, returns None.

equipBoxingGloves()

equipBoxingGloves(self)

Give this spaz some boxing gloves.

equipShields()

equipShields(self)

Give this spaz a nice energy shield.

exists()

exists(self)

Returns True if the actor is still visible or present in some way. Note that a dying character should still return True here as long as their corpse exists; this is about presence, not being 'alive'.

If this returns False, it is assumed the actor can be completely deleted without affecting the game; this call is often used when 'pruning' lists of actors.

The default implementation of this method returns 'node.exists()' if the actor has a 'node' attr; otherwise True.

getDeathPoints()

getDeathPoints(self, how)

Get the points awarded for killing this spaz

getFactory()

<class method>

getFactory(cls)

Returns the shared bs.SpazFactory object, creating it if necessary.

handleMessage()

handleMessage(self, m)

General message handling; can be passed any message object.

isAlive()

isAlive(self)

Method override; returns whether ol' spaz is still kickin'.

onBombPress()

onBombPress(self)

Called to 'press bomb' on this spaz; used for player or AI connections.

onBombRelease()

onBombRelease(self)

Called to 'release bomb' on this spaz; used for player or AI connections.

onFinalize()

onFinalize(self)

onFinalize is called for each remaining bs.Actor when its bs.Activity is shutting down. Actors can use this opportunity to clear callbacks or other references which have the potential of keeping the bs.Activity alive inadvertantly.

Once an actor has been finalized (see bs.Actor.isFinalized()) it should no longer perform any game-object manipulation (creating, modifying, or deleting nodes, media, timers, etc.) Attempts to do so will likely in errors.

onFlyPress()

onFlyPress(self)

Called to 'press fly' on this spaz; used for player or AI connections.

onFlyRelease()

onFlyRelease(self)

Called to 'release fly' on this spaz; used for player or AI connections.

onJumpPress()

onJumpPress(self)

Called to 'press jump' on this spaz; used by player or AI connections.

onJumpRelease()

onJumpRelease(self)

Called to 'release jump' on this spaz; used by player or AI connections.

onMove()

onMove(self, x, y)

Called to set the joystick amount for this spaz; used for player or AI connections.

onMoveLeftRight()

onMoveLeftRight(self, value)

Called to set the left/right joystick amount on this spaz; used for player or AI connections. value will be between -32768 to 32767 WARNING: deprecated; use onMove instead.

onMoveUpDown()

onMoveUpDown(self, value)

Called to set the up/down joystick amount on this spaz; used for player or AI connections. value will be between -32768 to 32767 WARNING: deprecated; use onMove instead.

onPickUpPress()

onPickUpPress(self)

Called to 'press pick-up' on this spaz; used by player or AI connections.

onPickUpRelease()

onPickUpRelease(self)

Called to 'release pick-up' on this spaz; used by player or AI connections.

onPunched()

onPunched(self, damage)

Called when this spaz gets punched.

onPunchPress()

onPunchPress(self)

Called to 'press punch' on this spaz; used for player or AI connections.

onPunchRelease()

onPunchRelease(self)

Called to 'release punch' on this spaz; used for player or AI connections.

onRun()

onRun(self, value)

Called to 'press run' on this spaz; used for player or AI connections.

setBombCount()

setBombCount(self, count)

(no docs)

setLandMineCount()

setLandMineCount(self, count)

Set the number of land-mines this spaz is carrying.

setScoreText()

setScoreText(self, t, color=(1, 1, 0.4), flash=False)

Utility func to show a message momentarily over our spaz that follows him around; Handy for score updates and things.

shatter()

shatter(self, extreme=False)

Break the poor spaz into little bits.


bs.SpazBot

inherits from: bs.Spaz, bs.Actor

category: Bot Classes

A really dumb AI version of bs.Spaz. Add these to a bs.BotSet to use them.

Note: currently the AI has no real ability to navigate obstacles and so should only be used on wide-open maps.

When a SpazBot is killed, it delivers a bs.SpazBotDeathMessage to the current activity.

When a SpazBot is punched, it delivers a bs.SpazBotPunchedMessage to the current activity.

Attributes Inherited:

node

Methods Inherited:

addDroppedBombCallback(), autoRetain(), curse(), curseExplode(), dropBomb(), equipBoxingGloves(), equipShields(), exists(), getActivity(), getDeathPoints(), getFactory(), isAlive(), isFinalized(), onBombPress(), onBombRelease(), onFlyPress(), onFlyRelease(), onJumpPress(), onJumpRelease(), onMove(), onMoveLeftRight(), onMoveUpDown(), onPickUpPress(), onPickUpRelease(), onPunchPress(), onPunchRelease(), onRun(), setBombCount(), setLandMineCount(), setScoreText(), shatter()

Methods Defined or Overridden:

<constructor>, handleMessage(), onFinalize(), onPunched()

<constructor>

bs.SpazBot(self)

Instantiate a spaz-bot.

handleMessage()

handleMessage(self, m)

General message handling; can be passed any message object.

onFinalize()

onFinalize(self)

onFinalize is called for each remaining bs.Actor when its bs.Activity is shutting down. Actors can use this opportunity to clear callbacks or other references which have the potential of keeping the bs.Activity alive inadvertantly.

Once an actor has been finalized (see bs.Actor.isFinalized()) it should no longer perform any game-object manipulation (creating, modifying, or deleting nodes, media, timers, etc.) Attempts to do so will likely in errors.

onPunched()

onPunched(self, damage)

Method override; sends a bs.SpazBotPunchedMessage to the current activity.


bs.SpazBotDeathMessage

<top level class>

category: Message Classes

A bs.SpazBot has died.

Attributes:

badGuy, how, killerPlayer

badGuy

The bs.SpazBot that was killed.

how

The particular type of death.

killerPlayer

The bs.Player that killed it (or None).

Methods:

<constructor>

bs.SpazBotDeathMessage(self, badGuy, killerPlayer, how)

Instantiate with given values.


bs.SpazBotPunchedMessage

<top level class>

category: Message Classes

A bs.SpazBot got punched.

Attributes:

badGuy, damage

badGuy

The bs.SpazBot that got punched.

damage

How much damage was done to the bs.SpazBot.

Methods:

<constructor>

bs.SpazBotPunchedMessage(self, badGuy, damage)

Instantiate a message with the given values.


bs.SpazFactory

<top level class>

Category: Game Flow Classes

Wraps up media and other resources used by bs.Spaz instances. Generally one of these is created per bs.Activity and shared between all spaz instances. Use bs.Spaz.getFactory() to return the shared factory for the current activity.

Attributes:

blockSound, curseMaterial, impactSoundsHard, impactSoundsHarder, impactSoundsMedium, pickupMaterial, punchMaterial, punchSound, punchSoundsStrong, punchSoundStronger, rollerMaterial, shatterSound, singlePlayerDeathSound, spazMaterial, splatterSound, swishSound

blockSound

A bs.Sound for when an attack is blocked by invincibility.

curseMaterial

A bs.Material applied to a cursed bs.Spaz that triggers an explosion.

impactSoundsHard

A tuple of bs.Sounds for when a bs.Spaz hits something really hard.

impactSoundsHarder

A tuple of bs.Sounds for when a bs.Spaz hits something really really hard.

impactSoundsMedium

A tuple of bs.Sounds for when a bs.Spaz hits something kinda hard.

pickupMaterial

A bs.Material applied to the 'grabber' body of a bs.Spaz.

punchMaterial

A bs.Material applied to the 'fist' of a bs.Spaz.

punchSound

A standard punch bs.Sound.

punchSoundsStrong

A tuple of stronger sounding punch bs.Sounds.

punchSoundStronger

A really really strong sounding punch bs.Sound.

rollerMaterial

A bs.Material applied to the invisible roller ball body that a bs.Spaz uses for locomotion.

shatterSound

A bs.Sound for when a frozen bs.Spaz shatters.

singlePlayerDeathSound

The sound that plays for an 'importan' spaz death such as in co-op games.

spazMaterial

A bs.Material applied to all of parts of a bs.Spaz.

splatterSound

A bs.Sound for when a bs.Spaz blows up via curse.

swishSound

A punch swish bs.Sound.

Methods:

<constructor>

bs.SpazFactory(self)

Instantiate a factory object.


bs.StandMessage

<top level class>

category: Message Classes

Tells an object to position itself to be standing upright at the given position. Used when teleporting players to home base, etc.

Attributes:

angle, position

angle

The angle to face (in degrees)

position

Where to stand.

Methods:

<constructor>

bs.StandMessage(self, position=(0, 0, 0), angle=0)

Instantiate with a given position and angle.


bs.Team

<top level class>

category: Game Flow Classes

A team of one or more bs.Players. Note that a player *always* has a team; in some cases, such as free-for-all bs.Sessions, the teams consists of just one bs.Player each.

Attributes:

color, gameData, name, players, sessionData

color

The team's color.

gameData

A dict for use by the current bs.Activity for storing data associated with this team. This gets cleared for each new bs.Activity.

name

The team's name.

players

The list of bs.Players on the team.

sessionData

A dict for use by the current bs.Session for storing data associated with this team. Unlike gameData, this perists for the duration of the session.

Methods:

<constructor>, celebrate(), getID()

<constructor>

bs.Team(self, teamID=0, name='', color=(1, 1, 1))

Instantiate a team. In most cases teams are provided to you automatically by the bs.Session, so calling this shouldn't be necessary.

celebrate()

celebrate(self, duration=10000)

Tells all players on the team to celebrate

getID()

getID(self)

Returns the numeric team ID.


bs.TeamBaseSession

inherits from: bs.Session

category: Game Flow Classes

Common base class for bs.TeamsSession and bs.FreeForAllSession. Free-for-all-mode is essentially just teams-mode with each bs.Player having their own bs.Team, so there is much overlap in functionality.

Attributes Inherited:

players, teams

Methods Inherited:

end(), getActivity(), getCustomMenuEntries(), handleMessage(), onPlayerLeave(), onTeamLeave(), setActivity()

Methods Defined or Overridden:

<constructor>, announceGameResults(), getGameNumber(), getMaxPlayers(), getNextGameDescription(), onActivityEnd(), onPlayerRequest(), onTeamJoin()

<constructor>

bs.TeamBaseSession(self)

Sets up playlists and launches a bs.Activity to accept joiners.

announceGameResults()

announceGameResults(self, activity, results, delay, announceWinningTeam=True)

Show game results at the end of a game (before transitioning to a score screen). This will include a zoom-text of 'BLUE WINS' or whatnot, along with a possible audio announcement of the same.

getGameNumber()

getGameNumber(self)

Returns which game in the series is currently being played.

getMaxPlayers()

getMaxPlayers(self)

Return the max number of bs.Players allowed to join the game at once.

getNextGameDescription()

getNextGameDescription(self)

Returns a description of the next game on deck

onActivityEnd()

onActivityEnd(self, activity, results)

Called when the current bs.Activity has ended. The session should look at the results and start another activity.

onPlayerRequest()

onPlayerRequest(self, player)

Called when a new bs.Player wants to join; should return True or False to accept/reject.

onTeamJoin()

onTeamJoin(self, team)

Called when a new bs.Team joins the session.


bs.TeamGameActivity

inherits from: bs.GameActivity, bs.Activity

category: Game Flow Classes

Base class for teams and free-for-all mode games. (Free-for-all is essentially just a special case where every bs.Player has their own bs.Team)

Attributes Inherited:

players, settings, teams

Methods Inherited:

cameraFlash(), continueOrEndGame(), createConfigUI(), endGame(), filterGameName(), getConfigDescriptionLocalized(), getConfigDisplayString(), getDescription(), getDescriptionDisplayString(), getDisplayString(), getInstanceDescription(), getInstanceDisplayString(), getInstanceNameLocalized(), getInstanceScoreBoardDescription(), getInstanceScoreBoardDisplayString(), getInstanceScoreBoardNameLocalized(), getMap(), getName(), getResolvedScoreInfo(), getScoreInfo(), getSession(), getSettings(), getSupportedMaps(), getTeamDisplayString(), handleMessage(), hasBegun(), hasEnded(), hasTransitionedIn(), isFinalized(), isTransitioningOut(), isWaitingForContinue(), onContinue(), onFinalize(), onPlayerJoin(), onPlayerLeave(), onTeamJoin(), onTeamLeave(), onTransitionOut(), projectFlagStand(), respawnPlayer(), setupStandardPowerupDrops(), setupStandardTimeLimit(), showInfo(), showScoreBoardInfo(), showZoomMessage(), spawnPlayer(), spawnPlayerIfExists()

Methods Defined or Overridden:

<constructor>, end(), onBegin(), onTransitionIn(), spawnPlayerSpaz(), supportsSessionType()

<constructor>

bs.TeamGameActivity(self, settings={})

Creates an activity in the current bs.Session. The activity will not be actually run until bs.Session.setActivity() is called. 'settings' should be a dict of key/value pairs specific to the activity.

Activities should preload as much of their media/etc as possible in their constructor, but none of it should actually be used until they are transitioned in.

end()

end(self, results=None, announceWinningTeam=True, announceDelay=100, force=False)

Method override; announces the single winning team unless 'announceWinningTeam' is False. (useful for games where there is not a single most-important winner).

onBegin()

onBegin(self)

Called once the previous bs.Activity has finished transitioning out. At this point the activity's initial players and teams are filled in and it should begin its actual game logic.

onTransitionIn()

onTransitionIn(self, music=None)

Method override; optionally can be passed a 'music' string which is the suggested type of music to play during the game. Note that in some cases music may be overridden by the map or other factors, which is why you should pass it in here instead of simply playing it yourself.

spawnPlayerSpaz()

spawnPlayerSpaz(self, player, position=None, angle=None)

Method override; spawns and wires up a standard bs.PlayerSpaz for a bs.Player.

If position or angle is not supplied, a default will be chosen based on the bs.Player and their bs.Team.

supportsSessionType()

<class method>

supportsSessionType(cls, sessionType)

Class method override; returns True for bs.TeamsSessions and bs.FreeForAllSessions; False otherwise.


bs.TeamGameResults

<top level class>

category: Game Flow Classes

Results for a completed bs.TeamGameActivity. Upon completion, a game should fill one of these out and pass it to its bs.Activity.end() call.

Methods:

<constructor>, setTeamScore()

<constructor>

bs.TeamGameResults(self)

Instantiate a results instance.

setTeamScore()

setTeamScore(self, team, score)

Set the score for a given bs.Team. This can be a number or None. (see the noneIsWinner arg in the constructor)


bs.TeamsSession

inherits from: bs.TeamBaseSession, bs.Session

category: Game Flow Classes

bs.Session type for teams mode games.

Attributes Inherited:

players, teams

Methods Inherited:

announceGameResults(), end(), getActivity(), getCustomMenuEntries(), getGameNumber(), getMaxPlayers(), getNextGameDescription(), handleMessage(), onActivityEnd(), onPlayerLeave(), onPlayerRequest(), onTeamJoin(), onTeamLeave(), setActivity()

Methods Defined or Overridden:

<constructor>

bs.TeamsSession(self)

Sets up playlists and launches a bs.Activity to accept joiners.


bs.Texture

<top level class>

category: Media Classes

A reference to a texture. Use bs.getTexture() to instantiate one.


bs.ThawMessage

<top level class>

category: Message Classes

Tells an object that was frozen by a bs.FrozenMessage to thaw out.


bs.Timer

<top level class>

category: Game Flow Classes

Timers are used to run code at later points in time.

bs.Timer(time, call, repeat=False, timeType='game') -> new bs.Timer

time: length of time, specified in milliseconds, relative to when the timer gets created. (so 1000 means to go off 1 second in the future).

timeType: can be 'game', 'net', or 'real'. If 'game', the timer will be based on game-time, which can be paused or run at various speeds. (in epic-mode, game-time progresses slower). If 'real', the timer will be based on actual clock time. Real-timers are only allowed in the UI context (for use in interface elements, etc.). If 'net', the timer will be based on network-time; this is like real-time in that it passes at a constant rate regardless of game speed, but it can be affected by things like momentary network outages or the game slowing down due to heavy load.

Note that timers will only fire while the bs.Timer object remains alive, so make sure to retain a reference to it somewhere.


bs.TNTSpawner

<top level class>

category: Game Flow Classes

Regenerates TNT at a given point in space every now and then.

Methods:

<constructor>

bs.TNTSpawner(self, position, respawnTime=30000)

Instantiate with a given position and respawnTime (in milliseconds).


bs.ToughGuyBot

inherits from: bs.SpazBot, bs.Spaz, bs.Actor

category: Bot Classes

A manly bot who walks and punches things.

Attributes Inherited:

node

Methods:

<all methods inherited from bs.SpazBot>


bs.ToughGuyBotLame

inherits from: bs.ToughGuyBot, bs.SpazBot, bs.Spaz, bs.Actor

category: Bot Classes

A less aggressive yellow version of bs.ToughGuyBot.

Attributes Inherited:

node

Methods:

<all methods inherited from bs.ToughGuyBot>


bs.ToughGuyBotPro

inherits from: bs.ToughGuyBot, bs.SpazBot, bs.Spaz, bs.Actor

category: Bot Classes

A more aggressive red version of bs.ToughGuyBot.

Attributes Inherited:

node

Methods:

<all methods inherited from bs.ToughGuyBot>


bs.ToughGuyBotProShielded

inherits from: bs.ToughGuyBotPro, bs.ToughGuyBot, bs.SpazBot, bs.Spaz, bs.Actor

category: Bot Classes

A more aggressive version of bs.ToughGuyBot who starts with shields.

Attributes Inherited:

node

Methods:

<all methods inherited from bs.ToughGuyBotPro>


bs.Vector

<top level class>

category: General Utility Classes

A 3d Vector.

Methods:

<constructor>, angle(), cross(), length(), normal(), x(), y(), z()

<constructor>

bs.Vector(self, x=0.0, y=0.0, z=0.0)

Instantiate with given x, y, and z values.

angle()

angle(self, other)

Return the angle between this and another Vector.

cross()

cross(self, other)

Return the cross product between this and another Vector.

length()

length(self)

Return this Vector's length.

normal()

normal(self)

Return this Vector's normal.

x()

x(self)

Return this Vector's x component

y()

y(self)

Return this Vector's y component

z()

z(self)

Return this Vector's z component


bs.WeakCall

<top level class>

category: General Utility Classes

Wraps a callable and arguments into a single callable object. When passed a bound method as the callable, the instance portion of it is weak-referenced, meaning the underlying instance is free to die if all other references to it go away. Should this occur, calling the WeakCall is simply a no-op.

Think of this as a handy way to tell an object to do something at some point in the future if it happens to still exist.

# EXAMPLE A: this code will create a FooClass instance and call its
# bar() method 5 seconds later; it will be kept alive even though
# we overwrite its variable with None because the bound method
# we pass as a timer callback (foo.bar) strong-references it
foo = FooClass()
bs.gameTimer(length=1000,call=foo.bar)
foo = None
# EXAMPLE B: this code will *not* keep our object alive; it will die
# when we overwrite it with None and its bar() method won't get called
foo = FooClass()
bs.gameTimer(length=1000,call=bs.WeakCall(foo.bar))
foo = None

Note: additional args and keywords you provide to the WeakCall() constructor are stored as regular strong-references; you'll need to wrap them in weakrefs manually if desired.

Methods:

<constructor>

bs.WeakCall(self, *args, **keywds)

Instantiate a WeakCall; pass a callable as the first arg, followed by any number of arguments or keywords.

# example: wrap a method call with some positional and keyword args:
myCallable = bs.WeakCall(myObj.doStuff,argVal,namedArg=anotherVal)
# now we have a single callable to run that whole mess..
# this is the same as calling myObj.doStuff(argVal,namedArg=anotherVal)
# (provided myObj still exists; this will do nothing otherwise)
myCallable()

bs.Widget

<top level class>

category: User Interface Classes

Class representing all UI elements; buttons, windows, etc. Currently, functions such as bs.buttonWidget() must be used to instantiate or edit these (hopefully will be improved soon).

Methods:

activate(), delete(), exists(), getChildren(), getScreenSpaceCenter(), getSelectedChild(), getWidgetType()

activate()

activate() -> None

Activates a widget; the same as if it had been clicked.

delete()

delete(ignoreMissing=True) -> None

Delete the widget. Ignores already-deleted widgets if ignoreMissing is True; otherwise an Exception is thrown.

exists()

exists() -> bool

Returns whether the widget still exists. Most functionality will fail on a nonexistant widget.

getChildren()

getChildren() -> list of bs.Widgets

Returns any child widgets of this widget.

getScreenSpaceCenter()

getScreenSpaceCenter() -> tuple of 2 floats

Returns the coords of the widget center relative to the center of the screen. This can be useful for placing pop-up windows and other special cases.

getSelectedChild()

getSelectedChild() -> bs.Widget

Returns the selected child widget or None if nothing is selected.

getWidgetType()

getWidgetType() -> string

Return the internal type of the widget as a string. Note that this is different from the Python bs.Widget type, which is the same for all widgets.


bs.animate()

animate(node, attr, keys, loop=False, offset=0, driver='gameTime')

category: Game Flow Functions

Creates an animCurve node with the provided values and time as an input, connect it to the provided attribute, and set it to die with the target. Key values are provided as time:value dictionary pairs. Time values are relative to the current time. Returns the animCurve node.


bs.animateArray()

animateArray(node, attr, size, keys, loop=False, offset=0, driver='gameTime')

category: Game Flow Functions

Like bsUtils.animate(), but operates on array attributes.


bs.applySettings()

applySettings() -> None

category: General Utility Functions

Apply current graphics/sound/etc settings. These settings can be found in the dict returned by bs.getConfig() and are stored between runs. Modify them in place and then call this function to make changes take effect.

# example - toggle full-screen mode:
bs.getConfig()["fullscreen"] = not bs.getConfig()["fullscreen"]
bs.applySettings()

bs.buttonWidget()

buttonWidget(edit=0, parent=None, size=None, position=None, onActivateCall=None, label=None, color=None, texture=None, textScale=None, enableSound=True, modelTransparent=None, modelOpaque=None, transitionDelay=None, onSelectCall=None, extraTouchBorderScale=None, buttonType=None, touchOnly=None, showBufferTop=None, icon=None, iconScale=None, iconTint=None, iconColor=None, autoSelect=None, repeat=None, maskTexture=None, tintTexture=None, tintColor=None, textFlatness=None, textResScale=None, enabled=None) -> bs.Widget

category: User Interface Functions

Return a new button widget, or edit an existing one if 'edit' is not None. Arguments that are not set to None are applied to the widget.


bs.callInGameThread()

callInGameThread(call) -> None

category: General Utility Functions

For use in custom python threads; sends a callable back to the game thread to be exec'ed there. Calls are always run in the UI context. If you want to push a call onto the event loop from the game thread, use bs.pushCall() instead, which automatically saves/restores the current context for you.


bs.checkBoxWidget()

checkBoxWidget(parent=None, size=None, position=None, value=None, clickSelect=None, onActivateCall=None, onValueChangeCall=None, onSelectCall=None, isRadioButton=False, scale=None, maxWidth=None, autoSelect=None, color=None) -> bs.Widget

category: User Interface Functions

Return a new check-box widget, or edit an existing one if 'edit' is not None. Arguments that are not set to None are applied to the widget.


bs.columnWidget()

columnWidget(parent=None, size=None, position=None, singleDepth=None, printListExitInstructions=None, leftBorder=None) -> bs.Widget

category: User Interface Functions

Return a new column widget, or edit an existing one if 'edit' is not None. Arguments that are not set to None are applied to the widget.


bs.containerWidget()

containerWidget(parent=None, size=None, position=None, selectedChild=None, transition=None, cancelButton=None, startButton=None, rootSelectable=None, onActivateCall=None, claimsLeftRight=None, claimsTab=None, selectionLoops=None, selectionLoopToParent=None, scale=None, type=None, onOutsideClickCall=None, singleDepth=None, visibleChild=None, stackOffset=None, color=None, onCancelCall=None, printListExitInstructions=None, clickActivate=None, alwaysHighlight=None,selectable=None,scaleOriginStackOffset=None,toolbarVisiblity=None) -> bs.Widget

category: User Interface Functions

Return a new container widget, or edit an existing one if edit is not None. Arguments that are not set to None are applied to the widget.


bs.emitBGDynamics()

emitBGDynamics(position, velocity=None, count=None) -> None

category: Game Flow Functions

Emit particles, smoke, etc. into the BG Dynamics layer (the secondary dynamics thread that runs in the background and just looks pretty). Note that the actual amount emitted may vary depending on graphics settings or other factors.


bs.gameTimer()

gameTimer(length, call, repeat=False) -> None

category: Game Flow Functions

Add a game-time timer action. The provided call will be triggered when a set amount of game time has passed. If you'd like a timer that can be cancelled or modified after creation, see the bs.Timer class.

# example: kill node bob after 10 game seconds have passed:
bs.gameTimer(10000,call=bob.delete)

bs.getActivity()

getActivity(exceptionOnNone=True) -> bs.Activity

category: Game Flow Functions

Returns the current bs.Activity instance. Note that this is based on context; thus code run in a timer generated in Activity 'foo' will properly return 'foo' here, even if another Activity has since been created or is transitioning in. If there is no current Activity an Exception is raised, or if exceptionOnNone is False then None is returned instead.


bs.getCollideModel()

getCollideModel(name) -> bs.CollideModel

category: Media Functions

Return a collide-model the provided specifications. Collide-models are used in physics calculations for such things as terrain.

Note that this function returns immediately even if the media has yet to be loaded. To avoid hitches, instantiate your media objects in advance of when you will be using them, allowing time for them to load in the background if necessary.


bs.getCollisionInfo()

getCollisionInfo(name or tuple of names) -> Varies based on value requested

category: Game Flow Functions

Return a collision value or tuple of values such as location, depth, nodes involved, etc. Only call this in response to a collision-triggered callback or message


bs.getConfig()

getConfig()

category: General Utility Functions

Returns a dict representing BombSquad's persistent config data. Be very careful to only put simple values in here that can be passed to json dumps/loads. This data gets committed to disk/cloud/etc when you call bs.writeConfig().


bs.getEnvironment()

getEnvironment() -> dictionary

category: General Utility Functions

Returns a dict containing general info about the operating environment such as version, platform, etc. Members are as follows:

'version' - the game version string; something like '1.3.24'.

'buildNumber' - the specific integer build number of the game. (something like 13954)

'configFilePath' - where the game's config file is stored on disk.

'userScriptsDirectory' - where users can put python scripts to have them seen by the game

'systemScriptsDirectory' - where the game is reading its built-in python scripts from

'platform' - the platform built for; currently this can be 'mac','windows','linux', 'android', or 'ios'.

'subplatform' - specific sub-platform; for this 'android' platform this could be 'ouya', 'amazon', or 'google'.

'debugBuild' - whether the game was compiled in debug mode.

'testBuild' - whether the game is a test build (extra error testing but not as slow as debug-builds).

'interfaceType' - the general interface-type the game is running under; can be 'phone','tabletSmall','tabletLarge', or 'desktop'.

'locale' - the country/language code detected by the game (something like 'en_US').

'userAgentString' - a string containing various bits of info about the OS/device/etc.


bs.getGameTime()

getGameTime() -> int

category: Game Flow Functions

Returns the current game time in milliseconds.


bs.getLanguage()

getLanguage(returnNoneForDefault=False)

category: General Utility Functions

Returns the language currently being used by the game. This may or may not equal the language in use by the OS.


bs.getMapsSupportingPlayType()

getMapsSupportingPlayType(playType)

category: Media Functions

Return a list of bs.Map types supporting a specified play-type (a string). Maps supporting a given play-type must provide a particular set of features or lend themselves to a certain style of play.

Play Types:

'melee' - general fighting map - has 2+ 'spawn' pts, 1+ 'powerupSpawn' pts

'teamFlag' - for CTF, etc - has 2+ 'spawn' pts, 2+ 'flag' pts, and 1+ 'powerupSpawn' pts

'keepAway'- has 2+ 'spawn' pts, 1+ 'flagDefault' pts, and 1+ 'powerupSpawn' pts

'conquest' - has 2+ 'flag' pts, 2+ 'spawnByFlag' pts, and 1+ 'powerupSpawn' pts

'kingOfTheHill' - has 2+ 'spawn' pts, 1+ 'flagDefault' pts, and 1+ 'powerupSpawn' pts

'hockey' - has 2 'goal' pts, 2+ 'spawn' pts, 1+ 'flagDefault' pts, 1+ 'powerupSpawn' pts

'football' - has 2 'goal' pts, 2+ 'spawn' pts, 1+ 'flagDefault' pts, 1+ 'powerupSpawn' pts

'race' - has 2+ 'racePoint' pts


bs.getModel()

getModel(name) -> bs.Model

category: Media Functions

Return a model matching the provided specifications.

Note that this function returns immediately even if the media has yet to be loaded. To avoid hitches, instantiate your media objects in advance of when you will be using them, allowing time for them to load in the background if necessary.


bs.getNodes()

getNodes() -> list of bs.Node objects

category: Game Flow Functions

Return all existing nodes


bs.getNormalizedColor()

getNormalizedColor(color)

category: General Utility Functions

Scale a color so its largest value is 1; useful for coloring lights.


bs.getRealTime()

getRealTime() -> int

category: General Utility Functions

Returns the current real time in milliseconds. Note that this time value will not change while the app is backgrounded, or if the system time changes, so it should never jump by large amounts.


bs.getSafeColor()

getSafeColor(color,targetIntensity=0.6) -> tuple

category: General Utility Functions

Given a color tuple of length 3 or 4, returns a color that is safe to display as text. This will slightly brighten dark blacks, etc.


bs.getSession()

getSession(exceptionOnNone=True) -> bs.Session

category: Game Flow Functions

Returns the current bs.Session instance. Note that this is based on context; thus code being run in the UI context will return the UI context here even if a game Session also exists, etc. If there is no current Session, an Exception is raised, or if exceptionOnNone is False then None is returned instead.


bs.getSharedObject()

getSharedObject(name)

category: Game Flow Functions

Returns a predefined node/material/texture/etc for the current activity, creating it if necessary. Available Values:

'globals': returns the 'globals' bs.Node, containing various global controls & values.

'objectMaterial': a bs.Material that should be applied to any small, normal, physical objects such as bombs, boxes, players, etc. Other materials often check for the presence of this material as a prerequisite for performing certain actions (such as disabling collisions between initially-overlapping objects)

'playerMaterial': a bs.Material to be applied to player parts. Generally, materials related to the process of scoring when reaching a goal, etc will look for the presence of this material on things that hit them.

'pickupMaterial': a bs.Material; collision shapes used for picking things up will have this material applied. To prevent an object from being picked up, you can add a material that disables collisions against things containing this material.

'footingMaterial': anything that can be 'walked on' should have this bs.Material applied; generally just terrain and whatnot. A character will snap upright whenever touching something with this material so it should not be applied to props, etc.

'attackMaterial': a bs.Material applied to explosion shapes, punch shapes, etc. An object not wanting to recieve impulse/etc messages can disable collisions against this material.

'deathMaterial': a bs.Material that sends a bs.DieMessage() to anything that touches it; handy for terrain below a cliff, etc.

'regionMaterial': a bs.Material used for non-physical collision shapes (regions); collisions can generally be allowed with this material even when initially overlapping since it is not physical.

'railingMaterial': a bs.Material with a very low friction/stiffness/etc that can be applied to invisible 'railings' useful for gently keeping characters from falling off of cliffs.


bs.getSound()

getSound(name) -> bs.Sound

category: Media Functions

Return a sound matching the provided specifications.

Note that this function returns immediately even if the media has yet to be loaded. To avoid hitches, instantiate your media objects in advance of when you will be using them, allowing time for them to load in the background if necessary.


bs.getSpecialChar()

getSpecialChar(name) -> string

category: General Utility Functions

Given a name, returns a special character as a utf-8 string snippet which can be included in any BombSquad string.

Note that these utilize the private-use block of unicode characters (U+E000-U+F8FF) and are specific to BombSquad; exporting or rendering them elsewhere will be meaningless.

Available Values:

'downArrow', 'upArrow', 'leftArrow', 'rightArrow': directional arrows.

'topButton', 'leftButton', 'rightButton', 'bottomButton': generic gamepad button icons.

'ouyaButtonO', 'ouyaButtonU', 'ouyaButtonY', 'ouyaButtonA': ouya gamepad button icons.

'rewindButton', 'playPauseButton', 'fastForwardButton', 'dPadCenterButton': FireTV remote buttons.


bs.getTexture()

getTexture(name) -> bs.Texture

category: Media Functions

Return a texture matching the provided specifications.

Note that this function returns immediately even if the media has yet to be loaded. To avoid hitches, instantiate your media objects in advance of when you will be using them, allowing time for them to load in the background if necessary.


bs.getTimeString()

getTimeString(t, centi=True)

category: General Utility Functions

Given a value in milliseconds, returns a Lstr with (hours if > 0):minutes:seconds:centiseconds. WARNING: this Lstr value is somewhat large so don't use this to repeatedly update node values in a timer/etc. for that purpose you should use timeDisplay nodes and attribute connections.


bs.getUIBounds()

getUIBounds() -> tuple

category: General Utility Functions

Returns a tuple of 4 values: (xMin, xMax, yMin, yMax) representing the range of values that can be plugged into a root level bs.ContainerWidget's stackOffset value while guaranteeing that its center remains onscreen.


bs.hScrollWidget()

hScrollWidget(parent=None, size=None, position=None, captureArrows=False, onSelectCall=None, centerSmallContent=None, color=None, highlight=None borderOpacity=None) -> bs.Widget

category: User Interface Functions

Return the name of a new horizontal scroll widget, or edit an existing one if 'edit' is not None. Arguments that are not set to None are applied to the widget.


bs.imageWidget()

imageWidget(edit=None, parent=None, size=None, position=None, color=None, texture=None, model=None, modelTransparent=None, modelOpaque=None, hasAlphaChannel=True, tintTexture=None, tintColor=None, transitionDelay=None, drawController=None, tiltScale=None, maskTexture=None, radialAmount=None) -> bs.Widget

category: User Interface Functions

Return a new image widget, or edit an existing one if 'edit' is not None. Arguments that are not set to None are applied to the widget.


bs.isBrowserLikelyAvailable()

isBrowserLikelyAvailable()

category: General Utility Functions

Returns whether or not a web-browser is likely to be available on the current device. If this returns False you may want to avoid calling bs.showURL() with any lengthy addresses. (bs.showURL() will display an address as a string in a window if unable to bring up a browser, but that is only useful for simple URLs.)


bs.isPointInBox()

isPointInBox(p, b)

category: General Utility Functions

Return whether a given point is within a given box. For use with standard def boxes (position|rotate|scale).


bs.netTimer()

netTimer(length, call, repeat=False) -> None

category: Game Flow Functions

Add a net-time timer action. This timer will be triggered when a set amount of 'net' time has passed (in milliseconds). Like real-time, net-time advances at a constant pace regardless of game speed, but it can be affected by things such as network outages or the game slowing down due to heavy load. If you need a timer that can be cancelled or modified after creation, see the bs.Timer class.


bs.newActivity()

newActivity(activityType) -> bs.Activity

category: General Utility Functions

Instantiates a bs.Activity given a type object. Activities require special setup and thus cannot be directly instantiated; You must go through this function.


bs.newNode()

newNode(type, owner=None, attrs=None, name=None, delegate=None) -> bs.Node

category: Game Flow Functions

Add a node of the given type to the game. If a dict is provided for 'attributes', the node's attributes will be set based on them.

'name', if provided, will be stored with the node purely for debugging purposes. If no name is provide, an automatic one will be generated such as 'terrain@foo.py:30'.

If 'delegate' is provided, python messages sent to the node will go to that object's handleMessage() method. Note that the delegate is stored as a weak-ref, so the node itself will not keep the object alive.

if 'owner' is provided, the node will be automatically killed when that object dies. 'owner' can be another node or a bs.Actor


bs.openURL()

openURL(address, *args, **keywds)

category: General Utility Functions

Open the provided url in a web-browser, or display the URL string in a window if that isn't possible.


bs.playMusic()

playMusic(musicType, continuous=False)

category: Game Flow Functions

A high level function to set or stop the current music based on a string musicType.

Current valid values for 'musicType': 'Menu', 'Victory', 'CharSelect', 'RunAway', 'Onslaught', 'Keep Away', 'Race', 'Epic Race', 'Scores', 'GrandRomp', 'ToTheDeath', 'Chosen One', 'ForwardMarch', 'FlagCatcher', 'Survival', 'Epic', 'Sports', 'Hockey', 'Football', 'Flying', 'Scary', 'Marching'.

This function will handle loading and playing sound media as necessary, and also supports custom user soundtracks on specific platforms so the user can override particular game music with their own.

Pass None to stop music.

if 'continuous' is True the musicType passed is the same as what is already playing, the playing track will not be restarted.


bs.playSound()

playSound(sound, volume=1, position=None, hostOnly=False) -> None

category: Game Flow Functions

Play a bs.Sound a single time. If position is not provided, the sound will be at a constant volume everywhere. Position should be a float tuple of size 3.


bs.printError()

printError(*args, **keywds)

category: General Utility Functions

Prints all arguments provided along with various info about the current context.


bs.printErrorOnce()

printErrorOnce(*args, **keywds)

category: General Utility Functions

A convenience wrapper to bs.printError() that only prints each unique error one time (uniqueness is based only on the arguments passed)


bs.printException()

printException(*args, **keywds)

category: General Utility Functions

Prints all arguments provided along with various info about the current context and the outstanding exception.


bs.printNodes()

printNodes() -> None

category: Game Flow Functions

Print various info about existing nodes; useful for debugging.


bs.pushCall()

pushCall(call) -> None

category: General Utility Functions

Pushes a call onto the event loop to be run during the next cycle; can be handy for calls that are disllowed from within other callbacks; etc.


bs.quit()

quit(soft=False) -> None

category: General Utility Functions

Quit the game. On systems like android, 'soft' will kill the activity but keep the process running.


bs.realTimer()

realTimer(length, call) -> None

category: General Utility Functions

Add a single-shot real-time timer action. This timer will be triggered when a set amount of real time has passed (in milliseconds). If you need a repeating timer you must use the bs.Timer class instead. Note that real-timers can only be created in the UI context; use bs.netTimer() or bs.gameTimer() when in an activity context.

# example: only you can prevent bombsquad addiction!
bs.realTimer(3600000,call=bs.Call(_doShowMessageDialog,"You've been playing too long!")")

bs.reloadMedia()

category: General Utility Functions

reloadMedia() -> None

Reload all currently loaded game media; useful for development/debugging.


bs.rowWidget()

rowWidget(edit=None, parent=None, size=None, position=None, selectable=None) -> bs.Widget

category: User Interface Functions

Return a new row widget, or edit an existing one if 'edit' is not None. Arguments that are not set to None are applied to the widget.


bs.screenMessage()

screenMessage(message, color=(1,1,1), top=False, image=None, log=False) -> None

category: General Utility Functions

Print a message to the local client's screen, in a given color.

If 'top' is True, the message will go to the top message area. For 'top' messages, 'image' can be a texture to display alongside the message. If 'log' is True, the message will also be printed to the output log


bs.scrollWidget()

scrollWidget(parent=None, size=None, position=None, captureArrows=False, onSelectCall=None, centerSmallContent=None, color=None, highlight=None borderOpacity=None) -> bs.Widget

category: User Interface Functions

Return the name of a new scroll widget, or edit an existing one if 'edit' is not None. Arguments that are not set to None are applied to the widget.


bs.shakeCamera()

shakeCamera(intensity=1.0) -> None

category: Game Flow Functions

Shake the camera. Note that some cameras and/or platforms (such as VR) may not show camera-shake, so don't rely on this always being visible to the user.


bs.textWidget()

textWidget(edit=None, parent=None, size=None, position=None, vAlign=None, hAlign=None, editable=None, padding=None, onReturnPressCall=None, selectable=None, onActivateCall=None, query=None, maxChars=None, color=None, clickActivate=None, scale=None, alwaysHighlight=None, drawController=None, description=None, transitionDelay=None, flatness=None, enabled=None, forceInternalEditing=None, alwaysShowCarat=None, maxWidth=None, maxHeight=None, big=None, extraTouchBorderScale=None, resScale=None) -> bs.Widget

category: User Interface Functions

Return a new text widget, or edit an existing one if 'edit' is not None. Arguments that are not set to None are applied to the widget.


bs.uni()

uni(s)

category: General Utility Functions

Given a string or unicode object, returns a unicode version of it


bs.utf8()

utf8(s)

category: General Utility Functions

Given a string or unicode object, returns a string (encoding with utf-8 if need be)


bs.widget()

widget(edit=None, upWidget=None, downWidget=None, leftWidget=None, rightWidget=None, showBufferTop=None, showBufferBottom=None, showBufferLeft=None, showBufferRight=None, autoSelect=None) -> None

category: User Interface Functions

Edit common features of any existing widget. This can only be used to edit; not create.


bs.writeConfig()

writeConfig(force=False, storeRemote=True)

category: General Utility Functions Commit the config to disk/cloud/etc

2 Responses to BombSquad Python API

  1. Fabian says:

    Could you explain how your namespacing works please. In your meteor shower demo you use bsBomb.Bomb not bs.Bomb.

    I’m trying to find where bs.BotSet is actually located.

    • Eric says:

      I’m actually in the middle of a huge reorganization of the python layer for version 1.3.24, which is what these new docs are based on. I’m bringing everything that modders should need to touch under the ‘bs’ module. Email me at support@froemling.net if you’d like a test build of 1.3.24 to try out, (including an updated meteor-shower). I think the API should be pretty stable (and a fair amount simpler) once this reorganization is done..

Leave a Reply

Your email address will not be published. Required fields are marked *