bauiv1 package¶

Submodules¶

bauiv1.onscreenkeyboard module¶

Provides the built-in on screen keyboard UI.

class bauiv1.onscreenkeyboard.OnScreenKeyboardWindow(adapter: StringEditAdapter)[source]¶

Bases: Window

Simple built-in on-screen keyboard.

Module contents¶

Ballistica user interface api version 1

class bauiv1.AppIntent¶

Bases: object

A high level directive given to the app.

Category: App Classes

class bauiv1.AppIntentDefault¶

Bases: AppIntent

Tells the app to simply run in its default mode.

class bauiv1.AppIntentExec(code: str)¶

Bases: AppIntent

Tells the app to exec some Python code.

class bauiv1.AppMode¶

Bases: object

A high level mode for the app.

Category: App Classes

classmethod can_handle_intent(intent: AppIntent) → bool[source]¶

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 _can_handle_intent() method) AND the AppExperience associated with the AppMode must be supported by the current app and runtime environment.

classmethod get_app_experience() → AppExperience[source]¶: Return the overall experience provided by this mode.

handle_intent(intent: AppIntent) → None[source]¶: Handle an intent.

on_activate() → None[source]¶: Called when the mode is being activated.

on_app_active_changed() → None[source]¶

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[source]¶: Called when the mode is being deactivated.

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

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 bauiv1.BasicMainWindowState(create_call: Callable[[Literal['in_right', 'in_left', 'in_scale'] | None, bauiv1.Widget | None], bauiv1.MainWindow])¶

Bases: MainWindowState

A basic MainWindowState holding a lambda to recreate a MainWindow.

create_window(transition: Literal['in_right', 'in_left', 'in_scale'] | None = None, origin_widget: bauiv1.Widget | None = None) → bauiv1.MainWindow[source]¶

Create a window based on this state.

WindowState child classes should override this to recreate their particular type of window.

class bauiv1.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 bauiv1.ContextRef[source]¶

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[source]¶

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[source]¶: Whether the context was created as empty.

is_expired() → bool[source]¶: Whether the context has expired.

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

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.

###### 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 bauiv1.Keyboard¶

Bases: object

Chars definitions for on-screen keyboard.

Category: App Classes

Keyboards are discoverable by the meta-tag system and the user can select which one they want to use. On-screen keyboard uses chars from active babase.Keyboard.

chars: list[tuple[str, ...]]¶

name: str¶

nums: tuple[str, ...]¶

pages: dict[str, tuple[str, ...]]¶

class bauiv1.LoginAdapter(login_type: LoginType)¶

Bases: object

Allows using implicit login types in an explicit way.

Some login types such as Google Play Game Services or Game Center are basically always present and often do not provide a way to log out from within a running app, so this adapter exists to use them in a flexible manner by ‘attaching’ and ‘detaching’ from an always-present login, allowing for its use alongside other login types. It also provides common functionality for server-side account verification and other handy bits.

class ImplicitLoginState(login_id: str, display_name: str)[source]¶

Bases: object

Describes the current state of an implicit login.

display_name: str¶

login_id: str¶

class SignInResult(credentials: str)[source]¶

Bases: object

Describes the final result of a sign-in attempt.

credentials: str¶

get_sign_in_token(completion_cb: Callable[[str | None], None]) → None[source]¶

Get a sign-in token from the adapter back end.

This token is then passed to the master-server to complete the sign-in process. The adapter can use this opportunity to bring up account creation UI, call its internal sign_in function, etc. as needed. The provided completion_cb should then be called with either a token or None if sign in failed or was cancelled.

is_back_end_active() → bool[source]¶: Is this adapter’s back-end currently active?

on_app_loading() → None[source]¶: Should be called for each adapter in on_app_loading.

on_back_end_active_change(active: bool) → None[source]¶

Called when active state for the back-end is (possibly) changing.

Meant to be overridden by subclasses. Being active means that the implicit login provided by the back-end is actually being used by the app. It should therefore register unlocked achievements, leaderboard scores, allow viewing native UIs, etc. When not active it should ignore everything and behave as if signed out, even if it technically is still signed in.

set_active_logins(logins: dict[LoginType, str]) → None[source]¶

