bacommon package

Functionality and data shared by all Ballistica components.

This includes clients, various servers, tools, etc.

Subpackages

• bacommon.bs package
• bacommon.clouddialog package
• bacommon.docui package
• bacommon.workspace package

Submodules

bacommon.app module

Common high level values/functionality related to Ballistica apps.

class bacommon.app.AppArchitecture(*values)

Bases: Enum

Processor architecture an app can be running on.

ARM = 'arm'

ARM64 = 'arm64'

UNKNOWN = 'unknown'

X86 = 'x86'

X86_64 = 'x86_64'

class bacommon.app.AppInterfaceIdiom(*values)

Bases: Enum

A general form-factor or method of experiencing a Ballistica app.

Note that it may be possible for a running app to switch idioms (for instance if a mobile device or computer is connected to a TV).

CONSOLE = 'console'

Screen with medium amount of detail visible; assumed to have game controller(s) as primary input. Note that this covers handheld or arcade cabinet scenarios in addition to tv-connected consoles.

DESKTOP = 'desktop'

Screen with high amount of detail visible; assumed to have keyboard/mouse as primary input.

HEADLESS = 'headless'

The app has no interface (generally is acting as a server).

PHONE = 'phone'

Small screen; assumed to have touch as primary input.

TABLET = 'tablet'

Medium size screen; assumed to have touch as primary input.

XR_HEADSET = 'xr_headset'

Displayed over or in place of of the real world on a headset; assumed to have hand tracking or spatial controllers as primary input.

XR_PHONE = 'xr_phone'

Displayed over or instead of the real world on a small screen; assumed to have device movement augmented by physical or touchscreen controls as primary input.

XR_TABLET = 'xr_tablet'

Displayed over or instead of the real world on a medium size screen; assumed to have device movement augmented by physical or touchscreen controls as primary input.

class bacommon.app.AppPlatform(*values)

Bases: Enum

Overall platform a build can target.

Each distinct flavor of an app has a unique combination of AppPlatform and AppVariant. Generally platform describes a set of hardware, while variant describes a destination or purpose for the build.

ANDROID = 'android'

IOS = 'ios'

LINUX = 'linux'

MACOS = 'macos'

TVOS = 'tvos'

UNKNOWN = 'unknown'

WINDOWS = 'windows'

class bacommon.app.AppVariant(*values)

Bases: Enum

A unique Ballistica build variation within a single platform.

Each distinct permutation of an app has a unique combination of AppPlatform and AppVariant. Generally platform describes a set of hardware, while variant describes a destination or purpose for the build.

AMAZON_APPSTORE = 'amazon_appstore'

APPLE_APP_STORE = 'apple_app_store'

ARCADE = 'arcade'

CARDBOARD = 'cardboard'

DEMO = 'demo'

EPIC_GAMES_STORE = 'epic_games_store'

GENERIC = 'generic'

Default builds.

GOOGLE_PLAY = 'google_play'

META = 'meta'

STEAM = 'steam'

TEST_BUILD = 'test_build'

Particular builds intended for public testing (may have some extra checks or logging enabled).

WINDOWS_STORE = 'windows_store'

bacommon.assets module

Functionality related to cloud based assets.

Warning

This is an internal api and subject to change at any time. Do not use it in mod code.

bacommon.bacloud module

Functionality related to the bacloud tool.

Warning

This is an internal api and subject to change at any time. Do not use it in mod code.

bacommon.build module

Functionality related to game builds.

Warning

This is an internal api and subject to change at any time. Do not use it in mod code.

bacommon.clienteffect module

ClientEffect related functionality.

Warning

This is an internal api and subject to change at any time. Do not use it in mod code.

bacommon.cloud module

Cloud related functionality.

Warning

This is an internal api and subject to change at any time. Do not use it in mod code.

bacommon.displayitem module

Functionality for displaying currencies, prizes, owned items, etc.

Warning

This is an internal api and subject to change at any time. Do not use it in mod code.

bacommon.locale module

Functionality for wrangling locale info.

class bacommon.locale.Locale(*values)

Bases: Enum

A distinct grouping of language, cultural norms, etc.

This list of locales is considered ‘sacred’ - we assume any values (and associated long values) added here remain in use out in the wild indefinitely. If a locale is superseded by a newer or more specific one, the new locale should be added and both new and old should map to the same LocaleResolved.

ARABIC = 'arabc'

BELARUSSIAN = 'blrs'

CHINESE = 'chn'

