BombSquadCore Python API

last updated on 2018-09-18 for BombSquad version 1.5.0 build 20000

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!

bs.Activity

<top level class>

category: Gameplay 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 on_begin() 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
on_begin() 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>, add_actor_weak_ref(), end(), getsession(), handlemessage(), has_begun(), has_ended(), has_transitioned_in(), is_expired(), is_transitioning_out(), on_begin(), on_expire(), on_player_join(), on_player_leave(), on_team_join(), on_team_leave(), on_transition_in(), on_transition_out(), retain_actor()

<constructor>

bs.Activity(settings)

Creates an activity in the current bs.Session.
The activity will not be actually run until bs.Session.set_activity()
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.

add_actor_weak_ref()

add_actor_weak_ref(self, actor)

Adds a weak-reference to a bs.Actor to the bs.Activity.
(called by the bs.Actor base class)

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, msg)

General message handling; can be passed any message object.

has_begun()

has_begun(self)

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

has_ended()

has_ended(self)

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

has_transitioned_in()

has_transitioned_in(self)

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

is_expired()

is_expired(self)

The activity is set as expired 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'.

is_transitioning_out()

is_transitioning_out(self)

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

on_begin()

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

on_expire()

on_expire(self)

Called when your activity is being expired.
If your activity has created anything explicitly that may be retaining
a strong reference to the activity and preventing it from dying, you
should clear that out 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.

on_player_join()

on_player_join(self, player)

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

on_player_leave()

on_player_leave(self, player)

Called when a player is leaving the activity.

on_team_join()

on_team_join(self, team)

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

on_team_leave()

on_team_leave(self, team)

Called when a bs.Team leaves the activity.

on_transition_in()