Keep the adapter informed of actively used logins.

This should be called by the app’s account subsystem to keep adapters up to date on the full set of logins attached to the currently-in-use account. Note that the logins dict passed in should be immutable as only a reference to it is stored, not a copy.

set_implicit_login_state(state: ImplicitLoginState | None) → None[source]¶

Keep the adapter informed of implicit login states.

This should be called by the adapter back-end when an account of their associated type gets logged in or out.

sign_in(result_cb: Callable[[LoginAdapter, SignInResult | Exception], None], description: str) → None[source]¶

Attempt to sign in via this adapter.

This can be called even if the back-end is not implicitly signed in; the adapter will attempt to sign in if possible. An exception will be returned if the sign-in attempt fails.

class bauiv1.LoginInfo(name: str)¶

Bases: object

Basic info about a login available in the app.plus.accounts section.

name: str¶

class bauiv1.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’))])

args¶

evaluate() → str[source]¶

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[source]¶: Given a json string, returns a babase.Lstr. Does no validation.

is_flat_value() → bool[source]¶

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 bauiv1.MainWindow(root_widget: bauiv1.Widget, *, transition: str | None, origin_widget: bauiv1.Widget | None, cleanupcheck: bool = True, refresh_on_screen_size_changes: bool = False)¶

Bases: Window

A special type of window that can be set as ‘main’.

The UI system has at most one main window at any given time. MainWindows support high level functionality such as saving and restoring states, allowing them to be automatically recreated when navigating back from other locations or when something like ui-scale changes.

get_main_window_state() → MainWindowState[source]¶: Return a WindowState to recreate this window, if supported.

main_window_back() → None[source]¶

Move back in the main window stack.

Is a no-op if the main window does not have control; no need to check main_window_has_control() first.

main_window_close(transition: str | None = None) → None[source]¶: Get window transitioning out if still alive.

main_window_has_control() → bool[source]¶

Is this MainWindow allowed to change the global main window?

It is a good idea to make sure this is True before calling main_window_replace(). This prevents fluke UI breakage such as multiple simultaneous events causing a MainWindow to spawn multiple replacements for itself.

main_window_replace(new_window: MainWindow, back_state: MainWindowState | None = None, is_auxiliary: bool = False) → None[source]¶: Replace ourself with a new MainWindow.

on_main_window_close() → None[source]¶

Called before transitioning out a main window.

A good opportunity to save window state/etc.

class bauiv1.MainWindowState¶

Bases: object

Persistent state for a specific MainWindow.

This allows MainWindows to be automatically recreated for back-button purposes, when switching app-modes, etc.

create_window(transition: Literal['in_right', 'in_left', 'in_scale'] | None = None, origin_widget: bauiv1.Widget | None = None) → MainWindow[source]¶

Create a window based on this state.

WindowState child classes should override this to recreate their particular type of window.

class bauiv1.Mesh[source]¶

Bases: object

Category: User Interface Classes

exception bauiv1.NotFoundError¶

Bases: Exception

Exception raised when a referenced object does not exist.

Category: Exception Classes

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

Bases: Enum

Permissions that can be requested from the OS.

Category: Enums

STORAGE = 0¶

class bauiv1.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[source]¶: Called to ask if we have settings UI we can show.

on_app_running() → None[source]¶: Called when the app reaches the running state.

on_app_shutdown() → None[source]¶: Called when the app is beginning the shutdown process.

on_app_shutdown_complete() → None[source]¶: Called when the app has completed the shutdown process.

on_app_suspend() → None[source]¶: Called when the app enters the suspended state.

on_app_unsuspend() → None[source]¶: Called when the app exits the suspended state.

show_settings_ui(source_widget: Any | None) → None[source]¶: Called to show our settings UI.

class bauiv1.PluginSpec(class_path: str, loadable: bool)¶

Bases: object

Represents a plugin the engine knows about.

Category: App Classes

The ‘enabled’ attr represents whether this plugin is set to load. Getting or setting that attr affects the corresponding app-config key. Remember to commit the app-config after making any changes.