CHINESE_SIMPLIFIED = 'chn_sim'

CHINESE_TRADITIONAL = 'chn_tr'

CROATIAN = 'croat'

CZECH = 'czch'

DANISH = 'dnsh'

DUTCH = 'dtch'

ENGLISH = 'eng'

ESPERANTO = 'esprnto'

FILIPINO = 'filp'

FRENCH = 'frnch'

GERMAN = 'grmn'

GIBBERISH = 'gibber'

GREEK = 'greek'

HINDI = 'hndi'

HUNGARIAN = 'hngr'

INDONESIAN = 'indnsn'

ITALIAN = 'italn'

KAZAKH = 'kazk'

KOREAN = 'kor'

MALAY = 'mlay'

PERSIAN = 'pers'

PIRATE_SPEAK = 'pirate'

POLISH = 'pol'

PORTUGUESE = 'prtg'

PORTUGUESE_BRAZIL = 'prtg_brz'

PORTUGUESE_PORTUGAL = 'prtg_pr'

ROMANIAN = 'rom'

RUSSIAN = 'rusn'

SERBIAN = 'srbn'

SLOVAK = 'slvk'

SPANISH = 'spn'

SPANISH_LATIN_AMERICA = 'spn_lat'

SPANISH_SPAIN = 'spn_spn'

SWEDISH = 'swed'

TAMIL = 'taml'

THAI = 'thai'

TURKISH = 'turk'

UKRAINIAN = 'ukrn'

VENETIAN = 'venetn'

VIETNAMESE = 'viet'

property description: str

A human readable description for the locale.

Intended as instructions to humans or AI for translating. For most locales this is simply the language name, but for special ones like pirate-speak it may include instructions.

classmethod from_long_value(value: str) → Locale

Given a long value, return a Locale.

property long_value: str

A longer more human readable alternative to value.

Like the regular enum values, these values will never change and can be used for persistent storage/etc.

property resolved: LocaleResolved

Return the associated resolved locale.

class bacommon.locale.LocaleResolved(*values)

Bases: Enum

A resolved Locale for use in logic.

These values should never be stored or transmitted and should always come from resolving a Locale which can be stored/transmitted. This gives us the freedom to revise this list as needed to keep our actual list of implemented resolved-locales as trim as possible.

ARABIC = 'arabc'

BELARUSSIAN = 'blrs'

CHINESE_SIMPLIFIED = 'chn_sim'

CHINESE_TRADITIONAL = 'chn_tr'

CROATIAN = 'croat'

CZECH = 'czch'

DANISH = 'dnsh'

DUTCH = 'dtch'

ENGLISH = 'eng'

ESPERANTO = 'esprnto'

FILIPINO = 'filp'

FRENCH = 'frnch'

GERMAN = 'grmn'

GIBBERISH = 'gibber'

GREEK = 'greek'

HINDI = 'hndi'

HUNGARIAN = 'hngr'

INDONESIAN = 'indnsn'

ITALIAN = 'italn'

KAZAKH = 'kazk'

KOREAN = 'kor'

MALAY = 'mlay'

PERSIAN = 'pers'

PIRATE_SPEAK = 'pirate'

POLISH = 'pol'

PORTUGUESE_BRAZIL = 'prtg_brz'

PORTUGUESE_PORTUGAL = 'prtg_pr'

ROMANIAN = 'rom'

RUSSIAN = 'rusn'

SERBIAN = 'srbn'

SLOVAK = 'slvk'

SPANISH_LATIN_AMERICA = 'spn_lat'

SPANISH_SPAIN = 'spn_spn'

SWEDISH = 'swed'

TAMIL = 'taml'

THAI = 'thai'

TURKISH = 'turk'

UKRAINIAN = 'ukrn'

VENETIAN = 'venetn'

VIETNAMESE = 'viet'

static from_tag(tag: str) → LocaleResolved

Return a locale for a given string tag.

Tags can be provided in BCP 47 form (‘en-US’) or POSIX locale string form (‘en_US.UTF-8’).

property locale: Locale

Return a locale that resolves to this resolved locale.

In some cases, such as when presenting locale options to the user, it makes sense to iterate over resolved locale values, as regular locales may include obsolete or redundant values. When storing locale values to disk or transmitting them, however, it is important to use plain locales. This method can be used to get back to a plain locale from a resolved one.

property tag: str

An IETF BCP 47 tag for this locale.

This is often simply a language code (‘en’) but may in some cases include the country (‘pt-BR’) or script (‘zh-Hans’). Locales which are not “real” will include an ‘x’ in the middle (‘en-x-pirate’).

bacommon.loggercontrol module

System for managing loggers.

class bacommon.loggercontrol.LoggerControlConfig(levels: dict[str, int] = <factory>)

Bases: object

A logging level configuration that applies to all loggers.

Any loggers not explicitly contained in the configuration will be set to NOTSET.

apply(*, warn_unexpected_loggers: bool = False, warn_missing_loggers: bool = False, ignore_log_prefixes: list[str] | None = None) → None

Apply the config to all Python loggers.

If ‘warn_unexpected_loggers’ is True, warnings will be issues for any loggers not explicitly covered by the config. This is useful to help ensure controls for all possible loggers are present in a UI/etc.

If ‘warn_missing_loggers’ is True, warnings will be issued for any loggers present in the config that are not found at apply time. This can be useful for pruning settings for no longer used loggers.

Warnings for any log names beginning with any strings in ‘ignore_log_prefixes’ will be suppressed. This can allow ignoring loggers associated with submodules for a given package and instead presenting only a top level logger (or none at all).

apply_diff(diffconfig: LoggerControlConfig) → LoggerControlConfig

Apply a diff config to ourself.

Note that values that resolve to NOTSET are left intact in the output config. This is so all loggers expected by either the base or diff config to exist can be created if desired/etc.

diff(baseconfig: LoggerControlConfig) → LoggerControlConfig

Return a config containing only changes compared to a base config.

Note that this omits all NOTSET values that resolve to NOTSET in the base config.

This diffed config can later be used with apply_diff() against the base config to recreate the state represented by self.

classmethod from_current_loggers() → Self

Build a config from the current set of loggers.

get_effective_level(logname: str) → int

Given a log name, predict its level if this config is applied.

levels: dict[str, int]

sanity_check_effective_levels() → None

Checks existing loggers to make sure they line up with us.

This can be called periodically to ensure that a control-config is properly driving log levels and that nothing else is changing them behind our back.

would_make_changes() → bool

Return whether calling apply would change anything.

bacommon.logging module

Logging functionality.

class bacommon.logging.ClientLoggerName(*values)

Bases: Enum

Logger names used on the Ballistica client.

ACCOUNT = 'ba.account'

ACCOUNT_CLIENT_V2 = 'ba.accountclientv2'

APP = 'ba.app'

ASSETS = 'ba.assets'

AUDIO = 'ba.audio'

BA = 'ba'

CACHE = 'ba.cache'

CLOUD_SUBSCRIPTION = 'ba.cloudsub'

CONNECTIVITY = 'ba.connectivity'

DISPLAYTIME = 'ba.displaytime'

ENV = 'ba.env'

GARBAGE_COLLECTION = 'ba.gc'

GRAPHICS = 'ba.gfx'

INPUT = 'ba.input'

LIFECYCLE = 'ba.lifecycle'

LOGIN_ADAPTER = 'ba.loginadapter'

NETWORKING = 'ba.net'

PERFORMANCE = 'ba.perf'

UI = 'ba.ui'

V2TRANSPORT = 'ba.v2transport'

property description: str

Return a short description for the logger.

bacommon.logging.get_base_logger_control_config_client() → LoggerControlConfig

Return the logger-control-config used by the Ballistica client.

This should remain consistent since local logger configurations are stored relative to this.

bacommon.login module

Functionality related to cloud based assets.

class bacommon.login.LoginType(*values)

Bases: Enum

Types of logins available.

EMAIL = 'email'

Email/password

GAME_CENTER = 'game_center'

Apple’s Game Center

GPGS = 'gpgs'

Google Play Game Services

property displayname: str

A human readable name for this value.

property displaynameshort: str

A short human readable name for this value.

bacommon.net module

Network related data and functionality.

Warning

This is an internal api and subject to change at any time. Do not use it in mod code.

bacommon.securedata module

Functionality related to verifying server generated data.

Warning

This is an internal api and subject to change at any time. Do not use it in mod code.

class bacommon.securedata.SecureDataChecker(starttime: datetime, endtime: datetime, publickeys: list[bytes])

Bases: object

Verifies data as being signed by our master server.

check(data: bytes, signature: bytes) → bool

Verify data, returning True if successful.

Note that this call imports and uses the cryptography module and can be slow; it generally should be done in a background thread or on a server.

endtime: datetime

publickeys: list[bytes]

starttime: datetime

bacommon.servermanager module

Functionality related to the server manager script.

class bacommon.servermanager.ChatMessageCommand(message: str, clients: list[int] | None)

Bases: ServerCommand

Chat message from the server.

clients: list[int] | None

message: str

class bacommon.servermanager.ClientListCommand

Bases: ServerCommand

Print a list of clients.

class bacommon.servermanager.KickCommand(client_id: int, ban_time: int | None)

Bases: ServerCommand

Kick a client.

ban_time: int | None

client_id: int

class bacommon.servermanager.ScreenMessageCommand(message: str, color: tuple[float, float, float] | None, clients: list[int] | None)

Bases: ServerCommand

Screen-message from the server.

clients: list[int] | None

color: tuple[float, float, float] | None

message: str

class bacommon.servermanager.ServerCommand

Bases: object

Base class for commands that can be sent to the server.

class bacommon.servermanager.ServerConfig(party_name: str = 'FFA', party_is_public: bool = True, authenticate_clients: bool = True, admins: list[str] = <factory>, enable_default_kick_voting: bool = True, public_ipv4_address: str | None = None, public_ipv6_address: str | None = None, port: int = 43210, max_party_size: int = 6, session_max_players_override: int | None = None, session_type: str = 'ffa', playlist_code: int | None = None, playlist_inline: list[dict[str, ~typing.Any]] | None = None, playlist_shuffle: bool = True, auto_balance_teams: bool = True, coop_campaign: str = 'Easy', coop_level: str = 'Onslaught Training', enable_telnet: bool = False, teams_series_length: int = 7, ffa_series_length: int = 24, stats_url: str | None = None, clean_exit_minutes: float | None = None, unclean_exit_minutes: float | None = None, idle_exit_minutes: float | None = None, show_tutorial: bool = False, team_names: tuple[str, str] | None = None, team_colors: tuple[tuple[float, float, float], tuple[float, float, float]] | None = None, enable_queue: bool = True, protocol_version: int | None = None, stress_test_players: int | None = None, player_rejoin_cooldown: float = 10.0, log_levels: dict[str, str] | None = None, dont_write_bytecode: bool = False)

Bases: object

Configuration for the server manager app (<appname>_server).

admins: list[str]

authenticate_clients: bool = True

auto_balance_teams: bool = True

clean_exit_minutes: float | None = None

coop_campaign: str = 'Easy'

coop_level: str = 'Onslaught Training'

dont_write_bytecode: bool = False

enable_default_kick_voting: bool = True

enable_queue: bool = True

enable_telnet: bool = False

ffa_series_length: int = 24

idle_exit_minutes: float | None = None

log_levels: dict[str, str] | None = None

max_party_size: int = 6

party_is_public: bool = True

party_name: str = 'FFA'

player_rejoin_cooldown: float = 10.0

playlist_code: int | None = None

playlist_inline: list[dict[str, Any]] | None = None

playlist_shuffle: bool = True

port: int = 43210

protocol_version: int | None = None

public_ipv4_address: str | None = None

public_ipv6_address: str | None = None

session_max_players_override: int | None = None

session_type: str = 'ffa'

show_tutorial: bool = False

stats_url: str | None = None

stress_test_players: int | None = None

team_colors: tuple[tuple[float, float, float], tuple[float, float, float]] | None = None

team_names: tuple[str, str] | None = None

teams_series_length: int = 7

unclean_exit_minutes: float | None = None

class bacommon.servermanager.ShutdownCommand(reason: ShutdownReason, immediate: bool)

Bases: ServerCommand

Tells the server to shut down.

immediate: bool

reason: ShutdownReason

class bacommon.servermanager.ShutdownReason(*values)

Bases: Enum

Reason a server is shutting down.

NONE = 'none'

RESTARTING = 'restarting'

class bacommon.servermanager.StartServerModeCommand(config: ServerConfig)

Bases: ServerCommand

Tells the app to switch into ‘server’ mode.

config: ServerConfig

bacommon.text module

Text related bits.

class bacommon.text.SpecialChar(*values)

Bases: Enum

Custom unicode characters the engine can display.

Keep this in sync with babase._mgen.enums.SpecialChar.

BACK = '\ue00b'

BOTTOM_BUTTON = '\ue008'

CLOSE = '\ue017'

CROWN = '\ue043'

DELETE = '\ue009'

DICE_BUTTON1 = '\ue022'