on_transition_in(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.on_begin() is called; they are still owned
by the previous activity up until this point.

on_transition_out()

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

retain_actor()

retain_actor(self, actor)

Adds a strong-reference to a bs.Actor to this Activity.
The referene will be lazily released once bs.Actor.exists()
returns False for the Actor. The bs.Actor.autoretain() method
is a convenient way to access this same functionality.

bs.Actor

<top level class>

category: Gameplay Classes

Actors are high level logical entities that act as controllers,
combining some number of bs.Nodes, bs.Textures, bs.Sounds, etc.
into one cohesive unit.

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 Actor in our game activity
self.flag = bs.Flag(position=(0, 10, 0))

# later, destroy the flag..
# (provided nothing else is holding a reference to it)
# we could also just assign a new flag to this value.
# either way, the old flag disappears.
self.flag = None

This is in contrast to the behavior of the more low level bs.Nodes,
which are always explicitly created and destroyed and don't care
how many Python references to them exist.

Note, however, that you can use the bs.Actor.autoretain() method
if you want an Actor to stick around until explicitly killed
regardless of references.

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
class 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 type with a 'handlemessage' method
# (though its not guaranteed to always have a meaningful effect)
# in this case the Actor instance will still be around, but its exists()
# and is_alive() methods will both return False
self.flag.handlemessage(bs.DieMessage())

Methods:

<constructor>, autoretain(), exists(), getactivity(), handlemessage(), is_alive(), is_expired(), on_expire()

<constructor>

bs.Actor()

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 lazily released once bs.Actor.exists() returns False for it
or when the Activity is expired. 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
meaningful way. Note that a dying character should still return
True here as long as their corpse exists; this is about presence,
not being 'alive' (see bs.Actor.is_alive() for that).

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, such as with bs.Actor.autoretain()

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

Note that the boolean operator for the Actor class calls this method,
so a simple "if myactor" test will conveniently do the right thing
even if myactor is set to None.

getactivity()

getactivity(self, doraise=True)

Return the bs.Activity this Actor is associated with.
If the Activity no longer exists, raises an Exception
or returns None depending on whether 'doraise' is set.

handlemessage()

handlemessage(self, msg)

General message handling; can be passed any message object.

is_alive()

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

is_expired()

is_expired(self)

Returns whether the Actor is expired.
(see bs.Actor.on_expire())

on_expire()

on_expire(self)

on_expire() 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 inadvertently (Activities can not exit cleanly while
any Python references to them remain.)

Once an actor is expired (see bs.Actor.is_expired()) it should no
longer perform any game-affecting operations (creating, modifying,
or deleting nodes, media, timers, etc.) Attempts to do so will
likely result in errors.

bs.AppConfig

inherits from: dict

category: General Utility Classes

A special dict that holds the game's persistant configuration values.
It also provides methods for fetching values with app-defined fallback
defaults, applying contained values to the game, and committing the
config to storage.

Call bs.appconfig() to get the single shared instance of this class.

AppConfig data is stored as json on disk on so make sure to only place
json-friendly values in it (dict, list, str, float, int, bool).
Be aware that tuples will be quietly converted to lists.

Methods Defined or Overridden:

apply(), apply_and_commit(), commit(), default_value(), resolve(), valid_keys()

apply()

apply(self)

Applies config values to the running app.

apply_and_commit()

apply_and_commit(self)

Convenience method to run apply() followed by commit()
(That way the commit() will not occur if apply() hits invalid data)

commit()

commit(self)

Commits the config to local storage. Note that this call is
asynchronous so the actual write to disk may not occur immediately.

default_value()

default_value(self, key)

Given a string key, returns the predefined default value for it.
This is the value that will be returned by bs.AppConfig.resolve() if
the key is not present in the config dict.

Raises an Exception for unrecognized key names. To get a list of valid
keys, use bs.AppConfig.valid_keys()

resolve()

resolve(self, key)

Given a string key, returns a config value. This will substitute
application defaults for values not present in the config dict,
filter some invalid values, etc. Note that these values (including
defaults) do not represent the state of the app; simply the state
of its config. Use bs.AppState to access actual live state.

Raises an Exception for unrecognized key names. To get a list of valid
keys, use bs.AppConfig.valid_keys().

valid_keys()

valid_keys(self)

Returns the list of key names can be used with bs.AppConfig.resolve(),
bs.AppConfig.default_value(), etc.

This set of keys does not vary across platforms and may include keys
that are obsolete or not relevant on the current running version.
(for instance VR related keys on non-VR platforms). This is to minimize
the amount of platform checking

Note that it is perfectly legal to store arbitrary named data in the
config, but in that case it is up to the user to test for the existence
of the key in the config dict, fall back to consistent defaults, etc.

bs.AppState

<top level class>

category: General Utility Classes

A class for accessing live app state.

Use bs.appstate() to access the single shared instance of this class.

Note that properties that are not documented here should be considered
'non-public' and subject to change without warning.

bs.Blast

inherits from: bs.Actor

category: Gameplay Classes

An explosion, as generated by a bs.Bomb or some other object.

Methods Inherited:

autoretain(), exists(), getactivity(), is_alive(), is_expired(), on_expire()

Methods Defined or Overridden:

<constructor>, handlemessage()

<constructor>

bs.Blast(position=(0, 1, 0), velocity=(0, 0, 0), blast_radius=2.0, blast_type='normal', source_player=None, hit_type='explosion', hit_subtype='normal')

Instantiate with given values.

handlemessage()

handlemessage(self, msg)

General message handling; can be passed any message object.

bs.Bomb

inherits from: bs.Actor

category: Gameplay Classes

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

Methods Inherited:

autoretain(), exists(), getactivity(), is_alive(), is_expired()

Methods Defined or Overridden:

<constructor>, add_explode_callback(), arm(), explode(), get_factory(), get_source_player(), handlemessage(), on_expire()

<constructor>

bs.Bomb(position=(0, 1, 0), velocity=(0, 0, 0), bomb_type='normal', blast_radius=2.0, source_player=None, owner=None)

Create a new Bomb.

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

add_explode_callback()

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

get_factory()

<class method>

get_factory()

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

get_source_player()

get_source_player(self)

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

handlemessage()

handlemessage(self, msg)

General message handling; can be passed any message object.

activate_sound, blast_material, bomb_material, bomb_model, debris_fall_sound, dink_sounds, explode_sounds, freeze_sound, fuse_sound, hiss_sound, ice_tex, impact_blast_material, impact_bomb_model, impact_lit_tex, impact_tex, land_mine_blast_material, land_mine_lit_tex, land_mine_model, land_mine_no_explode_material, land_mine_tex, normal_sound_material, regular_tex, roll_sound, sticky_bomb_model, sticky_impact_sound, sticky_material, sticky_tex, tnt_model, tnt_tex, warn_sound, wood_debris_fall_sound

activate_sound

A bs.Sound for an activating impact bomb.

blast_material

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

bomb_material

A bs.Material applied to all bombs.

bomb_model

The bs.Model of a standard or ice bomb.

debris_fall_sound

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

dink_sounds

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

explode_sounds

A tuple of bs.Sounds for explosions.

freeze_sound

A bs.Sound of an ice bomb freezing something.

fuse_sound

A bs.Sound of a burning fuse.

hiss_sound

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

ice_tex

The bs.Texture for ice bombs.

impact_blast_material

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

impact_bomb_model

The bs.Model of an impact-bomb.

impact_lit_tex

The bs.Texture for impact bombs with lights lit.

impact_tex

The bs.Texture for impact bombs.

land_mine_blast_material

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

land_mine_lit_tex

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

land_mine_model

The bs.Model of a land-mine.

land_mine_no_explode_material

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.

land_mine_tex

The bs.Texture for land-mines.

normal_sound_material

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

regular_tex

The bs.Texture for regular bombs.

roll_sound

bs.Sound for a rolling bomb.

sticky_bomb_model

The bs.Model of a sticky-bomb.

sticky_impact_sound

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

sticky_material

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

sticky_tex

The bs.Texture for sticky bombs.

tnt_model

The bs.Model of a tnt box.

tnt_tex

The bs.Texture for tnt boxes.

warn_sound

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

wood_debris_fall_sound

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

Methods:

<constructor>, random_explode_sound()

<constructor>

bs.BombFactory()

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

random_explode_sound()

random_explode_sound(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>, add_bot(), celebrate(), clear(), final_celebrate(), get_living_bots(), have_living_bots(), spawn_bot(), start_moving(), stop_moving()

<constructor>

bs.BotSet()

Create a bot-set.

add_bot()

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

final_celebrate()

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

get_living_bots()

get_living_bots(self)

Returns the living bots in the set.

have_living_bots()

have_living_bots(self)

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

spawn_bot()

spawn_bot(self, bot_type, pos, spawn_time=3000, on_spawn_call=None)

Spawn a bot from this set.

start_moving()

start_moving(self)

Starts processing bot AI updates and let them start doing their thing.

stop_moving()

stop_moving(self)

bs.Call(*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
mycall = bs.Call(myobj.dostuff, argval1, namedarg=argval2)

# now we have a single callable to run that whole mess
# this is the same as calling myobj.dostuff(argval1, namedarg=argval2)
mycall()

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>

Context(source)

category: General Utility Classes

A BombSquad Context. Many operations such as bs.newnode() or
bs.gettexture() 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 'source' argument
is passed, which can 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 instance:
Gives the context for the provided bs.Activity.
Most all code run during a game happens in an Activity's Context.

a bs.Session instance:
Gives the context for the provided bs.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'):
   tex1 = bs.gettexture('foo_tex_1')
   tex2 = bs.gettexture('foo_tex_2')

bs.ContextCall

<top level class>

ContextCall(call)

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 if the context
it belongs to shuts down.

Generally you should not need to use this directly; all standard
BombSquad callbacks involved with timers, materials, UI functions,
etc. handle this under-the-hood 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
runs some game code 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 (expired)
context.

You can also use bs.WeakCall for similar functionality, but
ContextCall has the added bonus that it will not run during context
shutdown, 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).
start_some_long_action(callback_when_done=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.
start_long_action(callback_when_done=bs.ContextCall(self.mycallback))

bs.CoopGameActivity

inherits from: bs.GameActivity, bs.Activity

category: Gameplay Classes

Base class for cooperative-mode games.

Attributes Inherited:

players, settings, teams

Methods Inherited:

add_actor_weak_ref(), camera_flash(), continue_or_end_game(), create_config_ui(), end(), end_game(), get_config_display_string(), get_description(), get_description_display_string(), get_display_string(), get_instance_description(), get_instance_display_string(), get_instance_scoreboard_description(), get_instance_scoreboard_display_string(), get_resolved_score_info(), get_score_info(), get_settings(), get_supported_maps(), get_team_display_string(), getmap(), getname(), getsession(), handlemessage(), has_begun(), has_ended(), has_transitioned_in(), is_expired(), is_transitioning_out(), is_waiting_for_continue(), on_continue(), on_expire(), on_player_join(), on_player_leave(), on_team_join(), on_team_leave(), on_transition_in(), on_transition_out(), project_flag_stand(), respawn_player(), retain_actor(), setup_standard_powerup_drops(), setup_standard_time_limit(), show_info(), show_scoreboard_info(), show_zoom_message(), spawn_player(), spawn_player_if_exists()

Methods Defined or Overridden:

<constructor>, celebrate(), fade_to_red(), get_score_type(), on_begin(), setup_low_life_warning_sound(), spawn_player_spaz(), supports_session_type()

<constructor>

bs.CoopGameActivity(settings)

Instantiates the Activity.

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.

fade_to_red()

fade_to_red(self)

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

get_score_type()

get_score_type(self)

Return the score unit this co-op game uses ('point', 'seconds', etc.)

on_begin()

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

setup_low_life_warning_sound()

setup_low_life_warning_sound(self)

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

spawn_player_spaz()

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

Spawn and wire up a standard player spaz

supports_session_type()

<class method>

supports_session_type(sessiontype)

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

bs.CoopSession

inherits from: bs.Session

category: Gameplay 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:

campaign, lobby, max_players, min_players, players, teams

Methods Inherited:

end(), getactivity(), handlemessage(), on_player_request(), on_team_join(), on_team_leave(), set_activity()

Methods Defined or Overridden:

<constructor>, get_current_game_instance(), get_custom_menu_entries(), on_activity_end(), on_player_leave(), restart()

<constructor>

bs.CoopSession()

Instantiate a co-op mode session.

get_current_game_instance()

get_current_game_instance(self)

Return the game instance currently being played in this co-op session

get_custom_menu_entries()

get_custom_menu_entries(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 and 'call' being the callable to trigger if the entry
is pressed.

on_activity_end()

on_activity_end(self, activity, results)

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

on_player_leave()

on_player_leave(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(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(node)

Instantiate with a given bs.Node.

bs.ExplodeyBot

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

category: Bot Classes

A bot who runs and explodes in 5 seconds.

Attributes Inherited:

node

Methods:

bs.ExplodeyBotNoTimeLimit

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

category: Bot Classes

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

Attributes Inherited:

node

Methods:

bs.ExplodeyBotShielded

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

category: Bot Classes

A bs.ExplodeyBot who starts with shields.

Attributes Inherited:

node

Methods:

bs.Flag

inherits from: bs.Actor

category: Gameplay 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(), is_alive(), is_expired(), on_expire()

Methods Defined or Overridden:

<constructor>, get_factory(), handlemessage(), set_score_text()

<constructor>

bs.Flag(position=(0, 1, 0), color=(1, 1, 1), materials=None, touchable=True, dropped_timeout=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 can be a list of extra bs.Materials to apply to the flag.

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

get_factory()

<class method>

get_factory()

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

handlemessage()

handlemessage(self, msg)

General message handling; can be passed any message object.

set_score_text()

set_score_text(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(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(flag, node)

Instantiate with given values.

bs.FlagFactory

<top level class>

category: Gameplay 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.get_factory().

Attributes:

flag_texture, flagmaterial, impact_sound, no_hit_material, skid_sound

flag_texture

The bs.Texture for flags.

flagmaterial

The bs.Material applied to all bs.Flags.

impact_sound

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

no_hit_material

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

skid_sound

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

Methods:

<constructor>

bs.FlagFactory()

Instantiate a FlagFactory.
You shouldn't need to do this; call bs.Flag.get_factory() 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(flag, node)

Instantiate with given values.

bs.FreeForAllSession

inherits from: bs.TeamBaseSession, bs.Session

category: Gameplay Classes

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

Attributes Inherited:

campaign, lobby, max_players, min_players, players, teams

Methods Inherited:

announce_game_results(), end(), get_custom_menu_entries(), get_ffa_series_length(), get_game_number(), get_max_players(), get_next_game_description(), get_series_length(), getactivity(), handlemessage(), on_activity_end(), on_player_leave(), on_player_request(), on_team_join(), on_team_leave(), set_activity()

Methods Defined or Overridden:

<constructor>

bs.FreeForAllSession()

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: Gameplay 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:

add_actor_weak_ref(), getsession(), has_begun(), has_ended(), has_transitioned_in(), is_expired(), is_transitioning_out(), on_expire(), on_team_join(), on_team_leave(), on_transition_out(), retain_actor()

Methods Defined or Overridden:

<constructor>, camera_flash(), continue_or_end_game(), create_config_ui(), end(), end_game(), get_config_display_string(), get_description(), get_description_display_string(), get_display_string(), get_instance_description(), get_instance_display_string(), get_instance_scoreboard_description(), get_instance_scoreboard_display_string(), get_resolved_score_info(), get_score_info(), get_settings(), get_supported_maps(), get_team_display_string(), getmap(), getname(), handlemessage(), is_waiting_for_continue(), on_begin(), on_continue(), on_player_join(), on_player_leave(), on_transition_in(), project_flag_stand(), respawn_player(), setup_standard_powerup_drops(), setup_standard_time_limit(), show_info(), show_scoreboard_info(), show_zoom_message(), spawn_player(), spawn_player_if_exists(), spawn_player_spaz(), supports_session_type()

<constructor>

bs.GameActivity(settings)

Instantiates the Activity.

camera_flash()

camera_flash(self, duration=999)

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

continue_or_end_game()

continue_or_end_game(self)

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

create_config_ui()

<class method>

create_config_ui(sessiontype, config, completion_call)

Launch an in-game UI to configure settings for this game type for the
given bs.Session type.

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

'completion_call' 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.get_settings() and bs.GameActivity.get_supported_maps()
they can just rely on the default implementation here which calls those
methods.

end()

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

end_game()

end_game(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.setup_standard_time_limit()) will work with the game.

get_config_display_string()

<class method>

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

get_description()

<class method>

get_description(sessiontype)

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

get_description_display_string()

<class method>

get_description_display_string(sessiontype)

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

get_display_string()

<class method>

get_display_string(settings=None)

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

get_instance_description()

get_instance_description(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
get_instance_scoreboard_description().

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.

get_instance_display_string()

get_instance_display_string(self)

Returns a name for this particular game instance.

get_instance_scoreboard_description()

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

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

get_instance_scoreboard_display_string()

get_instance_scoreboard_display_string(self)

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

get_resolved_score_info()

<class method>

get_resolved_score_info()

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

get_score_info()

<class method>

get_score_info()

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):

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

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

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

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

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

get_settings()

<class method>

get_settings(sessiontype)

Called by the default bs.GameActivity.create_config_ui()
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)

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

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

'choices': A list of name/value pairs the user can choose from by name.

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

# example get_settings() implementation for a capture-the-flag game:
@classmethod
def get_settings(cls,sessiontype):
    return [("Score to Win", {
                'default': 3,
                'min_value': 1
            }),
            ("Flag Touch Return Time", {
                'default': 0,
                'min_value': 0,
                'increment': 1
            }),
            ("Flag Idle Return Time", {
                'default': 30,
                'min_value': 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
            })]

get_supported_maps()

<class method>

get_supported_maps(sessiontype)

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

get_team_display_string()

<class method>

get_team_display_string(name)

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

getmap()

getmap(self)

Returns the bs.Map in use for this activity.

getname()

<class method>

getname()

Return a name for this game type in English.

handlemessage()

handlemessage(self, msg)

General message handling; can be passed any message object.

is_waiting_for_continue()

is_waiting_for_continue(self)

Returns whether or not this activity is currently waiting for the
player to continue (or timeout)

on_begin()

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

on_continue()

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

on_player_join()

on_player_join(self, player)

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

on_player_leave()

on_player_leave(self, player)

Called when a player is leaving the activity.

on_transition_in()

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

project_flag_stand()

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

respawn_player()

respawn_player(self, player, respawn_time=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 spawn_player() will
be called if the Player still exists.
An explicit 'respawn_time' can optionally be provided
(in milliseconds).

setup_standard_powerup_drops()

setup_standard_powerup_drops(self, enable_tnt=True)

Create standard powerup drops for the current map.

setup_standard_time_limit()

setup_standard_time_limit(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, end_game() will be called.

show_info()

show_info(self)

show the game description

show_scoreboard_info()

show_scoreboard_info(self)

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

show_zoom_message()

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

spawn_player()

spawn_player(self, player)

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

spawn_player_if_exists()

spawn_player_if_exists(self, player)

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

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

spawn_player_spaz()

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

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

supports_session_type()

<class method>

supports_session_type(sessiontype)

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

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(srcnode=None, pos=Vector(0,0,0), velocity=Vector(0,0,0), magnitude=1.0, velocity_magnitude=0.0, radius=1.0, source_player=None, kick_back=1.0, flat_damage=None, hit_type='generic', force_direction=None, hit_subtype='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 take damage.

Attributes:

intensity

The intensity of the impact.

Methods:

<constructor>

bs.ImpactDamageMessage(intensity)

Instantiate a messages with a given intensity value.

bs.InputDevice

<top level class>

category: Gameplay 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(), get_account_name(), get_axis_name(), get_button_name(), get_client_id(), get_id(), get_instance_number(), get_unique_identifier(), getname(), getplayer(), is_connected_to_remote_player(), is_controller_app(), is_remote_client(), remove_remote_player_from_game()

exists()

exists() -> bool

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

Note that you can also use the boolean operator for this same
functionality, so a statement such as "if myinput" will do
the right thing both for InputDevice objects and values of None.

get_account_name()

get_account_name(full) -> str

Returns the account name associated with this device. (used to get account names for remote players)

get_axis_name()

get_axis_name() -> str

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

get_button_name()

get_button_name(button_id) -> str

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

get_client_id()

get_client_id() -> int

Returns the numeric client-id this device is associated with.
This is only meaningful for remote client inputs; for all local devices
this will return -1

get_id()

get_id() -> int

Returns the unique numeric ID for this input device.

get_instance_number()

get_instance_number() -> int

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

get_unique_identifier()

get_unique_identifier() -> str

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)

getname()

getname() -> str

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.

is_connected_to_remote_player()

is_connected_to_remote_player() -> bool

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

is_controller_app()

is_controller_app() -> bool

Returns whether or not this input-device represents the BSRemote controller app.

is_remote_client()

is_remote_client() -> bool

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

remove_remote_player_from_game()

remove_remote_player_from_game() -> None

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

bs.Level

<top level class>

category: Gameplay Classes

Represents a distinct named co-op game/map/settings combination.

Methods:

<constructor>, get_complete(), get_config_dict(), get_display_string(), get_high_scores(), get_index(), get_preview_tex(), get_preview_tex_name(), get_rating(), get_score_version_string(), get_settings(), getcampaign(), getgametype(), getname(), set_complete(), set_high_scores(), submit_rating()

<constructor>

bs.Level(name, gametype, settings, preview_tex_name, displayname=None)

Initializes a Level object with the provided values.

get_complete()

get_complete(self)

Returns whether this Level has been completed.

get_config_dict()

get_config_dict(self)

Return a dict within the main bs config dict containing
state for this Level

get_display_string()

get_display_string(self)

Returns a bs.Lstr representing the name of this Level

get_high_scores()

get_high_scores(self)

Returns the current high scores for this Level.

get_index()

get_index(self)

Returns the order this Level is at in its Campaign.
Raises an Exception if not a Campaign Level

get_preview_tex()

get_preview_tex(self)

Loads/returns the preview Texture for this Level.

get_preview_tex_name()

get_preview_tex_name(self)

Returns the preview texture name for this Level.

get_rating()

get_rating(self)

Returns the current rating for this Level.

get_score_version_string()

get_score_version_string(self)

Returns the score version string for this Level.
If a Level's gameplay changes significantly, its version string
can be changed to separate its high score lists/etc. from the old.

get_settings()

get_settings(self)

Returns the settings for this Level.

getcampaign()

getcampaign(self)

Returns the campaign this Level is associated with, or None otherwise.

getgametype()

getgametype(self)

Returns the game-type for this Level.

getname()

getname(self)

Returns the unique name for this Level.

set_complete()

set_complete(self, val)

Set whether or not this level is complete.

set_high_scores()

set_high_scores(self, high_scores)

Sets high scores for this level.

submit_rating()

submit_rating(self, rating)

Submits a rating for this Level, replacing the old if it is higher.

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 bs_language_*.py files
in the game or the translations pages at bombsquadgame.com/translate.

# EXAMPLE 1: specify a string from a resource path
mynode.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.
mynode.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.
mynode.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 res_a but replace ${NAME} with the value of the resource at res_b
mytextnode.text = bs.Lstr(resource='res_a',
                          subs=[('${NAME}', bs.Lstr(resource='res_b'))])

Methods:

<constructor>, evaluate(), is_flat_value()

<constructor>

bs.Lstr(*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_resource' 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).
'fallback_value' can be a literal string that will be used if neither
the resource nor the fallback resource is found ('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.

is_flat_value()

is_flat_value(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: Gameplay Classes

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

Methods Inherited:

autoretain(), exists(), getactivity(), is_alive(), is_expired(), on_expire()

Methods Defined or Overridden:

<constructor>, get_def_bound_box(), get_def_point(), get_def_points(), get_ffa_start_position(), get_flag_position(), get_music_type(), get_preview_texture_name(), get_start_position(), getname(), handlemessage(), is_point_near_edge(), on_preload(), preload()

<constructor>

bs.Map(vr_overlay_offset=None)

Instantiate a map.

get_def_bound_box()

get_def_bound_box(self, name)

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

get_def_point()

get_def_point(self, name)

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

get_def_points()

get_def_points(self, name)

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

get_ffa_start_position()

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

get_flag_position()

get_flag_position(self, team_index)

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)

get_music_type()

<class method>

get_music_type()

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

get_preview_texture_name()

<class method>

preload()

Preload map media.
This runs the class's on_preload() method as needed to prep it to run.
Preloading should generally be done in a bs.Activity's __init__ method.
Note that this is a classmethod since it is not operate on map
instances but rather on the class itself before instances are made

bs.Material

<top level class>

Material(name=None)

category: Gameplay 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',
'roller_materials', and 'punch_materials', which correspond to the
various parts it creates.

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

Methods:

add_actions(), getname()

add_actions()

add_actions(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 ('condition_name', cond_arg),
or a more complex nested one might look like (('some_condition',
cond_arg), 'or', ('another_condition', cond2_arg)).

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

Available Conditions:

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

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

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

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

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

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

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

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

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

('they_are_different_node_than_us') - 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 'at_connect' or 'at_disconnect'. 'at_connect' means to fire
when the two parts first come in contact; 'at_disconnect' means to
fire once they cease being in contact.

('message', who, when, message_obj) - sends a message object; 'who' can
be either 'our_node' or 'their_node', 'when' can be 'at_connect' or
'at_disconnect', and message_obj is the message object to send.
This has the same effect as calling the node's handlemessage()
method.

('modify_part_collision', 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), 'use_node_collide'
(boolean value; whether to honor modify_node_collision 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).

('modify_node_collision', attr, value) - similar to
modify_part_collision, 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 modify_part_collision 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
modify_node_collision 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.

('impact_sound', 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.

('skid_sound', 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.

('roll_sound', 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.add_actions(conditions=(('we_are_younger_than', 100),
                         'or',('they_are_younger_than', 100)),
             actions=('modify_node_collision', '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.add_actions(actions=(('modify_part_collision', 'physical', False),
                      ('message', 'their_node', 'at_connect', bs.DieMessage())))

# example 3: play some sounds when we're contacting the ground:
m = bs.Material()
m.add_actions(conditions=('they_have_material',
                          bs.stdobj('footing_material')),
              actions=(('impact_sound', bs.getsound('metalHit'), 2, 5),
                       ('skid_sound', bs.getsound('metalSkid'), 2, 5)))

getname()

getname() -> str

Returns the material name. Name is only for debugging.

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

<top level class>

category: Gameplay Classes

Nodes are the basic low-level building-block of a
BombSquad game. At its core, a game is nothing more
than a scene 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 an invalid
Node reference (sometimes used as attr values/etc).

Methods:

add_death_action(), connectattr(), delete(), exists(), getdelegate(), getname(), getnodetype(), handlemessage()

add_death_action()

add_death_action(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(ignore_missing=True) -> None

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

exists()

exists() -> bool

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

Note that you can also use the boolean operator for this same
functionality, so a statement such as "if mynode" will do
the right thing both for Node objects and values of None.

getdelegate()

getdelegate() -> object

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

getname()

getname() -> str

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

getnodetype()

getnodetype() -> str

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(*args) -> 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: Gameplay 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(), is_alive(), is_expired(), on_expire()

Methods Defined or Overridden:

<constructor>, handlemessage()

<constructor>

bs.NodeActor(node)

Instantiate with a given bs.Node.

handlemessage()

handlemessage(self, msg)

General message handling; can be passed any message object.

bs.OnScreenCountdown

inherits from: bs.Actor

category: Gameplay Classes

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

Methods Inherited:

autoretain(), exists(), getactivity(), handlemessage(), is_alive(), is_expired()

Methods Defined or Overridden:

<constructor>, on_expire(), start()

<constructor>

bs.OnScreenCountdown(duration, endcall=None)

Duration is provided in seconds

on_expire()

on_expire(self)

start()

start(self)

Starts the timer.

bs.OnScreenTimer

inherits from: bs.Actor

category: Gameplay Classes

A handy on-screen timer.
Useful for time-based games where time increases.

Methods Inherited:

autoretain(), exists(), getactivity(), is_alive(), is_expired(), on_expire()

Methods Defined or Overridden:

<constructor>, getstarttime(), handlemessage(), hasstarted(), start(), stop()

<constructor>

bs.OnScreenTimer()

Instantiates an Actor in the current bs.Activity.

getstarttime()

getstarttime(self)

Returns the game-time when start() was called

handlemessage()

handlemessage(self, msg)

General message handling; can be passed any message object.

hasstarted()

hasstarted(self)

Returns whether this timer has started yet.

start()

start(self)

Starts the timer.

stop()

stop(self, endtime=None)

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.

node

The current bs.Node associated with this Player.

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:

assign_input_call(), exists(), get_account_id(), get_icon(), get_id(), get_input_device(), get_team(), getname(), is_alive(), remove_from_game(), reset_input(), set_actor(), set_name()

assign_input_call()

assign_input_call(type, 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.

Note that you can also use the boolean operator for this same
functionality, so a statement such as "if player" will do
the right thing both for Player objects and values of None.

get_account_id()

get_account_id() -> str

Return the Account ID this player is signed in under, if
there is one and it can be determined with relative certainty.
Returns None otherwise. Note that this may require an active
internet connection (especially for network-connected players)
and may return None for a short while after a player initially
joins (while verification occurs).

get_icon()

get_icon() -> dict

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

get_id()

get_id() -> int

Returns the unique numeric ID for this player.

get_input_device()

get_input_device() -> bs.InputDevice

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

get_team()

get_team() -> bs.Team

Returns the player's team.

getname()

getname(full=False, icon=True) -> str

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

is_alive()

is_alive() -> bool

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

remove_from_game()

remove_from_game() -> None

Removes the player from the game.

reset_input()

reset_input() -> None

Clears out the player's assigned input actions.

set_actor()

set_actor(actor) -> None

Set the player's associated bs.Actor.

set_name()

set_name(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(score)

Instantiate with the given values

bs.PlayerSpaz

inherits from: bs.Spaz, bs.Actor

category: Gameplay 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:

add_dropped_bomb_callback(), autoretain(), curse(), curse_explode(), drop_bomb(), equip_boxing_gloves(), equip_shields(), exists(), get_death_points(), get_factory(), getactivity(), is_alive(), is_expired(), on_bomb_press(), on_bomb_release(), on_expire(), on_fly_press(), on_fly_release(), on_jump_press(), on_jump_release(), on_move(), on_move_left_right(), on_move_up_down(), on_pickup_press(), on_pickup_release(), on_punch_press(), on_punch_release(), on_punched(), on_run(), set_bomb_count(), set_land_mine_count(), set_score_text(), shatter(), shield_decay()

Methods Defined or Overridden:

<constructor>, connect_controls_to_player(), disconnect_controls_from_player(), getplayer(), handlemessage()

<constructor>

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

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

connect_controls_to_player()

connect_controls_to_player(self, enable_jump=True, enable_punch=True, enable_pickup=True, enable_bomb=True, enable_run=True, enable_fly=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.

disconnect_controls_from_player()

disconnect_controls_from_player(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, msg)

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(spaz, was_killed, 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(spaz)

Instantiate with the given bs.Spaz value.

bs.PopupText

inherits from: bs.Actor

category: Gameplay Classes

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

Methods Inherited:

autoretain(), exists(), getactivity(), is_alive(), is_expired(), on_expire()

Methods Defined or Overridden:

<constructor>, handlemessage()

<constructor>

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

Instantiate with given values.

random_offset 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, msg)

General message handling; can be passed any message object.

bs.Powerup

inherits from: bs.Actor

category: Gameplay Classes

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

Attributes:

node, poweruptype

node

The 'prop' bs.Node representing this box.

poweruptype

The string powerup type. This can be 'triple_bombs', 'punch',
'ice_bombs', 'impact_bombs', 'land_mines', 'sticky_bombs', 'shield',
'health', or 'curse'.

Methods Inherited:

autoretain(), exists(), getactivity(), is_alive(), is_expired(), on_expire()

Methods Defined or Overridden:

<constructor>, get_factory(), handlemessage()

<constructor>

bs.Powerup(position=(0, 1, 0), poweruptype='triple_bombs', expire=True)

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

see bs.Powerup.poweruptype for valid type strings.

get_factory()

<class method>

get_factory()

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

handlemessage()

handlemessage(self, msg)

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: Gameplay 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.get_factory().

Attributes:

health_powerup_sound, model, model_simple, powerdown_sound, powerup_accept_material, powerup_material, powerup_sound, tex_bomb, tex_curse, tex_health, tex_ice_bombs, tex_impact_bombs, tex_land_mines, tex_punch, tex_shield, tex_sticky_bombs

health_powerup_sound

bs.Sound played when a health powerup is accepted.

model

The bs.Model of the powerup box.

model_simple

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

powerdown_sound

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

powerup_accept_material

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

powerup_material

bs.Material applied to powerup boxes.

powerup_sound

bs.Sound played when a powerup is accepted.

tex_bomb

Triple-bomb powerup bs.Texture.

tex_curse

Curse powerup bs.Texture.

tex_health

Health powerup bs.Texture.

tex_ice_bombs

Ice bomb powerup bs.Texture.

tex_impact_bombs

Impact-bomb powerup bs.Texture.

tex_land_mines

Land-mine powerup bs.Texture.

tex_punch

Punch powerup bs.Texture.

tex_shield

Shield powerup bs.Texture.

tex_sticky_bombs

Sticky bomb powerup bs.Texture.

Methods:

<constructor>, get_random_powerup_type()

<constructor>

bs.PowerupFactory()

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

get_random_powerup_type()

get_random_powerup_type(self, forcetype=None, excludetypes=None)

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, source_node

poweruptype

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

source_node

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 source_node 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(poweruptype, source_node=<bs.Node object at 0x10fc16e10>)

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

bs.RespawnIcon

<top level class>

category: Gameplay Classes

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

Attributes:

visible

Is this icon still visible?

Methods:

<constructor>

bs.RespawnIcon(player, respawn_time)

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

bs.Scoreboard

<top level class>

category: Gameplay Classes

A display for player or team scores during the game.

Methods:

<constructor>, remove_team(), set_team_value()

<constructor>

bs.Scoreboard(label=None, score_split=0.7)

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

remove_team()

remove_team(self, team_id)

remove the team with the given id from the scoreboard

set_team_value()

set_team_value(self, team, score, max_score=None, countdown=False, flash=True, show_value=True)

Update the score-board display for the given team.

bs.Session

<top level class>

category: Gameplay 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:

campaign, lobby, max_players, min_players, players, teams

campaign

The bs.Campaign instance this Session represents, or None if
there is no associated Campaign.

lobby

The bs.Lobby instance where new bs.Players go to select a
Profile/Team/etc. before being added to games.
Be aware this value may be None if a Session does not allow
any such selection.

max_players

The maximum number of Players allowed in the Session.

min_players

The minimun number of Players who must be present for the Session
to proceed past the initial joining screen.

players

All bs.Players in the Session. Most things should use the player
list in bs.Activity; not this. Some players, such as those who have
not yet selected a character, will only appear on this list.

teams

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

Methods:

<constructor>, end(), get_custom_menu_entries(), getactivity(), handlemessage(), on_activity_end(), on_player_leave(), on_player_request(), on_team_join(), on_team_leave(), set_activity()

<constructor>

bs.Session(team_names=None, team_colors=None, use_team_colors=True, min_players=1, max_players=8, allow_mid_activity_joins=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.

get_custom_menu_entries()

get_custom_menu_entries(self)

getactivity()

getactivity(self)

Returns the current foreground activity for this session.

handlemessage()

handlemessage(self, msg)

General message handling; can be passed any message object.

on_activity_end()

on_activity_end(self, activity, results)

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

on_player_leave()

on_player_leave(self, player)

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

on_player_request()

on_player_request(self, player)

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

on_team_join()

on_team_join(self, team)

Called when a new bs.Team joins the session.

on_team_leave()

on_team_leave(self, team)

Called when a bs.Team is leaving the session.

set_activity()

set_activity(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
(on_transition_in, etc) to get it. (so you can't do
session.set_activity(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: Gameplay 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(), is_expired()

Methods Defined or Overridden:

<constructor>, add_dropped_bomb_callback(), curse(), curse_explode(), drop_bomb(), equip_boxing_gloves(), equip_shields(), exists(), get_death_points(), get_factory(), handlemessage(), is_alive(), on_bomb_press(), on_bomb_release(), on_expire(), on_fly_press(), on_fly_release(), on_jump_press(), on_jump_release(), on_move(), on_move_left_right(), on_move_up_down(), on_pickup_press(), on_pickup_release(), on_punch_press(), on_punch_release(), on_punched(), on_run(), set_bomb_count(), set_land_mine_count(), set_score_text(), shatter(), shield_decay()

<constructor>

bs.Spaz(color=(1, 1, 1), highlight=(0.5, 0.5, 0.5), character='Spaz', source_player=None, start_invincible=True, can_accept_powerups=True, powerups_expire=False, demo_mode=False)

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

add_dropped_bomb_callback()

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

curse_explode()

curse_explode(self, source_player=None)

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

drop_bomb()

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

equip_boxing_gloves()

equip_boxing_gloves(self)

Give this spaz some boxing gloves.

equip_shields()

equip_shields(self, decay=False)

Give this spaz a nice energy shield.

exists()

exists(self)

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, such as with bs.Actor.autoretain()

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

Note that the boolean operator for the Actor class calls this method,
so a simple "if myactor" test will conveniently do the right thing
even if myactor is set to None.

get_death_points()

get_death_points(self, how)

Get the points awarded for killing this spaz

get_factory()

<class method>

get_factory()

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

handlemessage()

handlemessage(self, msg)

General message handling; can be passed any message object.

is_alive()

is_alive(self)

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

on_bomb_press()

on_bomb_press(self)

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

on_bomb_release()

on_bomb_release(self)

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

on_expire()

on_expire(self)

on_fly_press()

on_fly_press(self)

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

on_fly_release()

on_fly_release(self)

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

on_jump_press()

on_jump_press(self)

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

on_jump_release()

on_jump_release(self)

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

on_move()

on_move(self, x, y)

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

on_move_left_right()

on_move_left_right(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 on_move instead.

on_move_up_down()

on_move_up_down(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 on_move instead.

on_pickup_press()

on_pickup_press(self)

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

on_pickup_release()

on_pickup_release(self)

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

on_punch_press()

on_punch_press(self)

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

on_punch_release()

on_punch_release(self)

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

on_punched()

on_punched(self, damage)

Called when this spaz gets punched.

on_run()

on_run(self, value)

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

set_bomb_count()

set_bomb_count(self, count)

Sets the number of bombs this Spaz has.

set_land_mine_count()

set_land_mine_count(self, count)

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

set_score_text()

set_score_text(self, text, 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.

shield_decay()

shield_decay(self)

Called repeatedly to decay shield HP over time.

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:

add_dropped_bomb_callback(), autoretain(), curse(), curse_explode(), drop_bomb(), equip_boxing_gloves(), equip_shields(), exists(), get_death_points(), get_factory(), getactivity(), is_alive(), is_expired(), on_bomb_press(), on_bomb_release(), on_fly_press(), on_fly_release(), on_jump_press(), on_jump_release(), on_move(), on_move_left_right(), on_move_up_down(), on_pickup_press(), on_pickup_release(), on_punch_press(), on_punch_release(), on_run(), set_bomb_count(), set_land_mine_count(), set_score_text(), shatter(), shield_decay()

Methods Defined or Overridden:

<constructor>, handlemessage(), on_expire(), on_punched(), set_player_points(), update_ai()

<constructor>

bs.SpazBot()

Instantiate a spaz-bot.

handlemessage()

handlemessage(self, msg)

General message handling; can be passed any message object.

on_expire()

on_expire(self)

on_punched()

on_punched(self, damage)

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

set_player_points()

set_player_points(self, pts)

Provide the spaz-bot with the locations of players it
should be targeting.

update_ai()

update_ai(self)

Should be called periodically to update the spaz' AI

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(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(badguy, damage)

Instantiate a message with the given values.

bs.SpazFactory

<top level class>

Category: Gameplay 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.get_factory() to return
the shared factory for the current activity.

Attributes:

block_sound, curse_material, impact_sounds_hard, impact_sounds_harder, impact_sounds_medium, pickup_material, punch_material, punch_sound, punch_sound_strong, punch_sound_stronger, roller_material, shatter_sound, single_player_death_sound, spaz_material, splatter_sound, swish_sound

block_sound

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

curse_material

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

impact_sounds_hard

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

impact_sounds_harder

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

impact_sounds_medium

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

pickup_material

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

punch_material

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

punch_sound

A standard punch bs.Sound.

punch_sound_strong

A tuple of stronger sounding punch bs.Sounds.

punch_sound_stronger

A really really strong sounding punch bs.Sound.

roller_material

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

shatter_sound

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

single_player_death_sound

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

spaz_material

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

splatter_sound

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

swish_sound

A punch swish bs.Sound.

Methods:

<constructor>, get_media(), get_style()

<constructor>

bs.SpazFactory()

Instantiate a factory object.

get_media()

get_media(self, character)

Return the set of media used by this variant of spaz

get_style()

get_style(self, character)

Return the named style for this character
(influences subtle aspects of their appearance, etc)

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(position=(0, 0, 0), angle=0)

Instantiate with a given position and angle.

bs.StickyBot

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

category: Bot Classes

A crazy bot who runs and throws sticky bombs.

Attributes Inherited:

node

Methods:

bs.StickyBotStatic

inherits from: bs.StickyBot, 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:

bs.Team

<top level class>

category: Gameplay 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,
each team consists of just one bs.Player.

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(), get_id()

<constructor>

bs.Team(team_id=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

get_id()

get_id(self)

Returns the numeric team ID.

bs.TeamBaseSession

inherits from: bs.Session

category: Gameplay 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:

campaign, lobby, max_players, min_players, players, teams

Methods Inherited:

end(), get_custom_menu_entries(), getactivity(), handlemessage(), on_player_leave(), on_team_leave(), set_activity()

Methods Defined or Overridden:

<constructor>, announce_game_results(), get_ffa_series_length(), get_game_number(), get_max_players(), get_next_game_description(), get_series_length(), on_activity_end(), on_player_request(), on_team_join()

<constructor>

bs.TeamBaseSession()

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

announce_game_results()

announce_game_results(self, activity, results, delay, announce_winning_team=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.

get_ffa_series_length()

get_ffa_series_length(self)

Return free-for-all series length

get_game_number()

get_game_number(self)

Returns which game in the series is currently being played.

get_max_players()

get_max_players(self)

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

get_next_game_description()

get_next_game_description(self)

Returns a description of the next game on deck

get_series_length()

get_series_length(self)

Return teams series length

on_activity_end()

on_activity_end(self, activity, results)

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

on_player_request()

on_player_request(self, player)

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

on_team_join()

on_team_join(self, team)

Called when a new bs.Team joins the session.

bs.TeamGameActivity

inherits from: bs.GameActivity, bs.Activity

category: Gameplay 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:

add_actor_weak_ref(), camera_flash(), continue_or_end_game(), create_config_ui(), end_game(), get_config_display_string(), get_description(), get_description_display_string(), get_display_string(), get_instance_description(), get_instance_display_string(), get_instance_scoreboard_description(), get_instance_scoreboard_display_string(), get_resolved_score_info(), get_score_info(), get_settings(), get_supported_maps(), get_team_display_string(), getmap(), getname(), getsession(), handlemessage(), has_begun(), has_ended(), has_transitioned_in(), is_expired(), is_transitioning_out(), is_waiting_for_continue(), on_continue(), on_expire(), on_player_join(), on_player_leave(), on_team_join(), on_team_leave(), on_transition_out(), project_flag_stand(), respawn_player(), retain_actor(), setup_standard_powerup_drops(), setup_standard_time_limit(), show_info(), show_scoreboard_info(), show_zoom_message(), spawn_player(), spawn_player_if_exists()

Methods Defined or Overridden:

<constructor>, end(), on_begin(), on_transition_in(), spawn_player_spaz(), supports_session_type()

<constructor>

bs.TeamGameActivity(settings)

Instantiates the Activity.

end()

end(self, results=None, announce_winning_team=True, announce_delay=100, force=False)

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

on_begin()

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

on_transition_in()

on_transition_in(self, music=None)

spawn_player_spaz()

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

supports_session_type()

<class method>

supports_session_type(sessiontype)

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

bs.TeamGameResults

<top level class>

category: Gameplay 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>, get_lower_is_better(), get_player_info(), get_score_name(), get_score_type(), get_team_score(), get_team_score_str(), get_teams(), get_winners(), get_winning_team(), has_score_for_team(), set_team_score()

<constructor>

bs.TeamGameResults()

Instantiate a results instance.

get_lower_is_better()

get_lower_is_better(self)

Return whether lower scores are better

get_player_info()

get_player_info(self)

Return info about the players represented by the results

get_score_name()

get_score_name(self)

Return the name associated with scores ('points', etc)

get_score_type()

get_score_type(self)

Return the type of score

get_team_score()

get_team_score(self, team)

Return the score for a given bs.Team

get_team_score_str()

get_team_score_str(self, team)

Return the score for the given bs.Team as a string,
properly formatted for the score type.

get_teams()

get_teams(self)

Return all bs.Teams in the results.

get_winners()

get_winners(self)

Return an ordered list of dicts containing score and teams

get_winning_team()

get_winning_team(self)

Return the winning bs.Team if there is exactly one; None othewise.

has_score_for_team()

has_score_for_team(self, team)

Return whether there is a score for a given bs.Team

set_team_score()

set_team_score(self, team, score)

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

bs.TeamsSession

inherits from: bs.TeamBaseSession, bs.Session

category: Gameplay Classes

bs.Session type for teams mode games.

Attributes Inherited:

campaign, lobby, max_players, min_players, players, teams

Methods Inherited:

announce_game_results(), end(), get_custom_menu_entries(), get_ffa_series_length(), get_game_number(), get_max_players(), get_next_game_description(), get_series_length(), getactivity(), handlemessage(), on_activity_end(), on_player_leave(), on_player_request(), on_team_join(), on_team_leave(), set_activity()

Methods Defined or Overridden:

<constructor>

bs.TeamsSession()

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>

Timer(time, call, repeat=False, timetype='sim', timeformat='s')

category: General Utility Classes

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

This class encapsulates a timer in the current bs.Context.
The underlying timer will be destroyed when either this object is
no longer referenced or when its Context (Activity, etc.) dies. If you
do not want to worry about keeping a reference to your timer around,
you should use the bs.timer() function instead.

time: length of time (in seconds by default) that the timer will wait
before firing. Note that the actual delay experienced may vary
depending on the timetype. (see below)

call: A callable Python object. Note that the timer will retain a
strong reference to the callable for as long as it exists, so you
may want to look into concepts such as bs.WeakCall if that is not
desired.

repeat: if True, the timer will fire repeatedly, with each successive
firing having the same delay as the first.

timetype can be either 'sim', 'base', or 'real'. It defaults to
'sim'. Types are explained below:

'sim' time maps to local simulation time in bs.Activity or bs.Session
Contexts. This means that it may progress slower in slow-motion play
modes, stop when the game is paused, etc. This time type is not
available in UI contexts.

'base' time is also linked to gameplay in bs.Activity or bs.Session
Contexts, but it progresses at a constant rate regardless of
slow-motion states or pausing. It can, however, slow down or stop
in certain cases such as network outages or game slowdowns due to
cpu load. Like 'sim' time, this is unavailable in UI contexts.

'real' time always maps to actual clock time with a bit of filtering
added, regardless of Context. (the filtering prevents it from going
backwards or jumping forward by large amounts due to the app being
backgrounded, system time changing, etc.)
Real time timers are currently only available in the UI context.

the 'timeformat' arg defaults to 's' for seconds but can also be 'ms'
if you want to pass time as milliseconds.

# example: use a Timer object to print repeatedly for a few seconds:
def say_it():
    bs.screenmessage('BADGER!')
def stop_saying_it():
    self.t = None
    bs.screenmessage('MUSHROOM MUSHROOM!')
# create our timer; it will run as long as we hold self.t
self.t = bs.Timer(0.3, say_it, repeat=True)
# now fire off a one-shot timer to kill it
bs.timer(3.89, stop_saying_it)

bs.TNTSpawner

<top level class>

category: Gameplay Classes

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

Methods:

<constructor>

bs.TNTSpawner(position, respawn_time=30000)

<constructor>

bs.Vector(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.timer(5.0, foo.bar)
foo = None

# EXAMPLE B: this code will *not* keep our object alive; it will die
# when we overwrite it with None and the timer will be a no-op when it
# fires
foo = FooClass()
bs.timer(5.0, 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(*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:
myweakcall = bs.WeakCall(myobj.dostuff, argval1, namedarg=argval2)

# now we have a single callable to run that whole mess..
# this is the same as calling myobj.dostuff(argval1, namedarg=argval2)
# (provided my_obj still exists; this will do nothing otherwise)
myweakcall()

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(), get_children(), get_screen_space_center(), get_selected_child(), get_widget_type()

activate()

activate() -> None

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

delete()

delete(ignore_missing=True) -> None

Delete the Widget. Ignores already-deleted Widgets if ignore_missing
is True; otherwise an Exception is thrown.

exists()

exists() -> bool

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

Note that you can also use the boolean operator for this same
functionality, so a statement such as "if mywidget" will do
the right thing both for Widget objects and values of None.

get_children()

get_children() -> list

Returns any child Widgets of this Widget.

get_screen_space_center()

get_screen_space_center() -> tuple

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.

get_selected_child()

get_selected_child() -> bs.Widget

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

get_widget_type()

get_widget_type() -> str

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, timetype='sim', timeformat='s')

category: Gameplay 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. By default, times are specified in seconds,
but timeformat can also be set to 'ms' to recreate the old behavior
(prior to bs 1.5) of taking milliseconds. Returns the animcurve node.

bs.animate_array()

animate_array(node, attr, size, keys, loop=False, offset=0, timetype='sim', timeformat='s')

category: Gameplay Functions

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

bs.appconfig()

appconfig() -> bs.AppConfig

category: General Utility Functions

Returns the bs.AppConfig representing the game's persistent config data.

Note that there is one single 'live' AppConfig instance that this returns;
no copies are made.

bs.appstate()

appstate()
-> bs.AppState

category: General Utility Functions

Returns the shared bs.AppState instance for the app.

bs.buttonwidget()

buttonwidget(edit=None, parent=None, size=None, position=None,
on_activate_call=None, label=None, color=None, down_widget=None,
up_widget=None, left_widget=None, right_widget=None, texture=None,
text_scale=None, text_color=None, enable_sound=True,
model_transparent=None, model_opaque=None, repeat=None, scale=None,
transition_delay=None, on_select_call=None, button_type=None,
extra_touch_border_scale=None, selectable=None, show_buffer_top=None,
icon=None, icon_scale=None, icon_tint=None, icon_color=None,
autoselect=None, mask_texture=None, tint_texture=None,
tint_color=None, tint2_color=None, text_flatness=None,
text_res_scale=None, enabled=None) -> bs.Widget

category: User Interface Functions

Create 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.camerashake()

camerashake(intensity=1.0) -> None

category: Gameplay Functions

Shake the camera. Note that some cameras and/or platforms (such as VR) may
not display camera-shake, so do not rely on this always being visible to the player.

bs.checkboxwidget()

checkboxwidget(edit=None, parent=None, size=None, position=None,
text=None, value=None, on_value_change_call=None,
on_select_call=None, text_scale=None, text_color=None, scale=None,
is_radio_button=None, max_width=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(edit=None, parent=None, size=None, position=None,
background=None, selected_child=None, visible_child=None,
single_depth=None, print_list_exit_instructions=None,
left_border=None, top_border=None, bottom_border=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(edit=None, parent=None, size=None, position=None,
background=None, selected_child=None, transition=None,
cancel_button=None, start_button=None, root_selectable=None,
on_activate_call=None, claims_left_right=None, claims_tab=None,
selection_loops=None, selection_loop_to_parent=None, scale=None,
on_outside_click_call=None, single_depth=None, visible_child=None,
stack_offset=None, color=None, on_cancel_call=None,
print_list_exit_instructions=None, click_activate=None,
always_highlight=None, selectable=None,
scale_origin_stack_offset=None, toolbar_visibility=None,
on_select_call=None, claim_outside_clicks=None, claims_up_down=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.emitfx()

emitfx(position, velocity=None, count=10, scale=1.0, spread=1.0, chunk_type='rock',
emit_type='chunks', tendril_type='smoke') -> None

category: Gameplay 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.env()

env() -> dict

category: General Utility Functions

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

'version' - a human-readable version string; something like '1.3.24'.

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

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

'user_scripts_directory' - where users can put Python scripts to have
them seen by the game

'system_scripts_directory' - 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 the 'android' platform this
could be values such as 'ouya', 'amazon', or 'google'.

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

'test_build' - whether the game was compiled in test mode
(extra error testing but not as slow as debug mode).

'interface_type' - the general interface-type the game is running
under; can be 'large', 'medium', or 'small'.

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

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

bs.get_collision_info()

get_collision_info(*args) -> object

category: Gameplay 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.getactivity()

getactivity(doraise=True) -> bs.Activity

category: Gameplay 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 doraise is
False then None is returned instead.

bs.getcollidemodel()

getcollidemodel(name) -> bs.CollideModel

category: Media Functions

Return a named collide-model.

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.getlanguage()

getlanguage(none_for_default=False)

category: General Utility Functions

Returns the language currently being used by the game.
This may or may not correspond to the language in use by the OS.
(the user can explicitly override the language in-game, etc.)

if 'none_for_default' is True, will return None if no
language has been explicitly set by the user instead
of returning the default language.

bs.getmaps()

getmaps(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 and/or lend themselves to a certain style of play.

Play Types:

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

'team_flag' - for CTF, etc - has 2+ 'spawn' pts,
2+ 'flag' pts, and 1+ 'powerup_spawn' pts

'keep_away'- has 2+ 'spawn' pts, 1+ 'flag_default' pts,
and 1+ 'powerup_spawn' pts

'conquest' - has 2+ 'flag' pts, 2+ 'spawn_by_flag' pts,
and 1+ 'powerup_spawn' pts

'king_of_the_hill' - has 2+ 'spawn' pts, 1+ 'flag_default' pts,
and 1+ 'powerup_spawn' pts

'hockey' - has 2 'goal' pts, 2+ 'spawn' pts, 1+ 'flag_default' pts,
1+ 'powerup_spawn' pts

'football' - has 2 'goal' pts, 2+ 'spawn' pts, 1+ 'flag_default' pts,
1+ 'powerup_spawn' pts

'race' - has 2+ 'racePoint' pts

bs.getmodel()

getmodel(name) -> bs.Model

category: Media Functions

Return a named model.

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

category: Gameplay Functions

Return all nodes in the current bs.Context.

bs.getsession()

getsession(doraise=True) -> bs.Session

category: Gameplay 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 doraise is False then None is returned instead.

bs.getsound()

getsound(name) -> bs.Sound

category: Media Functions

Return a named sound.

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.gettexture()

gettexture(name) -> bs.Texture

category: Media Functions

Return a named texture.

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.hscrollwidget()

hscrollwidget(edit=None, parent=None, size=None, position=None,
background=None, selected_child=None, capture_arrows=None,
on_select_call=None, center_small_content=None, color=None,
highlight=None, border_opacity=None, simple_culling_h=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, opacity=None, model_transparent=None,
model_opaque=None, has_alpha_channel=True, tint_texture=None,
tint_color=None, transition_delay=None, draw_controller=None,
tint2_color=None, tilt_scale=None, mask_texture=None,
radial_amount=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.is_browser_likely_available()

is_browser_likely_available()

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.show_url() with any lengthy addresses.
(bs.show_url() 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.is_point_in_box()

is_point_in_box(pnt, box)

category: General Utility Functions

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

bs.new_activity()

new_activity(activity_type, settings=None) -> 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: Gameplay Functions

Add a node of the given type to the game.

If a dict is provided for 'attributes', the node's initial attributes
will be set based on them.

'name', if provided, will be stored with the node purely for debugging
purposes. If no name is provided, 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.normalized_color()

normalized_color(color)

category: General Utility Functions

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

bs.open_url()

open_url(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: Gameplay 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.0, position=None, host_only=False) -> None

category: Gameplay 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.print_error()

print_error(*args, **keywds)

category: General Utility Functions

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

bs.print_error_once()

print_error_once(*args, **keywds)

category: General Utility Functions

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

bs.print_exception()

print_exception(*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: Gameplay Functions

Print various info about existing nodes; useful for debugging.

bs.pushcall()

pushcall(call, from_other_thread=False) -> 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.

This call expects to be used in the game thread, and will automatically
save and restore the bs.Context to behave seamlessly.

If you want to push a call from outside of the game thread,
however, you can pass 'from_other_thread' as True. In this case
the call will always run in the UI context on the game thread.

bs.quit()

quit(soft=False, back=False) -> None

category: General Utility Functions

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

bs.rowwidget()

rowwidget(edit=None, parent=None, size=None, position=None,
background=None, selected_child=None, visible_child=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.safecolor()

safecolor(color, target_intensity=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.screenmessage()

screenmessage(message, color=(1,1,1), top=False, image=None, log=False, clients=None, transient=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
'clients' can be a list of client-ids the message should be sent to,
or None to specify that everyone should receive it.
If 'transient' is True, the message will not be included in the
game-stream and thus will not show up when viewing replays.
Currently the 'clients' option only works for transient messages.

bs.scrollwidget()

scrollwidget(edit=None, parent=None, size=None, position=None,
background=None, selected_child=None, capture_arrows=False,
on_select_call=None, center_small_content=None, color=None,
highlight=None, border_opacity=None, simple_culling_v=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.set_analytics_screen()

set_analytics_screen(screen) -> None

category: General Utility Functions

Used for analytics to see where in the app players spend their time.
Generally called when opening a new window or entering some UI.
'screen' should be a string description of an app location
('Main Menu', etc.)

bs.specialchar()

specialchar(name) -> str

category: General Utility Functions

Given a name, returns a BombSquad-specific special character which can
be included in strings. Note that these make use of the unicode
private use character ranges and thus will not display correctly
outside of the game.

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:

'down_arrow', 'up_arrow', 'left_arrow', 'right_arrow':
directional arrows.

'top_button', 'left_button', 'right_button', 'bottom_button':
generic gamepad button icons.

'rewind_button', 'play_pause_button', 'fast_forward_button',
'dpad_center_button': tv remote buttons.

bs.stdobj()

stdobj(name)

category: Gameplay Functions

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

Available values for 'name':

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

'object_material': 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)

'player_material': 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.

'pickup_material': 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.

'footing_material': 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.

'attack_material': 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.

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

'region_material': 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.

'railing_material': 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.textwidget()

textwidget(edit=None, parent=None, size=None, position=None, text=None,
v_align=None, h_align=None, editable=None, padding=None,
on_return_press_call=None, on_activate_call=None, selectable=None,
query=None, max_chars=None, color=None, click_activate=None,
on_select_call=None, always_highlight=None, draw_controller=None,
scale=None, corner_scale=None, description=None,
transition_delay=None, max_width=None, max_height=None,
flatness=None, shadow=None, autoselect=None, rotate=None,
enabled=None, force_internal_editing=None, always_show_carat=None,
big=None, extra_touch_border_scale=None, res_scale=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.time()

time(timetype='sim', timeformat='s') -> float

category: General Utility Functions

Returns the current time (in seconds by default).
The time returned depends on the current bs.Context and timetype.

timetype can be either 'sim', 'base', or 'real'. It defaults to
'sim'. Types are explained below:

the 'timeformat' arg defaults to 's' which returns float seconds, but
it can also be 'ms' which returns int milliseconds

Note: If you need pure unfiltered clock time, just use the standard
Python functions such as time.time().

bs.timer()

timer(time, call, repeat=False, timetype='sim', timeformat='s')
-> None

category: General Utility Functions

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

This function adds a timer to the current bs.Context.
This timer cannot be canceled or modified once created. If you
require the ability to do so, use the bs.Timer class instead.

time: length of time (in seconds by default) that the timer will wait
before firing. Note that the actual delay experienced may vary
depending on the timetype. (see below)

repeat: if True, the timer will fire repeatedly, with each successive
firing having the same delay as the first.

timetype can be either 'sim', 'base', or 'real'. It defaults to
'sim'. Types are explained below:

the 'timeformat' arg defaults to 's' for seconds but can also be 'ms'
if you want to pass time as milliseconds.

# timer example: print some stuff through time:
bs.screenmessage('hello from now!')
bs.timer(1.0, bs.Call(bs.screenmessage, 'hello from the future!'))
bs.timer(2.0, bs.Call(bs.screenmessage, 'hello from the future 2!'))

bs.timestring()

timestring(timeval, centi=True, timeformat='s')

category: General Utility Functions

Given a time value, returns a bs.Lstr with:
(hours if > 0 ) : minutes : seconds : (centiseconds if centi=True).

Time 't' is specified in seconds by default, or 'timeformat' can
be set to 'ms' to accept millisecond values.

WARNING: this Lstr value is somewhat large so don't use this to
rapidly update Node text values for an onscreen timer or you may
waste significant network bandwidth. For that purpose you should
use a 'timedisplay' Node and attribute connections.

bs.uibounds()

uibounds() -> tuple

category: General Utility Functions

Returns a tuple of 4 values: (x-min, x-max, y-min, y-max) representing
the range of values that can be plugged into a root level
bs.ContainerWidget's stack_offset value while guaranteeing that its
center remains onscreen.

bs.widget()

widget(edit=None, up_widget=None, down_widget=None,
left_widget=None, right_widget=None, show_buffer_top=None,
show_buffer_bottom=None, show_buffer_left=None,
show_buffer_right=None, autoselect=None) -> None

category: User Interface Functions

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

last updated on 2018-09-18 for BombSquad version 1.5.0 build 20000

Table of Contents

Attributes:

players, settings, teams

Methods:

Methods:

<constructor>, autoretain(), exists(), getactivity(), handlemessage(), is_alive(), is_expired(), on_expire()

Methods Defined or Overridden:

apply(), apply_and_commit(), commit(), default_value(), resolve(), valid_keys()

Methods Inherited:

autoretain(), exists(), getactivity(), is_alive(), is_expired(), on_expire()

Methods Defined or Overridden:

<constructor>, handlemessage()

Methods Inherited:

autoretain(), exists(), getactivity(), is_alive(), is_expired()

Methods Defined or Overridden:

<constructor>, add_explode_callback(), arm(), explode(), get_factory(), get_source_player(), handlemessage(), on_expire()

<class method>

Attributes Inherited:

Methods:

Attributes Inherited:

Methods:

Attributes Inherited:

Methods:

Attributes Inherited:

Methods:

Attributes Inherited:

Methods:

Attributes Inherited:

Methods:

Attributes Inherited:

Methods:

Attributes Inherited:

Methods:

Attributes:

Methods: