bascenev1 package

Module contents

Gameplay-centric api for classic BombSquad.

class bascenev1.Activity(settings: dict)

Bases: DependencyComponent, Generic[PlayerT, TeamT]

Units of execution wrangled by a bascenev1.Session.

Category: Gameplay Classes

Examples of Activities include games, score-screens, cutscenes, etc. A bascenev1.Session has one ‘current’ Activity at any time, though their existence can overlap during transitions.

add_actor_weak_ref(actor: bascenev1.Actor) → None

Add a weak-reference to a bascenev1.Actor to the bascenev1.Activity.

(called by the bascenev1.Actor base class)

add_player(sessionplayer: bascenev1.SessionPlayer) → None

(internal)

add_team(sessionteam: bascenev1.SessionTeam) → None

Add a team to the Activity

(internal)

allow_kick_idle_players = True

allow_mid_activity_joins: bool = True

allow_pausing = False

announce_player_deaths = False

begin(session: bascenev1.Session) → None

Begin the activity.

(internal)

can_show_ad_on_death = False

property context: bascenev1.ContextRef

A context-ref pointing at this activity.

create_player(sessionplayer: bascenev1.SessionPlayer) → PlayerT

Create the Player instance for this Activity.

Subclasses can override this if the activity’s player class requires a custom constructor; otherwise it will be called with no args. Note that the player object should not be used at this point as it is not yet fully wired up; wait for bascenev1.Activity.on_player_join() for that.

create_team(sessionteam: bascenev1.SessionTeam) → TeamT

Create the Team instance for this Activity.

Subclasses can override this if the activity’s team class requires a custom constructor; otherwise it will be called with no args. Note that the team object should not be used at this point as it is not yet fully wired up; wait for on_team_join() for that.

property customdata: dict

Entities needing to store simple data with an activity can put it here. This dict will be deleted when the activity expires, so contained objects generally do not need to worry about handling expired activities.

end(results: Any = None, delay: float = 0.0, force: bool = False) → None

Commences Activity shutdown and delivers results to the Session.

‘delay’ is the time delay before the Activity actually ends (in seconds). 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.

expire() → None

Begin the process of tearing down the activity.

(internal)

property expired: bool

Whether the activity is expired.

An 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 a ‘zombie’.

property globalsnode: bascenev1.Node

The ‘globals’ bascenev1.Node for the activity. This contains various global controls and values.

handlemessage(msg: Any) → Any

General message handling; can be passed any message object.

has_begun() → bool

Return whether bascenev1.Activity.on_begin() has run.

has_ended() → bool

Return whether the activity has commenced ending.

has_transitioned_in() → bool

Return whether bascenev1.Activity.on_transition_in() has run.

inherits_music = False

inherits_slow_motion = False

inherits_tint = False

inherits_vr_camera_offset = False

inherits_vr_overlay_center = False

is_joining_activity = False

is_transitioning_out() → bool

Return whether bascenev1.Activity.on_transition_out() has run.

on_begin() → None

Called once the previous 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() → None

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(player: PlayerT) → None

Called when a new bascenev1.Player has joined the Activity.

(including the initial set of Players)

on_player_leave(player: PlayerT) → None

Called when a bascenev1.Player is leaving the Activity.

on_team_join(team: TeamT) → None

Called when a new bascenev1.Team joins the Activity.

(including the initial set of Teams)

on_team_leave(team: TeamT) → None

Called when a bascenev1.Team leaves the Activity.

on_transition_in() → None

Called when the Activity is first becoming visible.

Upon this call, the Activity should fade in backgrounds, start playing music, etc. It does not yet have access to players or teams, however. They remain owned by the previous Activity up until bascenev1.Activity.on_begin() is called.

on_transition_out() → None

Called when your activity begins transitioning out.

Note that this may happen at any time even if bascenev1.Activity.end() has not been called.

players: list[PlayerT]

property playertype: type[PlayerT]

The type of bascenev1.Player this Activity is using.

remove_player(sessionplayer: bascenev1.SessionPlayer) → None

Remove a player from the Activity while it is running.

(internal)

remove_team(sessionteam: bascenev1.SessionTeam) → None

Remove a team from a Running Activity

(internal)

retain_actor(actor: bascenev1.Actor) → None

Add a strong-reference to a bascenev1.Actor to this Activity.

The reference will be lazily released once bascenev1.Actor.exists() returns False for the Actor. The bascenev1.Actor.autoretain() method is a convenient way to access this same functionality.

property session: bascenev1.Session

The bascenev1.Session this bascenev1.Activity belongs to.

Raises a babase.SessionNotFoundError if the Session no longer exists.

set_has_ended(val: bool) → None

(internal)

settings_raw: dict[str, Any]

slow_motion = False

property stats: bascenev1.Stats

The stats instance accessible while the activity is running.

If access is attempted before or after, raises a bascenev1.NotFoundError.

teams: list[TeamT]

property teamtype: type[TeamT]

The type of bascenev1.Team this Activity is using.

transition_in(prev_globals: bascenev1.Node | None) → None

Called by Session to kick off transition-in.

(internal)

transition_out() → None

Called by the Session to start us transitioning out.

transition_time = 0.0

use_fixed_vr_overlay = False

class bascenev1.ActivityData

Bases: object

(internal)

context() → bascenev1.ContextRef

Return a context-ref pointing to the activity.

exists() → bool

Returns whether the ActivityData still exists. Most functionality will fail on a nonexistent instance.

expire() → None

Expires the internal data for the activity

make_foreground() → None

Sets this activity as the foreground one in its session.

start() → None

Begins the activity running

class bascenev1.Actor

Bases: object

High level logical entities in a bascenev1.Activity.

Category: Gameplay Classes

Actors act as controllers, combining some number of Nodes, Textures, Sounds, etc. into a high-level cohesive unit.

Some example actors include the Bomb, Flag, and Spaz classes that live in the bascenev1lib.actor.* modules.

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:

##### Example >>> # Create a flag Actor in our game activity: … from bascenev1lib.actor.flag import Flag … self.flag = 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 bascenev1.Node, which is always explicitly created and destroyed and doesn’t care how many Python references to it exist.

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

Another key feature of bascenev1.Actor is its bascenev1.Actor.handlemessage() method, which takes a single arbitrary object as an argument. This provides a safe way to communicate between bascenev1.Actor, bascenev1.Activity, bascenev1.Session, and any other class providing a handlemessage() method. The most universally handled message type for Actors is the bascenev1.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 bascenev1.Actor.exists() and bascenev1.Actor.is_alive() methods will both return False. >>> self.flag.handlemessage(bascenev1.DieMessage())

property activity: bascenev1.Activity

The Activity this Actor was created in.

Raises a bascenev1.ActivityNotFoundError if the Activity no longer exists.

autoretain() → ActorT

Keep this Actor alive without needing to hold a reference to it.

This keeps the bascenev1.Actor in existence by storing a reference to it with the bascenev1.Activity it was created in. The reference is lazily released once bascenev1.Actor.exists() returns False for it or when the Activity is set as expired. This can be a convenient alternative to storing references explicitly just to keep a bascenev1.Actor from dying. For convenience, this method returns the bascenev1.Actor it is called with, enabling chained statements such as: myflag = bascenev1.Flag().autoretain()

exists() → bool

Returns whether the Actor is still present in a meaningful way.

Note that a dying character should still return True here as long as their corpse is visible; this is about presence, not being ‘alive’ (see bascenev1.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 bascenev1.Actor.autoretain()

The default implementation of this method always return 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.

property expired: bool

Whether the Actor is expired.

(see bascenev1.Actor.on_expire())

getactivity(doraise: bool = True) → bascenev1.Activity | None

Return the bascenev1.Activity this Actor is associated with.

If the Activity no longer exists, raises a bascenev1.ActivityNotFoundError or returns None depending on whether ‘doraise’ is True.

handlemessage(msg: Any) → Any

General message handling; can be passed any message object.

is_alive() → bool

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 consider themselves to be alive or not. In cases where dead/alive is irrelevant, True should be returned.

on_expire() → None

Called for remaining `bascenev1.Actor`s when their activity dies.

Actors can use this opportunity to clear callbacks or other references which have the potential of keeping the bascenev1.Activity alive inadvertently (Activities can not exit cleanly while any Python references to them remain.)

Once an actor is expired (see bascenev1.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.

class bascenev1.AppIntent

Bases: object

A high level directive given to the app.

Category: App Classes

class bascenev1.AppIntentDefault

Bases: AppIntent

Tells the app to simply run in its default mode.

class bascenev1.AppIntentExec(code: str)

Bases: AppIntent

Tells the app to exec some Python code.

class bascenev1.AppMode

Bases: object

A high level mode for the app.

Category: App Classes

classmethod can_handle_intent(intent: AppIntent) → bool

Return whether this mode can handle the provided intent.

For this to return True, the AppMode must claim to support the provided intent (via its _supports_intent() method) AND the AppExperience associated with the AppMode must be supported by the current app and runtime environment.

classmethod get_app_experience() → AppExperience

Return the overall experience provided by this mode.

handle_intent(intent: AppIntent) → None

Handle an intent.

on_activate() → None

Called when the mode is being activated.

on_app_active_changed() → None

Called when ba*.app.active changes while this mode is active.

The app-mode may want to take action such as pausing a running game in such cases.

on_deactivate() → None

Called when the mode is being deactivated.

class bascenev1.AppTimer(time: float, call: Callable[[], Any], repeat: bool = False)

Bases: object

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

Category: General Utility Classes

This class encapsulates a timer based on app-time. The underlying timer will be destroyed when this object is no longer referenced. If you do not want to worry about keeping a reference to your timer around, use the babase.apptimer() function instead to get a one-off timer.

##### Arguments ###### time > Length of time in seconds that the timer will wait before firing.

###### call > A callable Python object. Remember 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 babase.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.

##### Example

Use a Timer object to print repeatedly for a few seconds: … def say_it(): … babase.screenmessage(‘BADGER!’) … def stop_saying_it(): … global g_timer … g_timer = None … babase.screenmessage(‘MUSHROOM MUSHROOM!’) … # Create our timer; it will run as long as we have the self.t ref. … g_timer = babase.AppTimer(0.3, say_it, repeat=True) … # Now fire off a one-shot timer to kill it. … babase.apptimer(3.89, stop_saying_it)

class bascenev1.AssetPackage

Bases: DependencyComponent

bascenev1.DependencyComponent representing a bundled package of assets.

Category: Asset Classes

classmethod dep_is_present(config: Any = None) → bool

Return whether this component/config is present on this device.

getcollisionmesh(name: str) → bascenev1.CollisionMesh

Load a named bascenev1.CollisionMesh from the AssetPackage.

Behavior is similar to bascenev1.getcollisionmesh()

getdata(name: str) → bascenev1.Data

Load a named bascenev1.Data from the AssetPackage.

Behavior is similar to bascenev1.getdata()

getmesh(name: str) → bascenev1.Mesh

Load a named bascenev1.Mesh from the AssetPackage.

Behavior is similar to bascenev1.getmesh()

getsound(name: str) → bascenev1.Sound

Load a named bascenev1.Sound from the AssetPackage.

Behavior is similar to bascenev1.getsound()

gettexture(name: str) → bascenev1.Texture

Load a named bascenev1.Texture from the AssetPackage.

Behavior is similar to bascenev1.gettexture()

class bascenev1.BaseTimer(time: float, call: Callable[[], Any], repeat: bool = False)

Bases: object

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

Category: General Utility Classes

This class encapsulates a base-time timer in the current scene 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 bascenev1.basetimer() function instead.

###### time (float) > Length of time in seconds that the timer will wait before firing.

###### call (Callable[[], Any]) > A callable Python object. Remember 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 babase.WeakCall if that is not desired.

###### repeat (bool) > If True, the timer will fire repeatedly, with each successive firing having the same delay as the first.

##### Example

Use a BaseTimer object to print repeatedly for a few seconds: >>> import bascenev1 as bs … def say_it(): … bs.screenmessage(‘BADGER!’) … def stop_saying_it(): … global g_timer … g_timer = None … bs.screenmessage(‘MUSHROOM MUSHROOM!’) … # Create our timer; it will run as long as we have the self.t ref. … g_timer = bs.BaseTimer(0.3, say_it, repeat=True) … # Now fire off a one-shot timer to kill it. … bs.basetimer(3.89, stop_saying_it)

class bascenev1.BoolSetting(name: str, default: bool)

Bases: Setting

A boolean game setting.

Category: Settings Classes

default: bool

class bascenev1.Call(*args: Any, **keywds: Any)

Bases: object

Wraps a callable and arguments into a single callable object.

Category: General Utility Classes

The callable is strong-referenced so it won’t die until this object does.

WARNING: This is exactly the same as Python’s built in functools.partial(). Use functools.partial instead of this for new code, as this will probably be deprecated at some point.

Note that a bound method (ex: myobj.dosomething) contains a reference to self (myobj in that case), so you will be keeping that object alive too. Use babase.WeakCall if you want to pass a method to a callback without keeping its object alive.

class bascenev1.Campaign(name: str, sequential: bool = True, levels: list[bascenev1.Level] | None = None)

Bases: object

Represents a unique set or series of baclassic.Level-s.

Category: App Classes

addlevel(level: bascenev1.Level, index: int | None = None) → None

Adds a baclassic.Level to the Campaign.

property configdict: dict[str, Any]

Return the live config dict for this campaign.

get_selected_level() → str

Return the name of the Level currently selected in the UI.

getlevel(name: str) → bascenev1.Level

Return a contained baclassic.Level by name.

property levels: list[bascenev1.Level]

The list of baclassic.Level-s in the Campaign.

property name: str

The name of the Campaign.

reset() → None

Reset state for the Campaign.

property sequential: bool

Whether this Campaign’s levels must be played in sequence.

set_selected_level(levelname: str) → None

Set the Level currently selected in the UI (by name).

class bascenev1.CelebrateMessage(duration: float = 10.0)

Bases: object

Tells an object to celebrate.

Category: Message Classes

duration: float = 10.0

class bascenev1.ChoiceSetting(name: str, default: Any, choices: list[tuple[str, Any]])

Bases: Setting

A setting with multiple choices.

Category: Settings Classes

choices: list[tuple[str, Any]]

class bascenev1.Chooser(vpos: float, sessionplayer: bascenev1.SessionPlayer, lobby: Lobby)

Bases: object

A character/team selector for a bascenev1.Player.

Category: Gameplay Classes

get_character_name() → str

Return the selected character name.

get_color() → Sequence[float]

Return the currently selected color.

get_highlight() → Sequence[float]

Return the currently selected highlight.

get_lobby() → bascenev1.Lobby | None

Return this chooser’s lobby if it still exists; otherwise None.

getplayer() → bascenev1.SessionPlayer

Return the player associated with this chooser.

handlemessage(msg: Any) → Any

Standard generic message handler.

property lobby: bascenev1.Lobby

The chooser’s baclassic.Lobby.

property ready: bool

Whether this chooser is checked in as ready.

reload_profiles() → None

Reload all player profiles.

property sessionplayer: bascenev1.SessionPlayer

The bascenev1.SessionPlayer associated with this chooser.

property sessionteam: bascenev1.SessionTeam

Return this chooser’s currently selected bascenev1.SessionTeam.

set_dead(val: bool) → None

(internal)

set_vpos(vpos: float) → None

(internal)

update_from_profile() → None

Set character/colors based on the current profile.

update_position() → None

Update this chooser’s position.

class bascenev1.Collision

Bases: object

A class providing info about occurring collisions.

Category: Gameplay Classes

property opposingbody: int

The body index on the opposing node in the current collision.

property opposingnode: bascenev1.Node

The node the current callback material node is hitting.

Throws a bascenev1.NodeNotFoundError if the node does not exist. This can be expected in some cases such as in ‘disconnect’ callbacks triggered by deleting a currently-colliding node.

property position: bascenev1.Vec3

The position of the current collision.

property sourcenode: bascenev1.Node

The node containing the material triggering the current callback.

Throws a bascenev1.NodeNotFoundError if the node does not exist, though the node should always exist (at least at the start of the collision callback).

class bascenev1.CollisionMesh

Bases: object

A reference to a collision-mesh.

Category: Asset Classes

Use bascenev1.getcollisionmesh() to instantiate one.

exception bascenev1.ContextError

Bases: Exception

Exception raised when a call is made in an invalid context.

Category: Exception Classes

Examples of this include calling UI functions within an Activity context or calling scene manipulation functions outside of a game context.

class bascenev1.ContextRef

Bases: object

Store or use a ballistica context.

Category: General Utility Classes

Many operations such as bascenev1.newnode() or bascenev1.gettexture() operate implicitly on a current ‘context’. A context is some sort of state that functionality can implicitly use. Context determines, for example, which scene nodes or textures get added to without having to specify it explicitly in the newnode()/gettexture() call. Contexts can also affect object lifecycles; for example a babase.ContextCall will become a no-op when the context it was created in is destroyed.

In general, if you are a modder, you should not need to worry about contexts; mod code should mostly be getting run in the correct context and timers and other callbacks will take care of saving and restoring contexts automatically. There may be rare cases, however, where you need to deal directly with contexts, and that is where this class comes in.

Creating a babase.ContextRef() will capture a reference to the current context. Other modules may provide ways to access their contexts; for example a bascenev1.Activity instance has a ‘context’ attribute. You can also use babase.ContextRef.empty() to create a reference to no context. Some code such as UI calls may expect this and may complain if you try to use them within a context.

##### Usage ContextRefs are generally used with the Python ‘with’ statement, which sets the context they point to as current on entry and resets it to the previous value on exit.

##### Example Explicitly create a few UI bits with no context set. (UI stuff may complain if called within a context): >>> with bui.ContextRef.empty(): … my_container = bui.containerwidget()

classmethod empty() → ContextRef

Return a ContextRef pointing to no context.

This is useful when code should be run free of a context. For example, UI code generally insists on being run this way. Otherwise, callbacks set on the UI could inadvertently stop working due to a game activity ending, which would be unintuitive behavior.

is_empty() → bool

Whether the context was created as empty.

is_expired() → bool

Whether the context has expired.

class bascenev1.CoopGameActivity(settings: dict)

Bases: GameActivity[PlayerT, TeamT]

Base class for cooperative-mode games.

Category: Gameplay Classes

celebrate(duration: float) → None

Tells all existing player-controlled characters to celebrate.

Can be useful in co-op games when the good guys score or complete a wave. duration is given in seconds.

fade_to_red() → None

Fade the screen to red; (such as when the good guys have lost).

get_score_type() → str

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

on_begin() → None

Called once the previous 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() → None

Set up a beeping noise to play when any players are near death.

spawn_player_spaz(player: PlayerT, position: Sequence[float] = (0.0, 0.0, 0.0), angle: float | None = None) → PlayerSpaz

Spawn and wire up a standard player spaz.

classmethod supports_session_type(sessiontype: type[bascenev1.Session]) → bool

Return whether this game supports the provided Session type.

class bascenev1.CoopSession

Bases: Session

A bascenev1.Session which runs cooperative-mode games.

Category: Gameplay Classes

These generally consist of 1-4 players against the computer and include functionality such as high score lists.

allow_mid_activity_joins = False

campaign: bascenev1.Campaign | None

get_current_game_instance() → bascenev1.GameActivity

Get the game instance currently being played.

get_custom_menu_entries() → list[dict[str, Any]]

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(activity: bascenev1.Activity, results: Any) → None

Method override for co-op sessions.

Jumps between co-op games and score screens.

on_player_leave(sessionplayer: bascenev1.SessionPlayer) → None

Called when a previously-accepted bascenev1.SessionPlayer leaves.

restart() → None

Restart the current game activity.

should_allow_mid_activity_joins(activity: bascenev1.Activity) → bool

Ask ourself if we should allow joins during an Activity.

Note that for a join to be allowed, both the Session and Activity have to be ok with it (via this function and the Activity.allow_mid_activity_joins property.

use_team_colors = False

use_teams = True

class bascenev1.Data

Bases: object

A reference to a data object.

Category: Asset Classes

Use bascenev1.getdata() to instantiate one.

getvalue() → Any

Return the data object’s value.

This can consist of anything representable by json (dicts, lists, numbers, bools, None, etc). Note that this call will block if the data has not yet been loaded, so it can be beneficial to plan a short bit of time between when the data object is requested and when it’s value is accessed.

class bascenev1.DeathType(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

A reason for a death.

Category: Enums

FALL = 'fall'

GENERIC = 'generic'

IMPACT = 'impact'

LEFT_GAME = 'left_game'

OUT_OF_BOUNDS = 'out_of_bounds'

REACHED_GOAL = 'reached_goal'

class bascenev1.Dependency(cls: type[T], config: Any = None)

Bases: Generic[T]

A dependency on a DependencyComponent (with an optional config).

Category: Dependency Classes

This class is used to request and access functionality provided by other DependencyComponent classes from a DependencyComponent class. The class functions as a descriptor, allowing dependencies to be added at a class level much the same as properties or methods and then used with class instances to access those dependencies. For instance, if you do ‘floofcls = bascenev1.Dependency(FloofClass)’ you would then be able to instantiate a FloofClass in your class’s methods via self.floofcls().

get_hash() → int

Return the dependency’s hash, calculating it if necessary.

class bascenev1.DependencyComponent

Bases: object

Base class for all classes that can act as or use dependencies.

Category: Dependency Classes

classmethod dep_is_present(config: Any = None) → bool

Return whether this component/config is present on this device.

classmethod get_dynamic_deps(config: Any = None) → list[Dependency]

Return any dynamically-calculated deps for this component/config.

Deps declared statically as part of the class do not need to be included here; this is only for additional deps that may vary based on the dep config value. (for instance a map required by a game type)

class bascenev1.DependencySet(root_dependency: Dependency[T])

Bases: Generic[T]

Set of resolved dependencies and their associated data.

Category: Dependency Classes

To use DependencyComponents, a set must be created, resolved, and then loaded. The DependencyComponents are only valid while the set remains in existence.

get_asset_package_ids() → set[str]

Return the set of asset-package-ids required by this dep-set.

Must be called on a resolved dep-set.

load() → None

Instantiate all DependencyComponents in the set.

Returns a wrapper which can be used to instantiate the root dep.

resolve() → None

Resolve the complete set of required dependencies for this set.

Raises a bascenev1.DependencyError if dependencies are missing (or other Exception types on other errors).

property resolved: bool

Whether this set has been successfully resolved.

property root: T

The instantiated root DependencyComponent instance for the set.

class bascenev1.DieMessage(immediate: bool = False, how: DeathType = DeathType.GENERIC)

Bases: object

A message telling an object to die.

Category: Message Classes

Most bascenev1.Actor-s respond to this.

how: DeathType = 'generic'

immediate: bool = False

class bascenev1.DisplayTimer(time: float, call: Callable[[], Any], repeat: bool = False)

Bases: object

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

Category: General Utility Classes

This class encapsulates a timer based on display-time. The underlying timer will be destroyed when this object is no longer referenced. If you do not want to worry about keeping a reference to your timer around, use the babase.displaytimer() function instead to get a one-off timer.

Display-time is a time value intended to be used for animation and other visual purposes. It will generally increment by a consistent amount each frame. It will pass at an overall similar rate to AppTime, but trades accuracy for smoothness.

##### Arguments ###### time > Length of time in seconds that the timer will wait before firing.

###### call > A callable Python object. Remember 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 babase.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.

##### Example

Use a Timer object to print repeatedly for a few seconds: … def say_it(): … babase.screenmessage(‘BADGER!’) … def stop_saying_it(): … global g_timer … g_timer = None … babase.screenmessage(‘MUSHROOM MUSHROOM!’) … # Create our timer; it will run as long as we have the self.t ref. … g_timer = babase.DisplayTimer(0.3, say_it, repeat=True) … # Now fire off a one-shot timer to kill it. … babase.displaytimer(3.89, stop_saying_it)

class bascenev1.DropMessage

Bases: object

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

Category: Message Classes

class bascenev1.DroppedMessage(node: bascenev1.Node)

Bases: object

Tells an object that it has been dropped.

Category: Message Classes

node: bascenev1.Node

class bascenev1.DualTeamSession

Bases: MultiTeamSession

bascenev1.Session type for teams mode games.

Category: Gameplay Classes

use_team_colors = True

use_teams = True

class bascenev1.EmptyPlayer

Bases: Player[bascenev1.EmptyTeam]

An empty player for use by Activities that don’t need to define one.

Category: Gameplay Classes

bascenev1.Player and bascenev1.Team are ‘Generic’ types, and so passing those top level classes as type arguments when defining a bascenev1.Activity reduces type safety. For example, activity.teams[0].player will have type ‘Any’ in that case. For that reason, it is better to pass EmptyPlayer and EmptyTeam when defining a bascenev1.Activity that does not need custom types of its own.

Note that EmptyPlayer defines its team type as EmptyTeam and vice versa, so if you want to define your own class for one of them you should do so for both.

class bascenev1.EmptyTeam

Bases: Team[bascenev1.EmptyPlayer]

An empty player for use by Activities that don’t need to define one.

Category: Gameplay Classes

bascenev1.Player and bascenev1.Team are ‘Generic’ types, and so passing those top level classes as type arguments when defining a bascenev1.Activity reduces type safety. For example, activity.teams[0].player will have type ‘Any’ in that case. For that reason, it is better to pass EmptyPlayer and EmptyTeam when defining a bascenev1.Activity that does not need custom types of its own.

Note that EmptyPlayer defines its team type as EmptyTeam and vice versa, so if you want to define your own class for one of them you should do so for both.

class bascenev1.FloatChoiceSetting(name: str, default: float, choices: list[tuple[str, float]])

Bases: ChoiceSetting

A float setting with multiple choices.

Category: Settings Classes

choices: list[tuple[str, float]]

default: float

class bascenev1.FloatSetting(name: str, default: float, min_value: float = 0.0, max_value: float = 9999.0, increment: float = 1.0)

Bases: Setting

A floating point game setting.

Category: Settings Classes

default: float

increment: float = 1.0

max_value: float = 9999.0

min_value: float = 0.0

class bascenev1.FreeForAllSession

Bases: MultiTeamSession

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

Category: Gameplay Classes

get_ffa_point_awards() → dict[int, int]

Return the number of points awarded for different rankings.

This is based on the current number of players.

use_team_colors = False

use_teams = False

class bascenev1.FreezeMessage

Bases: object

Tells an object to become frozen.

Category: Message Classes

As seen in the effects of an ice bascenev1.Bomb.

class bascenev1.GameActivity(settings: dict)

Bases: Activity[PlayerT, TeamT]

Common base class for all game bascenev1.Activities.

Category: Gameplay Classes

allow_kick_idle_players = True

allow_pausing = True

available_settings: list[bascenev1.Setting] | None = None

default_music: bascenev1.MusicType | None = None

description: str | None = None

end(results: Any = None, delay: float = 0.0, force: bool = False) → None

Commences Activity shutdown and delivers results to the Session.

‘delay’ is the time delay before the Activity actually ends (in seconds). 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.

end_game() → None

Tell the game to wrap up and call bascenev1.Activity.end().

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

classmethod get_available_settings(sessiontype: type[bascenev1.Session]) → list[bascenev1.Setting]

Return a list of settings relevant to this game type when running under the provided session type.

classmethod get_description(sessiontype: type[bascenev1.Session]) → str

Get a str description of this game type.

The default implementation simply returns the ‘description’ class var. Classes which want to change their description depending on the session can override this method.

classmethod get_description_display_string(sessiontype: type[bascenev1.Session]) → babase.Lstr

Return a translated version of get_description().

Sub-classes should override get_description(); not this.

classmethod get_display_string(settings: dict | None = None) → Lstr

Return a descriptive name for this game/settings combo.

Subclasses should override getname(); not this.

get_instance_description() → str | Sequence

Return a description for this 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_description_short().

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_raw[‘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_description_short() → str | Sequence

Return a short description for this game instance in English.

This description is used above the game scoreboard in the corner of the screen, so it should be as concise as possible. It should be lowercase and should not contain periods or other punctuation.

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

# This will give us something like ‘score 3 goals’ in English # and can properly translate to ‘anota 3 goles’ in Spanish. # If we just returned the string ‘score 3 goals’ here, there would # have to be a translation entry for each specific number. ew. return [‘score ${ARG1} goals’, self.settings_raw[‘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() → Lstr

Return a name for this particular game instance.

get_instance_scoreboard_display_string() → Lstr

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

classmethod get_settings_display_string(config: dict[str, Any]) → babase.Lstr

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.

classmethod get_supported_maps(sessiontype: type[bascenev1.Session]) → list[str]

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

classmethod get_team_display_string(name: str) → Lstr

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

classmethod getname() → str

Return a str name for this game type.

This default implementation simply returns the ‘name’ class attr.

classmethod getscoreconfig() → bascenev1.ScoreConfig

Return info about game scoring setup; can be overridden by games.

handlemessage(msg: Any) → Any

General message handling; can be passed any message object.

property map: Map

The map being used for this game.

Raises a bascenev1.MapNotFoundError if the map does not currently exist.

name: str | None = None

on_begin() → None

Called once the previous 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_player_join(player: PlayerT) → None

Called when a new bascenev1.Player has joined the Activity.

(including the initial set of Players)

on_transition_in() → None

Called when the Activity is first becoming visible.

Upon this call, the Activity should fade in backgrounds, start playing music, etc. It does not yet have access to players or teams, however. They remain owned by the previous Activity up until bascenev1.Activity.on_begin() is called.

respawn_player(player: PlayerT, respawn_time: float | None = None) → None

Given a bascenev1.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 seconds).

scoreconfig: bascenev1.ScoreConfig | None = None

setup_standard_powerup_drops(enable_tnt: bool = True) → None

Create standard powerup drops for the current map.

setup_standard_time_limit(duration: float) → None

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_kill_points = True

show_zoom_message(message: babase.Lstr, *, color: Sequence[float] = (0.9, 0.4, 0.0), scale: float = 0.8, duration: float = 2.0, trail: bool = False) → None

Zooming text used to announce game names and winners.

spawn_player(player: PlayerT) → bascenev1.Actor

Spawn something for the provided bascenev1.Player.

The default implementation simply calls spawn_player_spaz().

spawn_player_if_exists(player: PlayerT) → None

A utility method which calls self.spawn_player() only if the bascenev1.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(player: PlayerT, position: Sequence[float] = (0, 0, 0), angle: float | None = None) → PlayerSpaz

Create and wire up a bascenev1.PlayerSpaz for the provided Player.

classmethod supports_session_type(sessiontype: type[bascenev1.Session]) → bool

Return whether this game supports the provided Session type.

tips: list[str | bascenev1.GameTip] = []

class bascenev1.GameResults

Bases: object

Results for a completed game.

Category: Gameplay Classes

Upon completion, a game should fill one of these out and pass it to its bascenev1.Activity.end call.

get_sessionteam_score(sessionteam: bascenev1.SessionTeam) → int | None

Return the score for a given bascenev1.SessionTeam.

get_sessionteam_score_str(sessionteam: bascenev1.SessionTeam) → babase.Lstr

Return the score for the given session-team as an Lstr.

(properly formatted for the score type.)

has_score_for_sessionteam(sessionteam: bascenev1.SessionTeam) → bool

Return whether there is a score for a given session-team.

property lower_is_better: bool

Whether lower scores are better.

property playerinfos: list[bascenev1.PlayerInfo]

Get info about the players represented by the results.

property score_label: str

The label associated with scores (‘points’, etc).

property scoretype: bascenev1.ScoreType

The type of score.

property sessionteams: list[bascenev1.SessionTeam]

Return all bascenev1.SessionTeams in the results.

set_game(game: bascenev1.GameActivity) → None

Set the game instance these results are applying to.

set_team_score(team: bascenev1.Team, score: int | None) → None

Set the score for a given team.

This can be a number or None. (see the none_is_winner arg in the constructor)

property winnergroups: list[WinnerGroup]

Get an ordered list of winner groups.

property winning_sessionteam: bascenev1.SessionTeam | None

The winning SessionTeam if there is exactly one, or else None.

class bascenev1.GameTip(text: str, icon: bascenev1.Texture | None = None, sound: bascenev1.Sound | None = None)

Bases: object

Defines a tip presentable to the user at the start of a game.

Category: Gameplay Classes

icon: bascenev1.Texture | None = None

sound: bascenev1.Sound | None = None

text: str

class bascenev1.HitMessage(*, srcnode: bascenev1.Node | None = None, pos: Sequence[float] | None = None, velocity: Sequence[float] | None = None, magnitude: float = 1.0, velocity_magnitude: float = 0.0, radius: float = 1.0, source_player: bascenev1.Player | None = None, kick_back: float = 1.0, flat_damage: float | None = None, hit_type: str = 'generic', force_direction: Sequence[float] | None = None, hit_subtype: str = 'default')

Bases: object

Tells an object it has been hit in some way.

Category: Message Classes

This is used by punches, explosions, etc to convey their effect to a target.

get_source_player(playertype: type[PlayerT]) → PlayerT | None

Return the source-player if one exists and is the provided type.

class bascenev1.HostInfo(name: str, build_number: int, address: str | None, port: int | None)

Bases: object

Info about a host.

address: str | None

build_number: int

name: str

port: int | None

class bascenev1.ImpactDamageMessage(intensity: float)

Bases: object

Tells an object that it has been jarred violently.

Category: Message Classes

intensity: float

class bascenev1.InputDevice

Bases: object

An input-device such as a gamepad, touchscreen, or keyboard.

Category: Gameplay Classes

allows_configuring: bool

Whether the input-device can be configured in the app.

allows_configuring_in_system_settings: bool

Whether the input-device can be configured in the system. setings app. This can be used to redirect the user to go there if they attempt to configure the device.

client_id: int

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

detach_from_player() → None

Detach the device from any player it is controlling.

This applies both to local players and remote players.

exists() → bool

Return whether the underlying device for this object is still present.

get_axis_name(axis_id: int) → str

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

Can return an empty string if the value is not meaningful to humans.

get_button_name(button_id: int) → babase.Lstr

Given a button ID, return a human-readable name for that key/button.

Can return an empty string if the value is not meaningful to humans.

get_default_player_name() → str

(internal)

Returns the default player name for this device. (used for the ‘random’ profile)

get_player_profiles() → dict

(internal)

get_v1_account_name(full: bool) → str

Returns the account name associated with this device.

(can be used to get account names for remote players)

has_meaningful_button_names: bool

Whether button names returned by this instance match labels on the actual device. (Can be used to determine whether to show them in controls-overlays, etc.).

id: int

The unique numeric id of this device.

instance_number: int

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

is_attached_to_player() → bool

Return whether this device is controlling a player of some sort.

This can mean either a local player or a remote player.

is_controller_app: bool

Whether this input-device represents a locally-connected controller-app.

is_remote_client: bool

Whether this input-device represents a remotely-connected client.

is_test_input: bool

Whether this input-device is a dummy device for testing.

name: str

The name of the device.

player: bascenev1.SessionPlayer | None

The player associated with this input device.

unique_identifier: str

A string that can be used to persistently identify the device, even among other devices of the same type. Used for saving prefs, etc.

class bascenev1.InputType(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Types of input a controller can send to the game.

Category: Enums

BOMB_PRESS = 8

BOMB_RELEASE = 9

DOWN_PRESS = 25

DOWN_RELEASE = 26

FLY_PRESS = 13

FLY_RELEASE = 14

HOLD_POSITION_PRESS = 17

HOLD_POSITION_RELEASE = 18

JUMP_PRESS = 4

JUMP_RELEASE = 5

LEFT_PRESS = 19

LEFT_RELEASE = 20

LEFT_RIGHT = 3

PICK_UP_PRESS = 10

PICK_UP_RELEASE = 11

PUNCH_PRESS = 6

PUNCH_RELEASE = 7

RIGHT_PRESS = 21

RIGHT_RELEASE = 22

RUN = 12

START_PRESS = 15

START_RELEASE = 16

UP_DOWN = 2

UP_PRESS = 23

UP_RELEASE = 24

class bascenev1.IntChoiceSetting(name: str, default: int, choices: list[tuple[str, int]])

Bases: ChoiceSetting

An int setting with multiple choices.

Category: Settings Classes

choices: list[tuple[str, int]]

default: int

class bascenev1.IntSetting(name: str, default: int, min_value: int = 0, max_value: int = 9999, increment: int = 1)

Bases: Setting

An integer game setting.

Category: Settings Classes

default: int

increment: int = 1

max_value: int = 9999

min_value: int = 0

class bascenev1.JoinActivity(settings: dict)

Bases: Activity[EmptyPlayer, EmptyTeam]

Standard activity for waiting for players to join.

It shows tips and other info and waits for all players to check ready.

on_transition_in() → None

Called when the Activity is first becoming visible.

Upon this call, the Activity should fade in backgrounds, start playing music, etc. It does not yet have access to players or teams, however. They remain owned by the previous Activity up until bascenev1.Activity.on_begin() is called.

class bascenev1.Level(name: str, gametype: type[bascenev1.GameActivity], settings: dict, preview_texture_name: str, *, displayname: str | None = None)

Bases: object

An entry in a bascenev1.Campaign.

Category: Gameplay Classes

property campaign: bascenev1.Campaign | None

The baclassic.Campaign this Level is associated with, or None.

property complete: bool

Whether this Level has been completed.

property displayname: bascenev1.Lstr

The localized name for this Level.

property gametype: type[bascenev1.GameActivity]

The type of game used for this Level.

get_high_scores() → dict

Return the current high scores for this Level.

get_score_version_string() → str

Return the score version string for this Level.

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

get_settings() → dict[str, Any]

Returns the settings for this Level.

property index: int

The zero-based index of this Level in its baclassic.Campaign.

Access results in a RuntimeError if the Level is not assigned to a Campaign.

property name: str

The unique name for this Level.

property preview_texture_name: str

The preview texture name for this Level.

property rating: float

The current rating for this Level.

set_campaign(campaign: bascenev1.Campaign, index: int) → None

For use by baclassic.Campaign when adding levels to itself.

(internal)

set_complete(val: bool) → None

Set whether or not this level is complete.

set_high_scores(high_scores: dict) → None

Set high scores for this level.

set_rating(rating: float) → None

Set a rating for this Level, replacing the old ONLY IF higher.

class bascenev1.Lobby

Bases: object

Container for baclassic.Choosers.

Category: Gameplay Classes

add_chooser(sessionplayer: bascenev1.SessionPlayer) → None

Add a chooser to the lobby for the provided player.

check_all_ready() → bool

Return whether all choosers are marked ready.

create_join_info() → JoinInfo

Create a display of on-screen information for joiners.

(how to switch teams, players, etc.) Intended for use in initial joining-screens.

get_choosers() → list[Chooser]

Return the lobby’s current choosers.

property next_add_team: int

(internal)

reload_profiles() → None

Reload available player profiles.

remove_all_choosers() → None

Remove all choosers without kicking players.

This is called after all players check in and enter a game.

remove_all_choosers_and_kick_players() → None

Remove all player choosers and kick attached players.

remove_chooser(player: bascenev1.SessionPlayer) → None

Remove a single player’s chooser; does not kick them.

This is used when a player enters the game and no longer needs a chooser.

property sessionteams: list[bascenev1.SessionTeam]

bascenev1.SessionTeams available in this lobby.

update_positions() → None

Update positions for all choosers.

property use_team_colors: bool

A bool for whether this lobby is using team colors.

If False, inidividual player colors are used instead.

class bascenev1.Lstr(*args: Any, **keywds: Any)

Bases: object

Used to define strings in a language-independent way.

Category: General Utility Classes

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 legacy.ballistica.net/translate.

##### Examples EXAMPLE 1: specify a string from a resource path >>> mynode.text = babase.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 = babase.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 = babase.Lstr(value=’${A} / ${B}’, … subs=[(‘${A}’, str(score)), (‘${B}’, str(total))])

EXAMPLE 4: babase.Lstr’s 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 = babase.Lstr( … resource=’res_a’, … subs=[(‘${NAME}’, babase.Lstr(resource=’res_b’))])

evaluate() → str

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

static from_json(json_string: str) → babase.Lstr

Given a json string, returns a babase.Lstr. Does no validation.

is_flat_value() → bool

Return whether the Lstr is a ‘flat’ value.

This is defined as a simple string value incorporating no translations, resources, or substitutions. In this case it may be reasonable to replace it with a raw string value, perform string manipulation on it, etc.

class bascenev1.Map(vr_overlay_offset: Sequence[float] | None = None)

Bases: Actor

A game map.

Category: Gameplay Classes

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

defs: Any = None

exists() → bool

Returns whether the Actor is still present in a meaningful way.

Note that a dying character should still return True here as long as their corpse is visible; this is about presence, not being ‘alive’ (see bascenev1.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 bascenev1.Actor.autoretain()

The default implementation of this method always return 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_def_bound_box(name: str) → tuple[float, float, float, float, float, float] | None

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

get_def_point(name: str) → Sequence[float] | None

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

get_def_points(name: str) → list[Sequence[float]]

Return a list of named points.

Return as many sequential ones are defined (flag1, flag2, flag3), etc. If none are defined, returns an empty list.

get_ffa_start_position(players: Sequence[bascenev1.Player]) → Sequence[float]

Return a random starting position in one of the FFA spawn areas.

If a list of bascenev1.Player-s is provided; the returned points will be as far from these players as possible.

get_flag_position(team_index: int | None = None) → Sequence[float]

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)

classmethod get_music_type() → bascenev1.MusicType | None

Return a music-type string that should be played on this map.

If None is returned, default music will be used.

classmethod get_play_types() → list[str]

Return valid play types for this map.

classmethod get_preview_texture_name() → str | None

Return the name of the preview texture for this map.

get_start_position(team_index: int) → Sequence[float]

Return a random starting position for the given team index.

classmethod getname() → str

Return the unique name of this map, in English.

handlemessage(msg: Any) → Any

General message handling; can be passed any message object.

is_point_near_edge(point: Vec3, running: bool = False) → bool

Return whether the provided point is near an edge of the map.

Simple bot logic uses this call to determine if they are approaching a cliff or wall. If this returns True they will generally not walk/run any farther away from the origin. If ‘running’ is True, the buffer should be a bit larger.

name = 'Map'

classmethod on_preload() → Any

Called when the map is being preloaded.

It should return any media/data it requires to operate

classmethod preload() → None

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

class bascenev1.Material(label: str | None = None)

Bases: object

An entity applied to game objects to modify collision behavior.

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 bascenev1.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 bascenev1.Material to instantiate a blank material, and then use its babase.Material.add_actions() method to define what the material does.

add_actions(actions: tuple, conditions: tuple | None = 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 bascenev1.Material?

###### (‘they_dont_have_material’, material) > Does the part we’re hitting not have a given bascenev1.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 bascenev1.Node as us?

###### (‘they_are_different_node_than_us’) > Does the part we’re hitting belong to a different bascenev1.Node?

##### 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 babase.Node.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 each other 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 bascenev1.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 bascenev1.Sound, a target-impulse, and a volume.

###### (‘skid_sound’, sound, targetImpulse, volume) > Plays a sound during a collision when parts are ‘scraping’ against each other. Provide a bascenev1.Sound, a target-impulse, and a volume.

###### (‘roll_sound’, sound, targetImpulse, volume) > Plays a sound during a collision when parts are ‘rolling’ against each other. Provide a bascenev1.Sound, a target-impulse, and a volume.

##### Examples 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 = bascenev1.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 bascenev1.DieMessage to anything we touch, but cause no physical response. This should cause any bascenev1.Actor to drop dead: >>> m = bascenev1.Material() … m.add_actions( … actions=((‘modify_part_collision’, ‘physical’, False), … (‘message’, ‘their_node’, ‘at_connect’, … bascenev1.DieMessage())))

Example 3: play some sounds when we’re contacting the ground: >>> m = bascenev1.Material() … m.add_actions( … conditions=(‘they_have_material’, shared.footing_material), … actions=(

(‘impact_sound’, bascenev1.getsound(‘metalHit’), 2, 5), (‘skid_sound’, bascenev1.getsound(‘metalSkid’), 2, 5)))

label: str

A label for the material; only used for debugging.

class bascenev1.Mesh

Bases: object

A reference to a mesh.

Category: Asset Classes

Meshes are used for drawing. Use bascenev1.getmesh() to instantiate one.

class bascenev1.MultiTeamSession

Bases: Session

Common base for DualTeamSession and FreeForAllSession.

Category: Gameplay Classes

Free-for-all-mode is essentially just teams-mode with each bascenev1.Player having their own bascenev1.Team, so there is much overlap in functionality.

announce_game_results(activity: bascenev1.GameActivity, results: bascenev1.GameResults, delay: float, announce_winning_team: bool = True) → None

Show basic game result 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() → int

Return free-for-all series length.

get_game_number() → int

Returns which game in the series is currently being played.

get_max_players() → int

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

get_next_game_description() → Lstr

Returns a description of the next game on deck.

get_series_length() → int

Return teams series length.

on_activity_end(activity: bascenev1.Activity, results: Any) → None

Called when the current bascenev1.Activity has ended.

The bascenev1.Session should look at the results and start another bascenev1.Activity.

on_team_join(team: bascenev1.SessionTeam) → None

Called when a new bascenev1.Team joins the session.

class bascenev1.MusicType(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Types of music available to play in-game.

Category: Enums

These do not correspond to specific pieces of music, but rather to ‘situations’. The actual music played for each type can be overridden by the game or by the user.

CHAR_SELECT = 'CharSelect'

CHOSEN_ONE = 'Chosen One'

EPIC = 'Epic'

EPIC_RACE = 'Epic Race'

FLAG_CATCHER = 'FlagCatcher'

FLYING = 'Flying'

FOOTBALL = 'Football'

FORWARD_MARCH = 'ForwardMarch'

GRAND_ROMP = 'GrandRomp'

HOCKEY = 'Hockey'

KEEP_AWAY = 'Keep Away'

MARCHING = 'Marching'

MENU = 'Menu'

ONSLAUGHT = 'Onslaught'

RACE = 'Race'

RUN_AWAY = 'RunAway'

SCARY = 'Scary'

SCORES = 'Scores'

SPORTS = 'Sports'

SURVIVAL = 'Survival'

TO_THE_DEATH = 'ToTheDeath'

VICTORY = 'Victory'

class bascenev1.Node

Bases: object

Reference to a Node; the low level building block of a game.

Category: Gameplay Classes

At its core, a game is nothing more than a scene of Nodes with attributes getting interconnected or set over time.

A bascenev1.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 Python references to it exist. To explicitly add a new node to the game, use bascenev1.newnode(), and to explicitly delete one,

use bascenev1.Node.delete().

babase.Node.exists() can be used to determine if a Node still points to a live node in the game.

You can use ba.Node(None) to instantiate an invalid Node reference (sometimes used as attr values/etc).

add_death_action(action: Callable[[], None]) → 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.

allow_kick_idle_players: bool = False

always_show_health_bar: bool = False

ambient_color: Sequence[float] = (1.0, 1.0, 1.0)

area_of_interest_bounds: Sequence[float] = (-1, -1, -1, 1, 1, 1)

billboard_cross_out: bool = False

billboard_opacity: float = 0.0

billboard_texture: bascenev1.Texture | None = None

bomb_pressed: bool = False

boxing_gloves: bool = False

boxing_gloves_flashing: bool = False

camera_mode: str = 'rotate'

client_only: bool = False

color: Sequence[float] = (0.0, 0.0, 0.0)

connectattr(srcattr: str, dstnode: Node, dstattr: str) → 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 = bascenev1.newnode(‘light’) … loc = bascenev1.newnode(‘locator’, attrs={‘position’: (0, 10, 0)}) … loc.connectattr(‘position’, light, ‘position’)

counter_text: str = ''

counter_texture: bascenev1.Texture | None = None

curse_death_time: int = 0

damage: int = 0

damage_smoothed: float = 0.0

dead: bool = False

debris_friction: float = 0.0

debris_kill_height: float = 0.0

delete(ignore_missing: bool = True) → None

Delete the node. Ignores already-deleted nodes if ignore_missing is True; otherwise a bascenev1.NodeNotFoundError is thrown.

exists() → bool

Returns whether the Node still exists. Most functionality will fail on a nonexistent 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.

extras_material: Sequence[bascenev1.Material] = ()

flashing: bool = False

floor_reflection: bool = False

fly_pressed: bool = False

frozen: bool = False

getdelegate(type: type[_T], doraise: Literal[False] = False) → _T | None

getdelegate(type: type[_T], doraise: Literal[True]) → _T

Return the node’s current delegate object if it matches a certain type.

If the node has no delegate or it is not an instance of the passed type, then None will be returned. If ‘doraise’ is True, then an babase.DelegateNotFoundError will be raised instead.

getname() → str

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

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

bascenev1.Node)

gravity_scale: float = 1.0

handlemessage(*args: Any) → None

General message handling; can be passed any message object.

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

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

happy_thoughts_mode: bool = False

hockey: bool = False

hold_body: int = 0

hold_node: bascenev1.Node | None = None

hold_position_pressed: bool = False

host_only: bool = False

hurt: float = 0.0

input0: float = 0.0

input1: float = 0.0

input2: float = 0.0

input3: float = 0.0

invincible: bool = False

is_area_of_interest: bool = False

jump_pressed: bool = False

knockout: float = 0.0

loop: bool = False

materials: Sequence[bascenev1.Material] = ()

mesh_opaque: bascenev1.Mesh | None = None

mesh_transparent: bascenev1.Mesh | None = None

mini_billboard_1_end_time: int = 0

mini_billboard_1_start_time: int = 0

mini_billboard_1_texture: bascenev1.Texture | None = None

mini_billboard_2_end_time: int = 0

mini_billboard_2_start_time: int = 0

mini_billboard_2_texture: bascenev1.Texture | None = None

mini_billboard_3_end_time: int = 0

mini_billboard_3_start_time: int = 0

mini_billboard_3_texture: bascenev1.Texture | None = None

move_left_right: float = 0.0

move_up_down: float = 0.0

music: str = ''

music_continuous: bool = False

music_count: int = 0

name: str = ''

name_color: Sequence[float] = (0.0, 0.0, 0.0)

offset: float = 0.0

opacity: float = 0.0

paused: bool = False

pickup_materials: Sequence[bascenev1.Material] = ()

pickup_pressed: bool = False

position: Sequence[float] = (0.0, 0.0, 0.0)

position_center: Sequence[float] = (0.0, 0.0, 0.0)

position_forward: Sequence[float] = (0.0, 0.0, 0.0)

premultiplied: bool = False

punch_materials: Sequence[bascenev1.Material] = ()

punch_momentum_angular: float = 0.0

punch_momentum_linear: Sequence[float] = (0.0, 0.0, 0.0)

punch_position: Sequence[float] = (0.0, 0.0, 0.0)

punch_power: float = 0.0

punch_pressed: bool = False

punch_velocity: Sequence[float] = (0.0, 0.0, 0.0)

rate: int = 0

roller_materials: Sequence[bascenev1.Material] = ()

rotate: float = 0.0

run: float = 0.0

scale: float | Sequence[float] = 0.0

shadow_offset: Sequence[float] = (0.0, 0.0)

shadow_ortho: bool = False

shadow_range: Sequence[float] = (0, 0, 0, 0)

shattered: int = 0

size: Sequence[float] = (0.0, 0.0, 0.0)

slow_motion: bool = False

source_player: bascenev1.Player | None = None

stick_to_owner: bool = False

text: babase.Lstr | str = ''

texture: bascenev1.Texture | None = None

time: int = 0

time1: int = 0

time2: int = 0

timemax: int = 0

times: Sequence[int] = (1, 2, 3, 4, 5)

tint: Sequence[float] = (1.0, 1.0, 1.0)

tint2_color: Sequence[float] = (0.0, 0.0, 0.0)

tint_color: Sequence[float] = (0.0, 0.0, 0.0)

tint_texture: bascenev1.Texture | None = None

use_fixed_vr_overlay: bool = False

values: Sequence[float] = (1.0, 2.0, 3.0, 4.0)

velocity: Sequence[float] = (0.0, 0.0, 0.0)

vignette_inner: Sequence[float] = (0.0, 0.0)

vignette_outer: Sequence[float] = (0.0, 0.0)

vr_camera_offset: Sequence[float] = (0.0, 0.0, 0.0)

vr_depth: float = 0.0

vr_near_clip: float = 0.0

vr_overlay_center: Sequence[float] = (0.0, 0.0, 0.0)

vr_overlay_center_enabled: bool = False

class bascenev1.NodeActor(node: bascenev1.Node)

Bases: Actor

A simple bascenev1.Actor type that wraps a single bascenev1.Node.

Category: Gameplay Classes

This Actor will delete its Node when told to die, and it’s exists() call will return whether the Node still exists or not.

exists() → bool

Returns whether the Actor is still present in a meaningful way.

Note that a dying character should still return True here as long as their corpse is visible; this is about presence, not being ‘alive’ (see bascenev1.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 bascenev1.Actor.autoretain()

The default implementation of this method always return 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.

handlemessage(msg: Any) → Any

General message handling; can be passed any message object.

exception bascenev1.NodeNotFoundError

Bases: NotFoundError

Exception raised when an expected Node does not exist.

Category: Exception Classes

exception bascenev1.NotFoundError

Bases: Exception

Exception raised when a referenced object does not exist.

Category: Exception Classes

class bascenev1.OutOfBoundsMessage

Bases: object

A message telling an object that it is out of bounds.

Category: Message Classes

class bascenev1.PickUpMessage(node: bascenev1.Node)

Bases: object

Tells an object that it has picked something up.

Category: Message Classes

node: bascenev1.Node

class bascenev1.PickedUpMessage(node: bascenev1.Node)

Bases: object

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

Category: Message Classes

node: bascenev1.Node

class bascenev1.Player

Bases: Generic[TeamT]

A player in a specific bascenev1.Activity.

Category: Gameplay Classes

These correspond to bascenev1.SessionPlayer objects, but are associated with a single bascenev1.Activity instance. This allows activities to specify their own custom bascenev1.Player types.

actor: bascenev1.Actor | None

assigninput(inputtype: babase.InputType | tuple[babase.InputType, ...], call: Callable) → None

Set the python callable to be run for one or more types of input.

character: str

color: Sequence[float]

property customdata: dict

Arbitrary values associated with the player. Though it is encouraged that most player values be properly defined on the bascenev1.Player subclass, it may be useful for player-agnostic objects to store values here. This dict is cleared when the player leaves or expires so objects stored here will be disposed of at the expected time, unlike the Player instance itself which may continue to be referenced after it is no longer part of the game.

exists() → bool

Whether the underlying player still exists.

This will return False if the underlying bascenev1.SessionPlayer has left the game or if the bascenev1.Activity this player was associated with has ended. Most functionality will fail on a nonexistent 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.

expire() → None

Called when the Player is expiring (when its Activity does so).

(internal)

get_icon() → dict[str, Any]

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

getname(full: bool = False, icon: bool = True) → str

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

highlight: Sequence[float]

is_alive() → bool

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

leave() → None

Called when the Player leaves a running game.

(internal)

property node: bascenev1.Node

A bascenev1.Node of type ‘player’ associated with this Player.

This node can be used to get a generic player position/etc.

on_expire() → None

Can be overridden to handle player expiration.

The player expires when the Activity it is a part of expires. Expired players should no longer run any game logic (which will likely error). They should, however, remove any references to players/teams/games/etc. which could prevent them from being freed.

property position: Vec3

The position of the player, as defined by its bascenev1.Actor.

If the player currently has no actor, raises a babase.ActorNotFoundError.

postinit(sessionplayer: bascenev1.SessionPlayer) → None

Wire up a newly created player.

(internal)

resetinput() → None

Clears out the player’s assigned input actions.

property sessionplayer: bascenev1.SessionPlayer

Return the bascenev1.SessionPlayer corresponding to this Player.

Throws a bascenev1.SessionPlayerNotFoundError if it does not exist.

property team: TeamT

The bascenev1.Team for this player.

class bascenev1.PlayerDiedMessage(player: bascenev1.Player, was_killed: bool, killerplayer: bascenev1.Player | None, how: DeathType)

Bases: object

A message saying a bascenev1.Player has died.

Category: Message Classes

getkillerplayer(playertype: type[PlayerT]) → PlayerT | None

Return the bascenev1.Player responsible for the killing, if any.

Pass the Player type being used by the current game.

getplayer(playertype: type[PlayerT]) → PlayerT

Return the bascenev1.Player that died.

The type of player for the current activity should be passed so that the type-checker properly identifies the returned value as one.

how: DeathType

killed: bool

class bascenev1.PlayerInfo(name: str, character: str)

Bases: object

Holds basic info about a player.

Category: Gameplay Classes

character: str

name: str

exception bascenev1.PlayerNotFoundError

Bases: NotFoundError

Exception raised when an expected player does not exist.

Category: Exception Classes

class bascenev1.PlayerProfilesChangedMessage

Bases: object

Signals player profiles may have changed and should be reloaded.

class bascenev1.PlayerRecord(name: str, name_full: str, sessionplayer: bascenev1.SessionPlayer, stats: bascenev1.Stats)

Bases: object

Stats for an individual player in a bascenev1.Stats object.

Category: Gameplay Classes

This does not necessarily correspond to a bascenev1.Player that is still present (stats may be retained for players that leave mid-game)

associate_with_sessionplayer(sessionplayer: bascenev1.SessionPlayer) → None

Associate this entry with a bascenev1.SessionPlayer.

cancel_multi_kill_timer() → None

Cancel any multi-kill timer for this player entry.

character: str

get_icon() → dict[str, Any]

Get the icon for this instance’s player.

get_last_sessionplayer() → bascenev1.SessionPlayer

Return the last bascenev1.Player we were associated with.

getactivity() → bascenev1.Activity | None

Return the bascenev1.Activity this instance is associated with.

Returns None if the activity no longer exists.

getname(full: bool = False) → str

Return the player entry’s name.

property player: bascenev1.SessionPlayer

Return the instance’s associated bascenev1.SessionPlayer.

Raises a bascenev1.SessionPlayerNotFoundError if the player no longer exists.

submit_kill(showpoints: bool = True) → None

Submit a kill for this player entry.

property team: bascenev1.SessionTeam

The bascenev1.SessionTeam the last associated player was last on.

This can still return a valid result even if the player is gone. Raises a bascenev1.SessionTeamNotFoundError if the team no longer exists.

class bascenev1.PlayerScoredMessage(score: int)

Bases: object

Informs something that a bascenev1.Player scored.

Category: Message Classes

score: int

class bascenev1.Plugin

Bases: object

A plugin to alter app behavior in some way.

Category: App Classes

Plugins are discoverable by the meta-tag system and the user can select which ones they want to enable. Enabled plugins are then called at specific times as the app is running in order to modify its behavior in some way.

has_settings_ui() → bool

Called to ask if we have settings UI we can show.

on_app_running() → None

Called when the app reaches the running state.

on_app_shutdown() → None

Called when the app is beginning the shutdown process.

on_app_shutdown_complete() → None

Called when the app has completed the shutdown process.

on_app_suspend() → None

Called when the app enters the suspended state.

on_app_unsuspend() → None

Called when the app exits the suspended state.

show_settings_ui(source_widget: Any | None) → None

Called to show our settings UI.

class bascenev1.PowerupAcceptMessage

Bases: object

A message informing a bascenev1.Powerup that it was accepted.

Category: Message Classes

This is generally sent in response to a bascenev1.PowerupMessage to inform the box (or whoever granted it) that it can go away.

class bascenev1.PowerupMessage(poweruptype: str, sourcenode: bascenev1.Node | None = None)

Bases: object

A message telling an object to accept a powerup.

Category: Message Classes

This message is normally received by touching a bascenev1.PowerupBox.

poweruptype: str

sourcenode: bascenev1.Node | None = None

class bascenev1.ScoreConfig(label: str = 'Score', scoretype: bascenev1.ScoreType = ScoreType.POINTS, lower_is_better: bool = False, none_is_winner: bool = False, version: str = '')

Bases: object

Settings for how a game handles scores.

Category: Gameplay Classes

label: str = 'Score'

lower_is_better: bool = False

none_is_winner: bool = False

scoretype: bascenev1.ScoreType = 'p'

version: str = ''

class bascenev1.ScoreScreenActivity(settings: dict)

Bases: Activity[EmptyPlayer, EmptyTeam]

A standard score screen that fades in and shows stuff for a while.

After a specified delay, player input is assigned to end the activity.

default_music: MusicType | None = 'Scores'

inherits_tint = True

inherits_vr_camera_offset = True

on_begin() → None

Called once the previous 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_player_join(player: EmptyPlayer) → None

Called when a new bascenev1.Player has joined the Activity.

(including the initial set of Players)

on_transition_in() → None

Called when the Activity is first becoming visible.

Upon this call, the Activity should fade in backgrounds, start playing music, etc. It does not yet have access to players or teams, however. They remain owned by the previous Activity up until bascenev1.Activity.on_begin() is called.

transition_time = 0.5

use_fixed_vr_overlay = True

class bascenev1.ScoreType(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Type of scores.

Category: Enums

MILLISECONDS = 'ms'

POINTS = 'p'

SECONDS = 's'

class bascenev1.Session(depsets: Sequence[bascenev1.DependencySet], *, team_names: Sequence[str] | None = None, team_colors: Sequence[Sequence[float]] | None = None, min_players: int = 1, max_players: int = 8, submit_score: bool = True)

Bases: object

Defines a high level series of bascenev1.Activity-es.

Category: Gameplay Classes

Examples of sessions are bascenev1.FreeForAllSession, bascenev1.DualTeamSession, and bascenev1.CoopSession.

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

begin_next_activity() → None

Called once the previous activity has been totally torn down.

This means we’re ready to begin the next one

property context: bascenev1.ContextRef

A context-ref pointing at this activity.

customdata: dict

end() → None

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.

end_activity(activity: bascenev1.Activity, results: Any, delay: float, force: bool) → None

Commence shutdown of a bascenev1.Activity (if not already occurring).

‘delay’ is the time delay before the Activity actually ends (in seconds). 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.

get_custom_menu_entries() → list[dict[str, Any]]

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.

getactivity() → bascenev1.Activity | None

Return the current foreground activity for this session.

handlemessage(msg: Any) → Any

General message handling; can be passed any message object.

lobby: bascenev1.Lobby

max_players: int

min_players: int

on_activity_end(activity: bascenev1.Activity, results: Any) → None

Called when the current bascenev1.Activity has ended.

The bascenev1.Session should look at the results and start another bascenev1.Activity.

on_player_leave(sessionplayer: bascenev1.SessionPlayer) → None

Called when a previously-accepted bascenev1.SessionPlayer leaves.

on_player_request(player: bascenev1.SessionPlayer) → bool

Called when a new bascenev1.Player wants to join the Session.

This should return True or False to accept/reject.

on_team_join(team: bascenev1.SessionTeam) → None

Called when a new bascenev1.Team joins the session.

on_team_leave(team: bascenev1.SessionTeam) → None

Called when a bascenev1.Team is leaving the session.

property sessionglobalsnode: bascenev1.Node

The sessionglobals bascenev1.Node for the session.

sessionplayers: list[bascenev1.SessionPlayer]

sessionteams: list[bascenev1.SessionTeam]

setactivity(activity: bascenev1.Activity) → None

Assign a new current bascenev1.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.setactivity(foo) and then bascenev1.newnode() to add a node to foo)

should_allow_mid_activity_joins(activity: bascenev1.Activity) → bool

Ask ourself if we should allow joins during an Activity.

Note that for a join to be allowed, both the Session and Activity have to be ok with it (via this function and the Activity.allow_mid_activity_joins property.

transitioning_out_activity_was_freed(can_show_ad_on_death: bool) → None

(internal)

use_team_colors: bool = True

use_teams: bool = False

class bascenev1.SessionData

Bases: object

(internal)

context() → bascenev1.ContextRef

Return a context-ref pointing to the session.

exists() → bool

Returns whether the SessionData still exists. Most functionality will fail on a nonexistent instance.

class bascenev1.SessionPlayer

Bases: object

A reference to a player in the bascenev1.Session.

Category: Gameplay Classes

These are created and managed internally and provided to your bascenev1.Session/bascenev1.Activity instances. Be aware that, like `ba.Node`s, bascenev1.SessionPlayer objects are ‘weak’ references under-the-hood; a player can leave the game at

any point. For this reason, you should make judicious use of the

babase.SessionPlayer.exists() method (or boolean operator) to ensure that a SessionPlayer is still present if retaining references to one for any length of time.

activityplayer: bascenev1.Player | None

The current game-specific instance for this player.

assigninput(type: bascenev1.InputType | tuple[bascenev1.InputType, ...], call: Callable) → None

Set the python callable to be run for one or more types of input.

character: str

The character this player has selected in their profile.

color: Sequence[float]

The base color for this Player. In team games this will match the bascenev1.SessionTeam’s color.

exists() → bool

Return whether the underlying player is still in the game.

get_icon() → dict[str, Any]

Returns the character’s icon (images, colors, etc contained in a dict.

get_icon_info() → dict[str, Any]

(internal)

get_v1_account_id() → str

Return the V1 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).

getname(full: bool = False, icon: bool = True) → str

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

highlight: Sequence[float]

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.

id: int

The unique numeric ID of the 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.

in_game: bool

This bool value will be True once the Player has completed any lobby character/team selection.

inputdevice: bascenev1.InputDevice

The input device associated with the player.

remove_from_game() → None

Removes the player from the game.

resetinput() → None

Clears out the player’s assigned input actions.

sessionteam: bascenev1.SessionTeam

The bascenev1.SessionTeam this Player is on. If the SessionPlayer is still in its lobby selecting a team/etc. then a bascenev1.SessionTeamNotFoundError will be raised.

set_icon_info(texture: str, tint_texture: str, tint_color: Sequence[float], tint2_color: Sequence[float]) → None

(internal)

setactivity(activity: bascenev1.Activity | None) → None

(internal)

setdata(team: bascenev1.SessionTeam, character: str, color: Sequence[float], highlight: Sequence[float]) → None

(internal)

setname(name: str, full_name: str | None = None, real: bool = True) → 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.

setnode(node: bascenev1.Node | None) → None

(internal)

class bascenev1.SessionTeam(team_id: int = 0, name: babase.Lstr | str = '', color: Sequence[float] = (1.0, 1.0, 1.0))

Bases: object

A team of one or more bascenev1.SessionPlayers.

Category: Gameplay Classes

Note that a SessionPlayer always has a SessionTeam; in some cases, such as free-for-all bascenev1.Sessions, each SessionTeam consists of just one SessionPlayer.

color: tuple[float, ...]

customdata: dict

id: int

leave() → None

(internal)

name: babase.Lstr | str

players: list[bascenev1.SessionPlayer]

class bascenev1.Setting(name: str, default: Any)

Bases: object

Defines a user-controllable setting for a game or other entity.

Category: Gameplay Classes

default: Any

name: str

class bascenev1.ShouldShatterMessage

Bases: object

Tells an object that it should shatter.

Category: Message Classes

class bascenev1.Sound

Bases: object

A reference to a sound.

Category: Asset Classes

Use bascenev1.getsound() to instantiate one.

play(volume: float = 1.0, position: Sequence[float] | None = None, host_only: bool = False) → None

Play the sound a single time.

Category: Gameplay Functions

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

class bascenev1.StandLocation(position: Vec3, angle: float | None = None)

Bases: object

Describes a point in space and an angle to face.

Category: Gameplay Classes

angle: float | None = None

position: babase.Vec3

class bascenev1.StandMessage(position: Sequence[float] = (0.0, 0.0, 0.0), angle: float = 0.0)

Bases: object

A message telling an object to move to a position in space.

Category: Message Classes

Used when teleporting players to home base, etc.

angle: float = 0.0

position: Sequence[float] = (0.0, 0.0, 0.0)

class bascenev1.Stats

Bases: object

Manages scores and statistics for a bascenev1.Session.

Category: Gameplay Classes

get_records() → dict[str, bascenev1.PlayerRecord]

Get PlayerRecord corresponding to still-existing players.

getactivity() → bascenev1.Activity | None

Get the activity associated with this instance.

May return None.

player_scored(player: bascenev1.Player, base_points: int = 1, *, target: Sequence[float] | None = None, kill: bool = False, victim_player: bascenev1.Player | None = None, scale: float = 1.0, color: Sequence[float] | None = None, title: str | babase.Lstr | None = None, screenmessage: bool = True, display: bool = True, importance: int = 1, showpoints: bool = True, big_message: bool = False) → int

Register a score for the player.

Return value is actual score with multipliers and such factored in.

player_was_killed(player: bascenev1.Player, killed: bool = False, killer: bascenev1.Player | None = None) → None

Should be called when a player is killed.

register_sessionplayer(player: bascenev1.SessionPlayer) → None

Register a bascenev1.SessionPlayer with this score-set.

reset() → None

Reset the stats instance completely.

reset_accum() → None

Reset per-sound sub-scores.

setactivity(activity: bascenev1.Activity | None) → None

Set the current activity for this instance.

class bascenev1.Team

Bases: Generic[PlayerT]

A team in a specific bascenev1.Activity.

Category: Gameplay Classes

These correspond to bascenev1.SessionTeam objects, but are created per activity so that the activity can use its own custom team subclass.

color: tuple[float, ...]

property customdata: dict

Arbitrary values associated with the team. Though it is encouraged that most player values be properly defined on the bascenev1.Team subclass, it may be useful for player-agnostic objects to store values here. This dict is cleared when the team leaves or expires so objects stored here will be disposed of at the expected time, unlike the Team instance itself which may continue to be referenced after it is no longer part of the game.

expire() → None

Called when the Team is expiring (due to the Activity expiring).

(internal)

id: int

leave() → None

Called when the Team leaves a running game.

(internal)

manual_init(team_id: int, name: Lstr | str, color: tuple[float, ...]) → None

Manually init a team for uses such as bots.

name: babase.Lstr | str

on_expire() → None

Can be overridden to handle team expiration.

players: list[PlayerT]

postinit(sessionteam: SessionTeam) → None

Wire up a newly created SessionTeam.

(internal)

property sessionteam: SessionTeam

Return the bascenev1.SessionTeam corresponding to this Team.

Throws a babase.SessionTeamNotFoundError if there is none.

class bascenev1.TeamGameActivity(settings: dict)

Bases: GameActivity[PlayerT, TeamT]

Base class for teams and free-for-all mode games.

Category: Gameplay Classes

(Free-for-all is essentially just a special case where every bascenev1.Player has their own bascenev1.Team)

end(results: Any = None, announce_winning_team: bool = True, announce_delay: float = 0.1, force: bool = False) → None

End the game and announce the single winning team unless ‘announce_winning_team’ is False. (for results without a single most-important winner).

on_begin() → None

Called once the previous 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() → None

Called when the Activity is first becoming visible.

Upon this call, the Activity should fade in backgrounds, start playing music, etc. It does not yet have access to players or teams, however. They remain owned by the previous Activity up until bascenev1.Activity.on_begin() is called.

spawn_player_spaz(player: PlayerT, position: Sequence[float] | None = None, angle: float | None = None) → PlayerSpaz

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

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

classmethod supports_session_type(sessiontype: type[bascenev1.Session]) → bool

Class method override; returns True for ba.DualTeamSessions and ba.FreeForAllSessions; False otherwise.

class bascenev1.Texture

Bases: object

A reference to a texture.

Category: Asset Classes

Use bascenev1.gettexture() to instantiate one.

class bascenev1.ThawMessage

Bases: object

Tells an object to stop being frozen.

Category: Message Classes

class bascenev1.Timer(time: float, call: Callable[[], Any], repeat: bool = False)

Bases: object

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

Category: General Utility Classes

This class encapsulates a scene-time timer in the current bascenev1.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.

Scene time maps to local simulation time in bascenev1.Activity or bascenev1.Session Contexts. This means that it may progress slower in slow-motion play modes, stop when the game is paused, etc.

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

##### Example

Use a Timer object to print repeatedly for a few seconds: >>> import bascenev1 as bs … def say_it(): … bs.screenmessage(‘BADGER!’) … def stop_saying_it(): … global g_timer … g_timer = None … bs.screenmessage(‘MUSHROOM MUSHROOM!’) … # Create our timer; it will run as long as we have the self.t ref. … g_timer = 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)

class bascenev1.UIScale(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

The overall scale the UI is being rendered for. Note that this is independent of pixel resolution. For example, a phone and a desktop PC might render the game at similar pixel resolutions but the size they display content at will vary significantly.

Category: Enums

‘large’ is used for devices such as desktop PCs where fine details can

be clearly seen. UI elements are generally smaller on the screen and more content can be seen at once.

‘medium’ is used for devices such as tablets, TVs, or VR headsets.

This mode strikes a balance between clean readability and amount of content visible.

‘small’ is used primarily for phones or other small devices where

content needs to be presented as large and clear in order to remain readable from an average distance.

LARGE = 2

MEDIUM = 1

SMALL = 0

class bascenev1.Vec3

class bascenev1.Vec3(value: float)

class bascenev1.Vec3(values: Sequence[float])

class bascenev1.Vec3(x: float, y: float, z: float)

Bases: Sequence[float]

A vector of 3 floats.

Category: General Utility Classes

These can be created the following ways (checked in this order): - with no args, all values are set to 0 - with a single numeric arg, all values are set to that value - with a single three-member sequence arg, sequence values are copied - otherwise assumes individual x/y/z args (positional or keywords)

cross(other: Vec3) → Vec3

Returns the cross product of this vector and another.

dot(other: Vec3) → float

Returns the dot product of this vector and another.

length() → float

Returns the length of the vector.

normalized() → Vec3

Returns a normalized version of the vector.

x: float

The vector’s X component.

y: float

The vector’s Y component.

z: float

The vector’s Z component.

class bascenev1.WeakCall(*args: Any, **keywds: Any)

Bases: object

Wrap a callable and arguments into a single callable object.

Category: General Utility Classes

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.

##### Examples 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() … babase.apptimer(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() … babase.apptimer(5.0, ba.WeakCall(foo.bar)) … foo = None

EXAMPLE C: Wrap a method call with some positional and keyword args: >>> myweakcall = babase.WeakCall(self.dostuff, argval1, … namedarg=argval2) … # Now we have a single callable to run that whole mess. … # The same as calling myobj.dostuff(argval1, namedarg=argval2) … # (provided my_obj still exists; this will do nothing … # otherwise). … myweakcall()

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.

bascenev1.add_clean_frame_callback(call: Callable) → None

(internal)

Provide an object to be called once the next non-progress-bar-frame has been rendered. Useful for queueing things to load in the background without elongating any current progress-bar-load.

bascenev1.animate(node: bascenev1.Node, attr: str, keys: dict[float, float], loop: bool = False, offset: float = 0) → bascenev1.Node

Animate values on a target bascenev1.Node.

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 MILLISECONDS to recreate the old behavior (prior to ba 1.5) of taking milliseconds. Returns the animcurve node.

bascenev1.animate_array(node: bascenev1.Node, attr: str, size: int, keys: dict[float, Sequence[float]], *, loop: bool = False, offset: float = 0) → None

Animate an array of values on a target bascenev1.Node.

Category: Gameplay Functions

Like bs.animate, but operates on array attributes.

bascenev1.apptime() → babase.AppTime

Return the current app-time in seconds.

Category: General Utility Functions

App-time is a monotonic time value; it starts at 0.0 when the app launches and will never jump by large amounts or go backwards, even if the system time changes. Its progression will pause when the app is in a suspended state.

Note that the AppTime returned here is simply float; it just has a unique type in the type-checker’s eyes to help prevent it from being accidentally used with time functionality expecting other time types.

bascenev1.apptimer(time: float, call: Callable[[], Any]) → None

Schedule a callable object to run based on app-time.

Category: General Utility Functions

This function creates a one-off timer which cannot be canceled or modified once created. If you require the ability to do so, or need a repeating timer, use the babase.AppTimer class instead.

##### Arguments ###### time (float) > Length of time in seconds that the timer will wait before firing.

###### call (Callable[[], Any]) > A callable Python object. Note that the timer will retain a strong reference to the callable for as long as the timer exists, so you may want to look into concepts such as babase.WeakCall if that is not desired.

##### Examples Print some stuff through time: >>> babase.screenmessage(‘hello from now!’) >>> babase.apptimer(1.0, babase.Call(babase.screenmessage,

‘hello from the future!’))

>>> babase.apptimer(2.0, babase.Call(babase.screenmessage,
...                       'hello from the future 2!'))

bascenev1.basetime() → bascenev1.BaseTime

Return the base-time in seconds for the current scene-v1 context.

Category: General Utility Functions

Base-time is a time value that progresses at a constant rate for a scene, even when the scene is sped up, slowed down, or paused. It may, however, speed up or slow down due to replay speed adjustments or may slow down if the cpu is overloaded. Note that the value returned here is simply a float; it just has a unique type in the type-checker’s eyes to help prevent it from being accidentally used with time functionality expecting other time types.

bascenev1.basetimer(time: float, call: Callable[[], Any], repeat: bool = False) → None

Schedule a call to run at a later point in scene base-time. Base-time is a value that progresses at a constant rate for a scene,

even when the scene is sped up, slowed down, or paused. It may, however, speed up or slow down due to replay speed adjustments or may slow down if the cpu is overloaded.

Category: General Utility Functions

This function adds a timer to the current scene context. This timer cannot be canceled or modified once created. If you

require the ability to do so, use the bascenev1.BaseTimer class instead.

##### Arguments ###### time (float) > Length of time in seconds that the timer will wait before firing.

###### call (Callable[[], Any]) > A callable Python object. Remember that the timer will retain a strong reference to the callable for the duration of the timer, so you may want to look into concepts such as babase.WeakCall if that is not desired.

###### repeat (bool) > If True, the timer will fire repeatedly, with each successive firing having the same delay as the first.

##### Examples Print some stuff through time: >>> import bascenev1 as bs >>> bs.screenmessage(‘hello from now!’) >>> bs.basetimer(1.0, bs.Call(bs.screenmessage, ‘hello from the future!’)) >>> bs.basetimer(2.0, bs.Call(bs.screenmessage, … ‘hello from the future 2!’))

bascenev1.broadcastmessage(message: str | babase.Lstr, color: Sequence[float] | None = None, top: bool = False, image: dict[str, Any] | None = None, log: bool = False, clients: Sequence[int] | None = None, transient: bool = False) → None

Broadcast a screen-message to clients in the current session.

Category: General Utility Functions

If ‘top’ is True, the message will go to the top message area. For ‘top’ messages, ‘image’ must be a dict containing ‘texture’ and ‘tint_texture’ textures and ‘tint_color’ and ‘tint2_color’ colors. This defines an icon to display alongside the message. If ‘log’ is True, the message will also be submitted to the 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.

bascenev1.cameraflash(duration: float = 999.0) → None

Create a strobing camera flash effect.

Category: Gameplay Functions

(as seen when a team wins a game) Duration is in seconds.

bascenev1.camerashake(intensity: float = 1.0) → None

Shake the camera.

Category: Gameplay Functions

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 as a gameplay cue.

bascenev1.capture_gamepad_input(call: Callable[[dict], None]) → None

(internal)

Add a callable to be called for subsequent gamepad events. The method is passed a dict containing info about the event.

bascenev1.capture_keyboard_input(call: Callable[[dict], None]) → None

(internal)

Add a callable to be called for subsequent keyboard-game-pad events. The method is passed a dict containing info about the event.

bascenev1.chatmessage(message: str | babase.Lstr, clients: Sequence[int] | None = None, sender_override: str | None = None) → None

(internal)

bascenev1.client_info_query_response(token: str, response: Any) → None

(internal)

bascenev1.connect_to_party(address: str, port: int | None = None, print_progress: bool = True) → None

(internal)

bascenev1.disconnect_client(client_id: int, ban_time: int = 300) → bool

(internal)

bascenev1.disconnect_from_host() → None

(internal)

Category: General Utility Functions

bascenev1.displaytime() → babase.DisplayTime

Return the current display-time in seconds.

Category: General Utility Functions

Display-time is a time value intended to be used for animation and other visual purposes. It will generally increment by a consistent amount each frame. It will pass at an overall similar rate to AppTime, but trades accuracy for smoothness.

Note that the value returned here is simply a float; it just has a unique type in the type-checker’s eyes to help prevent it from being accidentally used with time functionality expecting other time types.

bascenev1.displaytimer(time: float, call: Callable[[], Any]) → None

Schedule a callable object to run based on display-time.

Category: General Utility Functions

This function creates a one-off timer which cannot be canceled or modified once created. If you require the ability to do so, or need a repeating timer, use the babase.DisplayTimer class instead.

Display-time is a time value intended to be used for animation and other visual purposes. It will generally increment by a consistent amount each frame. It will pass at an overall similar rate to AppTime, but trades accuracy for smoothness.

##### Arguments ###### time (float) > Length of time in seconds that the timer will wait before firing.

###### call (Callable[[], Any]) > A callable Python object. Note that the timer will retain a strong reference to the callable for as long as the timer exists, so you may want to look into concepts such as babase.WeakCall if that is not desired.

##### Examples Print some stuff through time: >>> babase.screenmessage(‘hello from now!’) >>> babase.displaytimer(1.0, babase.Call(babase.screenmessage, … ‘hello from the future!’)) >>> babase.displaytimer(2.0, babase.Call(babase.screenmessage, … ‘hello from the future 2!’))

bascenev1.emitfx(position: Sequence[float], velocity: Sequence[float] | None = None, count: int = 10, scale: float = 1.0, spread: float = 1.0, chunk_type: str = 'rock', emit_type: str = 'chunks', tendril_type: str = 'smoke') → None

Emit particles, smoke, etc. into the fx sim layer.

Category: Gameplay Functions

The fx sim layer is a secondary dynamics simulation that runs in the background and just looks pretty; it does not affect gameplay. Note that the actual amount emitted may vary depending on graphics settings, exiting element counts, or other factors.

bascenev1.end_host_scanning() → None

(internal)

Category: General Utility Functions

bascenev1.existing(obj: ExistableT | None) → ExistableT | None

Convert invalid references to None for any babase.Existable object.

Category: Gameplay Functions

To best support type checking, it is important that invalid references not be passed around and instead get converted to values of None. That way the type checker can properly flag attempts to pass possibly-dead objects (FooType | None) into functions expecting only live ones (FooType), etc. This call can be used on any ‘existable’ object (one with an exists() method) and will convert it to a None value if it does not exist.

For more info, see notes on ‘existables’ here: https://ballistica.net/wiki/Coding-Style-Guide

bascenev1.fade_screen(to: int = 0, time: float = 0.25, endcall: Callable[[], None] | None = None) → None

(internal)

Fade the local game screen in our out from black over a duration of time. if “to” is 0, the screen will fade out to black. Otherwise it will fade in from black. If endcall is provided, it will be run after a completely faded frame is drawn.

bascenev1.filter_playlist(playlist: PlaylistType, sessiontype: type[Session], *, add_resolved_type: bool = False, remove_unowned: bool = True, mark_unowned: bool = False, name: str = '?') → PlaylistType

Return a filtered version of a playlist.

Strips out or replaces invalid or unowned game types, makes sure all settings are present, and adds in a ‘resolved_type’ which is the actual type.

bascenev1.get_chat_messages() → list[str]

(internal)

bascenev1.get_connection_to_host_info() → dict

(internal)

bascenev1.get_connection_to_host_info_2() → bascenev1.HostInfo | None

Return info about the host we are currently connected to.

bascenev1.get_default_free_for_all_playlist() → list[dict[str, Any]]

Return a default playlist for free-for-all mode.

bascenev1.get_default_powerup_distribution() → Sequence[tuple[str, int]]

Standard set of powerups.

bascenev1.get_default_teams_playlist() → list[dict[str, Any]]

Return a default playlist for teams mode.

bascenev1.get_filtered_map_name(name: str) → str

Filter a map name to account for name changes, etc.

Category: Asset Functions

This can be used to support old playlists, etc.

bascenev1.get_foreground_host_activity() → bascenev1.Activity | None

(internal)

Returns the bascenev1.Activity currently in the foreground, or None if there is none.

bascenev1.get_foreground_host_session() → bascenev1.Session | None

(internal)

Return the bascenev1.Session currently being displayed, or None if there is none.

bascenev1.get_game_port() → int

(internal)

Return the port ballistica is hosting on.

bascenev1.get_game_roster() → list[dict[str, Any]]

(internal)

bascenev1.get_local_active_input_devices_count() → int

(internal)

bascenev1.get_map_class(name: str) → type[Map]

Return a map type given a name.

Category: Asset Functions

bascenev1.get_map_display_string(name: str) → Lstr

Return a babase.Lstr for displaying a given map’s name.

Category: Asset Functions

bascenev1.get_player_colors() → list[tuple[float, float, float]]

Return user-selectable player colors.

bascenev1.get_player_profile_colors(profilename: str | None, profiles: dict[str, dict[str, Any]] | None = None) → tuple[tuple[float, float, float], tuple[float, float, float]]

Given a profile, return colors for them.

bascenev1.get_player_profile_icon(profilename: str) → str

Given a profile name, returns an icon string for it.

(non-account profiles only)

bascenev1.get_public_party_enabled() → bool

(internal)

bascenev1.get_public_party_max_size() → int

(internal)

bascenev1.get_random_names() → list

(internal)

Returns the random names used by the game.

bascenev1.get_remote_app_name() → babase.Lstr

(internal)

bascenev1.get_replay_speed_exponent() → int

(internal)

Returns current replay speed value. Actual displayed speed is pow(2,speed).

bascenev1.get_trophy_string(trophy_id: str) → str

Given a trophy id, returns a string to visualize it.

bascenev1.get_ui_input_device() → bascenev1.InputDevice | None

(internal)

Returns the input-device that currently owns the user interface, or None if there is none.

bascenev1.getactivity(doraise: bool = True) → bascenev1.Activity | None

Return the current bascenev1.Activity instance.

Category: Gameplay Functions

Note that this is based on context_ref; 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, raises a babase.ActivityNotFoundError. If doraise is False, None will be returned instead in that case.

bascenev1.getcollision() → Collision

Return the in-progress collision.

Category: Gameplay Functions

bascenev1.getcollisionmesh(name: str) → bascenev1.CollisionMesh

Return a collision-mesh, loading it if necessary.

Category: Asset Functions

Collision-meshes are used in physics calculations for such things as terrain.

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

bascenev1.getdata(name: str) → bascenev1.Data

Return a data, loading it if necessary.

Category: Asset Functions

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

bascenev1.getinputdevice(name: str, unique_id: str, doraise: bool = True) → Any

(internal)

Given a type name and a unique identifier, returns an InputDevice. Throws an Exception if the input-device is not found, or returns None if ‘doraise’ is False.

bascenev1.getmesh(name: str) → bascenev1.Mesh

Return a mesh, loading it if necessary.

Category: Asset Functions

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

load in the background if necessary.

bascenev1.getnodes() → list

Return all nodes in the current bascenev1.Context.

Category: Gameplay Functions

bascenev1.getsession(doraise: bool = True) → bascenev1.Session | None

Category: Gameplay Functions

Returns the current bascenev1.Session instance. Note that this is based on context_ref; thus code being run in the UI context will return the UI context_ref 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.

bascenev1.getsound(name: str) → bascenev1.Sound

Return a sound, loading it if necessary.

Category: Asset Functions

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

bascenev1.gettexture(name: str) → bascenev1.Texture

Return a texture, loading it if necessary.

Category: Asset Functions

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

bascenev1.have_connected_clients() → bool

(internal)

Category: General Utility Functions

bascenev1.have_touchscreen_input() → bool

(internal)

Returns whether or not a touch-screen input is present

bascenev1.host_scan_cycle() → list

(internal)

bascenev1.increment_analytics_count(name: str, increment: int = 1) → None

(internal)

bascenev1.init_campaigns() → None

Fill out initial default Campaigns.

bascenev1.is_in_replay() → bool

(internal)

bascenev1.is_point_in_box(pnt: Sequence[float], box: Sequence[float]) → bool

Return whether a given point is within a given box.

category: General Utility Functions

For use with standard def boxes (position|rotate|scale).

bascenev1.is_replay_paused() → bool

(internal)

Returns if Replay is paused or not.

bascenev1.lock_all_input() → None

(internal)

Prevents all keyboard, mouse, and gamepad events from being processed.

bascenev1.ls_input_devices() → None

Print debugging info about game objects.

Category: General Utility Functions

This call only functions in debug builds of the game. It prints various info about the current object count, etc.

bascenev1.ls_objects() → None

Log debugging info about C++ level objects.

Category: General Utility Functions

This call only functions in debug builds of the game. It prints various info about the current object count, etc.

bascenev1.new_host_session(sessiontype: type[bascenev1.Session], benchmark_type: str | None = None) → None

(internal)

bascenev1.new_replay_session(file_name: str) → None

(internal)

bascenev1.newactivity(activity_type: type[bascenev1.Activity], settings: dict | None = None) → bascenev1.Activity

Instantiates a bascenev1.Activity given a type object.

Category: General Utility Functions

Activities require special setup and thus cannot be directly instantiated; you must go through this function.

bascenev1.newnode(type: str, owner: bascenev1.Node | None = None, attrs: dict | None = None, name: str | None = None, delegate: Any = None) → bascenev1.Node

Add a node of the given type to the game.

Category: Gameplay Functions

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

bascenev1.normalized_color(color: Sequence[float]) → tuple[float, ...]

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

category: General Utility Functions

bascenev1.pause_replay() → None

(internal)

Pauses replay.

bascenev1.print_live_object_warnings(when: Any, ignore_session: bascenev1.Session | None = None, ignore_activity: bascenev1.Activity | None = None) → None

Print warnings for remaining objects in the current context.

IMPORTANT - don’t call this in production; usage of gc.get_objects() can bork Python. See notes at top of efro.debug module.

bascenev1.printnodes() → None

Print various info about existing nodes; useful for debugging.

Category: Gameplay Functions

bascenev1.protocol_version() → int

(internal)

bascenev1.pushcall(call: Callable, from_other_thread: bool = False, suppress_other_thread_warning: bool = False, other_thread_use_fg_context: bool = False, raw: bool = False) → None

Push a call to the logic event-loop. Category: General Utility Functions

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

If you want to push a call from outside of the logic thread, however, you can pass ‘from_other_thread’ as True. In this case the call will always run in the UI context_ref on the logic thread or whichever context_ref is in the foreground if other_thread_use_fg_context is True. Passing raw=True will disable thread checks and context_ref sets/restores.

bascenev1.register_map(maptype: type[Map]) → None

Register a map class with the game.

bascenev1.release_gamepad_input() → None

(internal)

Resumes normal gamepad event processing.

bascenev1.release_keyboard_input() → None

(internal)

Resumes normal keyboard event processing.

bascenev1.reset_random_player_names() → None

(internal)

bascenev1.resume_replay() → None

(internal)

Resumes replay.

bascenev1.safecolor(color: Sequence[float], target_intensity: float = 0.6) → tuple[float, ...]

Given a color tuple, return a color safe to display as text.

Category: General Utility Functions

Accepts tuples of length 3 or 4. This will slightly brighten very dark colors, etc.

bascenev1.screenmessage(message: str | babase.Lstr, color: Sequence[float] | None = None, log: bool = False) → None

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

Category: General Utility Functions

Note that this version of the function is purely for local display. To broadcast screen messages in network play, look for methods such as broadcastmessage() provided by the scene-version packages.

bascenev1.seek_replay(delta: float) → None

(internal)

Rewind or fast-forward replay.

bascenev1.set_admins(admins: list[str]) → None

(internal)

bascenev1.set_analytics_screen(screen: str) → None

Used for analytics to see where in the app players spend their time.

Category: General Utility Functions

Generally called when opening a new window or entering some UI. ‘screen’ should be a string description of an app location (‘Main Menu’, etc.)

bascenev1.set_authenticate_clients(enable: bool) → None

(internal)

bascenev1.set_debug_speed_exponent(speed: int) → None

(internal)

Sets the debug speed scale for the game. Actual speed is pow(2,speed).

bascenev1.set_enable_default_kick_voting(enable: bool) → None

(internal)

bascenev1.set_internal_music(music: babase.SimpleSound | None, volume: float = 1.0, loop: bool = True) → None

(internal).

bascenev1.set_map_bounds(bounds: tuple[float, float, float, float, float, float]) → None

(internal)

Set map bounds. Generally nodes that go outside of this box are killed.

bascenev1.set_master_server_source(source: int) → None

(internal)

bascenev1.set_max_players_override(max_players: int | None) → None

Set the override for how many players can join a session

bascenev1.set_player_rejoin_cooldown(cooldown: float) → None

Set the cooldown for individual players rejoining after leaving.

bascenev1.set_public_party_enabled(enabled: bool) → None

(internal)

bascenev1.set_public_party_max_size(max_size: int) → None

(internal)

bascenev1.set_public_party_name(name: str) → None

(internal)

bascenev1.set_public_party_public_address_ipv4(address: str | None) → None

(internal)

bascenev1.set_public_party_public_address_ipv6(address: str | None) → None

(internal)

bascenev1.set_public_party_queue_enabled(max_size: bool) → None

(internal)

bascenev1.set_public_party_stats_url(url: str | None) → None

(internal)

bascenev1.set_replay_speed_exponent(speed: int) → None

(internal)

Set replay speed. Actual displayed speed is pow(2, speed).

bascenev1.set_touchscreen_editing(editing: bool) → None

(internal)

bascenev1.setmusic(musictype: MusicType | None, continuous: bool = False) → None

Set the app to play (or stop playing) a certain type of music.

category: Gameplay Functions

This function will handle loading and playing sound assets 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 and musictype is the same as what is already playing, the playing track will not be restarted.

bascenev1.show_damage_count(damage: str, position: Sequence[float], direction: Sequence[float]) → None

Pop up a damage count at a position in space.

Category: Gameplay Functions

bascenev1.storagename(suffix: str | None = None) → str

Generate a unique name for storing class data in shared places.

Category: General Utility Functions

This consists of a leading underscore, the module path at the call site with dots replaced by underscores, the containing class’s qualified name, and the provided suffix. When storing data in public places such as ‘customdata’ dicts, this minimizes the chance of collisions with other similarly named classes.

Note that this will function even if called in the class definition.

##### Examples Generate a unique name for storage purposes: >>> class MyThingie: … # This will give something like … # ‘_mymodule_submodule_mythingie_data’. … _STORENAME = babase.storagename(‘data’) … … # Use that name to store some data in the Activity we were … # passed. … def __init__(self, activity): … activity.customdata[self._STORENAME] = {}

bascenev1.time() → bascenev1.Time

Return the current scene time in seconds.

Category: General Utility Functions

Scene time maps to local simulation time in bascenev1.Activity or bascenev1.Session Contexts. This means that it may progress slower in slow-motion play modes, stop when the game is paused, etc.

Note that the value returned here is simply a float; it just has a unique type in the type-checker’s eyes to help prevent it from being accidentally used with time functionality expecting other time types.

bascenev1.timer(time: float, call: Callable[[], Any], repeat: bool = False) → None

Schedule a call to run at a later point in time.

Category: General Utility Functions

This function adds a scene-time timer to the current babase.Context. This timer cannot be canceled or modified once created. If you

require the ability to do so, use the babase.Timer class instead.

Scene time maps to local simulation time in bascenev1.Activity or bascenev1.Session Contexts. This means that it may progress slower in slow-motion play modes, stop when the game is paused, etc.

##### Arguments ###### time (float) > Length of scene time in seconds that the timer will wait before firing.

###### call (Callable[[], Any]) > 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 babase.WeakCall if that is not desired.

###### repeat (bool) > If True, the timer will fire repeatedly, with each successive firing having the same delay as the first.

##### Examples Print some stuff through time: >>> import bascenev1 as bs >>> 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!’))

bascenev1.timestring(timeval: float | int, centi: bool = True) → babase.Lstr

Generate a babase.Lstr for displaying a time value.

Category: General Utility Functions

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

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

bascenev1.unlock_all_input() → None

(internal)

Resumes normal keyboard, mouse, and gamepad event processing.