DICE_BUTTON2 = '\ue023'

DICE_BUTTON3 = '\ue024'

DICE_BUTTON4 = '\ue025'

DOWN_ARROW = '\ue004'

DPAD_CENTER_BUTTON = '\ue010'

DRAGON = '\ue048'

EXPLODINARY_LOGO = '\ue031'

EYE_BALL = '\ue045'

FAST_FORWARD_BUTTON = '\ue00f'

FEDORA = '\ue041'

FIREBALL = '\ue04f'

FLAG_ALGERIA = '\ue054'

FLAG_ARGENTINA = '\ue05f'

FLAG_AUSTRALIA = '\ue058'

FLAG_BRAZIL = '\ue035'

FLAG_CANADA = '\ue039'

FLAG_CHILE = '\ue061'

FLAG_CHINA = '\ue037'

FLAG_CZECH_REPUBLIC = '\ue057'

FLAG_EGYPT = '\ue052'

FLAG_FRANCE = '\ue03c'

FLAG_GERMANY = '\ue034'

FLAG_INDIA = '\ue03a'

FLAG_INDONESIA = '\ue03d'

FLAG_IRAN = '\ue05d'

FLAG_ITALY = '\ue03e'

FLAG_JAPAN = '\ue03b'

FLAG_KUWAIT = '\ue053'

FLAG_MALAYSIA = '\ue056'

FLAG_MEXICO = '\ue033'

FLAG_NETHERLANDS = '\ue040'

FLAG_PHILIPPINES = '\ue060'

FLAG_POLAND = '\ue05e'

FLAG_QATAR = '\ue051'

FLAG_RUSSIA = '\ue036'

FLAG_SAUDI_ARABIA = '\ue055'

FLAG_SINGAPORE = '\ue059'

FLAG_SOUTH_KOREA = '\ue03f'

FLAG_UNITED_ARAB_EMIRATES = '\ue050'

FLAG_UNITED_KINGDOM = '\ue038'

FLAG_UNITED_STATES = '\ue032'

GAME_CENTER_LOGO = '\ue021'

GAME_CIRCLE_LOGO = '\ue026'

GOOGLE_PLAY_GAMES_LOGO = '\ue020'

HAL = '\ue042'

HEART = '\ue047'

HELMET = '\ue049'

LEFT_ARROW = '\ue001'

LEFT_BUTTON = '\ue005'

LOCAL_ACCOUNT = '\ue030'

LOGO = '\ue01e'

LOGO_FLAT = '\ue00c'

MIKIROG = '\ue062'

MOON = '\ue04d'

MUSHROOM = '\ue04a'

NINJA_STAR = '\ue04b'

NVIDIA_LOGO = '\ue05c'

OCULUS_LOGO = '\ue05a'

OUYA_BUTTON_A = '\ue01c'

OUYA_BUTTON_O = '\ue019'

OUYA_BUTTON_U = '\ue01a'

OUYA_BUTTON_Y = '\ue01b'

PARTY_ICON = '\ue027'

PAUSE_BUTTON = '\ue016'

PLAY_BUTTON = '\ue015'

PLAY_PAUSE_BUTTON = '\ue00e'

PLAY_STATION_CIRCLE_BUTTON = '\ue012'

PLAY_STATION_CROSS_BUTTON = '\ue011'

PLAY_STATION_SQUARE_BUTTON = '\ue014'

PLAY_STATION_TRIANGLE_BUTTON = '\ue013'

REWIND_BUTTON = '\ue00d'

RIGHT_ARROW = '\ue002'

RIGHT_BUTTON = '\ue007'

SHIFT = '\ue00a'

SKULL = '\ue046'

SPIDER = '\ue04e'

STEAM_LOGO = '\ue05b'

TEST_ACCOUNT = '\ue028'

TICKET = '\ue01f'

TICKET_BACKING = '\ue029'

TOKEN = '\ue01d'

TOP_BUTTON = '\ue006'

TROPHY0A = '\ue02d'

TROPHY0B = '\ue02e'

TROPHY1 = '\ue02a'

TROPHY2 = '\ue02b'

TROPHY3 = '\ue02c'

TROPHY4 = '\ue02f'

UP_ARROW = '\ue003'

V2_LOGO = '\ue063'

VIKING_HELMET = '\ue04c'

YIN_YANG = '\ue044'

bacommon.transfer module

Functionality related to transferring files/data.

Warning

This is an internal api and subject to change at any time. Do not use it in mod code.