The ‘attempted_load’ attr will be True if the engine has attempted to load the plugin. If ‘attempted_load’ is True for a PluginSpec but the ‘plugin’ attr is None, it means there was an error loading the plugin. If a plugin’s api-version does not match the running app, if a new plugin is detected with auto-enable-plugins disabled, or if the user has explicitly disabled a plugin, the engine will not even attempt to load it.

attempt_load_if_enabled() → Plugin | None[source]¶: Possibly load the plugin and log any errors.

property enabled: bool¶: Whether the user wants this plugin to load.

class bauiv1.QuitType(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

‘soft’ may hide/reset the app but keep the process running, depending: on the platform.
‘back’ is a variant of ‘soft’ which may give ‘back-button-pressed’: behavior depending on the platform. (returning to some previous activity instead of dumping to the home screen, etc.)
‘hard’ leads to the process exiting. This generally should be avoided: on platforms such as mobile.

BACK = 1¶

HARD = 2¶

SOFT = 0¶

class bauiv1.Sound[source]¶

Bases: object

Category: User Interface Classes

play(volume: float = 1.0) → None[source]¶: Play the sound locally.

stop() → None[source]¶: Stop the sound if it is playing.

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

Bases: Enum

Special characters the game can print.

Category: Enums

BACK = 10¶

BOTTOM_BUTTON = 7¶

CROWN = 64¶

DELETE = 8¶

DICE_BUTTON1 = 31¶

DICE_BUTTON2 = 32¶

DICE_BUTTON3 = 33¶

DICE_BUTTON4 = 34¶

DOWN_ARROW = 0¶

DPAD_CENTER_BUTTON = 15¶

DRAGON = 69¶

EXPLODINARY_LOGO = 46¶

EYE_BALL = 66¶

FAST_FORWARD_BUTTON = 14¶

FEDORA = 62¶

FIREBALL = 76¶

FLAG_ALGERIA = 81¶

FLAG_ARGENTINA = 92¶

FLAG_AUSTRALIA = 85¶

FLAG_BRAZIL = 50¶

FLAG_CANADA = 54¶

FLAG_CHILE = 94¶

FLAG_CHINA = 52¶

FLAG_CZECH_REPUBLIC = 84¶

FLAG_EGYPT = 79¶

FLAG_FRANCE = 57¶

FLAG_GERMANY = 49¶

FLAG_INDIA = 55¶

FLAG_INDONESIA = 58¶

FLAG_IRAN = 90¶

FLAG_ITALY = 59¶

FLAG_JAPAN = 56¶

FLAG_KUWAIT = 80¶

FLAG_MALAYSIA = 83¶

FLAG_MEXICO = 48¶

FLAG_NETHERLANDS = 61¶

FLAG_PHILIPPINES = 93¶

FLAG_POLAND = 91¶

FLAG_QATAR = 78¶

FLAG_RUSSIA = 51¶

FLAG_SAUDI_ARABIA = 82¶

FLAG_SINGAPORE = 86¶

FLAG_SOUTH_KOREA = 60¶

FLAG_UNITED_ARAB_EMIRATES = 77¶

FLAG_UNITED_KINGDOM = 53¶

FLAG_UNITED_STATES = 47¶

GAME_CENTER_LOGO = 30¶

GAME_CIRCLE_LOGO = 35¶

GOOGLE_PLAY_GAMES_LOGO = 29¶

HAL = 63¶

HEART = 68¶

HELMET = 70¶

LEFT_ARROW = 2¶

LEFT_BUTTON = 5¶

LOCAL_ACCOUNT = 45¶

LOGO = 27¶

LOGO_FLAT = 11¶

MIKIROG = 95¶

MOON = 74¶

MUSHROOM = 71¶

NINJA_STAR = 72¶

NVIDIA_LOGO = 89¶

OCULUS_LOGO = 87¶

OUYA_BUTTON_A = 25¶

OUYA_BUTTON_O = 22¶

OUYA_BUTTON_U = 23¶

OUYA_BUTTON_Y = 24¶

PARTY_ICON = 36¶

PAUSE_BUTTON = 21¶

PLAY_BUTTON = 20¶

PLAY_PAUSE_BUTTON = 13¶

PLAY_STATION_CIRCLE_BUTTON = 17¶

PLAY_STATION_CROSS_BUTTON = 16¶

PLAY_STATION_SQUARE_BUTTON = 19¶

PLAY_STATION_TRIANGLE_BUTTON = 18¶

REWIND_BUTTON = 12¶

RIGHT_ARROW = 3¶

RIGHT_BUTTON = 6¶

SHIFT = 9¶

SKULL = 67¶

SPIDER = 75¶

STEAM_LOGO = 88¶

TEST_ACCOUNT = 37¶

TICKET = 28¶

TICKET_BACKING = 38¶

TOKEN = 26¶

TOP_BUTTON = 4¶

TROPHY0A = 42¶

TROPHY0B = 43¶

TROPHY1 = 39¶

TROPHY2 = 40¶

TROPHY3 = 41¶

TROPHY4 = 44¶

UP_ARROW = 1¶

V2_LOGO = 96¶

VIKING_HELMET = 73¶

YIN_YANG = 65¶

class bauiv1.Texture[source]¶

Bases: object

Category: User Interface Classes

class bauiv1.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 bauiv1.UIV1AppSubsystem¶

Bases: AppSubsystem

Consolidated UI functionality for the app.

Category: App Classes

To use this class, access the single instance of it at ‘ba.app.ui’.

class RootUIElement(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]¶

Bases: Enum

Stuff provided by the root ui.

ACCOUNT_BUTTON = 'account_button'¶

ACHIEVEMENTS_BUTTON = 'achievements_button'¶

CHEST_SLOT_0 = 'chest_slot_0'¶

CHEST_SLOT_1 = 'chest_slot_1'¶

CHEST_SLOT_2 = 'chest_slot_2'¶

CHEST_SLOT_3 = 'chest_slot_3'¶

GET_TOKENS_BUTTON = 'get_tokens_button'¶

INBOX_BUTTON = 'inbox_button'¶

INVENTORY_BUTTON = 'inventory_button'¶

LEVEL_METER = 'level_meter'¶

MENU_BUTTON = 'menu_button'¶

SETTINGS_BUTTON = 'settings_button'¶

SQUAD_BUTTON = 'squad_button'¶

STORE_BUTTON = 'store_button'¶

TICKETS_METER = 'tickets_meter'¶

TOKENS_METER = 'tokens_meter'¶

TROPHY_METER = 'trophy_meter'¶

property available: bool¶

Can uiv1 currently be used?

Code that may run in headless mode, before the UI has been spun up, while other ui systems are active, etc. can check this to avoid likely erroring.

clear_main_window(transition: str | None = None) → None[source]¶: Clear any existing main window.

get_main_window() → bauiv1.MainWindow | None[source]¶: Return main window, if any.

has_main_window() → bool[source]¶: Return whether a main menu window is present.

on_app_loading() → None[source]¶

Called when the app reaches the loading state.

Note that subsystems created after the app switches to the loading state will not receive this callback. Subsystems created by plugins are an example of this.

on_screen_size_change() → None[source]¶

Called when the screen size changes.

Will not be called for the initial screen size.

on_ui_scale_change() → None[source]¶

Called when screen ui-scale changes.

Will not be called for the initial ui scale.

reset() → None[source]¶

Reset the subsystem to a default state.

This is called when switching app modes, but may be called at other times too.

restore_main_window_state(state: MainWindowState) → None[source]¶: Restore UI to a saved state.

save_main_window_state(window: MainWindow) → MainWindowState[source]¶

Fully initialize a window-state from a window.

Use this to get a complete state for later restoration purposes. Calling the window’s get_main_window_state() directly is insufficient.

set_main_window(window: bauiv1.MainWindow, *, from_window: bauiv1.MainWindow | None | bool = True, is_back: bool = False, is_top_level: bool = False, is_auxiliary: bool = False, back_state: MainWindowState | None = None, suppress_warning: bool = False) → None[source]¶

Set the current ‘main’ window.

Generally this should not be called directly; The high level MainWindow methods main_window_replace() and main_window_back() should be used whenever possible to implement navigation.

The caller is responsible for cleaning up any previous main window.

property uiscale: UIScale¶: Current ui scale for the app.

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

class bauiv1.Widget[source]¶

Bases: object

Internal type for low level UI elements; buttons, windows, etc.

Category: User Interface Classes

This class represents a weak reference to a widget object in the internal C++ layer. Currently, functions such as bauiv1.buttonwidget() must be used to instantiate or edit these.

activate() → None[source]¶: Activates a widget; the same as if it had been clicked.

add_delete_callback(call: Callable) → None[source]¶: Add a call to be run immediately after this widget is destroyed.

delete(ignore_missing: bool = True) → None[source]¶: Delete the Widget. Ignores already-deleted Widgets if ignore_missing is True; otherwise an Exception is thrown.

exists() → bool[source]¶

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

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

get_children() → list[bauiv1.Widget][source]¶: Returns any child Widgets of this Widget.

get_screen_space_center() → tuple[float, float][source]¶: Returns the coords of the bauiv1.Widget center relative to the center of the screen. This can be useful for placing pop-up windows and other special cases.

get_selected_child() → bauiv1.Widget | None[source]¶: Returns the selected child Widget or None if nothing is selected.

get_widget_type() → str[source]¶: Return the internal type of the Widget as a string. Note that this is different from the Python bauiv1.Widget type, which is the same for all widgets.

transitioning_out: bool¶

Whether this widget is in the process of dying (read only).

It can be useful to check this on a window’s root widget to prevent multiple window actions from firing simultaneously, potentially leaving the UI in a broken state.

class bauiv1.Window(root_widget: bauiv1.Widget, cleanupcheck: bool = True)¶

Bases: object

A basic window.

Category: User Interface Classes

Essentially wraps a ContainerWidget with some higher level functionality.

get_root_widget() → bauiv1.Widget[source]¶: Return the root widget.

bauiv1.add_clean_frame_callback(call: Callable) → None[source]¶

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

bauiv1.allows_ticket_sales() → bool[source]¶: (internal)

bauiv1.appname() → str[source]¶: (internal)

bauiv1.appnameupper() → str[source]¶

(internal)

Return whether this build of the game can display full unicode such as Emoji, Asian languages, etc.

bauiv1.apptime() → babase.AppTime[source]¶

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.

bauiv1.apptimer(time: float, call: Callable[[], Any]) → None[source]¶

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!'))

Create or edit a button widget.

Category: User Interface Functions

Pass a valid existing bauiv1.Widget as ‘edit’ to modify it; otherwise a new one is created and returned. Arguments that are not set to None are applied to the Widget.

bauiv1.charstr(char_id: babase.SpecialChar) → str[source]¶

Get a unicode string representing a special character.

Category: General Utility Functions

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

See babase.SpecialChar for the list of available characters.

Create or edit a check-box widget.

Category: User Interface Functions

Pass a valid existing bauiv1.Widget as ‘edit’ to modify it; otherwise a new one is created and returned. Arguments that are not set to None are applied to the Widget.

bauiv1.clipboard_is_supported() → bool[source]¶

Return whether this platform supports clipboard operations at all.

Category: General Utility Functions

If this returns False, UIs should not show ‘copy to clipboard’ buttons, etc.

bauiv1.clipboard_set_text(value: str) → None[source]¶

Copy a string to the system clipboard.

Category: General Utility Functions

Ensure that babase.clipboard_is_supported() returns True before adding: buttons/etc. that make use of this functionality.

Create or edit a column widget.

Category: User Interface Functions

Pass a valid existing bauiv1.Widget as ‘edit’ to modify it; otherwise a new one is created and returned. Arguments that are not set to None are applied to the Widget.

bauiv1.commit_app_config() → None¶

Commit the config to persistent storage.

Category: General Utility Functions

(internal)

bauiv1.containerwidget(*, edit: bauiv1.Widget | None = None, parent: bauiv1.Widget | None = None, id: str | None = None, size: Sequence[float] | None = None, position: Sequence[float] | None = None, background: bool | None = None, selected_child: bauiv1.Widget | None = None, transition: str | None = None, cancel_button: bauiv1.Widget | None = None, start_button: bauiv1.Widget | None = None, root_selectable: bool | None = None, on_activate_call: Callable[[], None] | None = None, claims_left_right: bool | None = None, selection_loops: bool | None = None, selection_loops_to_parent: bool | None = None, scale: float | None = None, on_outside_click_call: Callable[[], None] | None = None, single_depth: bool | None = None, visible_child: bauiv1.Widget | None = None, stack_offset: Sequence[float] | None = None, color: Sequence[float] | None = None, on_cancel_call: Callable[[], None] | None = None, print_list_exit_instructions: bool | None = None, click_activate: bool | None = None, always_highlight: bool | None = None, selectable: bool | None = None, scale_origin_stack_offset: Sequence[float] | None = None, toolbar_visibility: Literal['menu_minimal', 'menu_minimal_no_back', 'menu_full', 'menu_full_no_back', 'menu_store', 'menu_store_no_back', 'menu_in_game', 'menu_tokens', 'get_tokens', 'no_menu_minimal', 'inherit'] | None = None, on_select_call: Callable[[], None] | None = None, claim_outside_clicks: bool | None = None, claims_up_down: bool | None = None) → bauiv1.Widget[source]¶

Create or edit a container widget.

Category: User Interface Functions

Pass a valid existing bauiv1.Widget as ‘edit’ to modify it; otherwise a new one is created and returned. Arguments that are not set to None are applied to the Widget.

bauiv1.displaytime() → babase.DisplayTime[source]¶

Return the current display-time in seconds.

Category: General Utility Functions

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.

bauiv1.displaytimer(time: float, call: Callable[[], Any]) → None[source]¶

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.

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

##### 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!’))

bauiv1.do_once() → bool[source]¶

Return whether this is the first time running a line of code.

Category: General Utility Functions

This is used by ‘print_once()’ type calls to keep from overflowing logs. The call functions by registering the filename and line where The call is made from. Returns True if this location has not been registered already, and False if it has.

##### Example This print will only fire for the first loop iteration: >>> for i in range(10): … if babase.do_once(): … print(‘HelloWorld once from loop!’)

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

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

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

bauiv1.fullscreen_control_available() → bool[source]¶: (internal)

bauiv1.fullscreen_control_get() → bool[source]¶: (internal)

bauiv1.fullscreen_control_key_shortcut() → str | None[source]¶: (internal)

bauiv1.fullscreen_control_set(val: bool) → None[source]¶: (internal)

bauiv1.get_display_resolution() → tuple[int, int] | None[source]¶

(internal)

Return the currently selected display resolution for fullscreen display. Returns None if resolutions cannot be directly set.

bauiv1.get_input_idle_time() → float[source]¶: Return seconds since any local input occurred (touch, keypress, etc.).

bauiv1.get_ip_address_type(addr: str) → AddressFamily¶: Return socket.AF_INET6 or socket.AF_INET4 for the provided address.

bauiv1.get_low_level_config_value(key: str, default_value: int) → int[source]¶: (internal)

bauiv1.get_max_graphics_quality() → str[source]¶

(internal)

Return the max graphics-quality supported on the current hardware.

bauiv1.get_qrcode_texture(url: str) → bauiv1.Texture[source]¶

Return a QR code texture.

The provided url must be 64 bytes or less.

bauiv1.get_remote_app_name() → babase.Lstr¶: (internal)

bauiv1.get_replays_dir() → str[source]¶: (internal)

bauiv1.get_special_widget(name: Literal['squad_button', 'back_button', 'account_button', 'achievements_button', 'settings_button', 'inbox_button', 'store_button', 'get_tokens_button', 'inventory_button', 'tickets_meter', 'tokens_meter', 'trophy_meter', 'level_meter', 'overlay_stack', 'chest_0_button', 'chest_1_button', 'chest_2_button', 'chest_3_button']) → bauiv1.Widget[source]¶: (internal)

bauiv1.get_string_height(string: str, suppress_warning: bool = False) → float[source]¶

(internal)

Given a string, returns its height using the standard small app font.

bauiv1.get_string_width(string: str, suppress_warning: bool = False) → float[source]¶

(internal)

Given a string, returns its width using the standard small app font.

bauiv1.get_type_name(cls: type) → str¶: Return a full type name including module for a class.

bauiv1.get_virtual_screen_size() → tuple[float, float][source]¶

(internal)

Return the current virtual size of the display.

bauiv1.getclass(name: str, subclassof: type[T], check_sdlib_modulename_clash: bool = False) → type[T]¶

Given a full class name such as foo.bar.MyClass, return the class.

Category: General Utility Functions

The class will be checked to make sure it is a subclass of the provided ‘subclassof’ class, and a TypeError will be raised if not.

bauiv1.getmesh(name: str) → bauiv1.Mesh[source]¶: Load a mesh for use solely in the local user interface.

bauiv1.getsound(name: str) → bauiv1.Sound[source]¶: Load a sound for use in the ui.

bauiv1.gettexture(name: str) → bauiv1.Texture[source]¶: Load a texture for use in the ui.

bauiv1.have_permission(permission: babase.Permission) → bool[source]¶: (internal)

Create or edit a horizontal scroll widget.

Category: User Interface Functions

Pass a valid existing bauiv1.Widget as ‘edit’ to modify it; otherwise a new one is created and returned. Arguments that are not set to None are applied to the Widget.

bauiv1.imagewidget(*, edit: bauiv1.Widget | None = None, parent: bauiv1.Widget | None = None, size: Sequence[float] | None = None, position: Sequence[float] | None = None, color: Sequence[float] | None = None, texture: bauiv1.Texture | None = None, opacity: float | None = None, mesh_transparent: bauiv1.Mesh | None = None, mesh_opaque: bauiv1.Mesh | None = None, has_alpha_channel: bool = True, tint_texture: bauiv1.Texture | None = None, tint_color: Sequence[float] | None = None, transition_delay: float | None = None, draw_controller: bauiv1.Widget | None = None, tint2_color: Sequence[float] | None = None, tilt_scale: float | None = None, mask_texture: bauiv1.Texture | None = None, radial_amount: float | None = None, draw_controller_mult: float | None = None) → bauiv1.Widget[source]¶

Create or edit an image widget.

Category: User Interface Functions

Pass a valid existing bauiv1.Widget as ‘edit’ to modify it; otherwise a new one is created and returned. Arguments that are not set to None are applied to the Widget.

bauiv1.in_logic_thread() → bool[source]¶

(internal)

Returns whether or not the current thread is the logic thread.

bauiv1.in_main_menu() → bool[source]¶

(internal)

Returns whether or not the app-mode is currently in a main menu situation (as opposed to gameplay).

bauiv1.increment_analytics_count(name: str, increment: int = 1) → None[source]¶: (internal)

bauiv1.is_browser_likely_available() → bool¶

Return whether a browser likely exists on the current device.

category: General Utility Functions

If this returns False you may want to avoid calling babase.open_url() with any lengthy addresses. (babase.open_url() will display an address as a string in a window if unable to bring up a browser, but that is only useful for simple URLs.)

bauiv1.is_xcode_build() → bool[source]¶: (internal)

bauiv1.lock_all_input() → None[source]¶

(internal)

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

bauiv1.native_review_request() → None[source]¶: (internal)

bauiv1.native_review_request_supported() → bool[source]¶: (internal)

bauiv1.open_file_externally(path: str) → None[source]¶

(internal)

Open the provided file in the default external app.

bauiv1.open_url(address: str, force_fallback: bool = False) → None[source]¶

Open the provided URL.

Category: General Utility Functions

Attempts to open the provided url in a web-browser. If that is not possible (or force_fallback is True), instead displays the url as a string and/or qrcode.

bauiv1.overlay_web_browser_close() → bool[source]¶

Close any open overlay web browser.

Category: General Utility Functions

bauiv1.overlay_web_browser_is_open() → bool[source]¶

Return whether an overlay web browser is open currently.

Category: General Utility Functions

bauiv1.overlay_web_browser_is_supported() → bool[source]¶

Return whether an overlay web browser is supported here.

Category: General Utility Functions

An overlay web browser is a small dialog that pops up over the top of the main engine window. It can be used for performing simple tasks such as sign-ins.

bauiv1.overlay_web_browser_open_url(address: str) → None[source]¶

Open the provided URL in an overlayw web browser.

Category: General Utility Functions

An overlay web browser is a small dialog that pops up over the top of the main engine window. It can be used for performing simple tasks such as sign-ins.

bauiv1.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[source]¶

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.

bauiv1.quit(confirm: bool = False, quit_type: babase.QuitType | None = None) → None[source]¶

Quit the app.

Category: General Utility Functions

If ‘confirm’ is True, a confirm dialog will be presented if conditions allow; otherwise the quit will still be immediate. See docs for babase.QuitType for explanations of the optional ‘quit_type’ arg.

bauiv1.request_permission(permission: babase.Permission) → None[source]¶: (internal)

bauiv1.root_ui_pause_updates() → None[source]¶: Temporarily pause updates to the root ui for animation purposes.

bauiv1.root_ui_resume_updates() → None[source]¶: Temporarily resume updates to the root ui for animation purposes.

Create or edit a row widget.

Category: User Interface Functions

Pass a valid existing bauiv1.Widget as ‘edit’ to modify it; otherwise a new one is created and returned. Arguments that are not set to None are applied to the Widget.

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

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.

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

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.

Create or edit a scroll widget.

Category: User Interface Functions

Pass a valid existing bauiv1.Widget as ‘edit’ to modify it; otherwise a new one is created and returned. Arguments that are not set to None are applied to the Widget.

bauiv1.set_analytics_screen(screen: str) → None[source]¶

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

bauiv1.set_low_level_config_value(key: str, value: int) → None[source]¶: (internal)

bauiv1.set_party_window_open(value: bool) → None[source]¶: (internal)

bauiv1.set_ui_input_device(input_device_id: int | None) → None[source]¶

(internal)

Sets the input-device that currently owns the user interface.

Create or edit a spinner widget.

Category: User Interface Functions

Pass a valid existing bauiv1.Widget as ‘edit’ to modify it; otherwise a new one is created and returned. Arguments that are not set to None are applied to the Widget.

bauiv1.supports_max_fps() → bool[source]¶: (internal)

bauiv1.supports_unicode_display() → bool[source]¶: Return whether we can display all unicode characters in the gui.

bauiv1.supports_vsync() → bool[source]¶: (internal)

Create or edit a text widget.

Category: User Interface Functions

Pass a valid existing bauiv1.Widget as ‘edit’ to modify it; otherwise a new one is created and returned. Arguments that are not set to None are applied to the Widget.

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

bauiv1.uibounds() → tuple[float, float, float, float][source]¶

(internal)

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

bauiv1.uicleanupcheck(obj: Any, widget: bauiv1.Widget) → None¶

Checks to ensure a widget-owning object gets cleaned up properly.

Category: User Interface Functions

This adds a check which will print an error message if the provided object still exists ~5 seconds after the provided bauiv1.Widget dies.

This is a good sanity check for any sort of object that wraps or controls a bauiv1.Widget. For instance, a ‘Window’ class instance has no reason to still exist once its root container bauiv1.Widget has fully transitioned out and been destroyed. Circular references or careless strong referencing can lead to such objects never getting destroyed, however, and this helps detect such cases to avoid memory leaks.

bauiv1.unlock_all_input() → None[source]¶

(internal)

Resumes normal keyboard, mouse, and gamepad event processing.

bauiv1.utc_now_cloud() → datetime.datetime¶

Returns estimated utc time regardless of local clock settings.

Applies offsets pulled from server communication/etc.

bauiv1.widget(*, edit: bauiv1.Widget, up_widget: bauiv1.Widget | None = None, down_widget: bauiv1.Widget | None = None, left_widget: bauiv1.Widget | None = None, right_widget: bauiv1.Widget | None = None, show_buffer_top: float | None = None, show_buffer_bottom: float | None = None, show_buffer_left: float | None = None, show_buffer_right: float | None = None, depth_range: tuple[float, float] | None = None, autoselect: bool | None = None) → None[source]¶

Edit common attributes of any widget.

Category: User Interface Functions

Unlike other UI calls, this can only be used to edit, not to create.

bauiv1.workspaces_in_use() → bool[source]¶

(internal)

Returns whether workspaces functionality has been enabled at any point this run.