babase
Common shared Ballistica components.
For modding purposes, this package should generally not be used directly. Instead one should use purpose-built packages such as bascenev1 or bauiv1 which themselves import various functionality from here and reexpose it in a more focused way.
1# Released under the MIT License. See LICENSE for details. 2# 3"""Common shared Ballistica components. 4 5For modding purposes, this package should generally not be used directly. 6Instead one should use purpose-built packages such as bascenev1 or bauiv1 7which themselves import various functionality from here and reexpose it in 8a more focused way. 9""" 10# pylint: disable=redefined-builtin 11 12# The stuff we expose here at the top level is our 'public' api for use 13# from other modules/packages. Code *within* this package should import 14# things from this package's submodules directly to reduce the chance of 15# dependency loops. The exception is TYPE_CHECKING blocks and 16# annotations since those aren't evaluated at runtime. 17 18from efro.util import set_canonical_module_names 19 20 21import _babase 22from _babase import ( 23 add_clean_frame_callback, 24 allows_ticket_sales, 25 android_get_external_files_dir, 26 appname, 27 appnameupper, 28 apptime, 29 apptimer, 30 AppTimer, 31 asset_loads_allowed, 32 fullscreen_control_available, 33 fullscreen_control_get, 34 fullscreen_control_key_shortcut, 35 fullscreen_control_set, 36 charstr, 37 clipboard_get_text, 38 clipboard_has_text, 39 clipboard_is_supported, 40 clipboard_set_text, 41 ContextCall, 42 ContextRef, 43 displaytime, 44 displaytimer, 45 DisplayTimer, 46 do_once, 47 env, 48 Env, 49 fade_screen, 50 fatal_error, 51 get_display_resolution, 52 get_immediate_return_code, 53 get_input_idle_time, 54 get_low_level_config_value, 55 get_max_graphics_quality, 56 get_replays_dir, 57 get_string_height, 58 get_string_width, 59 get_v1_cloud_log_file_path, 60 getsimplesound, 61 has_user_run_commands, 62 have_chars, 63 have_permission, 64 in_logic_thread, 65 increment_analytics_count, 66 invoke_main_menu, 67 is_os_playing_music, 68 is_xcode_build, 69 lock_all_input, 70 mac_music_app_get_playlists, 71 mac_music_app_get_volume, 72 mac_music_app_init, 73 mac_music_app_play_playlist, 74 mac_music_app_set_volume, 75 mac_music_app_stop, 76 music_player_play, 77 music_player_set_volume, 78 music_player_shutdown, 79 music_player_stop, 80 native_review_request, 81 native_review_request_supported, 82 native_stack_trace, 83 open_file_externally, 84 open_url, 85 overlay_web_browser_close, 86 overlay_web_browser_is_open, 87 overlay_web_browser_is_supported, 88 overlay_web_browser_open_url, 89 print_load_info, 90 push_back_press, 91 pushcall, 92 quit, 93 reload_media, 94 request_permission, 95 safecolor, 96 screenmessage, 97 set_analytics_screen, 98 set_low_level_config_value, 99 set_thread_name, 100 set_ui_input_device, 101 show_progress_bar, 102 shutdown_suppress_begin, 103 shutdown_suppress_end, 104 shutdown_suppress_count, 105 SimpleSound, 106 supports_max_fps, 107 supports_vsync, 108 unlock_all_input, 109 user_agent_string, 110 Vec3, 111 workspaces_in_use, 112) 113 114from babase._accountv2 import AccountV2Handle, AccountV2Subsystem 115from babase._app import App 116from babase._appconfig import commit_app_config 117from babase._appintent import AppIntent, AppIntentDefault, AppIntentExec 118from babase._appmode import AppMode 119from babase._appsubsystem import AppSubsystem 120from babase._appmodeselector import AppModeSelector 121from babase._appconfig import AppConfig 122from babase._apputils import ( 123 handle_leftover_v1_cloud_log_file, 124 is_browser_likely_available, 125 garbage_collect, 126 get_remote_app_name, 127 AppHealthMonitor, 128) 129from babase._devconsole import ( 130 DevConsoleTab, 131 DevConsoleTabEntry, 132 DevConsoleSubsystem, 133) 134from babase._emptyappmode import EmptyAppMode 135from babase._error import ( 136 print_exception, 137 print_error, 138 ContextError, 139 NotFoundError, 140 PlayerNotFoundError, 141 SessionPlayerNotFoundError, 142 NodeNotFoundError, 143 ActorNotFoundError, 144 InputDeviceNotFoundError, 145 WidgetNotFoundError, 146 ActivityNotFoundError, 147 TeamNotFoundError, 148 MapNotFoundError, 149 SessionTeamNotFoundError, 150 SessionNotFoundError, 151 DelegateNotFoundError, 152) 153from babase._general import ( 154 utf8_all, 155 DisplayTime, 156 AppTime, 157 WeakCall, 158 Call, 159 existing, 160 Existable, 161 verify_object_death, 162 storagename, 163 getclass, 164 get_type_name, 165) 166from babase._language import Lstr, LanguageSubsystem 167from babase._login import LoginAdapter, LoginInfo 168 169# noinspection PyProtectedMember 170# (PyCharm inspection bug?) 171from babase._mgen.enums import ( 172 Permission, 173 SpecialChar, 174 InputType, 175 UIScale, 176 QuitType, 177) 178from babase._math import normalized_color, is_point_in_box, vec3validate 179from babase._meta import MetadataSubsystem 180from babase._net import get_ip_address_type, DEFAULT_REQUEST_TIMEOUT_SECONDS 181from babase._plugin import PluginSpec, Plugin, PluginSubsystem 182from babase._stringedit import StringEditAdapter, StringEditSubsystem 183from babase._text import timestring 184 185_babase.app = app = App() 186app.postinit() 187 188__all__ = [ 189 'AccountV2Handle', 190 'AccountV2Subsystem', 191 'ActivityNotFoundError', 192 'ActorNotFoundError', 193 'allows_ticket_sales', 194 'add_clean_frame_callback', 195 'android_get_external_files_dir', 196 'app', 197 'app', 198 'App', 199 'AppConfig', 200 'AppHealthMonitor', 201 'AppIntent', 202 'AppIntentDefault', 203 'AppIntentExec', 204 'AppMode', 205 'appname', 206 'appnameupper', 207 'AppModeSelector', 208 'AppSubsystem', 209 'apptime', 210 'AppTime', 211 'apptime', 212 'apptimer', 213 'AppTimer', 214 'asset_loads_allowed', 215 'Call', 216 'fullscreen_control_available', 217 'fullscreen_control_get', 218 'fullscreen_control_key_shortcut', 219 'fullscreen_control_set', 220 'charstr', 221 'clipboard_get_text', 222 'clipboard_has_text', 223 'clipboard_is_supported', 224 'clipboard_set_text', 225 'commit_app_config', 226 'ContextCall', 227 'ContextError', 228 'ContextRef', 229 'DelegateNotFoundError', 230 'DevConsoleTab', 231 'DevConsoleTabEntry', 232 'DevConsoleSubsystem', 233 'DisplayTime', 234 'displaytime', 235 'displaytimer', 236 'DisplayTimer', 237 'do_once', 238 'EmptyAppMode', 239 'env', 240 'Env', 241 'Existable', 242 'existing', 243 'fade_screen', 244 'fatal_error', 245 'garbage_collect', 246 'get_display_resolution', 247 'get_immediate_return_code', 248 'get_input_idle_time', 249 'get_ip_address_type', 250 'get_low_level_config_value', 251 'get_max_graphics_quality', 252 'get_remote_app_name', 253 'get_replays_dir', 254 'get_string_height', 255 'get_string_width', 256 'get_v1_cloud_log_file_path', 257 'get_type_name', 258 'getclass', 259 'getsimplesound', 260 'handle_leftover_v1_cloud_log_file', 261 'has_user_run_commands', 262 'have_chars', 263 'have_permission', 264 'in_logic_thread', 265 'increment_analytics_count', 266 'InputDeviceNotFoundError', 267 'InputType', 268 'invoke_main_menu', 269 'is_browser_likely_available', 270 'is_browser_likely_available', 271 'is_os_playing_music', 272 'is_point_in_box', 273 'is_xcode_build', 274 'LanguageSubsystem', 275 'lock_all_input', 276 'LoginAdapter', 277 'LoginInfo', 278 'Lstr', 279 'mac_music_app_get_playlists', 280 'mac_music_app_get_volume', 281 'mac_music_app_init', 282 'mac_music_app_play_playlist', 283 'mac_music_app_set_volume', 284 'mac_music_app_stop', 285 'MapNotFoundError', 286 'MetadataSubsystem', 287 'music_player_play', 288 'music_player_set_volume', 289 'music_player_shutdown', 290 'music_player_stop', 291 'native_review_request', 292 'native_review_request_supported', 293 'native_stack_trace', 294 'NodeNotFoundError', 295 'normalized_color', 296 'NotFoundError', 297 'open_file_externally', 298 'open_url', 299 'overlay_web_browser_close', 300 'overlay_web_browser_is_open', 301 'overlay_web_browser_is_supported', 302 'overlay_web_browser_open_url', 303 'Permission', 304 'PlayerNotFoundError', 305 'Plugin', 306 'PluginSubsystem', 307 'PluginSpec', 308 'print_error', 309 'print_exception', 310 'print_load_info', 311 'push_back_press', 312 'pushcall', 313 'quit', 314 'QuitType', 315 'reload_media', 316 'request_permission', 317 'safecolor', 318 'screenmessage', 319 'SessionNotFoundError', 320 'SessionPlayerNotFoundError', 321 'SessionTeamNotFoundError', 322 'set_analytics_screen', 323 'set_low_level_config_value', 324 'set_thread_name', 325 'set_ui_input_device', 326 'show_progress_bar', 327 'shutdown_suppress_begin', 328 'shutdown_suppress_end', 329 'shutdown_suppress_count', 330 'SimpleSound', 331 'SpecialChar', 332 'storagename', 333 'StringEditAdapter', 334 'StringEditSubsystem', 335 'supports_max_fps', 336 'supports_vsync', 337 'TeamNotFoundError', 338 'timestring', 339 'UIScale', 340 'unlock_all_input', 341 'user_agent_string', 342 'utf8_all', 343 'Vec3', 344 'vec3validate', 345 'verify_object_death', 346 'WeakCall', 347 'WidgetNotFoundError', 348 'workspaces_in_use', 349 'DEFAULT_REQUEST_TIMEOUT_SECONDS', 350] 351 352# We want stuff to show up as babase.Foo instead of babase._sub.Foo. 353set_canonical_module_names(globals()) 354 355# Allow the native layer to wrap a few things up. 356_babase.reached_end_of_babase() 357 358# Marker we pop down at the very end so other modules can run sanity 359# checks to make sure we aren't importing them reciprocally when they 360# import us. 361_REACHED_END_OF_MODULE = True
426class AccountV2Handle: 427 """Handle for interacting with a V2 account. 428 429 This class supports the 'with' statement, which is how it is 430 used with some operations such as cloud messaging. 431 """ 432 433 accountid: str 434 tag: str 435 workspacename: str | None 436 workspaceid: str | None 437 logins: dict[LoginType, LoginInfo] 438 439 def __enter__(self) -> None: 440 """Support for "with" statement. 441 442 This allows cloud messages to be sent on our behalf. 443 """ 444 445 def __exit__(self, exc_type: Any, exc_value: Any, traceback: Any) -> Any: 446 """Support for "with" statement. 447 448 This allows cloud messages to be sent on our behalf. 449 """
Handle for interacting with a V2 account.
This class supports the 'with' statement, which is how it is used with some operations such as cloud messaging.
26class AccountV2Subsystem: 27 """Subsystem for modern account handling in the app. 28 29 Category: **App Classes** 30 31 Access the single shared instance of this class at 'ba.app.plus.accounts'. 32 """ 33 34 def __init__(self) -> None: 35 from babase._login import LoginAdapterGPGS, LoginAdapterGameCenter 36 37 # Whether or not everything related to an initial login 38 # (or lack thereof) has completed. This includes things like 39 # workspace syncing. Completion of this is what flips the app 40 # into 'running' state. 41 self._initial_sign_in_completed = False 42 43 self._kicked_off_workspace_load = False 44 45 self.login_adapters: dict[LoginType, LoginAdapter] = {} 46 47 self._implicit_signed_in_adapter: LoginAdapter | None = None 48 self._implicit_state_changed = False 49 self._can_do_auto_sign_in = True 50 51 adapter: LoginAdapter 52 if _babase.using_google_play_game_services(): 53 adapter = LoginAdapterGPGS() 54 self.login_adapters[adapter.login_type] = adapter 55 if _babase.using_game_center(): 56 adapter = LoginAdapterGameCenter() 57 self.login_adapters[adapter.login_type] = adapter 58 59 def on_app_loading(self) -> None: 60 """Should be called at standard on_app_loading time.""" 61 62 for adapter in self.login_adapters.values(): 63 adapter.on_app_loading() 64 65 def have_primary_credentials(self) -> bool: 66 """Are credentials currently set for the primary app account? 67 68 Note that this does not mean these credentials are currently valid; 69 only that they exist. If/when credentials are validated, the 'primary' 70 account handle will be set. 71 """ 72 raise NotImplementedError('This should be overridden.') 73 74 @property 75 def primary(self) -> AccountV2Handle | None: 76 """The primary account for the app, or None if not logged in.""" 77 return self.do_get_primary() 78 79 def on_primary_account_changed( 80 self, account: AccountV2Handle | None 81 ) -> None: 82 """Callback run after the primary account changes. 83 84 Will be called with None on log-outs and when new credentials 85 are set but have not yet been verified. 86 """ 87 assert _babase.in_logic_thread() 88 89 # Currently don't do anything special on sign-outs. 90 if account is None: 91 return 92 93 # If this new account has a workspace, update it and ask to be 94 # informed when that process completes. 95 if account.workspaceid is not None: 96 assert account.workspacename is not None 97 if ( 98 not self._initial_sign_in_completed 99 and not self._kicked_off_workspace_load 100 ): 101 self._kicked_off_workspace_load = True 102 _babase.app.workspaces.set_active_workspace( 103 account=account, 104 workspaceid=account.workspaceid, 105 workspacename=account.workspacename, 106 on_completed=self._on_set_active_workspace_completed, 107 ) 108 else: 109 # Don't activate workspaces if we've already told the game 110 # that initial-log-in is done or if we've already kicked 111 # off a workspace load. 112 _babase.screenmessage( 113 f'\'{account.workspacename}\'' 114 f' will be activated at next app launch.', 115 color=(1, 1, 0), 116 ) 117 _babase.getsimplesound('error').play() 118 return 119 120 # Ok; no workspace to worry about; carry on. 121 if not self._initial_sign_in_completed: 122 self._initial_sign_in_completed = True 123 _babase.app.on_initial_sign_in_complete() 124 125 def on_active_logins_changed(self, logins: dict[LoginType, str]) -> None: 126 """Should be called when logins for the active account change.""" 127 128 for adapter in self.login_adapters.values(): 129 adapter.set_active_logins(logins) 130 131 def on_implicit_sign_in( 132 self, login_type: LoginType, login_id: str, display_name: str 133 ) -> None: 134 """An implicit sign-in happened (called by native layer).""" 135 from babase._login import LoginAdapter 136 137 assert _babase.in_logic_thread() 138 139 with _babase.ContextRef.empty(): 140 self.login_adapters[login_type].set_implicit_login_state( 141 LoginAdapter.ImplicitLoginState( 142 login_id=login_id, display_name=display_name 143 ) 144 ) 145 146 def on_implicit_sign_out(self, login_type: LoginType) -> None: 147 """An implicit sign-out happened (called by native layer).""" 148 assert _babase.in_logic_thread() 149 with _babase.ContextRef.empty(): 150 self.login_adapters[login_type].set_implicit_login_state(None) 151 152 def on_no_initial_primary_account(self) -> None: 153 """Callback run if the app has no primary account after launch. 154 155 Either this callback or on_primary_account_changed will be called 156 within a few seconds of app launch; the app can move forward 157 with the startup sequence at that point. 158 """ 159 if not self._initial_sign_in_completed: 160 self._initial_sign_in_completed = True 161 _babase.app.on_initial_sign_in_complete() 162 163 @staticmethod 164 def _hashstr(val: str) -> str: 165 md5 = hashlib.md5() 166 md5.update(val.encode()) 167 return md5.hexdigest() 168 169 def on_implicit_login_state_changed( 170 self, 171 login_type: LoginType, 172 state: LoginAdapter.ImplicitLoginState | None, 173 ) -> None: 174 """Called when implicit login state changes. 175 176 Login systems that tend to sign themselves in/out in the 177 background are considered implicit. We may choose to honor or 178 ignore their states, allowing the user to opt for other login 179 types even if the default implicit one can't be explicitly 180 logged out or otherwise controlled. 181 """ 182 from babase._language import Lstr 183 184 assert _babase.in_logic_thread() 185 186 cfg = _babase.app.config 187 cfgkey = 'ImplicitLoginStates' 188 cfgdict = _babase.app.config.setdefault(cfgkey, {}) 189 190 # Store which (if any) adapter is currently implicitly signed 191 # in. Making the assumption there will only ever be one implicit 192 # adapter at a time; may need to revisit this logic if that 193 # changes. 194 prev_state = cfgdict.get(login_type.value) 195 if state is None: 196 self._implicit_signed_in_adapter = None 197 new_state = cfgdict[login_type.value] = None 198 else: 199 self._implicit_signed_in_adapter = self.login_adapters[login_type] 200 new_state = cfgdict[login_type.value] = self._hashstr( 201 state.login_id 202 ) 203 204 # Special case: if the user is already signed in but not 205 # with this implicit login, let them know that the 'Welcome 206 # back FOO' they likely just saw is not actually accurate. 207 if ( 208 self.primary is not None 209 and not self.login_adapters[login_type].is_back_end_active() 210 ): 211 service_str: Lstr | None 212 if login_type is LoginType.GPGS: 213 service_str = Lstr(resource='googlePlayText') 214 elif login_type is LoginType.GAME_CENTER: 215 # Note: Apparently Game Center is just called 'Game 216 # Center' in all languages. Can revisit if not true. 217 # https://developer.apple.com/forums/thread/725779 218 service_str = Lstr(value='Game Center') 219 elif login_type is LoginType.EMAIL: 220 # Not possible; just here for exhaustive coverage. 221 service_str = None 222 else: 223 assert_never(login_type) 224 if service_str is not None: 225 _babase.apptimer( 226 2.0, 227 partial( 228 _babase.screenmessage, 229 Lstr( 230 resource='notUsingAccountText', 231 subs=[ 232 ('${ACCOUNT}', state.display_name), 233 ('${SERVICE}', service_str), 234 ], 235 ), 236 (1, 0.5, 0), 237 ), 238 ) 239 240 cfg.commit() 241 242 # We want to respond any time the implicit state changes; 243 # generally this means the user has explicitly signed in/out or 244 # switched accounts within that back-end. 245 if prev_state != new_state: 246 if DEBUG_LOG: 247 logging.debug( 248 'AccountV2: Implicit state changed (%s -> %s);' 249 ' will update app sign-in state accordingly.', 250 prev_state, 251 new_state, 252 ) 253 self._implicit_state_changed = True 254 255 # We may want to auto-sign-in based on this new state. 256 self._update_auto_sign_in() 257 258 def on_cloud_connectivity_changed(self, connected: bool) -> None: 259 """Should be called with cloud connectivity changes.""" 260 del connected # Unused. 261 assert _babase.in_logic_thread() 262 263 # We may want to auto-sign-in based on this new state. 264 self._update_auto_sign_in() 265 266 def do_get_primary(self) -> AccountV2Handle | None: 267 """Internal - should be overridden by subclass.""" 268 raise NotImplementedError('This should be overridden.') 269 270 def set_primary_credentials(self, credentials: str | None) -> None: 271 """Set credentials for the primary app account.""" 272 raise NotImplementedError('This should be overridden.') 273 274 def _update_auto_sign_in(self) -> None: 275 plus = _babase.app.plus 276 assert plus is not None 277 278 # If implicit state has changed, try to respond. 279 if self._implicit_state_changed: 280 if self._implicit_signed_in_adapter is None: 281 # If implicit back-end has signed out, we follow suit 282 # immediately; no need to wait for network connectivity. 283 if DEBUG_LOG: 284 logging.debug( 285 'AccountV2: Signing out as result' 286 ' of implicit state change...', 287 ) 288 plus.accounts.set_primary_credentials(None) 289 self._implicit_state_changed = False 290 291 # Once we've made a move here we don't want to 292 # do any more automatic stuff. 293 self._can_do_auto_sign_in = False 294 295 else: 296 # Ok; we've got a new implicit state. If we've got 297 # connectivity, let's attempt to sign in with it. 298 # Consider this an 'explicit' sign in because the 299 # implicit-login state change presumably was triggered 300 # by some user action (signing in, signing out, or 301 # switching accounts via the back-end). NOTE: should 302 # test case where we don't have connectivity here. 303 if plus.cloud.is_connected(): 304 if DEBUG_LOG: 305 logging.debug( 306 'AccountV2: Signing in as result' 307 ' of implicit state change...', 308 ) 309 self._implicit_signed_in_adapter.sign_in( 310 self._on_explicit_sign_in_completed, 311 description='implicit state change', 312 ) 313 self._implicit_state_changed = False 314 315 # Once we've made a move here we don't want to 316 # do any more automatic stuff. 317 self._can_do_auto_sign_in = False 318 319 if not self._can_do_auto_sign_in: 320 return 321 322 # If we're not currently signed in, we have connectivity, and 323 # we have an available implicit login, auto-sign-in with it once. 324 # The implicit-state-change logic above should keep things 325 # mostly in-sync, but that might not always be the case due to 326 # connectivity or other issues. We prefer to keep people signed 327 # in as a rule, even if there are corner cases where this might 328 # not be what they want (A user signing out and then restarting 329 # may be auto-signed back in). 330 connected = plus.cloud.is_connected() 331 signed_in_v1 = plus.get_v1_account_state() == 'signed_in' 332 signed_in_v2 = plus.accounts.have_primary_credentials() 333 if ( 334 connected 335 and not signed_in_v1 336 and not signed_in_v2 337 and self._implicit_signed_in_adapter is not None 338 ): 339 if DEBUG_LOG: 340 logging.debug( 341 'AccountV2: Signing in due to on-launch-auto-sign-in...', 342 ) 343 self._can_do_auto_sign_in = False # Only ATTEMPT once 344 self._implicit_signed_in_adapter.sign_in( 345 self._on_implicit_sign_in_completed, description='auto-sign-in' 346 ) 347 348 def _on_explicit_sign_in_completed( 349 self, 350 adapter: LoginAdapter, 351 result: LoginAdapter.SignInResult | Exception, 352 ) -> None: 353 """A sign-in has completed that the user asked for explicitly.""" 354 from babase._language import Lstr 355 356 del adapter # Unused. 357 358 plus = _babase.app.plus 359 assert plus is not None 360 361 # Make some noise on errors since the user knows a 362 # sign-in attempt is happening in this case (the 'explicit' part). 363 if isinstance(result, Exception): 364 # We expect the occasional communication errors; 365 # Log a full exception for anything else though. 366 if not isinstance(result, CommunicationError): 367 logging.warning( 368 'Error on explicit accountv2 sign in attempt.', 369 exc_info=result, 370 ) 371 372 # For now just show 'error'. Should do better than this. 373 _babase.screenmessage( 374 Lstr(resource='internal.signInErrorText'), 375 color=(1, 0, 0), 376 ) 377 _babase.getsimplesound('error').play() 378 379 # Also I suppose we should sign them out in this case since 380 # it could be misleading to be still signed in with the old 381 # account. 382 plus.accounts.set_primary_credentials(None) 383 return 384 385 plus.accounts.set_primary_credentials(result.credentials) 386 387 def _on_implicit_sign_in_completed( 388 self, 389 adapter: LoginAdapter, 390 result: LoginAdapter.SignInResult | Exception, 391 ) -> None: 392 """A sign-in has completed that the user didn't ask for explicitly.""" 393 plus = _babase.app.plus 394 assert plus is not None 395 396 del adapter # Unused. 397 398 # Log errors but don't inform the user; they're not aware of this 399 # attempt and ignorance is bliss. 400 if isinstance(result, Exception): 401 # We expect the occasional communication errors; 402 # Log a full exception for anything else though. 403 if not isinstance(result, CommunicationError): 404 logging.warning( 405 'Error on implicit accountv2 sign in attempt.', 406 exc_info=result, 407 ) 408 return 409 410 # If we're still connected and still not signed in, 411 # plug in the credentials we got. We want to be extra cautious 412 # in case the user has since explicitly signed in since we 413 # kicked off. 414 connected = plus.cloud.is_connected() 415 signed_in_v1 = plus.get_v1_account_state() == 'signed_in' 416 signed_in_v2 = plus.accounts.have_primary_credentials() 417 if connected and not signed_in_v1 and not signed_in_v2: 418 plus.accounts.set_primary_credentials(result.credentials) 419 420 def _on_set_active_workspace_completed(self) -> None: 421 if not self._initial_sign_in_completed: 422 self._initial_sign_in_completed = True 423 _babase.app.on_initial_sign_in_complete()
Subsystem for modern account handling in the app.
Category: App Classes
Access the single shared instance of this class at 'ba.app.plus.accounts'.
59 def on_app_loading(self) -> None: 60 """Should be called at standard on_app_loading time.""" 61 62 for adapter in self.login_adapters.values(): 63 adapter.on_app_loading()
Should be called at standard on_app_loading time.
65 def have_primary_credentials(self) -> bool: 66 """Are credentials currently set for the primary app account? 67 68 Note that this does not mean these credentials are currently valid; 69 only that they exist. If/when credentials are validated, the 'primary' 70 account handle will be set. 71 """ 72 raise NotImplementedError('This should be overridden.')
Are credentials currently set for the primary app account?
Note that this does not mean these credentials are currently valid; only that they exist. If/when credentials are validated, the 'primary' account handle will be set.
74 @property 75 def primary(self) -> AccountV2Handle | None: 76 """The primary account for the app, or None if not logged in.""" 77 return self.do_get_primary()
The primary account for the app, or None if not logged in.
79 def on_primary_account_changed( 80 self, account: AccountV2Handle | None 81 ) -> None: 82 """Callback run after the primary account changes. 83 84 Will be called with None on log-outs and when new credentials 85 are set but have not yet been verified. 86 """ 87 assert _babase.in_logic_thread() 88 89 # Currently don't do anything special on sign-outs. 90 if account is None: 91 return 92 93 # If this new account has a workspace, update it and ask to be 94 # informed when that process completes. 95 if account.workspaceid is not None: 96 assert account.workspacename is not None 97 if ( 98 not self._initial_sign_in_completed 99 and not self._kicked_off_workspace_load 100 ): 101 self._kicked_off_workspace_load = True 102 _babase.app.workspaces.set_active_workspace( 103 account=account, 104 workspaceid=account.workspaceid, 105 workspacename=account.workspacename, 106 on_completed=self._on_set_active_workspace_completed, 107 ) 108 else: 109 # Don't activate workspaces if we've already told the game 110 # that initial-log-in is done or if we've already kicked 111 # off a workspace load. 112 _babase.screenmessage( 113 f'\'{account.workspacename}\'' 114 f' will be activated at next app launch.', 115 color=(1, 1, 0), 116 ) 117 _babase.getsimplesound('error').play() 118 return 119 120 # Ok; no workspace to worry about; carry on. 121 if not self._initial_sign_in_completed: 122 self._initial_sign_in_completed = True 123 _babase.app.on_initial_sign_in_complete()
Callback run after the primary account changes.
Will be called with None on log-outs and when new credentials are set but have not yet been verified.
125 def on_active_logins_changed(self, logins: dict[LoginType, str]) -> None: 126 """Should be called when logins for the active account change.""" 127 128 for adapter in self.login_adapters.values(): 129 adapter.set_active_logins(logins)
Should be called when logins for the active account change.
131 def on_implicit_sign_in( 132 self, login_type: LoginType, login_id: str, display_name: str 133 ) -> None: 134 """An implicit sign-in happened (called by native layer).""" 135 from babase._login import LoginAdapter 136 137 assert _babase.in_logic_thread() 138 139 with _babase.ContextRef.empty(): 140 self.login_adapters[login_type].set_implicit_login_state( 141 LoginAdapter.ImplicitLoginState( 142 login_id=login_id, display_name=display_name 143 ) 144 )
An implicit sign-in happened (called by native layer).
146 def on_implicit_sign_out(self, login_type: LoginType) -> None: 147 """An implicit sign-out happened (called by native layer).""" 148 assert _babase.in_logic_thread() 149 with _babase.ContextRef.empty(): 150 self.login_adapters[login_type].set_implicit_login_state(None)
An implicit sign-out happened (called by native layer).
152 def on_no_initial_primary_account(self) -> None: 153 """Callback run if the app has no primary account after launch. 154 155 Either this callback or on_primary_account_changed will be called 156 within a few seconds of app launch; the app can move forward 157 with the startup sequence at that point. 158 """ 159 if not self._initial_sign_in_completed: 160 self._initial_sign_in_completed = True 161 _babase.app.on_initial_sign_in_complete()
Callback run if the app has no primary account after launch.
Either this callback or on_primary_account_changed will be called within a few seconds of app launch; the app can move forward with the startup sequence at that point.
169 def on_implicit_login_state_changed( 170 self, 171 login_type: LoginType, 172 state: LoginAdapter.ImplicitLoginState | None, 173 ) -> None: 174 """Called when implicit login state changes. 175 176 Login systems that tend to sign themselves in/out in the 177 background are considered implicit. We may choose to honor or 178 ignore their states, allowing the user to opt for other login 179 types even if the default implicit one can't be explicitly 180 logged out or otherwise controlled. 181 """ 182 from babase._language import Lstr 183 184 assert _babase.in_logic_thread() 185 186 cfg = _babase.app.config 187 cfgkey = 'ImplicitLoginStates' 188 cfgdict = _babase.app.config.setdefault(cfgkey, {}) 189 190 # Store which (if any) adapter is currently implicitly signed 191 # in. Making the assumption there will only ever be one implicit 192 # adapter at a time; may need to revisit this logic if that 193 # changes. 194 prev_state = cfgdict.get(login_type.value) 195 if state is None: 196 self._implicit_signed_in_adapter = None 197 new_state = cfgdict[login_type.value] = None 198 else: 199 self._implicit_signed_in_adapter = self.login_adapters[login_type] 200 new_state = cfgdict[login_type.value] = self._hashstr( 201 state.login_id 202 ) 203 204 # Special case: if the user is already signed in but not 205 # with this implicit login, let them know that the 'Welcome 206 # back FOO' they likely just saw is not actually accurate. 207 if ( 208 self.primary is not None 209 and not self.login_adapters[login_type].is_back_end_active() 210 ): 211 service_str: Lstr | None 212 if login_type is LoginType.GPGS: 213 service_str = Lstr(resource='googlePlayText') 214 elif login_type is LoginType.GAME_CENTER: 215 # Note: Apparently Game Center is just called 'Game 216 # Center' in all languages. Can revisit if not true. 217 # https://developer.apple.com/forums/thread/725779 218 service_str = Lstr(value='Game Center') 219 elif login_type is LoginType.EMAIL: 220 # Not possible; just here for exhaustive coverage. 221 service_str = None 222 else: 223 assert_never(login_type) 224 if service_str is not None: 225 _babase.apptimer( 226 2.0, 227 partial( 228 _babase.screenmessage, 229 Lstr( 230 resource='notUsingAccountText', 231 subs=[ 232 ('${ACCOUNT}', state.display_name), 233 ('${SERVICE}', service_str), 234 ], 235 ), 236 (1, 0.5, 0), 237 ), 238 ) 239 240 cfg.commit() 241 242 # We want to respond any time the implicit state changes; 243 # generally this means the user has explicitly signed in/out or 244 # switched accounts within that back-end. 245 if prev_state != new_state: 246 if DEBUG_LOG: 247 logging.debug( 248 'AccountV2: Implicit state changed (%s -> %s);' 249 ' will update app sign-in state accordingly.', 250 prev_state, 251 new_state, 252 ) 253 self._implicit_state_changed = True 254 255 # We may want to auto-sign-in based on this new state. 256 self._update_auto_sign_in()
Called when implicit login state changes.
Login systems that tend to sign themselves in/out in the background are considered implicit. We may choose to honor or ignore their states, allowing the user to opt for other login types even if the default implicit one can't be explicitly logged out or otherwise controlled.
258 def on_cloud_connectivity_changed(self, connected: bool) -> None: 259 """Should be called with cloud connectivity changes.""" 260 del connected # Unused. 261 assert _babase.in_logic_thread() 262 263 # We may want to auto-sign-in based on this new state. 264 self._update_auto_sign_in()
Should be called with cloud connectivity changes.
89class ActivityNotFoundError(NotFoundError): 90 """Exception raised when an expected bascenev1.Activity does not exist. 91 92 Category: **Exception Classes** 93 """
Exception raised when an expected bascenev1.Activity does not exist.
Category: Exception Classes
Inherited Members
- builtins.Exception
- Exception
- builtins.BaseException
- with_traceback
- add_note
- args
82class ActorNotFoundError(NotFoundError): 83 """Exception raised when an expected actor does not exist. 84 85 Category: **Exception Classes** 86 """
Exception raised when an expected actor does not exist.
Category: Exception Classes
Inherited Members
- builtins.Exception
- Exception
- builtins.BaseException
- with_traceback
- add_note
- args
49class App: 50 """A class for high level app functionality and state. 51 52 Category: **App Classes** 53 54 Use babase.app to access the single shared instance of this class. 55 56 Note that properties not documented here should be considered internal 57 and subject to change without warning. 58 """ 59 60 # pylint: disable=too-many-public-methods 61 62 # A few things defined as non-optional values but not actually 63 # available until the app starts. 64 plugins: PluginSubsystem 65 lang: LanguageSubsystem 66 health_monitor: AppHealthMonitor 67 68 # How long we allow shutdown tasks to run before killing them. 69 # Currently the entire app hard-exits if shutdown takes 10 seconds, 70 # so we need to keep it under that. 71 SHUTDOWN_TASK_TIMEOUT_SECONDS = 5 72 73 class State(Enum): 74 """High level state the app can be in.""" 75 76 # The app has not yet begun starting and should not be used in 77 # any way. 78 NOT_STARTED = 0 79 80 # The native layer is spinning up its machinery (screens, 81 # renderers, etc.). Nothing should happen in the Python layer 82 # until this completes. 83 NATIVE_BOOTSTRAPPING = 1 84 85 # Python app subsystems are being inited but should not yet 86 # interact or do any work. 87 INITING = 2 88 89 # Python app subsystems are inited and interacting, but the app 90 # has not yet embarked on a high level course of action. It is 91 # doing initial account logins, workspace & asset downloads, 92 # etc. 93 LOADING = 3 94 95 # All pieces are in place and the app is now doing its thing. 96 RUNNING = 4 97 98 # Used on platforms such as mobile where the app basically needs 99 # to shut down while backgrounded. In this state, all event 100 # loops are suspended and all graphics and audio must cease 101 # completely. Be aware that the suspended state can be entered 102 # from any other state including NATIVE_BOOTSTRAPPING and 103 # SHUTTING_DOWN. 104 SUSPENDED = 5 105 106 # The app is shutting down. This process may involve sending 107 # network messages or other things that can take up to a few 108 # seconds, so ideally graphics and audio should remain 109 # functional (with fades or spinners or whatever to show 110 # something is happening). 111 SHUTTING_DOWN = 6 112 113 # The app has completed shutdown. Any code running here should 114 # be basically immediate. 115 SHUTDOWN_COMPLETE = 7 116 117 class DefaultAppModeSelector(AppModeSelector): 118 """Decides which AppModes to use to handle AppIntents. 119 120 This default version is generated by the project updater based 121 on the 'default_app_modes' value in the projectconfig. 122 123 It is also possible to modify app mode selection behavior by 124 setting app.mode_selector to an instance of a custom 125 AppModeSelector subclass. This is a good way to go if you are 126 modifying app behavior dynamically via a plugin instead of 127 statically in a spinoff project. 128 """ 129 130 @override 131 def app_mode_for_intent( 132 self, intent: AppIntent 133 ) -> type[AppMode] | None: 134 # pylint: disable=cyclic-import 135 136 # __DEFAULT_APP_MODE_SELECTION_BEGIN__ 137 # This section generated by batools.appmodule; do not edit. 138 139 # Ask our default app modes to handle it. 140 # (generated from 'default_app_modes' in projectconfig). 141 import baclassic 142 import babase 143 144 for appmode in [ 145 baclassic.ClassicAppMode, 146 babase.EmptyAppMode, 147 ]: 148 if appmode.can_handle_intent(intent): 149 return appmode 150 151 return None 152 153 # __DEFAULT_APP_MODE_SELECTION_END__ 154 155 @override 156 def testable_app_modes(self) -> list[type[AppMode]]: 157 # pylint: disable=cyclic-import 158 159 # __DEFAULT_TESTABLE_APP_MODES_BEGIN__ 160 # This section generated by batools.appmodule; do not edit. 161 162 # Return all our default_app_modes as testable. 163 # (generated from 'default_app_modes' in projectconfig). 164 import baclassic 165 import babase 166 167 return [ 168 baclassic.ClassicAppMode, 169 babase.EmptyAppMode, 170 ] 171 # __DEFAULT_TESTABLE_APP_MODES_END__ 172 173 def __init__(self) -> None: 174 """(internal) 175 176 Do not instantiate this class. You can access the single shared 177 instance of it through various high level packages: 'babase.app', 178 'bascenev1.app', 'bauiv1.app', etc. 179 """ 180 181 # Hack for docs-generation: we can be imported with dummy modules 182 # instead of our actual binary ones, but we don't function. 183 if os.environ.get('BA_RUNNING_WITH_DUMMY_MODULES') == '1': 184 return 185 186 self.env: babase.Env = _babase.Env() 187 self.state = self.State.NOT_STARTED 188 189 # Default executor which can be used for misc background 190 # processing. It should also be passed to any additional asyncio 191 # loops we create so that everything shares the same single set 192 # of worker threads. 193 self.threadpool = ThreadPoolExecutor( 194 thread_name_prefix='baworker', 195 initializer=self._thread_pool_thread_init, 196 ) 197 198 self.meta = MetadataSubsystem() 199 self.net = NetworkSubsystem() 200 self.workspaces = WorkspaceSubsystem() 201 self.components = AppComponentSubsystem() 202 self.stringedit = StringEditSubsystem() 203 self.devconsole = DevConsoleSubsystem() 204 205 # This is incremented any time the app is backgrounded or 206 # foregrounded; can be a simple way to determine if network data 207 # should be refreshed/etc. 208 self.fg_state = 0 209 210 self._subsystems: list[AppSubsystem] = [] 211 self._native_bootstrapping_completed = False 212 self._init_completed = False 213 self._meta_scan_completed = False 214 self._native_start_called = False 215 self._native_suspended = False 216 self._native_shutdown_called = False 217 self._native_shutdown_complete_called = False 218 self._initial_sign_in_completed = False 219 self._called_on_initing = False 220 self._called_on_loading = False 221 self._called_on_running = False 222 self._subsystem_registration_ended = False 223 self._pending_apply_app_config = False 224 self._asyncio_loop: asyncio.AbstractEventLoop | None = None 225 self._asyncio_tasks: set[asyncio.Task] = set() 226 self._asyncio_timer: babase.AppTimer | None = None 227 self._config: babase.AppConfig | None = None 228 self._pending_intent: AppIntent | None = None 229 self._intent: AppIntent | None = None 230 self._mode_selector: babase.AppModeSelector | None = None 231 self._mode_instances: dict[type[AppMode], AppMode] = {} 232 self._mode: AppMode | None = None 233 self._shutdown_task: asyncio.Task[None] | None = None 234 self._shutdown_tasks: list[Coroutine[None, None, None]] = [ 235 self._wait_for_shutdown_suppressions(), 236 self._fade_and_shutdown_graphics(), 237 self._fade_and_shutdown_audio(), 238 ] 239 self._pool_thread_count = 0 240 241 # We hold a lock while lazy-loading our subsystem properties so 242 # we don't spin up any subsystem more than once, but the lock is 243 # recursive so that the subsystems can instantiate other 244 # subsystems. 245 self._subsystem_property_lock = RLock() 246 self._subsystem_property_data: dict[str, AppSubsystem | bool] = {} 247 248 def postinit(self) -> None: 249 """Called after we've been inited and assigned to babase.app. 250 251 Anything that accesses babase.app as part of its init process 252 must go here instead of __init__. 253 """ 254 255 # Hack for docs-generation: We can be imported with dummy 256 # modules instead of our actual binary ones, but we don't 257 # function. 258 if os.environ.get('BA_RUNNING_WITH_DUMMY_MODULES') == '1': 259 return 260 261 self.lang = LanguageSubsystem() 262 self.plugins = PluginSubsystem() 263 264 @property 265 def active(self) -> bool: 266 """Whether the app is currently front and center. 267 268 This will be False when the app is hidden, other activities 269 are covering it, etc. (depending on the platform). 270 """ 271 return _babase.app_is_active() 272 273 @property 274 def asyncio_loop(self) -> asyncio.AbstractEventLoop: 275 """The logic thread's asyncio event loop. 276 277 This allow async tasks to be run in the logic thread. 278 279 Generally you should call App.create_async_task() to schedule 280 async code to run instead of using this directly. That will 281 handle retaining the task and logging errors automatically. 282 Only schedule tasks onto asyncio_loop yourself when you intend 283 to hold on to the returned task and await its results. Releasing 284 the task reference can lead to subtle bugs such as unreported 285 errors and garbage-collected tasks disappearing before their 286 work is done. 287 288 Note that, at this time, the asyncio loop is encapsulated 289 and explicitly stepped by the engine's logic thread loop and 290 thus things like asyncio.get_running_loop() will unintuitively 291 *not* return this loop from most places in the logic thread; 292 only from within a task explicitly created in this loop. 293 Hopefully this situation will be improved in the future with a 294 unified event loop. 295 """ 296 assert _babase.in_logic_thread() 297 assert self._asyncio_loop is not None 298 return self._asyncio_loop 299 300 def create_async_task( 301 self, coro: Coroutine[Any, Any, T], *, name: str | None = None 302 ) -> None: 303 """Create a fully managed async task. 304 305 This will automatically retain and release a reference to the task 306 and log any exceptions that occur in it. If you need to await a task 307 or otherwise need more control, schedule a task directly using 308 App.asyncio_loop. 309 """ 310 assert _babase.in_logic_thread() 311 312 # We hold a strong reference to the task until it is done. 313 # Otherwise it is possible for it to be garbage collected and 314 # disappear midway if the caller does not hold on to the 315 # returned task, which seems like a great way to introduce 316 # hard-to-track bugs. 317 task = self.asyncio_loop.create_task(coro, name=name) 318 self._asyncio_tasks.add(task) 319 task.add_done_callback(self._on_task_done) 320 321 def _on_task_done(self, task: asyncio.Task) -> None: 322 # Report any errors that occurred. 323 try: 324 exc = task.exception() 325 if exc is not None: 326 logging.error( 327 "Error in async task '%s'.", task.get_name(), exc_info=exc 328 ) 329 except Exception: 330 logging.exception('Error reporting async task error.') 331 332 self._asyncio_tasks.remove(task) 333 334 @property 335 def config(self) -> babase.AppConfig: 336 """The babase.AppConfig instance representing the app's config state.""" 337 assert self._config is not None 338 return self._config 339 340 @property 341 def mode_selector(self) -> babase.AppModeSelector: 342 """Controls which app-modes are used for handling given intents. 343 344 Plugins can override this to change high level app behavior and 345 spinoff projects can change the default implementation for the 346 same effect. 347 """ 348 if self._mode_selector is None: 349 raise RuntimeError( 350 'mode_selector cannot be used until the app reaches' 351 ' the running state.' 352 ) 353 return self._mode_selector 354 355 @mode_selector.setter 356 def mode_selector(self, selector: babase.AppModeSelector) -> None: 357 self._mode_selector = selector 358 359 def _get_subsystem_property( 360 self, ssname: str, create_call: Callable[[], AppSubsystem | None] 361 ) -> AppSubsystem | None: 362 363 # Quick-out: if a subsystem is present, just return it; no 364 # locking necessary. 365 val = self._subsystem_property_data.get(ssname) 366 if val is not None: 367 if val is False: 368 # False means subsystem is confirmed as unavailable. 369 return None 370 if val is not True: 371 # A subsystem has been set. Return it. 372 return val 373 374 # Anything else (no val present or val True) requires locking. 375 with self._subsystem_property_lock: 376 val = self._subsystem_property_data.get(ssname) 377 if val is not None: 378 if val is False: 379 # False means confirmed as not present. 380 return None 381 if val is True: 382 # True means this property is already being loaded, 383 # and the fact that we're holding the lock means 384 # we're doing the loading, so this is a dependency 385 # loop. Not good. 386 raise RuntimeError( 387 f'Subsystem dependency loop detected for {ssname}' 388 ) 389 # Must be an instantiated subsystem. Noice. 390 return val 391 392 # Ok, there's nothing here for it. Instantiate and set it 393 # while we hold the lock. Set a placeholder value of True 394 # while we load so we can error if something we're loading 395 # tries to recursively load us. 396 self._subsystem_property_data[ssname] = True 397 398 # Do our one attempt to create the singleton. 399 val = create_call() 400 self._subsystem_property_data[ssname] = ( 401 False if val is None else val 402 ) 403 404 return val 405 406 # __FEATURESET_APP_SUBSYSTEM_PROPERTIES_BEGIN__ 407 # This section generated by batools.appmodule; do not edit. 408 409 @property 410 def classic(self) -> ClassicAppSubsystem | None: 411 """Our classic subsystem (if available).""" 412 return self._get_subsystem_property( 413 'classic', self._create_classic_subsystem 414 ) # type: ignore 415 416 @staticmethod 417 def _create_classic_subsystem() -> ClassicAppSubsystem | None: 418 # pylint: disable=cyclic-import 419 try: 420 from baclassic import ClassicAppSubsystem 421 422 return ClassicAppSubsystem() 423 except ImportError: 424 return None 425 except Exception: 426 logging.exception('Error importing baclassic.') 427 return None 428 429 @property 430 def plus(self) -> PlusAppSubsystem | None: 431 """Our plus subsystem (if available).""" 432 return self._get_subsystem_property( 433 'plus', self._create_plus_subsystem 434 ) # type: ignore 435 436 @staticmethod 437 def _create_plus_subsystem() -> PlusAppSubsystem | None: 438 # pylint: disable=cyclic-import 439 try: 440 from baplus import PlusAppSubsystem 441 442 return PlusAppSubsystem() 443 except ImportError: 444 return None 445 except Exception: 446 logging.exception('Error importing baplus.') 447 return None 448 449 @property 450 def ui_v1(self) -> UIV1AppSubsystem: 451 """Our ui_v1 subsystem (always available).""" 452 return self._get_subsystem_property( 453 'ui_v1', self._create_ui_v1_subsystem 454 ) # type: ignore 455 456 @staticmethod 457 def _create_ui_v1_subsystem() -> UIV1AppSubsystem: 458 # pylint: disable=cyclic-import 459 460 from bauiv1 import UIV1AppSubsystem 461 462 return UIV1AppSubsystem() 463 464 # __FEATURESET_APP_SUBSYSTEM_PROPERTIES_END__ 465 466 def register_subsystem(self, subsystem: AppSubsystem) -> None: 467 """Called by the AppSubsystem class. Do not use directly.""" 468 469 # We only allow registering new subsystems if we've not yet 470 # reached the 'running' state. This ensures that all subsystems 471 # receive a consistent set of callbacks starting with 472 # on_app_running(). 473 474 if self._subsystem_registration_ended: 475 raise RuntimeError( 476 'Subsystems can no longer be registered at this point.' 477 ) 478 self._subsystems.append(subsystem) 479 480 def add_shutdown_task(self, coro: Coroutine[None, None, None]) -> None: 481 """Add a task to be run on app shutdown. 482 483 Note that shutdown tasks will be canceled after 484 App.SHUTDOWN_TASK_TIMEOUT_SECONDS if they are still running. 485 """ 486 if ( 487 self.state is self.State.SHUTTING_DOWN 488 or self.state is self.State.SHUTDOWN_COMPLETE 489 ): 490 stname = self.state.name 491 raise RuntimeError( 492 f'Cannot add shutdown tasks with current state {stname}.' 493 ) 494 self._shutdown_tasks.append(coro) 495 496 def run(self) -> None: 497 """Run the app to completion. 498 499 Note that this only works on builds where Ballistica manages 500 its own event loop. 501 """ 502 _babase.run_app() 503 504 def threadpool_submit_no_wait(self, call: Callable[[], Any]) -> None: 505 """Submit a call to the app threadpool where result is not needed. 506 507 Normally, doing work in a thread-pool involves creating a future 508 and waiting for its result, which is an important step because it 509 propagates any Exceptions raised by the submitted work. When the 510 result in not important, however, this call can be used. The app 511 will log any exceptions that occur. 512 """ 513 fut = self.threadpool.submit(call) 514 fut.add_done_callback(self._threadpool_no_wait_done) 515 516 def set_intent(self, intent: AppIntent) -> None: 517 """Set the intent for the app. 518 519 Intent defines what the app is trying to do at a given time. 520 This call is asynchronous; the intent switch will happen in the 521 logic thread in the near future. If set_intent is called 522 repeatedly before the change takes place, the final intent to be 523 set will be used. 524 """ 525 526 # Mark this one as pending. We do this synchronously so that the 527 # last one marked actually takes effect if there is overlap 528 # (doing this in the bg thread could result in race conditions). 529 self._pending_intent = intent 530 531 # Do the actual work of calcing our app-mode/etc. in a bg thread 532 # since it may block for a moment to load modules/etc. 533 self.threadpool_submit_no_wait(partial(self._set_intent, intent)) 534 535 def push_apply_app_config(self) -> None: 536 """Internal. Use app.config.apply() to apply app config changes.""" 537 # To be safe, let's run this by itself in the event loop. 538 # This avoids potential trouble if this gets called mid-draw or 539 # something like that. 540 self._pending_apply_app_config = True 541 _babase.pushcall(self._apply_app_config, raw=True) 542 543 def on_native_start(self) -> None: 544 """Called by the native layer when the app is being started.""" 545 assert _babase.in_logic_thread() 546 assert not self._native_start_called 547 self._native_start_called = True 548 self._update_state() 549 550 def on_native_bootstrapping_complete(self) -> None: 551 """Called by the native layer once its ready to rock.""" 552 assert _babase.in_logic_thread() 553 assert not self._native_bootstrapping_completed 554 self._native_bootstrapping_completed = True 555 self._update_state() 556 557 def on_native_suspend(self) -> None: 558 """Called by the native layer when the app is suspended.""" 559 assert _babase.in_logic_thread() 560 assert not self._native_suspended # Should avoid redundant calls. 561 self._native_suspended = True 562 self._update_state() 563 564 def on_native_unsuspend(self) -> None: 565 """Called by the native layer when the app suspension ends.""" 566 assert _babase.in_logic_thread() 567 assert self._native_suspended # Should avoid redundant calls. 568 self._native_suspended = False 569 self._update_state() 570 571 def on_native_shutdown(self) -> None: 572 """Called by the native layer when the app starts shutting down.""" 573 assert _babase.in_logic_thread() 574 self._native_shutdown_called = True 575 self._update_state() 576 577 def on_native_shutdown_complete(self) -> None: 578 """Called by the native layer when the app is done shutting down.""" 579 assert _babase.in_logic_thread() 580 self._native_shutdown_complete_called = True 581 self._update_state() 582 583 def on_native_active_changed(self) -> None: 584 """Called by the native layer when the app active state changes.""" 585 assert _babase.in_logic_thread() 586 if self._mode is not None: 587 self._mode.on_app_active_changed() 588 589 def read_config(self) -> None: 590 """(internal)""" 591 from babase._appconfig import read_app_config 592 593 self._config = read_app_config() 594 595 def handle_deep_link(self, url: str) -> None: 596 """Handle a deep link URL.""" 597 from babase._language import Lstr 598 599 assert _babase.in_logic_thread() 600 601 appname = _babase.appname() 602 if url.startswith(f'{appname}://code/'): 603 code = url.replace(f'{appname}://code/', '') 604 if self.classic is not None: 605 self.classic.accounts.add_pending_promo_code(code) 606 else: 607 try: 608 _babase.screenmessage( 609 Lstr(resource='errorText'), color=(1, 0, 0) 610 ) 611 _babase.getsimplesound('error').play() 612 except ImportError: 613 pass 614 615 def on_initial_sign_in_complete(self) -> None: 616 """Called when initial sign-in (or lack thereof) completes. 617 618 This normally gets called by the plus subsystem. The 619 initial-sign-in process may include tasks such as syncing 620 account workspaces or other data so it may take a substantial 621 amount of time. 622 """ 623 assert _babase.in_logic_thread() 624 assert not self._initial_sign_in_completed 625 626 # Tell meta it can start scanning extra stuff that just showed 627 # up (namely account workspaces). 628 self.meta.start_extra_scan() 629 630 self._initial_sign_in_completed = True 631 self._update_state() 632 633 def _set_intent(self, intent: AppIntent) -> None: 634 from babase._appmode import AppMode 635 636 # This should be happening in a bg thread. 637 assert not _babase.in_logic_thread() 638 try: 639 # Ask the selector what app-mode to use for this intent. 640 if self.mode_selector is None: 641 raise RuntimeError('No AppModeSelector set.') 642 643 modetype: type[AppMode] | None 644 645 # Special case - for testing we may force a specific 646 # app-mode to handle this intent instead of going through our 647 # usual selector. 648 forced_mode_type = getattr(intent, '_force_app_mode_handler', None) 649 if isinstance(forced_mode_type, type) and issubclass( 650 forced_mode_type, AppMode 651 ): 652 modetype = forced_mode_type 653 else: 654 modetype = self.mode_selector.app_mode_for_intent(intent) 655 656 # NOTE: Since intents are somewhat high level things, 657 # perhaps we should do some universal thing like a 658 # screenmessage saying 'The app cannot handle the request' 659 # on failure. 660 661 if modetype is None: 662 raise RuntimeError( 663 f'No app-mode found to handle app-intent' 664 f' type {type(intent)}.' 665 ) 666 667 # Make sure the app-mode the selector gave us *actually* 668 # supports the intent. 669 if not modetype.can_handle_intent(intent): 670 raise RuntimeError( 671 f'Intent {intent} cannot be handled by AppMode type' 672 f' {modetype} (selector {self.mode_selector}' 673 f' incorrectly thinks that it can be).' 674 ) 675 676 # Ok; seems legit. Now instantiate the mode if necessary and 677 # kick back to the logic thread to apply. 678 mode = self._mode_instances.get(modetype) 679 if mode is None: 680 self._mode_instances[modetype] = mode = modetype() 681 _babase.pushcall( 682 partial(self._apply_intent, intent, mode), 683 from_other_thread=True, 684 ) 685 except Exception: 686 logging.exception('Error setting app intent to %s.', intent) 687 _babase.pushcall( 688 partial(self._display_set_intent_error, intent), 689 from_other_thread=True, 690 ) 691 692 def _apply_intent(self, intent: AppIntent, mode: AppMode) -> None: 693 assert _babase.in_logic_thread() 694 695 # ONLY apply this intent if it is still the most recent one 696 # submitted. 697 if intent is not self._pending_intent: 698 return 699 700 # If the app-mode for this intent is different than the active 701 # one, switch modes. 702 if type(mode) is not type(self._mode): 703 if self._mode is None: 704 is_initial_mode = True 705 else: 706 is_initial_mode = False 707 try: 708 self._mode.on_deactivate() 709 except Exception: 710 logging.exception( 711 'Error deactivating app-mode %s.', self._mode 712 ) 713 714 # Reset all subsystems. We assume subsystems won't be added 715 # at this point so we can use the list directly. 716 assert self._subsystem_registration_ended 717 for subsystem in self._subsystems: 718 try: 719 subsystem.reset() 720 except Exception: 721 logging.exception( 722 'Error in reset for subsystem %s.', subsystem 723 ) 724 725 self._mode = mode 726 try: 727 mode.on_activate() 728 except Exception: 729 # Hmm; what should we do in this case?... 730 logging.exception('Error activating app-mode %s.', mode) 731 732 # Let the world know when we first have an app-mode; certain 733 # app stuff such as input processing can proceed at that 734 # point. 735 if is_initial_mode: 736 _babase.on_initial_app_mode_set() 737 738 try: 739 mode.handle_intent(intent) 740 except Exception: 741 logging.exception( 742 'Error handling intent %s in app-mode %s.', intent, mode 743 ) 744 745 def _display_set_intent_error(self, intent: AppIntent) -> None: 746 """Show the *user* something went wrong setting an intent.""" 747 from babase._language import Lstr 748 749 del intent 750 _babase.screenmessage(Lstr(resource='errorText'), color=(1, 0, 0)) 751 _babase.getsimplesound('error').play() 752 753 def _on_initing(self) -> None: 754 """Called when the app enters the initing state. 755 756 Here we can put together subsystems and other pieces for the 757 app, but most things should not be doing any work yet. 758 """ 759 # pylint: disable=cyclic-import 760 from babase import _asyncio 761 from babase import _appconfig 762 from babase._apputils import AppHealthMonitor 763 from babase import _env 764 765 assert _babase.in_logic_thread() 766 767 _env.on_app_state_initing() 768 769 self._asyncio_loop = _asyncio.setup_asyncio() 770 self.health_monitor = AppHealthMonitor() 771 772 # __FEATURESET_APP_SUBSYSTEM_CREATE_BEGIN__ 773 # This section generated by batools.appmodule; do not edit. 774 775 # Poke these attrs to create all our subsystems. 776 _ = self.plus 777 _ = self.classic 778 _ = self.ui_v1 779 780 # __FEATURESET_APP_SUBSYSTEM_CREATE_END__ 781 782 # We're a pretty short-lived state. This should flip us to 783 # 'loading'. 784 self._init_completed = True 785 self._update_state() 786 787 def _on_loading(self) -> None: 788 """Called when we enter the loading state. 789 790 At this point, all built-in pieces of the app should be in place 791 and can start talking to each other and doing work. Though at a 792 high level, the goal of the app at this point is only to sign in 793 to initial accounts, download workspaces, and otherwise prepare 794 itself to really 'run'. 795 """ 796 assert _babase.in_logic_thread() 797 798 # Get meta-system scanning built-in stuff in the bg. 799 self.meta.start_scan(scan_complete_cb=self._on_meta_scan_complete) 800 801 # Inform all app subsystems in the same order they were inited. 802 # Operate on a copy of the list here because subsystems can 803 # still be added at this point. 804 for subsystem in self._subsystems.copy(): 805 try: 806 subsystem.on_app_loading() 807 except Exception: 808 logging.exception( 809 'Error in on_app_loading for subsystem %s.', subsystem 810 ) 811 812 # Normally plus tells us when initial sign-in is done. If plus 813 # is not present, however, we just do it ourself so we can 814 # proceed on to the running state. 815 if self.plus is None: 816 _babase.pushcall(self.on_initial_sign_in_complete) 817 818 def _on_meta_scan_complete(self) -> None: 819 """Called when meta-scan is done doing its thing.""" 820 assert _babase.in_logic_thread() 821 822 # Now that we know what's out there, build our final plugin set. 823 self.plugins.on_meta_scan_complete() 824 825 assert not self._meta_scan_completed 826 self._meta_scan_completed = True 827 self._update_state() 828 829 def _on_running(self) -> None: 830 """Called when we enter the running state. 831 832 At this point, all workspaces, initial accounts, etc. are in place 833 and we can actually get started doing whatever we're gonna do. 834 """ 835 assert _babase.in_logic_thread() 836 837 # Let our native layer know. 838 _babase.on_app_running() 839 840 # Set a default app-mode-selector if none has been set yet 841 # by a plugin or whatnot. 842 if self._mode_selector is None: 843 self._mode_selector = self.DefaultAppModeSelector() 844 845 # Inform all app subsystems in the same order they were 846 # registered. Operate on a copy here because subsystems can 847 # still be added at this point. 848 # 849 # NOTE: Do we need to allow registering still at this point? If 850 # something gets registered here, it won't have its 851 # on_app_running callback called. Hmm; I suppose that's the only 852 # way that plugins can register subsystems though. 853 for subsystem in self._subsystems.copy(): 854 try: 855 subsystem.on_app_running() 856 except Exception: 857 logging.exception( 858 'Error in on_app_running for subsystem %s.', subsystem 859 ) 860 861 # Cut off new subsystem additions at this point. 862 self._subsystem_registration_ended = True 863 864 # If 'exec' code was provided to the app, always kick that off 865 # here as an intent. 866 exec_cmd = _babase.exec_arg() 867 if exec_cmd is not None: 868 self.set_intent(AppIntentExec(exec_cmd)) 869 elif self._pending_intent is None: 870 # Otherwise tell the app to do its default thing *only* if a 871 # plugin hasn't already told it to do something. 872 self.set_intent(AppIntentDefault()) 873 874 def _apply_app_config(self) -> None: 875 assert _babase.in_logic_thread() 876 877 _babase.lifecyclelog('apply-app-config') 878 879 # If multiple apply calls have been made, only actually apply 880 # once. 881 if not self._pending_apply_app_config: 882 return 883 884 _pending_apply_app_config = False 885 886 # Inform all app subsystems in the same order they were inited. 887 # Operate on a copy here because subsystems may still be able to 888 # be added at this point. 889 for subsystem in self._subsystems.copy(): 890 try: 891 subsystem.do_apply_app_config() 892 except Exception: 893 logging.exception( 894 'Error in do_apply_app_config for subsystem %s.', subsystem 895 ) 896 897 # Let the native layer do its thing. 898 _babase.do_apply_app_config() 899 900 def _update_state(self) -> None: 901 # pylint: disable=too-many-branches 902 assert _babase.in_logic_thread() 903 904 # Shutdown-complete trumps absolutely all. 905 if self._native_shutdown_complete_called: 906 if self.state is not self.State.SHUTDOWN_COMPLETE: 907 self.state = self.State.SHUTDOWN_COMPLETE 908 _babase.lifecyclelog('app state shutdown complete') 909 self._on_shutdown_complete() 910 911 # Shutdown trumps all. Though we can't start shutting down until 912 # init is completed since we need our asyncio stuff to exist for 913 # the shutdown process. 914 elif self._native_shutdown_called and self._init_completed: 915 # Entering shutdown state: 916 if self.state is not self.State.SHUTTING_DOWN: 917 self.state = self.State.SHUTTING_DOWN 918 _babase.lifecyclelog('app state shutting down') 919 self._on_shutting_down() 920 921 elif self._native_suspended: 922 # Entering suspended state: 923 if self.state is not self.State.SUSPENDED: 924 self.state = self.State.SUSPENDED 925 self._on_suspend() 926 else: 927 # Leaving suspended state: 928 if self.state is self.State.SUSPENDED: 929 self._on_unsuspend() 930 931 # Entering or returning to running state 932 if self._initial_sign_in_completed and self._meta_scan_completed: 933 if self.state != self.State.RUNNING: 934 self.state = self.State.RUNNING 935 _babase.lifecyclelog('app state running') 936 if not self._called_on_running: 937 self._called_on_running = True 938 self._on_running() 939 # Entering or returning to loading state: 940 elif self._init_completed: 941 if self.state is not self.State.LOADING: 942 self.state = self.State.LOADING 943 _babase.lifecyclelog('app state loading') 944 if not self._called_on_loading: 945 self._called_on_loading = True 946 self._on_loading() 947 948 # Entering or returning to initing state: 949 elif self._native_bootstrapping_completed: 950 if self.state is not self.State.INITING: 951 self.state = self.State.INITING 952 _babase.lifecyclelog('app state initing') 953 if not self._called_on_initing: 954 self._called_on_initing = True 955 self._on_initing() 956 957 # Entering or returning to native bootstrapping: 958 elif self._native_start_called: 959 if self.state is not self.State.NATIVE_BOOTSTRAPPING: 960 self.state = self.State.NATIVE_BOOTSTRAPPING 961 _babase.lifecyclelog('app state native bootstrapping') 962 else: 963 # Only logical possibility left is NOT_STARTED, in which 964 # case we should not be getting called. 965 logging.warning( 966 'App._update_state called while in %s state;' 967 ' should not happen.', 968 self.state.value, 969 stack_info=True, 970 ) 971 972 async def _shutdown(self) -> None: 973 import asyncio 974 975 _babase.lock_all_input() 976 try: 977 async with asyncio.TaskGroup() as task_group: 978 for task_coro in self._shutdown_tasks: 979 # Note: Mypy currently complains if we don't take 980 # this return value, but we don't actually need to. 981 # https://github.com/python/mypy/issues/15036 982 _ = task_group.create_task( 983 self._run_shutdown_task(task_coro) 984 ) 985 except* Exception: 986 logging.exception('Unexpected error(s) in shutdown.') 987 988 # Note: ideally we should run this directly here, but currently 989 # it does some legacy stuff which blocks, so running it here 990 # gives us asyncio task-took-too-long warnings. If we can 991 # convert those to nice graceful async tasks we should revert 992 # this to a direct call. 993 _babase.pushcall(_babase.complete_shutdown) 994 995 async def _run_shutdown_task( 996 self, coro: Coroutine[None, None, None] 997 ) -> None: 998 """Run a shutdown task; report errors and abort if taking too long.""" 999 import asyncio 1000 1001 task = asyncio.create_task(coro) 1002 try: 1003 await asyncio.wait_for(task, self.SHUTDOWN_TASK_TIMEOUT_SECONDS) 1004 except Exception: 1005 logging.exception('Error in shutdown task (%s).', coro) 1006 1007 def _on_suspend(self) -> None: 1008 """Called when the app goes to a suspended state.""" 1009 assert _babase.in_logic_thread() 1010 1011 # Suspend all app subsystems in the opposite order they were inited. 1012 for subsystem in reversed(self._subsystems): 1013 try: 1014 subsystem.on_app_suspend() 1015 except Exception: 1016 logging.exception( 1017 'Error in on_app_suspend for subsystem %s.', subsystem 1018 ) 1019 1020 def _on_unsuspend(self) -> None: 1021 """Called when unsuspending.""" 1022 assert _babase.in_logic_thread() 1023 self.fg_state += 1 1024 1025 # Unsuspend all app subsystems in the same order they were inited. 1026 for subsystem in self._subsystems: 1027 try: 1028 subsystem.on_app_unsuspend() 1029 except Exception: 1030 logging.exception( 1031 'Error in on_app_unsuspend for subsystem %s.', subsystem 1032 ) 1033 1034 def _on_shutting_down(self) -> None: 1035 """(internal)""" 1036 assert _babase.in_logic_thread() 1037 1038 # Inform app subsystems that we're shutting down in the opposite 1039 # order they were inited. 1040 for subsystem in reversed(self._subsystems): 1041 try: 1042 subsystem.on_app_shutdown() 1043 except Exception: 1044 logging.exception( 1045 'Error in on_app_shutdown for subsystem %s.', subsystem 1046 ) 1047 1048 # Now kick off any async shutdown task(s). 1049 assert self._asyncio_loop is not None 1050 self._shutdown_task = self._asyncio_loop.create_task(self._shutdown()) 1051 1052 def _on_shutdown_complete(self) -> None: 1053 """(internal)""" 1054 assert _babase.in_logic_thread() 1055 1056 # Inform app subsystems that we're done shutting down in the opposite 1057 # order they were inited. 1058 for subsystem in reversed(self._subsystems): 1059 try: 1060 subsystem.on_app_shutdown_complete() 1061 except Exception: 1062 logging.exception( 1063 'Error in on_app_shutdown_complete for subsystem %s.', 1064 subsystem, 1065 ) 1066 1067 async def _wait_for_shutdown_suppressions(self) -> None: 1068 import asyncio 1069 1070 # Spin and wait for anything blocking shutdown to complete. 1071 starttime = _babase.apptime() 1072 _babase.lifecyclelog('shutdown-suppress wait begin') 1073 while _babase.shutdown_suppress_count() > 0: 1074 await asyncio.sleep(0.001) 1075 _babase.lifecyclelog('shutdown-suppress wait end') 1076 duration = _babase.apptime() - starttime 1077 if duration > 1.0: 1078 logging.warning( 1079 'Shutdown-suppressions lasted longer than ideal ' 1080 '(%.2f seconds).', 1081 duration, 1082 ) 1083 1084 async def _fade_and_shutdown_graphics(self) -> None: 1085 import asyncio 1086 1087 # Kick off a short fade and give it time to complete. 1088 _babase.lifecyclelog('fade-and-shutdown-graphics begin') 1089 _babase.fade_screen(False, time=0.15) 1090 await asyncio.sleep(0.15) 1091 1092 # Now tell the graphics system to go down and wait until 1093 # it has done so. 1094 _babase.graphics_shutdown_begin() 1095 while not _babase.graphics_shutdown_is_complete(): 1096 await asyncio.sleep(0.01) 1097 _babase.lifecyclelog('fade-and-shutdown-graphics end') 1098 1099 async def _fade_and_shutdown_audio(self) -> None: 1100 import asyncio 1101 1102 # Tell the audio system to go down and give it a bit of 1103 # time to do so gracefully. 1104 _babase.lifecyclelog('fade-and-shutdown-audio begin') 1105 _babase.audio_shutdown_begin() 1106 await asyncio.sleep(0.15) 1107 while not _babase.audio_shutdown_is_complete(): 1108 await asyncio.sleep(0.01) 1109 _babase.lifecyclelog('fade-and-shutdown-audio end') 1110 1111 def _threadpool_no_wait_done(self, fut: Future) -> None: 1112 try: 1113 fut.result() 1114 except Exception: 1115 logging.exception( 1116 'Error in work submitted via threadpool_submit_no_wait()' 1117 ) 1118 1119 def _thread_pool_thread_init(self) -> None: 1120 # Help keep things clear in profiling tools/etc. 1121 self._pool_thread_count += 1 1122 _babase.set_thread_name(f'ballistica worker-{self._pool_thread_count}')
A class for high level app functionality and state.
Category: App Classes
Use app to access the single shared instance of this class.
Note that properties not documented here should be considered internal and subject to change without warning.
248 def postinit(self) -> None: 249 """Called after we've been inited and assigned to babase.app. 250 251 Anything that accesses babase.app as part of its init process 252 must go here instead of __init__. 253 """ 254 255 # Hack for docs-generation: We can be imported with dummy 256 # modules instead of our actual binary ones, but we don't 257 # function. 258 if os.environ.get('BA_RUNNING_WITH_DUMMY_MODULES') == '1': 259 return 260 261 self.lang = LanguageSubsystem() 262 self.plugins = PluginSubsystem()
264 @property 265 def active(self) -> bool: 266 """Whether the app is currently front and center. 267 268 This will be False when the app is hidden, other activities 269 are covering it, etc. (depending on the platform). 270 """ 271 return _babase.app_is_active()
Whether the app is currently front and center.
This will be False when the app is hidden, other activities are covering it, etc. (depending on the platform).
273 @property 274 def asyncio_loop(self) -> asyncio.AbstractEventLoop: 275 """The logic thread's asyncio event loop. 276 277 This allow async tasks to be run in the logic thread. 278 279 Generally you should call App.create_async_task() to schedule 280 async code to run instead of using this directly. That will 281 handle retaining the task and logging errors automatically. 282 Only schedule tasks onto asyncio_loop yourself when you intend 283 to hold on to the returned task and await its results. Releasing 284 the task reference can lead to subtle bugs such as unreported 285 errors and garbage-collected tasks disappearing before their 286 work is done. 287 288 Note that, at this time, the asyncio loop is encapsulated 289 and explicitly stepped by the engine's logic thread loop and 290 thus things like asyncio.get_running_loop() will unintuitively 291 *not* return this loop from most places in the logic thread; 292 only from within a task explicitly created in this loop. 293 Hopefully this situation will be improved in the future with a 294 unified event loop. 295 """ 296 assert _babase.in_logic_thread() 297 assert self._asyncio_loop is not None 298 return self._asyncio_loop
The logic thread's asyncio event loop.
This allow async tasks to be run in the logic thread.
Generally you should call App.create_async_task() to schedule async code to run instead of using this directly. That will handle retaining the task and logging errors automatically. Only schedule tasks onto asyncio_loop yourself when you intend to hold on to the returned task and await its results. Releasing the task reference can lead to subtle bugs such as unreported errors and garbage-collected tasks disappearing before their work is done.
Note that, at this time, the asyncio loop is encapsulated and explicitly stepped by the engine's logic thread loop and thus things like asyncio.get_running_loop() will unintuitively not return this loop from most places in the logic thread; only from within a task explicitly created in this loop. Hopefully this situation will be improved in the future with a unified event loop.
300 def create_async_task( 301 self, coro: Coroutine[Any, Any, T], *, name: str | None = None 302 ) -> None: 303 """Create a fully managed async task. 304 305 This will automatically retain and release a reference to the task 306 and log any exceptions that occur in it. If you need to await a task 307 or otherwise need more control, schedule a task directly using 308 App.asyncio_loop. 309 """ 310 assert _babase.in_logic_thread() 311 312 # We hold a strong reference to the task until it is done. 313 # Otherwise it is possible for it to be garbage collected and 314 # disappear midway if the caller does not hold on to the 315 # returned task, which seems like a great way to introduce 316 # hard-to-track bugs. 317 task = self.asyncio_loop.create_task(coro, name=name) 318 self._asyncio_tasks.add(task) 319 task.add_done_callback(self._on_task_done)
Create a fully managed async task.
This will automatically retain and release a reference to the task and log any exceptions that occur in it. If you need to await a task or otherwise need more control, schedule a task directly using App.asyncio_loop.
334 @property 335 def config(self) -> babase.AppConfig: 336 """The babase.AppConfig instance representing the app's config state.""" 337 assert self._config is not None 338 return self._config
The AppConfig instance representing the app's config state.
340 @property 341 def mode_selector(self) -> babase.AppModeSelector: 342 """Controls which app-modes are used for handling given intents. 343 344 Plugins can override this to change high level app behavior and 345 spinoff projects can change the default implementation for the 346 same effect. 347 """ 348 if self._mode_selector is None: 349 raise RuntimeError( 350 'mode_selector cannot be used until the app reaches' 351 ' the running state.' 352 ) 353 return self._mode_selector
Controls which app-modes are used for handling given intents.
Plugins can override this to change high level app behavior and spinoff projects can change the default implementation for the same effect.
409 @property 410 def classic(self) -> ClassicAppSubsystem | None: 411 """Our classic subsystem (if available).""" 412 return self._get_subsystem_property( 413 'classic', self._create_classic_subsystem 414 ) # type: ignore
Our classic subsystem (if available).
429 @property 430 def plus(self) -> PlusAppSubsystem | None: 431 """Our plus subsystem (if available).""" 432 return self._get_subsystem_property( 433 'plus', self._create_plus_subsystem 434 ) # type: ignore
Our plus subsystem (if available).
449 @property 450 def ui_v1(self) -> UIV1AppSubsystem: 451 """Our ui_v1 subsystem (always available).""" 452 return self._get_subsystem_property( 453 'ui_v1', self._create_ui_v1_subsystem 454 ) # type: ignore
Our ui_v1 subsystem (always available).
466 def register_subsystem(self, subsystem: AppSubsystem) -> None: 467 """Called by the AppSubsystem class. Do not use directly.""" 468 469 # We only allow registering new subsystems if we've not yet 470 # reached the 'running' state. This ensures that all subsystems 471 # receive a consistent set of callbacks starting with 472 # on_app_running(). 473 474 if self._subsystem_registration_ended: 475 raise RuntimeError( 476 'Subsystems can no longer be registered at this point.' 477 ) 478 self._subsystems.append(subsystem)
Called by the AppSubsystem class. Do not use directly.
480 def add_shutdown_task(self, coro: Coroutine[None, None, None]) -> None: 481 """Add a task to be run on app shutdown. 482 483 Note that shutdown tasks will be canceled after 484 App.SHUTDOWN_TASK_TIMEOUT_SECONDS if they are still running. 485 """ 486 if ( 487 self.state is self.State.SHUTTING_DOWN 488 or self.state is self.State.SHUTDOWN_COMPLETE 489 ): 490 stname = self.state.name 491 raise RuntimeError( 492 f'Cannot add shutdown tasks with current state {stname}.' 493 ) 494 self._shutdown_tasks.append(coro)
Add a task to be run on app shutdown.
Note that shutdown tasks will be canceled after App.SHUTDOWN_TASK_TIMEOUT_SECONDS if they are still running.
496 def run(self) -> None: 497 """Run the app to completion. 498 499 Note that this only works on builds where Ballistica manages 500 its own event loop. 501 """ 502 _babase.run_app()
Run the app to completion.
Note that this only works on builds where Ballistica manages its own event loop.
504 def threadpool_submit_no_wait(self, call: Callable[[], Any]) -> None: 505 """Submit a call to the app threadpool where result is not needed. 506 507 Normally, doing work in a thread-pool involves creating a future 508 and waiting for its result, which is an important step because it 509 propagates any Exceptions raised by the submitted work. When the 510 result in not important, however, this call can be used. The app 511 will log any exceptions that occur. 512 """ 513 fut = self.threadpool.submit(call) 514 fut.add_done_callback(self._threadpool_no_wait_done)
Submit a call to the app threadpool where result is not needed.
Normally, doing work in a thread-pool involves creating a future and waiting for its result, which is an important step because it propagates any Exceptions raised by the submitted work. When the result in not important, however, this call can be used. The app will log any exceptions that occur.
516 def set_intent(self, intent: AppIntent) -> None: 517 """Set the intent for the app. 518 519 Intent defines what the app is trying to do at a given time. 520 This call is asynchronous; the intent switch will happen in the 521 logic thread in the near future. If set_intent is called 522 repeatedly before the change takes place, the final intent to be 523 set will be used. 524 """ 525 526 # Mark this one as pending. We do this synchronously so that the 527 # last one marked actually takes effect if there is overlap 528 # (doing this in the bg thread could result in race conditions). 529 self._pending_intent = intent 530 531 # Do the actual work of calcing our app-mode/etc. in a bg thread 532 # since it may block for a moment to load modules/etc. 533 self.threadpool_submit_no_wait(partial(self._set_intent, intent))
Set the intent for the app.
Intent defines what the app is trying to do at a given time. This call is asynchronous; the intent switch will happen in the logic thread in the near future. If set_intent is called repeatedly before the change takes place, the final intent to be set will be used.
535 def push_apply_app_config(self) -> None: 536 """Internal. Use app.config.apply() to apply app config changes.""" 537 # To be safe, let's run this by itself in the event loop. 538 # This avoids potential trouble if this gets called mid-draw or 539 # something like that. 540 self._pending_apply_app_config = True 541 _babase.pushcall(self._apply_app_config, raw=True)
Internal. Use app.config.apply() to apply app config changes.
543 def on_native_start(self) -> None: 544 """Called by the native layer when the app is being started.""" 545 assert _babase.in_logic_thread() 546 assert not self._native_start_called 547 self._native_start_called = True 548 self._update_state()
Called by the native layer when the app is being started.
550 def on_native_bootstrapping_complete(self) -> None: 551 """Called by the native layer once its ready to rock.""" 552 assert _babase.in_logic_thread() 553 assert not self._native_bootstrapping_completed 554 self._native_bootstrapping_completed = True 555 self._update_state()
Called by the native layer once its ready to rock.
557 def on_native_suspend(self) -> None: 558 """Called by the native layer when the app is suspended.""" 559 assert _babase.in_logic_thread() 560 assert not self._native_suspended # Should avoid redundant calls. 561 self._native_suspended = True 562 self._update_state()
Called by the native layer when the app is suspended.
564 def on_native_unsuspend(self) -> None: 565 """Called by the native layer when the app suspension ends.""" 566 assert _babase.in_logic_thread() 567 assert self._native_suspended # Should avoid redundant calls. 568 self._native_suspended = False 569 self._update_state()
Called by the native layer when the app suspension ends.
571 def on_native_shutdown(self) -> None: 572 """Called by the native layer when the app starts shutting down.""" 573 assert _babase.in_logic_thread() 574 self._native_shutdown_called = True 575 self._update_state()
Called by the native layer when the app starts shutting down.
577 def on_native_shutdown_complete(self) -> None: 578 """Called by the native layer when the app is done shutting down.""" 579 assert _babase.in_logic_thread() 580 self._native_shutdown_complete_called = True 581 self._update_state()
Called by the native layer when the app is done shutting down.
583 def on_native_active_changed(self) -> None: 584 """Called by the native layer when the app active state changes.""" 585 assert _babase.in_logic_thread() 586 if self._mode is not None: 587 self._mode.on_app_active_changed()
Called by the native layer when the app active state changes.
595 def handle_deep_link(self, url: str) -> None: 596 """Handle a deep link URL.""" 597 from babase._language import Lstr 598 599 assert _babase.in_logic_thread() 600 601 appname = _babase.appname() 602 if url.startswith(f'{appname}://code/'): 603 code = url.replace(f'{appname}://code/', '') 604 if self.classic is not None: 605 self.classic.accounts.add_pending_promo_code(code) 606 else: 607 try: 608 _babase.screenmessage( 609 Lstr(resource='errorText'), color=(1, 0, 0) 610 ) 611 _babase.getsimplesound('error').play() 612 except ImportError: 613 pass
Handle a deep link URL.
615 def on_initial_sign_in_complete(self) -> None: 616 """Called when initial sign-in (or lack thereof) completes. 617 618 This normally gets called by the plus subsystem. The 619 initial-sign-in process may include tasks such as syncing 620 account workspaces or other data so it may take a substantial 621 amount of time. 622 """ 623 assert _babase.in_logic_thread() 624 assert not self._initial_sign_in_completed 625 626 # Tell meta it can start scanning extra stuff that just showed 627 # up (namely account workspaces). 628 self.meta.start_extra_scan() 629 630 self._initial_sign_in_completed = True 631 self._update_state()
Called when initial sign-in (or lack thereof) completes.
This normally gets called by the plus subsystem. The initial-sign-in process may include tasks such as syncing account workspaces or other data so it may take a substantial amount of time.
73 class State(Enum): 74 """High level state the app can be in.""" 75 76 # The app has not yet begun starting and should not be used in 77 # any way. 78 NOT_STARTED = 0 79 80 # The native layer is spinning up its machinery (screens, 81 # renderers, etc.). Nothing should happen in the Python layer 82 # until this completes. 83 NATIVE_BOOTSTRAPPING = 1 84 85 # Python app subsystems are being inited but should not yet 86 # interact or do any work. 87 INITING = 2 88 89 # Python app subsystems are inited and interacting, but the app 90 # has not yet embarked on a high level course of action. It is 91 # doing initial account logins, workspace & asset downloads, 92 # etc. 93 LOADING = 3 94 95 # All pieces are in place and the app is now doing its thing. 96 RUNNING = 4 97 98 # Used on platforms such as mobile where the app basically needs 99 # to shut down while backgrounded. In this state, all event 100 # loops are suspended and all graphics and audio must cease 101 # completely. Be aware that the suspended state can be entered 102 # from any other state including NATIVE_BOOTSTRAPPING and 103 # SHUTTING_DOWN. 104 SUSPENDED = 5 105 106 # The app is shutting down. This process may involve sending 107 # network messages or other things that can take up to a few 108 # seconds, so ideally graphics and audio should remain 109 # functional (with fades or spinners or whatever to show 110 # something is happening). 111 SHUTTING_DOWN = 6 112 113 # The app has completed shutdown. Any code running here should 114 # be basically immediate. 115 SHUTDOWN_COMPLETE = 7
High level state the app can be in.
Inherited Members
- enum.Enum
- name
- value
117 class DefaultAppModeSelector(AppModeSelector): 118 """Decides which AppModes to use to handle AppIntents. 119 120 This default version is generated by the project updater based 121 on the 'default_app_modes' value in the projectconfig. 122 123 It is also possible to modify app mode selection behavior by 124 setting app.mode_selector to an instance of a custom 125 AppModeSelector subclass. This is a good way to go if you are 126 modifying app behavior dynamically via a plugin instead of 127 statically in a spinoff project. 128 """ 129 130 @override 131 def app_mode_for_intent( 132 self, intent: AppIntent 133 ) -> type[AppMode] | None: 134 # pylint: disable=cyclic-import 135 136 # __DEFAULT_APP_MODE_SELECTION_BEGIN__ 137 # This section generated by batools.appmodule; do not edit. 138 139 # Ask our default app modes to handle it. 140 # (generated from 'default_app_modes' in projectconfig). 141 import baclassic 142 import babase 143 144 for appmode in [ 145 baclassic.ClassicAppMode, 146 babase.EmptyAppMode, 147 ]: 148 if appmode.can_handle_intent(intent): 149 return appmode 150 151 return None 152 153 # __DEFAULT_APP_MODE_SELECTION_END__ 154 155 @override 156 def testable_app_modes(self) -> list[type[AppMode]]: 157 # pylint: disable=cyclic-import 158 159 # __DEFAULT_TESTABLE_APP_MODES_BEGIN__ 160 # This section generated by batools.appmodule; do not edit. 161 162 # Return all our default_app_modes as testable. 163 # (generated from 'default_app_modes' in projectconfig). 164 import baclassic 165 import babase 166 167 return [ 168 baclassic.ClassicAppMode, 169 babase.EmptyAppMode, 170 ] 171 # __DEFAULT_TESTABLE_APP_MODES_END__
Decides which AppModes to use to handle AppIntents.
This default version is generated by the project updater based on the 'default_app_modes' value in the projectconfig.
It is also possible to modify app mode selection behavior by setting app.mode_selector to an instance of a custom AppModeSelector subclass. This is a good way to go if you are modifying app behavior dynamically via a plugin instead of statically in a spinoff project.
130 @override 131 def app_mode_for_intent( 132 self, intent: AppIntent 133 ) -> type[AppMode] | None: 134 # pylint: disable=cyclic-import 135 136 # __DEFAULT_APP_MODE_SELECTION_BEGIN__ 137 # This section generated by batools.appmodule; do not edit. 138 139 # Ask our default app modes to handle it. 140 # (generated from 'default_app_modes' in projectconfig). 141 import baclassic 142 import babase 143 144 for appmode in [ 145 baclassic.ClassicAppMode, 146 babase.EmptyAppMode, 147 ]: 148 if appmode.can_handle_intent(intent): 149 return appmode 150 151 return None 152 153 # __DEFAULT_APP_MODE_SELECTION_END__
Given an AppIntent, return the AppMode that should handle it.
If None is returned, the AppIntent will be ignored.
This may be called in a background thread, so avoid any calls limited to logic thread use/etc.
155 @override 156 def testable_app_modes(self) -> list[type[AppMode]]: 157 # pylint: disable=cyclic-import 158 159 # __DEFAULT_TESTABLE_APP_MODES_BEGIN__ 160 # This section generated by batools.appmodule; do not edit. 161 162 # Return all our default_app_modes as testable. 163 # (generated from 'default_app_modes' in projectconfig). 164 import baclassic 165 import babase 166 167 return [ 168 baclassic.ClassicAppMode, 169 babase.EmptyAppMode, 170 ] 171 # __DEFAULT_TESTABLE_APP_MODES_END__
Return a list of modes to appear in the dev-console app-mode ui.
The user can switch between these app modes for testing. App-modes will be passed an AppIntentDefault when selected by the user.
Note that in normal circumstances AppModes should never be selected explicitly by the user but rather determined implicitly based on AppIntents.
18class AppConfig(dict): 19 """A special dict that holds the game's persistent configuration values. 20 21 Category: **App Classes** 22 23 It also provides methods for fetching values with app-defined fallback 24 defaults, applying contained values to the game, and committing the 25 config to storage. 26 27 Call babase.appconfig() to get the single shared instance of this class. 28 29 AppConfig data is stored as json on disk on so make sure to only place 30 json-friendly values in it (dict, list, str, float, int, bool). 31 Be aware that tuples will be quietly converted to lists when stored. 32 """ 33 34 def resolve(self, key: str) -> Any: 35 """Given a string key, return a config value (type varies). 36 37 This will substitute application defaults for values not present in 38 the config dict, filter some invalid values, etc. Note that these 39 values do not represent the state of the app; simply the state of its 40 config. Use babase.App to access actual live state. 41 42 Raises an Exception for unrecognized key names. To get the list of keys 43 supported by this method, use babase.AppConfig.builtin_keys(). Note 44 that it is perfectly legal to store other data in the config; it just 45 needs to be accessed through standard dict methods and missing values 46 handled manually. 47 """ 48 return _babase.resolve_appconfig_value(key) 49 50 def default_value(self, key: str) -> Any: 51 """Given a string key, return its predefined default value. 52 53 This is the value that will be returned by babase.AppConfig.resolve() 54 if the key is not present in the config dict or of an incompatible 55 type. 56 57 Raises an Exception for unrecognized key names. To get the list of keys 58 supported by this method, use babase.AppConfig.builtin_keys(). Note 59 that it is perfectly legal to store other data in the config; it just 60 needs to be accessed through standard dict methods and missing values 61 handled manually. 62 """ 63 return _babase.get_appconfig_default_value(key) 64 65 def builtin_keys(self) -> list[str]: 66 """Return the list of valid key names recognized by babase.AppConfig. 67 68 This set of keys can be used with resolve(), default_value(), etc. 69 It does not vary across platforms and may include keys that are 70 obsolete or not relevant on the current running version. (for instance, 71 VR related keys on non-VR platforms). This is to minimize the amount 72 of platform checking necessary) 73 74 Note that it is perfectly legal to store arbitrary named data in the 75 config, but in that case it is up to the user to test for the existence 76 of the key in the config dict, fall back to consistent defaults, etc. 77 """ 78 return _babase.get_appconfig_builtin_keys() 79 80 def apply(self) -> None: 81 """Apply config values to the running app. 82 83 This call is thread-safe and asynchronous; changes will happen 84 in the next logic event loop cycle. 85 """ 86 _babase.app.push_apply_app_config() 87 88 def commit(self) -> None: 89 """Commits the config to local storage. 90 91 Note that this call is asynchronous so the actual write to disk may not 92 occur immediately. 93 """ 94 commit_app_config() 95 96 def apply_and_commit(self) -> None: 97 """Run apply() followed by commit(); for convenience. 98 99 (This way the commit() will not occur if apply() hits invalid data) 100 """ 101 self.apply() 102 self.commit()
A special dict that holds the game's persistent configuration values.
Category: App Classes
It also provides methods for fetching values with app-defined fallback defaults, applying contained values to the game, and committing the config to storage.
Call babase.appconfig() to get the single shared instance of this class.
AppConfig data is stored as json on disk on so make sure to only place json-friendly values in it (dict, list, str, float, int, bool). Be aware that tuples will be quietly converted to lists when stored.
34 def resolve(self, key: str) -> Any: 35 """Given a string key, return a config value (type varies). 36 37 This will substitute application defaults for values not present in 38 the config dict, filter some invalid values, etc. Note that these 39 values do not represent the state of the app; simply the state of its 40 config. Use babase.App to access actual live state. 41 42 Raises an Exception for unrecognized key names. To get the list of keys 43 supported by this method, use babase.AppConfig.builtin_keys(). Note 44 that it is perfectly legal to store other data in the config; it just 45 needs to be accessed through standard dict methods and missing values 46 handled manually. 47 """ 48 return _babase.resolve_appconfig_value(key)
Given a string key, return a config value (type varies).
This will substitute application defaults for values not present in the config dict, filter some invalid values, etc. Note that these values do not represent the state of the app; simply the state of its config. Use App to access actual live state.
Raises an Exception for unrecognized key names. To get the list of keys supported by this method, use AppConfig.builtin_keys(). Note that it is perfectly legal to store other data in the config; it just needs to be accessed through standard dict methods and missing values handled manually.
50 def default_value(self, key: str) -> Any: 51 """Given a string key, return its predefined default value. 52 53 This is the value that will be returned by babase.AppConfig.resolve() 54 if the key is not present in the config dict or of an incompatible 55 type. 56 57 Raises an Exception for unrecognized key names. To get the list of keys 58 supported by this method, use babase.AppConfig.builtin_keys(). Note 59 that it is perfectly legal to store other data in the config; it just 60 needs to be accessed through standard dict methods and missing values 61 handled manually. 62 """ 63 return _babase.get_appconfig_default_value(key)
Given a string key, return its predefined default value.
This is the value that will be returned by AppConfig.resolve() if the key is not present in the config dict or of an incompatible type.
Raises an Exception for unrecognized key names. To get the list of keys supported by this method, use AppConfig.builtin_keys(). Note that it is perfectly legal to store other data in the config; it just needs to be accessed through standard dict methods and missing values handled manually.
65 def builtin_keys(self) -> list[str]: 66 """Return the list of valid key names recognized by babase.AppConfig. 67 68 This set of keys can be used with resolve(), default_value(), etc. 69 It does not vary across platforms and may include keys that are 70 obsolete or not relevant on the current running version. (for instance, 71 VR related keys on non-VR platforms). This is to minimize the amount 72 of platform checking necessary) 73 74 Note that it is perfectly legal to store arbitrary named data in the 75 config, but in that case it is up to the user to test for the existence 76 of the key in the config dict, fall back to consistent defaults, etc. 77 """ 78 return _babase.get_appconfig_builtin_keys()
Return the list of valid key names recognized by AppConfig.
This set of keys can be used with resolve(), default_value(), etc. It does not vary across platforms and may include keys that are obsolete or not relevant on the current running version. (for instance, VR related keys on non-VR platforms). This is to minimize the amount of platform checking necessary)
Note that it is perfectly legal to store arbitrary named data in the config, but in that case it is up to the user to test for the existence of the key in the config dict, fall back to consistent defaults, etc.
80 def apply(self) -> None: 81 """Apply config values to the running app. 82 83 This call is thread-safe and asynchronous; changes will happen 84 in the next logic event loop cycle. 85 """ 86 _babase.app.push_apply_app_config()
Apply config values to the running app.
This call is thread-safe and asynchronous; changes will happen in the next logic event loop cycle.
88 def commit(self) -> None: 89 """Commits the config to local storage. 90 91 Note that this call is asynchronous so the actual write to disk may not 92 occur immediately. 93 """ 94 commit_app_config()
Commits the config to local storage.
Note that this call is asynchronous so the actual write to disk may not occur immediately.
96 def apply_and_commit(self) -> None: 97 """Run apply() followed by commit(); for convenience. 98 99 (This way the commit() will not occur if apply() hits invalid data) 100 """ 101 self.apply() 102 self.commit()
Run apply() followed by commit(); for convenience.
(This way the commit() will not occur if apply() hits invalid data)
Inherited Members
- builtins.dict
- get
- setdefault
- pop
- popitem
- keys
- items
- values
- update
- fromkeys
- clear
- copy
379class AppHealthMonitor(AppSubsystem): 380 """Logs things like app-not-responding issues.""" 381 382 def __init__(self) -> None: 383 assert _babase.in_logic_thread() 384 super().__init__() 385 self._running = True 386 self._thread = Thread(target=self._app_monitor_thread_main, daemon=True) 387 self._thread.start() 388 self._response = False 389 self._first_check = True 390 391 @override 392 def on_app_loading(self) -> None: 393 # If any traceback dumps happened last run, log and clear them. 394 log_dumped_app_state(from_previous_run=True) 395 396 def _app_monitor_thread_main(self) -> None: 397 _babase.set_thread_name('ballistica app-monitor') 398 try: 399 self._monitor_app() 400 except Exception: 401 logging.exception('Error in AppHealthMonitor thread.') 402 403 def _set_response(self) -> None: 404 assert _babase.in_logic_thread() 405 self._response = True 406 407 def _check_running(self) -> bool: 408 # Workaround for the fact that mypy assumes _running 409 # doesn't change during the course of a function. 410 return self._running 411 412 def _monitor_app(self) -> None: 413 import time 414 415 while bool(True): 416 # Always sleep a bit between checks. 417 time.sleep(1.234) 418 419 # Do nothing while backgrounded. 420 while not self._running: 421 time.sleep(2.3456) 422 423 # Wait for the logic thread to run something we send it. 424 starttime = time.monotonic() 425 self._response = False 426 _babase.pushcall(self._set_response, raw=True) 427 while not self._response: 428 # Abort this check if we went into the background. 429 if not self._check_running(): 430 break 431 432 # Wait a bit longer the first time through since the app 433 # could still be starting up; we generally don't want to 434 # report that. 435 threshold = 10 if self._first_check else 5 436 437 # If we've been waiting too long (and the app is running) 438 # dump the app state and bail. Make an exception for the 439 # first check though since the app could just be taking 440 # a while to get going; we don't want to report that. 441 duration = time.monotonic() - starttime 442 if duration > threshold: 443 dump_app_state( 444 reason=f'Logic thread unresponsive' 445 f' for {threshold} seconds.' 446 ) 447 448 # We just do one alert for now. 449 return 450 451 time.sleep(1.042) 452 453 self._first_check = False 454 455 @override 456 def on_app_suspend(self) -> None: 457 assert _babase.in_logic_thread() 458 self._running = False 459 460 @override 461 def on_app_unsuspend(self) -> None: 462 assert _babase.in_logic_thread() 463 self._running = True
Logs things like app-not-responding issues.
391 @override 392 def on_app_loading(self) -> None: 393 # If any traceback dumps happened last run, log and clear them. 394 log_dumped_app_state(from_previous_run=True)
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.
455 @override 456 def on_app_suspend(self) -> None: 457 assert _babase.in_logic_thread() 458 self._running = False
Called when the app enters the suspended state.
460 @override 461 def on_app_unsuspend(self) -> None: 462 assert _babase.in_logic_thread() 463 self._running = True
Called when the app exits the suspended state.
Inherited Members
13class AppIntent: 14 """A high level directive given to the app. 15 16 Category: **App Classes** 17 """
A high level directive given to the app.
Category: App Classes
Tells the app to simply run in its default mode.
24class AppIntentExec(AppIntent): 25 """Tells the app to exec some Python code.""" 26 27 def __init__(self, code: str): 28 self.code = code
Tells the app to exec some Python code.
14class AppMode: 15 """A high level mode for the app. 16 17 Category: **App Classes** 18 19 """ 20 21 @classmethod 22 def get_app_experience(cls) -> AppExperience: 23 """Return the overall experience provided by this mode.""" 24 raise NotImplementedError('AppMode subclasses must override this.') 25 26 @classmethod 27 def can_handle_intent(cls, intent: AppIntent) -> bool: 28 """Return whether this mode can handle the provided intent. 29 30 For this to return True, the AppMode must claim to support the 31 provided intent (via its _supports_intent() method) AND the 32 AppExperience associated with the AppMode must be supported by 33 the current app and runtime environment. 34 """ 35 # TODO: check AppExperience. 36 return cls._supports_intent(intent) 37 38 @classmethod 39 def _supports_intent(cls, intent: AppIntent) -> bool: 40 """Return whether our mode can handle the provided intent. 41 42 AppModes should override this to define what they can handle. 43 Note that AppExperience does not have to be considered here; that 44 is handled automatically by the can_handle_intent() call.""" 45 raise NotImplementedError('AppMode subclasses must override this.') 46 47 def handle_intent(self, intent: AppIntent) -> None: 48 """Handle an intent.""" 49 raise NotImplementedError('AppMode subclasses must override this.') 50 51 def on_activate(self) -> None: 52 """Called when the mode is being activated.""" 53 54 def on_deactivate(self) -> None: 55 """Called when the mode is being deactivated.""" 56 57 def on_app_active_changed(self) -> None: 58 """Called when babase.app.active changes. 59 60 The app-mode may want to take action such as pausing a running 61 game in such cases. 62 """
A high level mode for the app.
Category: App Classes
21 @classmethod 22 def get_app_experience(cls) -> AppExperience: 23 """Return the overall experience provided by this mode.""" 24 raise NotImplementedError('AppMode subclasses must override this.')
Return the overall experience provided by this mode.
26 @classmethod 27 def can_handle_intent(cls, intent: AppIntent) -> bool: 28 """Return whether this mode can handle the provided intent. 29 30 For this to return True, the AppMode must claim to support the 31 provided intent (via its _supports_intent() method) AND the 32 AppExperience associated with the AppMode must be supported by 33 the current app and runtime environment. 34 """ 35 # TODO: check AppExperience. 36 return cls._supports_intent(intent)
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.
47 def handle_intent(self, intent: AppIntent) -> None: 48 """Handle an intent.""" 49 raise NotImplementedError('AppMode subclasses must override this.')
Handle an intent.
57 def on_app_active_changed(self) -> None: 58 """Called when babase.app.active changes. 59 60 The app-mode may want to take action such as pausing a running 61 game in such cases. 62 """
Called when babase.app.active changes.
The app-mode may want to take action such as pausing a running game in such cases.
14class AppModeSelector: 15 """Defines which AppModes are available or used to handle given AppIntents. 16 17 Category: **App Classes** 18 19 The app calls an instance of this class when passed an AppIntent to 20 determine which AppMode to use to handle the intent. Plugins or 21 spinoff projects can modify high level app behavior by replacing or 22 modifying the app's mode-selector. 23 """ 24 25 def app_mode_for_intent(self, intent: AppIntent) -> type[AppMode] | None: 26 """Given an AppIntent, return the AppMode that should handle it. 27 28 If None is returned, the AppIntent will be ignored. 29 30 This may be called in a background thread, so avoid any calls 31 limited to logic thread use/etc. 32 """ 33 raise NotImplementedError() 34 35 def testable_app_modes(self) -> list[type[AppMode]]: 36 """Return a list of modes to appear in the dev-console app-mode ui. 37 38 The user can switch between these app modes for testing. App-modes 39 will be passed an AppIntentDefault when selected by the user. 40 41 Note that in normal circumstances AppModes should never be 42 selected explicitly by the user but rather determined implicitly 43 based on AppIntents. 44 """ 45 raise NotImplementedError()
Defines which AppModes are available or used to handle given AppIntents.
Category: App Classes
The app calls an instance of this class when passed an AppIntent to determine which AppMode to use to handle the intent. Plugins or spinoff projects can modify high level app behavior by replacing or modifying the app's mode-selector.
25 def app_mode_for_intent(self, intent: AppIntent) -> type[AppMode] | None: 26 """Given an AppIntent, return the AppMode that should handle it. 27 28 If None is returned, the AppIntent will be ignored. 29 30 This may be called in a background thread, so avoid any calls 31 limited to logic thread use/etc. 32 """ 33 raise NotImplementedError()
Given an AppIntent, return the AppMode that should handle it.
If None is returned, the AppIntent will be ignored.
This may be called in a background thread, so avoid any calls limited to logic thread use/etc.
35 def testable_app_modes(self) -> list[type[AppMode]]: 36 """Return a list of modes to appear in the dev-console app-mode ui. 37 38 The user can switch between these app modes for testing. App-modes 39 will be passed an AppIntentDefault when selected by the user. 40 41 Note that in normal circumstances AppModes should never be 42 selected explicitly by the user but rather determined implicitly 43 based on AppIntents. 44 """ 45 raise NotImplementedError()
Return a list of modes to appear in the dev-console app-mode ui.
The user can switch between these app modes for testing. App-modes will be passed an AppIntentDefault when selected by the user.
Note that in normal circumstances AppModes should never be selected explicitly by the user but rather determined implicitly based on AppIntents.
15class AppSubsystem: 16 """Base class for an app subsystem. 17 18 Category: **App Classes** 19 20 An app 'subsystem' is a bit of a vague term, as pieces of the app 21 can technically be any class and are not required to use this, but 22 building one out of this base class provides conveniences such as 23 predefined callbacks during app state changes. 24 25 Subsystems must be registered with the app before it completes its 26 transition to the 'running' state. 27 """ 28 29 def __init__(self) -> None: 30 _babase.app.register_subsystem(self) 31 32 def on_app_loading(self) -> None: 33 """Called when the app reaches the loading state. 34 35 Note that subsystems created after the app switches to the 36 loading state will not receive this callback. Subsystems created 37 by plugins are an example of this. 38 """ 39 40 def on_app_running(self) -> None: 41 """Called when the app reaches the running state.""" 42 43 def on_app_suspend(self) -> None: 44 """Called when the app enters the suspended state.""" 45 46 def on_app_unsuspend(self) -> None: 47 """Called when the app exits the suspended state.""" 48 49 def on_app_shutdown(self) -> None: 50 """Called when the app begins shutting down.""" 51 52 def on_app_shutdown_complete(self) -> None: 53 """Called when the app completes shutting down.""" 54 55 def do_apply_app_config(self) -> None: 56 """Called when the app config should be applied.""" 57 58 def reset(self) -> None: 59 """Reset the subsystem to a default state. 60 61 This is called when switching app modes, but may be called 62 at other times too. 63 """
Base class for an app subsystem.
Category: App Classes
An app 'subsystem' is a bit of a vague term, as pieces of the app can technically be any class and are not required to use this, but building one out of this base class provides conveniences such as predefined callbacks during app state changes.
Subsystems must be registered with the app before it completes its transition to the 'running' state.
32 def on_app_loading(self) -> None: 33 """Called when the app reaches the loading state. 34 35 Note that subsystems created after the app switches to the 36 loading state will not receive this callback. Subsystems created 37 by plugins are an example of this. 38 """
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.
52 def on_app_shutdown_complete(self) -> None: 53 """Called when the app completes shutting down."""
Called when the app completes shutting down.
58 def reset(self) -> None: 59 """Reset the subsystem to a default state. 60 61 This is called when switching app modes, but may be called 62 at other times too. 63 """
Reset the subsystem to a default state.
This is called when switching app modes, but may be called at other times too.
552def apptime() -> babase.AppTime: 553 """Return the current app-time in seconds. 554 555 Category: **General Utility Functions** 556 557 App-time is a monotonic time value; it starts at 0.0 when the app 558 launches and will never jump by large amounts or go backwards, even if 559 the system time changes. Its progression will pause when the app is in 560 a suspended state. 561 562 Note that the AppTime returned here is simply float; it just has a 563 unique type in the type-checker's eyes to help prevent it from being 564 accidentally used with time functionality expecting other time types. 565 """ 566 import babase # pylint: disable=cyclic-import 567 568 return babase.AppTime(0.0)
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.
571def apptimer(time: float, call: Callable[[], Any]) -> None: 572 """Schedule a callable object to run based on app-time. 573 574 Category: **General Utility Functions** 575 576 This function creates a one-off timer which cannot be canceled or 577 modified once created. If you require the ability to do so, or need 578 a repeating timer, use the babase.AppTimer class instead. 579 580 ##### Arguments 581 ###### time (float) 582 > Length of time in seconds that the timer will wait before firing. 583 584 ###### call (Callable[[], Any]) 585 > A callable Python object. Note that the timer will retain a 586 strong reference to the callable for as long as the timer exists, so you 587 may want to look into concepts such as babase.WeakCall if that is not 588 desired. 589 590 ##### Examples 591 Print some stuff through time: 592 >>> babase.screenmessage('hello from now!') 593 >>> babase.apptimer(1.0, babase.Call(babase.screenmessage, 594 'hello from the future!')) 595 >>> babase.apptimer(2.0, babase.Call(babase.screenmessage, 596 ... 'hello from the future 2!')) 597 """ 598 return 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 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 WeakCall if that is not desired.
Examples
Print some stuff through time:
>>> screenmessage('hello from now!')
>>> apptimer(1.0, Call(screenmessage,
'hello from the future!'))
>>> apptimer(2.0, Call(screenmessage,
... 'hello from the future 2!'))
53class AppTimer: 54 """Timers are used to run code at later points in time. 55 56 Category: **General Utility Classes** 57 58 This class encapsulates a timer based on app-time. 59 The underlying timer will be destroyed when this object is no longer 60 referenced. If you do not want to worry about keeping a reference to 61 your timer around, use the babase.apptimer() function instead to get a 62 one-off timer. 63 64 ##### Arguments 65 ###### time 66 > Length of time in seconds that the timer will wait before firing. 67 68 ###### call 69 > A callable Python object. Remember that the timer will retain a 70 strong reference to the callable for as long as it exists, so you 71 may want to look into concepts such as babase.WeakCall if that is not 72 desired. 73 74 ###### repeat 75 > If True, the timer will fire repeatedly, with each successive 76 firing having the same delay as the first. 77 78 ##### Example 79 80 Use a Timer object to print repeatedly for a few seconds: 81 ... def say_it(): 82 ... babase.screenmessage('BADGER!') 83 ... def stop_saying_it(): 84 ... global g_timer 85 ... g_timer = None 86 ... babase.screenmessage('MUSHROOM MUSHROOM!') 87 ... # Create our timer; it will run as long as we have the self.t ref. 88 ... g_timer = babase.AppTimer(0.3, say_it, repeat=True) 89 ... # Now fire off a one-shot timer to kill it. 90 ... babase.apptimer(3.89, stop_saying_it) 91 """ 92 93 def __init__( 94 self, time: float, call: Callable[[], Any], repeat: bool = False 95 ) -> None: 96 pass
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 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 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(): ... screenmessage('BADGER!') ... def stop_saying_it(): ... global g_timer ... g_timer = None ... screenmessage('MUSHROOM MUSHROOM!') ... # Create our timer; it will run as long as we have the self.t ref. ... g_timer = AppTimer(0.3, say_it, repeat=True) ... # Now fire off a one-shot timer to kill it. ... apptimer(3.89, stop_saying_it)
621def charstr(char_id: babase.SpecialChar) -> str: 622 """Get a unicode string representing a special character. 623 624 Category: **General Utility Functions** 625 626 Note that these utilize the private-use block of unicode characters 627 (U+E000-U+F8FF) and are specific to the game; exporting or rendering 628 them elsewhere will be meaningless. 629 630 See babase.SpecialChar for the list of available characters. 631 """ 632 return str()
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 SpecialChar for the list of available characters.
635def clipboard_get_text() -> str: 636 """Return text currently on the system clipboard. 637 638 Category: **General Utility Functions** 639 640 Ensure that babase.clipboard_has_text() returns True before calling 641 this function. 642 """ 643 return str()
Return text currently on the system clipboard.
Category: General Utility Functions
Ensure that clipboard_has_text() returns True before calling this function.
646def clipboard_has_text() -> bool: 647 """Return whether there is currently text on the clipboard. 648 649 Category: **General Utility Functions** 650 651 This will return False if no system clipboard is available; no need 652 to call babase.clipboard_is_supported() separately. 653 """ 654 return bool()
Return whether there is currently text on the clipboard.
Category: General Utility Functions
This will return False if no system clipboard is available; no need to call clipboard_is_supported() separately.
657def clipboard_is_supported() -> bool: 658 """Return whether this platform supports clipboard operations at all. 659 660 Category: **General Utility Functions** 661 662 If this returns False, UIs should not show 'copy to clipboard' 663 buttons, etc. 664 """ 665 return bool()
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.
668def clipboard_set_text(value: str) -> None: 669 """Copy a string to the system clipboard. 670 671 Category: **General Utility Functions** 672 673 Ensure that babase.clipboard_is_supported() returns True before adding 674 buttons/etc. that make use of this functionality. 675 """ 676 return None
Copy a string to the system clipboard.
Category: General Utility Functions
Ensure that clipboard_is_supported() returns True before adding buttons/etc. that make use of this functionality.
99class ContextCall: 100 """A context-preserving callable. 101 102 Category: **General Utility Classes** 103 104 A ContextCall wraps a callable object along with a reference 105 to the current context (see babase.ContextRef); it handles restoring 106 the context when run and automatically clears itself if the context 107 it belongs to dies. 108 109 Generally you should not need to use this directly; all standard 110 Ballistica callbacks involved with timers, materials, UI functions, 111 etc. handle this under-the-hood so you don't have to worry about it. 112 The only time it may be necessary is if you are implementing your 113 own callbacks, such as a worker thread that does some action and then 114 runs some game code when done. By wrapping said callback in one of 115 these, you can ensure that you will not inadvertently be keeping the 116 current activity alive or running code in a torn-down (expired) 117 context_ref. 118 119 You can also use babase.WeakCall for similar functionality, but 120 ContextCall has the added bonus that it will not run during context_ref 121 shutdown, whereas babase.WeakCall simply looks at whether the target 122 object instance still exists. 123 124 ##### Examples 125 **Example A:** code like this can inadvertently prevent our activity 126 (self) from ending until the operation completes, since the bound 127 method we're passing (self.dosomething) contains a strong-reference 128 to self). 129 >>> start_some_long_action(callback_when_done=self.dosomething) 130 131 **Example B:** in this case our activity (self) can still die 132 properly; the callback will clear itself when the activity starts 133 shutting down, becoming a harmless no-op and releasing the reference 134 to our activity. 135 136 >>> start_long_action( 137 ... callback_when_done=babase.ContextCall(self.mycallback)) 138 """ 139 140 def __init__(self, call: Callable) -> None: 141 pass 142 143 def __call__(self) -> None: 144 """Support for calling.""" 145 pass
A context-preserving callable.
Category: General Utility Classes
A ContextCall wraps a callable object along with a reference to the current context (see ContextRef); it handles restoring the context when run and automatically clears itself if the context it belongs to dies.
Generally you should not need to use this directly; all standard Ballistica callbacks involved with timers, materials, UI functions, etc. handle this under-the-hood so you don't have to worry about it. The only time it may be necessary is if you are implementing your own callbacks, such as a worker thread that does some action and then runs some game code when done. By wrapping said callback in one of these, you can ensure that you will not inadvertently be keeping the current activity alive or running code in a torn-down (expired) context_ref.
You can also use WeakCall for similar functionality, but ContextCall has the added bonus that it will not run during context_ref shutdown, whereas WeakCall simply looks at whether the target object instance still exists.
Examples
Example A: code like this can inadvertently prevent our activity (self) from ending until the operation completes, since the bound method we're passing (self.dosomething) contains a strong-reference to self).
>>> start_some_long_action(callback_when_done=self.dosomething)
Example B: in this case our activity (self) can still die properly; the callback will clear itself when the activity starts shutting down, becoming a harmless no-op and releasing the reference to our activity.
>>> start_long_action(
... callback_when_done=ContextCall(self.mycallback))
16class ContextError(Exception): 17 """Exception raised when a call is made in an invalid context. 18 19 Category: **Exception Classes** 20 21 Examples of this include calling UI functions within an Activity context 22 or calling scene manipulation functions outside of a game context. 23 """
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.
Inherited Members
- builtins.Exception
- Exception
- builtins.BaseException
- with_traceback
- add_note
- args
148class ContextRef: 149 """Store or use a ballistica context. 150 151 Category: **General Utility Classes** 152 153 Many operations such as bascenev1.newnode() or bascenev1.gettexture() 154 operate implicitly on a current 'context'. A context is some sort of 155 state that functionality can implicitly use. Context determines, for 156 example, which scene nodes or textures get added to without having to 157 specify it explicitly in the newnode()/gettexture() call. Contexts can 158 also affect object lifecycles; for example a babase.ContextCall will 159 become a no-op when the context it was created in is destroyed. 160 161 In general, if you are a modder, you should not need to worry about 162 contexts; mod code should mostly be getting run in the correct 163 context and timers and other callbacks will take care of saving 164 and restoring contexts automatically. There may be rare cases, 165 however, where you need to deal directly with contexts, and that is 166 where this class comes in. 167 168 Creating a babase.ContextRef() will capture a reference to the current 169 context. Other modules may provide ways to access their contexts; for 170 example a bascenev1.Activity instance has a 'context' attribute. You 171 can also use babase.ContextRef.empty() to create a reference to *no* 172 context. Some code such as UI calls may expect this and may complain 173 if you try to use them within a context. 174 175 ##### Usage 176 ContextRefs are generally used with the Python 'with' statement, which 177 sets the context they point to as current on entry and resets it to 178 the previous value on exit. 179 180 ##### Example 181 Explicitly create a few UI bits with no context set. 182 (UI stuff may complain if called within a context): 183 >>> with bui.ContextRef.empty(): 184 ... my_container = bui.containerwidget() 185 """ 186 187 def __init__( 188 self, 189 ) -> None: 190 pass 191 192 def __enter__(self) -> None: 193 """Support for "with" statement.""" 194 pass 195 196 def __exit__(self, exc_type: Any, exc_value: Any, traceback: Any) -> Any: 197 """Support for "with" statement.""" 198 pass 199 200 @classmethod 201 def empty(cls) -> ContextRef: 202 """Return a ContextRef pointing to no context. 203 204 This is useful when code should be run free of a context. 205 For example, UI code generally insists on being run this way. 206 Otherwise, callbacks set on the UI could inadvertently stop working 207 due to a game activity ending, which would be unintuitive behavior. 208 """ 209 return ContextRef() 210 211 def is_empty(self) -> bool: 212 """Whether the context was created as empty.""" 213 return bool() 214 215 def is_expired(self) -> bool: 216 """Whether the context has expired.""" 217 return bool()
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 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 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 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()
200 @classmethod 201 def empty(cls) -> ContextRef: 202 """Return a ContextRef pointing to no context. 203 204 This is useful when code should be run free of a context. 205 For example, UI code generally insists on being run this way. 206 Otherwise, callbacks set on the UI could inadvertently stop working 207 due to a game activity ending, which would be unintuitive behavior. 208 """ 209 return 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.
61class DelegateNotFoundError(NotFoundError): 62 """Exception raised when an expected delegate object does not exist. 63 64 Category: **Exception Classes** 65 """
Exception raised when an expected delegate object does not exist.
Category: Exception Classes
Inherited Members
- builtins.Exception
- Exception
- builtins.BaseException
- with_traceback
- add_note
- args
20class DevConsoleTab: 21 """Defines behavior for a tab in the dev-console.""" 22 23 def refresh(self) -> None: 24 """Called when the tab should refresh itself.""" 25 26 def request_refresh(self) -> None: 27 """The tab can call this to request that it be refreshed.""" 28 _babase.dev_console_request_refresh() 29 30 def button( 31 self, 32 label: str, 33 pos: tuple[float, float], 34 size: tuple[float, float], 35 call: Callable[[], Any] | None = None, 36 h_anchor: Literal['left', 'center', 'right'] = 'center', 37 label_scale: float = 1.0, 38 corner_radius: float = 8.0, 39 style: Literal['normal', 'dark'] = 'normal', 40 ) -> None: 41 """Add a button to the tab being refreshed.""" 42 assert _babase.app.devconsole.is_refreshing 43 _babase.dev_console_add_button( 44 label, 45 pos[0], 46 pos[1], 47 size[0], 48 size[1], 49 call, 50 h_anchor, 51 label_scale, 52 corner_radius, 53 style, 54 ) 55 56 def text( 57 self, 58 text: str, 59 pos: tuple[float, float], 60 h_anchor: Literal['left', 'center', 'right'] = 'center', 61 h_align: Literal['left', 'center', 'right'] = 'center', 62 v_align: Literal['top', 'center', 'bottom', 'none'] = 'center', 63 scale: float = 1.0, 64 ) -> None: 65 """Add a button to the tab being refreshed.""" 66 assert _babase.app.devconsole.is_refreshing 67 _babase.dev_console_add_text( 68 text, pos[0], pos[1], h_anchor, h_align, v_align, scale 69 ) 70 71 def python_terminal(self) -> None: 72 """Add a Python Terminal to the tab being refreshed.""" 73 assert _babase.app.devconsole.is_refreshing 74 _babase.dev_console_add_python_terminal() 75 76 @property 77 def width(self) -> float: 78 """Return the current tab width. Only call during refreshes.""" 79 assert _babase.app.devconsole.is_refreshing 80 return _babase.dev_console_tab_width() 81 82 @property 83 def height(self) -> float: 84 """Return the current tab height. Only call during refreshes.""" 85 assert _babase.app.devconsole.is_refreshing 86 return _babase.dev_console_tab_height() 87 88 @property 89 def base_scale(self) -> float: 90 """A scale value set depending on the app's UI scale. 91 92 Dev-console tabs can incorporate this into their UI sizes and 93 positions if they desire. This must be done manually however. 94 """ 95 assert _babase.app.devconsole.is_refreshing 96 return _babase.dev_console_base_scale()
Defines behavior for a tab in the dev-console.
26 def request_refresh(self) -> None: 27 """The tab can call this to request that it be refreshed.""" 28 _babase.dev_console_request_refresh()
The tab can call this to request that it be refreshed.
56 def text( 57 self, 58 text: str, 59 pos: tuple[float, float], 60 h_anchor: Literal['left', 'center', 'right'] = 'center', 61 h_align: Literal['left', 'center', 'right'] = 'center', 62 v_align: Literal['top', 'center', 'bottom', 'none'] = 'center', 63 scale: float = 1.0, 64 ) -> None: 65 """Add a button to the tab being refreshed.""" 66 assert _babase.app.devconsole.is_refreshing 67 _babase.dev_console_add_text( 68 text, pos[0], pos[1], h_anchor, h_align, v_align, scale 69 )
Add a button to the tab being refreshed.
71 def python_terminal(self) -> None: 72 """Add a Python Terminal to the tab being refreshed.""" 73 assert _babase.app.devconsole.is_refreshing 74 _babase.dev_console_add_python_terminal()
Add a Python Terminal to the tab being refreshed.
76 @property 77 def width(self) -> float: 78 """Return the current tab width. Only call during refreshes.""" 79 assert _babase.app.devconsole.is_refreshing 80 return _babase.dev_console_tab_width()
Return the current tab width. Only call during refreshes.
82 @property 83 def height(self) -> float: 84 """Return the current tab height. Only call during refreshes.""" 85 assert _babase.app.devconsole.is_refreshing 86 return _babase.dev_console_tab_height()
Return the current tab height. Only call during refreshes.
88 @property 89 def base_scale(self) -> float: 90 """A scale value set depending on the app's UI scale. 91 92 Dev-console tabs can incorporate this into their UI sizes and 93 positions if they desire. This must be done manually however. 94 """ 95 assert _babase.app.devconsole.is_refreshing 96 return _babase.dev_console_base_scale()
A scale value set depending on the app's UI scale.
Dev-console tabs can incorporate this into their UI sizes and positions if they desire. This must be done manually however.
236@dataclass 237class DevConsoleTabEntry: 238 """Represents a distinct tab in the dev-console.""" 239 240 name: str 241 factory: Callable[[], DevConsoleTab]
Represents a distinct tab in the dev-console.
244class DevConsoleSubsystem: 245 """Subsystem for wrangling the dev console. 246 247 The single instance of this class can be found at 248 babase.app.devconsole. The dev-console is a simple always-available 249 UI intended for use by developers; not end users. Traditionally it 250 is available by typing a backtick (`) key on a keyboard, but now can 251 be accessed via an on-screen button (see settings/advanced to enable 252 said button). 253 """ 254 255 def __init__(self) -> None: 256 # All tabs in the dev-console. Add your own stuff here via 257 # plugins or whatnot. 258 self.tabs: list[DevConsoleTabEntry] = [ 259 DevConsoleTabEntry('Python', DevConsoleTabPython), 260 DevConsoleTabEntry('AppModes', DevConsoleTabAppModes), 261 DevConsoleTabEntry('UI', DevConsoleTabUI), 262 ] 263 if os.environ.get('BA_DEV_CONSOLE_TEST_TAB', '0') == '1': 264 self.tabs.append(DevConsoleTabEntry('Test', DevConsoleTabTest)) 265 self.is_refreshing = False 266 267 def do_refresh_tab(self, tabname: str) -> None: 268 """Called by the C++ layer when a tab should be filled out.""" 269 assert _babase.in_logic_thread() 270 271 # FIXME: We currently won't handle multiple tabs with the same 272 # name. We should give a clean error or something in that case. 273 tab: DevConsoleTab | None = None 274 for tabentry in self.tabs: 275 if tabentry.name == tabname: 276 tab = tabentry.factory() 277 break 278 279 if tab is None: 280 logging.error( 281 'DevConsole got refresh request for tab' 282 " '%s' which does not exist.", 283 tabname, 284 ) 285 return 286 287 self.is_refreshing = True 288 try: 289 tab.refresh() 290 finally: 291 self.is_refreshing = False
Subsystem for wrangling the dev console.
The single instance of this class can be found at babase.app.devconsole. The dev-console is a simple always-available UI intended for use by developers; not end users. Traditionally it is available by typing a backtick (`) key on a keyboard, but now can be accessed via an on-screen button (see settings/advanced to enable said button).
267 def do_refresh_tab(self, tabname: str) -> None: 268 """Called by the C++ layer when a tab should be filled out.""" 269 assert _babase.in_logic_thread() 270 271 # FIXME: We currently won't handle multiple tabs with the same 272 # name. We should give a clean error or something in that case. 273 tab: DevConsoleTab | None = None 274 for tabentry in self.tabs: 275 if tabentry.name == tabname: 276 tab = tabentry.factory() 277 break 278 279 if tab is None: 280 logging.error( 281 'DevConsole got refresh request for tab' 282 " '%s' which does not exist.", 283 tabname, 284 ) 285 return 286 287 self.is_refreshing = True 288 try: 289 tab.refresh() 290 finally: 291 self.is_refreshing = False
Called by the C++ layer when a tab should be filled out.
761def displaytime() -> babase.DisplayTime: 762 """Return the current display-time in seconds. 763 764 Category: **General Utility Functions** 765 766 Display-time is a time value intended to be used for animation and other 767 visual purposes. It will generally increment by a consistent amount each 768 frame. It will pass at an overall similar rate to AppTime, but trades 769 accuracy for smoothness. 770 771 Note that the value returned here is simply a float; it just has a 772 unique type in the type-checker's eyes to help prevent it from being 773 accidentally used with time functionality expecting other time types. 774 """ 775 import babase # pylint: disable=cyclic-import 776 777 return babase.DisplayTime(0.0)
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.
780def displaytimer(time: float, call: Callable[[], Any]) -> None: 781 """Schedule a callable object to run based on display-time. 782 783 Category: **General Utility Functions** 784 785 This function creates a one-off timer which cannot be canceled or 786 modified once created. If you require the ability to do so, or need 787 a repeating timer, use the babase.DisplayTimer class instead. 788 789 Display-time is a time value intended to be used for animation and other 790 visual purposes. It will generally increment by a consistent amount each 791 frame. It will pass at an overall similar rate to AppTime, but trades 792 accuracy for smoothness. 793 794 ##### Arguments 795 ###### time (float) 796 > Length of time in seconds that the timer will wait before firing. 797 798 ###### call (Callable[[], Any]) 799 > A callable Python object. Note that the timer will retain a 800 strong reference to the callable for as long as the timer exists, so you 801 may want to look into concepts such as babase.WeakCall if that is not 802 desired. 803 804 ##### Examples 805 Print some stuff through time: 806 >>> babase.screenmessage('hello from now!') 807 >>> babase.displaytimer(1.0, babase.Call(babase.screenmessage, 808 ... 'hello from the future!')) 809 >>> babase.displaytimer(2.0, babase.Call(babase.screenmessage, 810 ... 'hello from the future 2!')) 811 """ 812 return 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 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 WeakCall if that is not desired.
Examples
Print some stuff through time:
>>> screenmessage('hello from now!')
>>> displaytimer(1.0, Call(screenmessage,
... 'hello from the future!'))
>>> displaytimer(2.0, Call(screenmessage,
... 'hello from the future 2!'))
220class DisplayTimer: 221 """Timers are used to run code at later points in time. 222 223 Category: **General Utility Classes** 224 225 This class encapsulates a timer based on display-time. 226 The underlying timer will be destroyed when this object is no longer 227 referenced. If you do not want to worry about keeping a reference to 228 your timer around, use the babase.displaytimer() function instead to get a 229 one-off timer. 230 231 Display-time is a time value intended to be used for animation and 232 other visual purposes. It will generally increment by a consistent 233 amount each frame. It will pass at an overall similar rate to AppTime, 234 but trades accuracy for smoothness. 235 236 ##### Arguments 237 ###### time 238 > Length of time in seconds that the timer will wait before firing. 239 240 ###### call 241 > A callable Python object. Remember that the timer will retain a 242 strong reference to the callable for as long as it exists, so you 243 may want to look into concepts such as babase.WeakCall if that is not 244 desired. 245 246 ###### repeat 247 > If True, the timer will fire repeatedly, with each successive 248 firing having the same delay as the first. 249 250 ##### Example 251 252 Use a Timer object to print repeatedly for a few seconds: 253 ... def say_it(): 254 ... babase.screenmessage('BADGER!') 255 ... def stop_saying_it(): 256 ... global g_timer 257 ... g_timer = None 258 ... babase.screenmessage('MUSHROOM MUSHROOM!') 259 ... # Create our timer; it will run as long as we have the self.t ref. 260 ... g_timer = babase.DisplayTimer(0.3, say_it, repeat=True) 261 ... # Now fire off a one-shot timer to kill it. 262 ... babase.displaytimer(3.89, stop_saying_it) 263 """ 264 265 def __init__( 266 self, time: float, call: Callable[[], Any], repeat: bool = False 267 ) -> None: 268 pass
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 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 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(): ... screenmessage('BADGER!') ... def stop_saying_it(): ... global g_timer ... g_timer = None ... screenmessage('MUSHROOM MUSHROOM!') ... # Create our timer; it will run as long as we have the self.t ref. ... g_timer = DisplayTimer(0.3, say_it, repeat=True) ... # Now fire off a one-shot timer to kill it. ... displaytimer(3.89, stop_saying_it)
820def do_once() -> bool: 821 """Return whether this is the first time running a line of code. 822 823 Category: **General Utility Functions** 824 825 This is used by 'print_once()' type calls to keep from overflowing 826 logs. The call functions by registering the filename and line where 827 The call is made from. Returns True if this location has not been 828 registered already, and False if it has. 829 830 ##### Example 831 This print will only fire for the first loop iteration: 832 >>> for i in range(10): 833 ... if babase.do_once(): 834 ... print('HelloWorld once from loop!') 835 """ 836 return bool()
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 do_once():
... print('HelloWorld once from loop!')
19class EmptyAppMode(AppMode): 20 """An AppMode that does not do much at all.""" 21 22 @override 23 @classmethod 24 def get_app_experience(cls) -> AppExperience: 25 return AppExperience.EMPTY 26 27 @override 28 @classmethod 29 def _supports_intent(cls, intent: AppIntent) -> bool: 30 # We support default and exec intents currently. 31 return isinstance(intent, AppIntentExec | AppIntentDefault) 32 33 @override 34 def handle_intent(self, intent: AppIntent) -> None: 35 if isinstance(intent, AppIntentExec): 36 _babase.empty_app_mode_handle_app_intent_exec(intent.code) 37 return 38 assert isinstance(intent, AppIntentDefault) 39 _babase.empty_app_mode_handle_app_intent_default() 40 41 @override 42 def on_activate(self) -> None: 43 # Let the native layer do its thing. 44 _babase.empty_app_mode_activate() 45 46 @override 47 def on_deactivate(self) -> None: 48 # Let the native layer do its thing. 49 _babase.empty_app_mode_deactivate()
An AppMode that does not do much at all.
22 @override 23 @classmethod 24 def get_app_experience(cls) -> AppExperience: 25 return AppExperience.EMPTY
Return the overall experience provided by this mode.
33 @override 34 def handle_intent(self, intent: AppIntent) -> None: 35 if isinstance(intent, AppIntentExec): 36 _babase.empty_app_mode_handle_app_intent_exec(intent.code) 37 return 38 assert isinstance(intent, AppIntentDefault) 39 _babase.empty_app_mode_handle_app_intent_default()
Handle an intent.
41 @override 42 def on_activate(self) -> None: 43 # Let the native layer do its thing. 44 _babase.empty_app_mode_activate()
Called when the mode is being activated.
46 @override 47 def on_deactivate(self) -> None: 48 # Let the native layer do its thing. 49 _babase.empty_app_mode_deactivate()
Called when the mode is being deactivated.
Inherited Members
271class Env: 272 """Unchanging values for the current running app instance. 273 Access the single shared instance of this class at `babase.app.env`. 274 """ 275 276 android: bool 277 """Is this build targeting an Android based OS?""" 278 279 api_version: int 280 """The app's api version. 281 282 Only Python modules and packages associated with the current API 283 version number will be detected by the game (see the ba_meta tag). 284 This value will change whenever substantial backward-incompatible 285 changes are introduced to Ballistica APIs. When that happens, 286 modules/packages should be updated accordingly and set to target 287 the newer API version number.""" 288 289 arcade: bool 290 """Whether the app is targeting an arcade-centric experience.""" 291 292 config_file_path: str 293 """Where the app's config file is stored on disk.""" 294 295 data_directory: str 296 """Where bundled static app data lives.""" 297 298 debug: bool 299 """Whether the app is running in debug mode. 300 301 Debug builds generally run substantially slower than non-debug 302 builds due to compiler optimizations being disabled and extra 303 checks being run.""" 304 305 demo: bool 306 """Whether the app is targeting a demo experience.""" 307 308 device_name: str 309 """Human readable name of the device running this app.""" 310 311 engine_build_number: int 312 """Integer build number for the engine. 313 314 This value increases by at least 1 with each release of the engine. 315 It is independent of the human readable `version` string.""" 316 317 engine_version: str 318 """Human-readable version string for the engine; something like '1.3.24'. 319 320 This should not be interpreted as a number; it may contain 321 string elements such as 'alpha', 'beta', 'test', etc. 322 If a numeric version is needed, use `build_number`.""" 323 324 gui: bool 325 """Whether the app is running with a gui. 326 327 This is the opposite of `headless`.""" 328 329 headless: bool 330 """Whether the app is running headlessly (without a gui). 331 332 This is the opposite of `gui`.""" 333 334 python_directory_app: str | None 335 """Path where the app expects its bundled modules to live. 336 337 Be aware that this value may be None if Ballistica is running in 338 a non-standard environment, and that python-path modifications may 339 cause modules to be loaded from other locations.""" 340 341 python_directory_app_site: str | None 342 """Path where the app expects its bundled pip modules to live. 343 344 Be aware that this value may be None if Ballistica is running in 345 a non-standard environment, and that python-path modifications may 346 cause modules to be loaded from other locations.""" 347 348 python_directory_user: str | None 349 """Path where the app expects its user scripts (mods) to live. 350 351 Be aware that this value may be None if Ballistica is running in 352 a non-standard environment, and that python-path modifications may 353 cause modules to be loaded from other locations.""" 354 355 supports_soft_quit: bool 356 """Whether the running app supports 'soft' quit options. 357 358 This generally applies to mobile derived OSs, where an act of 359 'quitting' may leave the app running in the background waiting 360 in case it is used again.""" 361 362 test: bool 363 """Whether the app is running in test mode. 364 365 Test mode enables extra checks and features that are useful for 366 release testing but which do not slow the game down significantly.""" 367 368 tv: bool 369 """Whether the app is targeting a TV-centric experience.""" 370 371 vr: bool 372 """Whether the app is currently running in VR.""" 373 374 pass
Unchanging values for the current running app instance.
Access the single shared instance of this class at babase.app.env
.
The app's api version.
Only Python modules and packages associated with the current API version number will be detected by the game (see the ba_meta tag). This value will change whenever substantial backward-incompatible changes are introduced to Ballistica APIs. When that happens, modules/packages should be updated accordingly and set to target the newer API version number.
Whether the app is running in debug mode.
Debug builds generally run substantially slower than non-debug builds due to compiler optimizations being disabled and extra checks being run.
Integer build number for the engine.
This value increases by at least 1 with each release of the engine.
It is independent of the human readable version
string.
Human-readable version string for the engine; something like '1.3.24'.
This should not be interpreted as a number; it may contain
string elements such as 'alpha', 'beta', 'test', etc.
If a numeric version is needed, use build_number
.
Path where the app expects its bundled modules to live.
Be aware that this value may be None if Ballistica is running in a non-standard environment, and that python-path modifications may cause modules to be loaded from other locations.
Path where the app expects its bundled pip modules to live.
Be aware that this value may be None if Ballistica is running in a non-standard environment, and that python-path modifications may cause modules to be loaded from other locations.
Path where the app expects its user scripts (mods) to live.
Be aware that this value may be None if Ballistica is running in a non-standard environment, and that python-path modifications may cause modules to be loaded from other locations.
Whether the running app supports 'soft' quit options.
This generally applies to mobile derived OSs, where an act of 'quitting' may leave the app running in the background waiting in case it is used again.
37class Existable(Protocol): 38 """A Protocol for objects supporting an exists() method. 39 40 Category: **Protocols** 41 """ 42 43 def exists(self) -> bool: 44 """Whether this object exists."""
A Protocol for objects supporting an exists() method.
Category: Protocols
1767def _no_init_or_replace_init(self, *args, **kwargs): 1768 cls = type(self) 1769 1770 if cls._is_protocol: 1771 raise TypeError('Protocols cannot be instantiated') 1772 1773 # Already using a custom `__init__`. No need to calculate correct 1774 # `__init__` to call. This can lead to RecursionError. See bpo-45121. 1775 if cls.__init__ is not _no_init_or_replace_init: 1776 return 1777 1778 # Initially, `__init__` of a protocol subclass is set to `_no_init_or_replace_init`. 1779 # The first instantiation of the subclass will call `_no_init_or_replace_init` which 1780 # searches for a proper new `__init__` in the MRO. The new `__init__` 1781 # replaces the subclass' old `__init__` (ie `_no_init_or_replace_init`). Subsequent 1782 # instantiation of the protocol subclass will thus use the new 1783 # `__init__` and no longer call `_no_init_or_replace_init`. 1784 for base in cls.__mro__: 1785 init = base.__dict__.get('__init__', _no_init_or_replace_init) 1786 if init is not _no_init_or_replace_init: 1787 cls.__init__ = init 1788 break 1789 else: 1790 # should not happen 1791 cls.__init__ = object.__init__ 1792 1793 cls.__init__(self, *args, **kwargs)
51def existing(obj: ExistableT | None) -> ExistableT | None: 52 """Convert invalid references to None for any babase.Existable object. 53 54 Category: **Gameplay Functions** 55 56 To best support type checking, it is important that invalid references 57 not be passed around and instead get converted to values of None. 58 That way the type checker can properly flag attempts to pass possibly-dead 59 objects (FooType | None) into functions expecting only live ones 60 (FooType), etc. This call can be used on any 'existable' object 61 (one with an exists() method) and will convert it to a None value 62 if it does not exist. 63 64 For more info, see notes on 'existables' here: 65 https://ballistica.net/wiki/Coding-Style-Guide 66 """ 67 assert obj is None or hasattr(obj, 'exists'), f'No "exists" on {obj}' 68 return obj if obj is not None and obj.exists() else None
Convert invalid references to None for any 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
908def fatal_error(message: str) -> None: 909 """Trigger a fatal error. Use this in situations where it is not possible 910 for the engine to continue on in a useful way. This can sometimes 911 help provide more clear information at the exact source of a problem 912 as compared to raising an Exception. In the vast majority of cases, 913 however, Exceptions should be preferred. 914 """ 915 return None
Trigger a fatal error. Use this in situations where it is not possible for the engine to continue on in a useful way. This can sometimes help provide more clear information at the exact source of a problem as compared to raising an Exception. In the vast majority of cases, however, Exceptions should be preferred.
214def garbage_collect() -> None: 215 """Run an explicit pass of garbage collection. 216 217 category: General Utility Functions 218 219 May also print warnings/etc. if collection takes too long or if 220 uncollectible objects are found (so use this instead of simply 221 gc.collect(). 222 """ 223 gc.collect()
Run an explicit pass of garbage collection.
category: General Utility Functions
May also print warnings/etc. if collection takes too long or if uncollectible objects are found (so use this instead of simply gc.collect().
1000def get_input_idle_time() -> float: 1001 """Return seconds since any local input occurred (touch, keypress, etc.).""" 1002 return float()
Return seconds since any local input occurred (touch, keypress, etc.).
45def get_ip_address_type(addr: str) -> socket.AddressFamily: 46 """Return socket.AF_INET6 or socket.AF_INET4 for the provided address.""" 47 48 version = ipaddress.ip_address(addr).version 49 if version == 4: 50 return socket.AF_INET 51 assert version == 6 52 return socket.AF_INET6
Return socket.AF_INET6 or socket.AF_INET4 for the provided address.
112def get_type_name(cls: type) -> str: 113 """Return a full type name including module for a class.""" 114 return f'{cls.__module__}.{cls.__name__}'
Return a full type name including module for a class.
71def getclass( 72 name: str, subclassof: type[T], check_sdlib_modulename_clash: bool = False 73) -> type[T]: 74 """Given a full class name such as foo.bar.MyClass, return the class. 75 76 Category: **General Utility Functions** 77 78 The class will be checked to make sure it is a subclass of the provided 79 'subclassof' class, and a TypeError will be raised if not. 80 """ 81 import importlib 82 83 splits = name.split('.') 84 modulename = '.'.join(splits[:-1]) 85 classname = splits[-1] 86 if modulename in sys.stdlib_module_names and check_sdlib_modulename_clash: 87 raise Exception(f'{modulename} is an inbuilt module.') 88 module = importlib.import_module(modulename) 89 cls: type = getattr(module, classname) 90 91 if not issubclass(cls, subclassof): 92 raise TypeError(f'{name} is not a subclass of {subclassof}.') 93 return cls
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.
152def handle_leftover_v1_cloud_log_file() -> None: 153 """Handle an un-uploaded v1-cloud-log from a previous run.""" 154 155 # Only applies with classic present. 156 if _babase.app.classic is None: 157 return 158 try: 159 import json 160 161 if os.path.exists(_babase.get_v1_cloud_log_file_path()): 162 with open( 163 _babase.get_v1_cloud_log_file_path(), encoding='utf-8' 164 ) as infile: 165 info = json.loads(infile.read()) 166 infile.close() 167 do_send = should_submit_debug_info() 168 if do_send: 169 170 def response(data: Any) -> None: 171 # Non-None response means we were successful; 172 # lets kill it. 173 if data is not None: 174 try: 175 os.remove(_babase.get_v1_cloud_log_file_path()) 176 except FileNotFoundError: 177 # Saw this in the wild. The file just existed 178 # a moment ago but I suppose something could have 179 # killed it since. ¯\_(ツ)_/¯ 180 pass 181 182 _babase.app.classic.master_server_v1_post( 183 'bsLog', info, response 184 ) 185 else: 186 # If they don't want logs uploaded just kill it. 187 os.remove(_babase.get_v1_cloud_log_file_path()) 188 except Exception: 189 from babase import _error 190 191 _error.print_exception('Error handling leftover log file.')
Handle an un-uploaded v1-cloud-log from a previous run.
103class InputDeviceNotFoundError(NotFoundError): 104 """Exception raised when an expected input-device does not exist. 105 106 Category: **Exception Classes** 107 """
Exception raised when an expected input-device does not exist.
Category: Exception Classes
Inherited Members
- builtins.Exception
- Exception
- builtins.BaseException
- with_traceback
- add_note
- args
8class InputType(Enum): 9 """Types of input a controller can send to the game. 10 11 Category: Enums 12 13 """ 14 15 UP_DOWN = 2 16 LEFT_RIGHT = 3 17 JUMP_PRESS = 4 18 JUMP_RELEASE = 5 19 PUNCH_PRESS = 6 20 PUNCH_RELEASE = 7 21 BOMB_PRESS = 8 22 BOMB_RELEASE = 9 23 PICK_UP_PRESS = 10 24 PICK_UP_RELEASE = 11 25 RUN = 12 26 FLY_PRESS = 13 27 FLY_RELEASE = 14 28 START_PRESS = 15 29 START_RELEASE = 16 30 HOLD_POSITION_PRESS = 17 31 HOLD_POSITION_RELEASE = 18 32 LEFT_PRESS = 19 33 LEFT_RELEASE = 20 34 RIGHT_PRESS = 21 35 RIGHT_RELEASE = 22 36 UP_PRESS = 23 37 UP_RELEASE = 24 38 DOWN_PRESS = 25 39 DOWN_RELEASE = 26
Types of input a controller can send to the game.
Category: Enums
Inherited Members
- enum.Enum
- name
- value
27def is_browser_likely_available() -> bool: 28 """Return whether a browser likely exists on the current device. 29 30 category: General Utility Functions 31 32 If this returns False you may want to avoid calling babase.show_url() 33 with any lengthy addresses. (ba.show_url() will display an address 34 as a string in a window if unable to bring up a browser, but that 35 is only useful for simple URLs.) 36 """ 37 app = _babase.app 38 39 if app.classic is None: 40 logging.warning( 41 'is_browser_likely_available() needs to be updated' 42 ' to work without classic.' 43 ) 44 return True 45 46 platform = app.classic.platform 47 hastouchscreen = _babase.hastouchscreen() 48 49 # If we're on a vr device or an android device with no touchscreen, 50 # assume no browser. 51 # FIXME: Might not be the case anymore; should make this definable 52 # at the platform level. 53 if app.env.vr or (platform == 'android' and not hastouchscreen): 54 return False 55 56 # Anywhere else assume we've got one. 57 return True
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.show_url() with any lengthy addresses. (ba.show_url() will display an address as a string in a window if unable to bring up a browser, but that is only useful for simple URLs.)
38def is_point_in_box(pnt: Sequence[float], box: Sequence[float]) -> bool: 39 """Return whether a given point is within a given box. 40 41 category: General Utility Functions 42 43 For use with standard def boxes (position|rotate|scale). 44 """ 45 return ( 46 (abs(pnt[0] - box[0]) <= box[6] * 0.5) 47 and (abs(pnt[1] - box[1]) <= box[7] * 0.5) 48 and (abs(pnt[2] - box[2]) <= box[8] * 0.5) 49 )
Return whether a given point is within a given box.
category: General Utility Functions
For use with standard def boxes (position|rotate|scale).
22class LanguageSubsystem(AppSubsystem): 23 """Language functionality for the app. 24 25 Category: **App Classes** 26 27 Access the single instance of this class at 'babase.app.lang'. 28 """ 29 30 def __init__(self) -> None: 31 super().__init__() 32 self.default_language: str = self._get_default_language() 33 34 self._language: str | None = None 35 self._language_target: AttrDict | None = None 36 self._language_merged: AttrDict | None = None 37 self._test_timer: babase.AppTimer | None = None 38 39 @property 40 def locale(self) -> str: 41 """Raw country/language code detected by the game (such as 'en_US'). 42 43 Generally for language-specific code you should look at 44 babase.App.language, which is the language the game is using 45 (which may differ from locale if the user sets a language, etc.) 46 """ 47 env = _babase.env() 48 assert isinstance(env['locale'], str) 49 return env['locale'] 50 51 @property 52 def language(self) -> str: 53 """The current active language for the app. 54 55 This can be selected explicitly by the user or may be set 56 automatically based on locale or other factors. 57 """ 58 if self._language is None: 59 raise RuntimeError('App language is not yet set.') 60 return self._language 61 62 @property 63 def available_languages(self) -> list[str]: 64 """A list of all available languages. 65 66 Note that languages that may be present in game assets but which 67 are not displayable on the running version of the game are not 68 included here. 69 """ 70 langs = set() 71 try: 72 names = os.listdir( 73 os.path.join( 74 _babase.app.env.data_directory, 75 'ba_data', 76 'data', 77 'languages', 78 ) 79 ) 80 names = [n.replace('.json', '').capitalize() for n in names] 81 82 # FIXME: our simple capitalization fails on multi-word names; 83 # should handle this in a better way... 84 for i, name in enumerate(names): 85 if name == 'Chinesetraditional': 86 names[i] = 'ChineseTraditional' 87 except Exception: 88 from babase import _error 89 90 _error.print_exception() 91 names = [] 92 for name in names: 93 if self._can_display_language(name): 94 langs.add(name) 95 return sorted( 96 name for name in names if self._can_display_language(name) 97 ) 98 99 def testlanguage(self, langid: str) -> None: 100 """Set the app to test an in-progress language. 101 102 Pass a language id from the translation editor website as 'langid'; 103 something like 'Gibberish_3263'. Once set to testing, the engine 104 will repeatedly download and apply that same test language, so 105 changes can be made to it and observed live. 106 """ 107 print( 108 f'Language test mode enabled.' 109 f' Will fetch and apply \'{langid}\' every 5 seconds,' 110 f' so you can see your changes live.' 111 ) 112 self._test_timer = _babase.AppTimer( 113 5.0, partial(self._update_test_language, langid), repeat=True 114 ) 115 self._update_test_language(langid) 116 117 def _on_test_lang_response( 118 self, langid: str, response: None | dict[str, Any] 119 ) -> None: 120 if response is None: 121 return 122 self.setlanguage(response) 123 print(f'Fetched and applied {langid}.') 124 125 def _update_test_language(self, langid: str) -> None: 126 if _babase.app.classic is None: 127 raise RuntimeError('This requires classic.') 128 _babase.app.classic.master_server_v1_get( 129 'bsLangGet', 130 {'lang': langid, 'format': 'json'}, 131 partial(self._on_test_lang_response, langid), 132 ) 133 134 def setlanguage( 135 self, 136 language: str | dict | None, 137 print_change: bool = True, 138 store_to_config: bool = True, 139 ) -> None: 140 """Set the active app language. 141 142 Pass None to use OS default language. 143 """ 144 # pylint: disable=too-many-locals 145 # pylint: disable=too-many-statements 146 # pylint: disable=too-many-branches 147 assert _babase.in_logic_thread() 148 cfg = _babase.app.config 149 cur_language = cfg.get('Lang', None) 150 151 with open( 152 os.path.join( 153 _babase.app.env.data_directory, 154 'ba_data', 155 'data', 156 'languages', 157 'english.json', 158 ), 159 encoding='utf-8', 160 ) as infile: 161 lenglishvalues = json.loads(infile.read()) 162 163 # Special case - passing a complete dict for testing. 164 if isinstance(language, dict): 165 self._language = 'Custom' 166 lmodvalues = language 167 switched = False 168 print_change = False 169 store_to_config = False 170 else: 171 # Ok, we're setting a real language. 172 173 # Store this in the config if its changing. 174 if language != cur_language and store_to_config: 175 if language is None: 176 if 'Lang' in cfg: 177 del cfg['Lang'] # Clear it out for default. 178 else: 179 cfg['Lang'] = language 180 cfg.commit() 181 switched = True 182 else: 183 switched = False 184 185 # None implies default. 186 if language is None: 187 language = self.default_language 188 try: 189 if language == 'English': 190 lmodvalues = None 191 else: 192 lmodfile = os.path.join( 193 _babase.app.env.data_directory, 194 'ba_data', 195 'data', 196 'languages', 197 language.lower() + '.json', 198 ) 199 with open(lmodfile, encoding='utf-8') as infile: 200 lmodvalues = json.loads(infile.read()) 201 except Exception: 202 logging.exception("Error importing language '%s'.", language) 203 _babase.screenmessage( 204 f"Error setting language to '{language}';" 205 f' see log for details.', 206 color=(1, 0, 0), 207 ) 208 switched = False 209 lmodvalues = None 210 211 self._language = language 212 213 # Create an attrdict of *just* our target language. 214 self._language_target = AttrDict() 215 langtarget = self._language_target 216 assert langtarget is not None 217 _add_to_attr_dict( 218 langtarget, lmodvalues if lmodvalues is not None else lenglishvalues 219 ) 220 221 # Create an attrdict of our target language overlaid on our base 222 # (english). 223 languages = [lenglishvalues] 224 if lmodvalues is not None: 225 languages.append(lmodvalues) 226 lfull = AttrDict() 227 for lmod in languages: 228 _add_to_attr_dict(lfull, lmod) 229 self._language_merged = lfull 230 231 # Pass some keys/values in for low level code to use; start with 232 # everything in their 'internal' section. 233 internal_vals = [ 234 v for v in list(lfull['internal'].items()) if isinstance(v[1], str) 235 ] 236 237 # Cherry-pick various other values to include. 238 # (should probably get rid of the 'internal' section 239 # and do everything this way) 240 for value in [ 241 'replayNameDefaultText', 242 'replayWriteErrorText', 243 'replayVersionErrorText', 244 'replayReadErrorText', 245 ]: 246 internal_vals.append((value, lfull[value])) 247 internal_vals.append( 248 ('axisText', lfull['configGamepadWindow']['axisText']) 249 ) 250 internal_vals.append(('buttonText', lfull['buttonText'])) 251 lmerged = self._language_merged 252 assert lmerged is not None 253 random_names = [ 254 n.strip() for n in lmerged['randomPlayerNamesText'].split(',') 255 ] 256 random_names = [n for n in random_names if n != ''] 257 _babase.set_internal_language_keys(internal_vals, random_names) 258 if switched and print_change: 259 assert isinstance(language, str) 260 _babase.screenmessage( 261 Lstr( 262 resource='languageSetText', 263 subs=[ 264 ('${LANGUAGE}', Lstr(translate=('languages', language))) 265 ], 266 ), 267 color=(0, 1, 0), 268 ) 269 270 @override 271 def do_apply_app_config(self) -> None: 272 assert _babase.in_logic_thread() 273 assert isinstance(_babase.app.config, dict) 274 lang = _babase.app.config.get('Lang', self.default_language) 275 if lang != self._language: 276 self.setlanguage(lang, print_change=False, store_to_config=False) 277 278 def get_resource( 279 self, 280 resource: str, 281 fallback_resource: str | None = None, 282 fallback_value: Any = None, 283 ) -> Any: 284 """Return a translation resource by name. 285 286 DEPRECATED; use babase.Lstr functionality for these purposes. 287 """ 288 try: 289 # If we have no language set, try and set it to english. 290 # Also make a fuss because we should try to avoid this. 291 if self._language_merged is None: 292 try: 293 if _babase.do_once(): 294 logging.warning( 295 'get_resource() called before language' 296 ' set; falling back to english.' 297 ) 298 self.setlanguage( 299 'English', print_change=False, store_to_config=False 300 ) 301 except Exception: 302 logging.exception( 303 'Error setting fallback english language.' 304 ) 305 raise 306 307 # If they provided a fallback_resource value, try the 308 # target-language-only dict first and then fall back to 309 # trying the fallback_resource value in the merged dict. 310 if fallback_resource is not None: 311 try: 312 values = self._language_target 313 splits = resource.split('.') 314 dicts = splits[:-1] 315 key = splits[-1] 316 for dct in dicts: 317 assert values is not None 318 values = values[dct] 319 assert values is not None 320 val = values[key] 321 return val 322 except Exception: 323 # FIXME: Shouldn't we try the fallback resource in 324 # the merged dict AFTER we try the main resource in 325 # the merged dict? 326 try: 327 values = self._language_merged 328 splits = fallback_resource.split('.') 329 dicts = splits[:-1] 330 key = splits[-1] 331 for dct in dicts: 332 assert values is not None 333 values = values[dct] 334 assert values is not None 335 val = values[key] 336 return val 337 338 except Exception: 339 # If we got nothing for fallback_resource, 340 # default to the normal code which checks or 341 # primary value in the merge dict; there's a 342 # chance we can get an english value for it 343 # (which we weren't looking for the first time 344 # through). 345 pass 346 347 values = self._language_merged 348 splits = resource.split('.') 349 dicts = splits[:-1] 350 key = splits[-1] 351 for dct in dicts: 352 assert values is not None 353 values = values[dct] 354 assert values is not None 355 val = values[key] 356 return val 357 358 except Exception: 359 # Ok, looks like we couldn't find our main or fallback 360 # resource anywhere. Now if we've been given a fallback 361 # value, return it; otherwise fail. 362 from babase import _error 363 364 if fallback_value is not None: 365 return fallback_value 366 raise _error.NotFoundError( 367 f"Resource not found: '{resource}'" 368 ) from None 369 370 def translate( 371 self, 372 category: str, 373 strval: str, 374 raise_exceptions: bool = False, 375 print_errors: bool = False, 376 ) -> str: 377 """Translate a value (or return the value if no translation available) 378 379 DEPRECATED; use babase.Lstr functionality for these purposes. 380 """ 381 try: 382 translated = self.get_resource('translations')[category][strval] 383 except Exception as exc: 384 if raise_exceptions: 385 raise 386 if print_errors: 387 print( 388 ( 389 'Translate error: category=\'' 390 + category 391 + '\' name=\'' 392 + strval 393 + '\' exc=' 394 + str(exc) 395 + '' 396 ) 397 ) 398 translated = None 399 translated_out: str 400 if translated is None: 401 translated_out = strval 402 else: 403 translated_out = translated 404 assert isinstance(translated_out, str) 405 return translated_out 406 407 def is_custom_unicode_char(self, char: str) -> bool: 408 """Return whether a char is in the custom unicode range we use.""" 409 assert isinstance(char, str) 410 if len(char) != 1: 411 raise ValueError('Invalid Input; must be length 1') 412 return 0xE000 <= ord(char) <= 0xF8FF 413 414 def _can_display_language(self, language: str) -> bool: 415 """Tell whether we can display a particular language. 416 417 On some platforms we don't have unicode rendering yet which 418 limits the languages we can draw. 419 """ 420 421 # We don't yet support full unicode display on windows or linux :-(. 422 if ( 423 language 424 in { 425 'Chinese', 426 'ChineseTraditional', 427 'Persian', 428 'Korean', 429 'Arabic', 430 'Hindi', 431 'Vietnamese', 432 'Thai', 433 'Tamil', 434 } 435 and not _babase.can_display_full_unicode() 436 ): 437 return False 438 return True 439 440 def _get_default_language(self) -> str: 441 languages = { 442 'ar': 'Arabic', 443 'be': 'Belarussian', 444 'zh': 'Chinese', 445 'hr': 'Croatian', 446 'cs': 'Czech', 447 'da': 'Danish', 448 'nl': 'Dutch', 449 'eo': 'Esperanto', 450 'fil': 'Filipino', 451 'fr': 'French', 452 'de': 'German', 453 'el': 'Greek', 454 'hi': 'Hindi', 455 'hu': 'Hungarian', 456 'id': 'Indonesian', 457 'it': 'Italian', 458 'ko': 'Korean', 459 'ms': 'Malay', 460 'fa': 'Persian', 461 'pl': 'Polish', 462 'pt': 'Portuguese', 463 'ro': 'Romanian', 464 'ru': 'Russian', 465 'sr': 'Serbian', 466 'es': 'Spanish', 467 'sk': 'Slovak', 468 'sv': 'Swedish', 469 'ta': 'Tamil', 470 'th': 'Thai', 471 'tr': 'Turkish', 472 'uk': 'Ukrainian', 473 'vec': 'Venetian', 474 'vi': 'Vietnamese', 475 } 476 477 # Special case for Chinese: map specific variations to 478 # traditional. (otherwise will map to 'Chinese' which is 479 # simplified) 480 if self.locale in ('zh_HANT', 'zh_TW'): 481 language = 'ChineseTraditional' 482 else: 483 language = languages.get(self.locale[:2], 'English') 484 if not self._can_display_language(language): 485 language = 'English' 486 return language
Language functionality for the app.
Category: App Classes
Access the single instance of this class at 'babase.app.lang'.
39 @property 40 def locale(self) -> str: 41 """Raw country/language code detected by the game (such as 'en_US'). 42 43 Generally for language-specific code you should look at 44 babase.App.language, which is the language the game is using 45 (which may differ from locale if the user sets a language, etc.) 46 """ 47 env = _babase.env() 48 assert isinstance(env['locale'], str) 49 return env['locale']
Raw country/language code detected by the game (such as 'en_US').
Generally for language-specific code you should look at babase.App.language, which is the language the game is using (which may differ from locale if the user sets a language, etc.)
51 @property 52 def language(self) -> str: 53 """The current active language for the app. 54 55 This can be selected explicitly by the user or may be set 56 automatically based on locale or other factors. 57 """ 58 if self._language is None: 59 raise RuntimeError('App language is not yet set.') 60 return self._language
The current active language for the app.
This can be selected explicitly by the user or may be set automatically based on locale or other factors.
62 @property 63 def available_languages(self) -> list[str]: 64 """A list of all available languages. 65 66 Note that languages that may be present in game assets but which 67 are not displayable on the running version of the game are not 68 included here. 69 """ 70 langs = set() 71 try: 72 names = os.listdir( 73 os.path.join( 74 _babase.app.env.data_directory, 75 'ba_data', 76 'data', 77 'languages', 78 ) 79 ) 80 names = [n.replace('.json', '').capitalize() for n in names] 81 82 # FIXME: our simple capitalization fails on multi-word names; 83 # should handle this in a better way... 84 for i, name in enumerate(names): 85 if name == 'Chinesetraditional': 86 names[i] = 'ChineseTraditional' 87 except Exception: 88 from babase import _error 89 90 _error.print_exception() 91 names = [] 92 for name in names: 93 if self._can_display_language(name): 94 langs.add(name) 95 return sorted( 96 name for name in names if self._can_display_language(name) 97 )
A list of all available languages.
Note that languages that may be present in game assets but which are not displayable on the running version of the game are not included here.
99 def testlanguage(self, langid: str) -> None: 100 """Set the app to test an in-progress language. 101 102 Pass a language id from the translation editor website as 'langid'; 103 something like 'Gibberish_3263'. Once set to testing, the engine 104 will repeatedly download and apply that same test language, so 105 changes can be made to it and observed live. 106 """ 107 print( 108 f'Language test mode enabled.' 109 f' Will fetch and apply \'{langid}\' every 5 seconds,' 110 f' so you can see your changes live.' 111 ) 112 self._test_timer = _babase.AppTimer( 113 5.0, partial(self._update_test_language, langid), repeat=True 114 ) 115 self._update_test_language(langid)
Set the app to test an in-progress language.
Pass a language id from the translation editor website as 'langid'; something like 'Gibberish_3263'. Once set to testing, the engine will repeatedly download and apply that same test language, so changes can be made to it and observed live.
134 def setlanguage( 135 self, 136 language: str | dict | None, 137 print_change: bool = True, 138 store_to_config: bool = True, 139 ) -> None: 140 """Set the active app language. 141 142 Pass None to use OS default language. 143 """ 144 # pylint: disable=too-many-locals 145 # pylint: disable=too-many-statements 146 # pylint: disable=too-many-branches 147 assert _babase.in_logic_thread() 148 cfg = _babase.app.config 149 cur_language = cfg.get('Lang', None) 150 151 with open( 152 os.path.join( 153 _babase.app.env.data_directory, 154 'ba_data', 155 'data', 156 'languages', 157 'english.json', 158 ), 159 encoding='utf-8', 160 ) as infile: 161 lenglishvalues = json.loads(infile.read()) 162 163 # Special case - passing a complete dict for testing. 164 if isinstance(language, dict): 165 self._language = 'Custom' 166 lmodvalues = language 167 switched = False 168 print_change = False 169 store_to_config = False 170 else: 171 # Ok, we're setting a real language. 172 173 # Store this in the config if its changing. 174 if language != cur_language and store_to_config: 175 if language is None: 176 if 'Lang' in cfg: 177 del cfg['Lang'] # Clear it out for default. 178 else: 179 cfg['Lang'] = language 180 cfg.commit() 181 switched = True 182 else: 183 switched = False 184 185 # None implies default. 186 if language is None: 187 language = self.default_language 188 try: 189 if language == 'English': 190 lmodvalues = None 191 else: 192 lmodfile = os.path.join( 193 _babase.app.env.data_directory, 194 'ba_data', 195 'data', 196 'languages', 197 language.lower() + '.json', 198 ) 199 with open(lmodfile, encoding='utf-8') as infile: 200 lmodvalues = json.loads(infile.read()) 201 except Exception: 202 logging.exception("Error importing language '%s'.", language) 203 _babase.screenmessage( 204 f"Error setting language to '{language}';" 205 f' see log for details.', 206 color=(1, 0, 0), 207 ) 208 switched = False 209 lmodvalues = None 210 211 self._language = language 212 213 # Create an attrdict of *just* our target language. 214 self._language_target = AttrDict() 215 langtarget = self._language_target 216 assert langtarget is not None 217 _add_to_attr_dict( 218 langtarget, lmodvalues if lmodvalues is not None else lenglishvalues 219 ) 220 221 # Create an attrdict of our target language overlaid on our base 222 # (english). 223 languages = [lenglishvalues] 224 if lmodvalues is not None: 225 languages.append(lmodvalues) 226 lfull = AttrDict() 227 for lmod in languages: 228 _add_to_attr_dict(lfull, lmod) 229 self._language_merged = lfull 230 231 # Pass some keys/values in for low level code to use; start with 232 # everything in their 'internal' section. 233 internal_vals = [ 234 v for v in list(lfull['internal'].items()) if isinstance(v[1], str) 235 ] 236 237 # Cherry-pick various other values to include. 238 # (should probably get rid of the 'internal' section 239 # and do everything this way) 240 for value in [ 241 'replayNameDefaultText', 242 'replayWriteErrorText', 243 'replayVersionErrorText', 244 'replayReadErrorText', 245 ]: 246 internal_vals.append((value, lfull[value])) 247 internal_vals.append( 248 ('axisText', lfull['configGamepadWindow']['axisText']) 249 ) 250 internal_vals.append(('buttonText', lfull['buttonText'])) 251 lmerged = self._language_merged 252 assert lmerged is not None 253 random_names = [ 254 n.strip() for n in lmerged['randomPlayerNamesText'].split(',') 255 ] 256 random_names = [n for n in random_names if n != ''] 257 _babase.set_internal_language_keys(internal_vals, random_names) 258 if switched and print_change: 259 assert isinstance(language, str) 260 _babase.screenmessage( 261 Lstr( 262 resource='languageSetText', 263 subs=[ 264 ('${LANGUAGE}', Lstr(translate=('languages', language))) 265 ], 266 ), 267 color=(0, 1, 0), 268 )
Set the active app language.
Pass None to use OS default language.
270 @override 271 def do_apply_app_config(self) -> None: 272 assert _babase.in_logic_thread() 273 assert isinstance(_babase.app.config, dict) 274 lang = _babase.app.config.get('Lang', self.default_language) 275 if lang != self._language: 276 self.setlanguage(lang, print_change=False, store_to_config=False)
Called when the app config should be applied.
278 def get_resource( 279 self, 280 resource: str, 281 fallback_resource: str | None = None, 282 fallback_value: Any = None, 283 ) -> Any: 284 """Return a translation resource by name. 285 286 DEPRECATED; use babase.Lstr functionality for these purposes. 287 """ 288 try: 289 # If we have no language set, try and set it to english. 290 # Also make a fuss because we should try to avoid this. 291 if self._language_merged is None: 292 try: 293 if _babase.do_once(): 294 logging.warning( 295 'get_resource() called before language' 296 ' set; falling back to english.' 297 ) 298 self.setlanguage( 299 'English', print_change=False, store_to_config=False 300 ) 301 except Exception: 302 logging.exception( 303 'Error setting fallback english language.' 304 ) 305 raise 306 307 # If they provided a fallback_resource value, try the 308 # target-language-only dict first and then fall back to 309 # trying the fallback_resource value in the merged dict. 310 if fallback_resource is not None: 311 try: 312 values = self._language_target 313 splits = resource.split('.') 314 dicts = splits[:-1] 315 key = splits[-1] 316 for dct in dicts: 317 assert values is not None 318 values = values[dct] 319 assert values is not None 320 val = values[key] 321 return val 322 except Exception: 323 # FIXME: Shouldn't we try the fallback resource in 324 # the merged dict AFTER we try the main resource in 325 # the merged dict? 326 try: 327 values = self._language_merged 328 splits = fallback_resource.split('.') 329 dicts = splits[:-1] 330 key = splits[-1] 331 for dct in dicts: 332 assert values is not None 333 values = values[dct] 334 assert values is not None 335 val = values[key] 336 return val 337 338 except Exception: 339 # If we got nothing for fallback_resource, 340 # default to the normal code which checks or 341 # primary value in the merge dict; there's a 342 # chance we can get an english value for it 343 # (which we weren't looking for the first time 344 # through). 345 pass 346 347 values = self._language_merged 348 splits = resource.split('.') 349 dicts = splits[:-1] 350 key = splits[-1] 351 for dct in dicts: 352 assert values is not None 353 values = values[dct] 354 assert values is not None 355 val = values[key] 356 return val 357 358 except Exception: 359 # Ok, looks like we couldn't find our main or fallback 360 # resource anywhere. Now if we've been given a fallback 361 # value, return it; otherwise fail. 362 from babase import _error 363 364 if fallback_value is not None: 365 return fallback_value 366 raise _error.NotFoundError( 367 f"Resource not found: '{resource}'" 368 ) from None
Return a translation resource by name.
DEPRECATED; use Lstr functionality for these purposes.
370 def translate( 371 self, 372 category: str, 373 strval: str, 374 raise_exceptions: bool = False, 375 print_errors: bool = False, 376 ) -> str: 377 """Translate a value (or return the value if no translation available) 378 379 DEPRECATED; use babase.Lstr functionality for these purposes. 380 """ 381 try: 382 translated = self.get_resource('translations')[category][strval] 383 except Exception as exc: 384 if raise_exceptions: 385 raise 386 if print_errors: 387 print( 388 ( 389 'Translate error: category=\'' 390 + category 391 + '\' name=\'' 392 + strval 393 + '\' exc=' 394 + str(exc) 395 + '' 396 ) 397 ) 398 translated = None 399 translated_out: str 400 if translated is None: 401 translated_out = strval 402 else: 403 translated_out = translated 404 assert isinstance(translated_out, str) 405 return translated_out
Translate a value (or return the value if no translation available)
DEPRECATED; use Lstr functionality for these purposes.
407 def is_custom_unicode_char(self, char: str) -> bool: 408 """Return whether a char is in the custom unicode range we use.""" 409 assert isinstance(char, str) 410 if len(char) != 1: 411 raise ValueError('Invalid Input; must be length 1') 412 return 0xE000 <= ord(char) <= 0xF8FF
Return whether a char is in the custom unicode range we use.
32class LoginAdapter: 33 """Allows using implicit login types in an explicit way. 34 35 Some login types such as Google Play Game Services or Game Center are 36 basically always present and often do not provide a way to log out 37 from within a running app, so this adapter exists to use them in a 38 flexible manner by 'attaching' and 'detaching' from an always-present 39 login, allowing for its use alongside other login types. It also 40 provides common functionality for server-side account verification and 41 other handy bits. 42 """ 43 44 @dataclass 45 class SignInResult: 46 """Describes the final result of a sign-in attempt.""" 47 48 credentials: str 49 50 @dataclass 51 class ImplicitLoginState: 52 """Describes the current state of an implicit login.""" 53 54 login_id: str 55 display_name: str 56 57 def __init__(self, login_type: LoginType): 58 assert _babase.in_logic_thread() 59 self.login_type = login_type 60 self._implicit_login_state: LoginAdapter.ImplicitLoginState | None = ( 61 None 62 ) 63 self._on_app_loading_called = False 64 self._implicit_login_state_dirty = False 65 self._back_end_active = False 66 67 # Which login of our type (if any) is associated with the 68 # current active primary account. 69 self._active_login_id: str | None = None 70 71 self._last_sign_in_time: float | None = None 72 self._last_sign_in_desc: str | None = None 73 74 def on_app_loading(self) -> None: 75 """Should be called for each adapter in on_app_loading.""" 76 77 assert not self._on_app_loading_called 78 self._on_app_loading_called = True 79 80 # Any implicit state we received up until now needs to be pushed 81 # to the app account subsystem. 82 self._update_implicit_login_state() 83 84 def set_implicit_login_state( 85 self, state: ImplicitLoginState | None 86 ) -> None: 87 """Keep the adapter informed of implicit login states. 88 89 This should be called by the adapter back-end when an account 90 of their associated type gets logged in or out. 91 """ 92 assert _babase.in_logic_thread() 93 94 # Ignore redundant sets. 95 if state == self._implicit_login_state: 96 return 97 98 if DEBUG_LOG: 99 if state is None: 100 logging.debug( 101 'LoginAdapter: %s implicit state changed;' 102 ' now signed out.', 103 self.login_type.name, 104 ) 105 else: 106 logging.debug( 107 'LoginAdapter: %s implicit state changed;' 108 ' now signed in as %s.', 109 self.login_type.name, 110 state.display_name, 111 ) 112 113 self._implicit_login_state = state 114 self._implicit_login_state_dirty = True 115 116 # (possibly) push it to the app for handling. 117 self._update_implicit_login_state() 118 119 # This might affect whether we consider that back-end as 'active'. 120 self._update_back_end_active() 121 122 def set_active_logins(self, logins: dict[LoginType, str]) -> None: 123 """Keep the adapter informed of actively used logins. 124 125 This should be called by the app's account subsystem to 126 keep adapters up to date on the full set of logins attached 127 to the currently-in-use account. 128 Note that the logins dict passed in should be immutable as 129 only a reference to it is stored, not a copy. 130 """ 131 assert _babase.in_logic_thread() 132 if DEBUG_LOG: 133 logging.debug( 134 'LoginAdapter: %s adapter got active logins %s.', 135 self.login_type.name, 136 {k: v[:4] + '...' + v[-4:] for k, v in logins.items()}, 137 ) 138 139 self._active_login_id = logins.get(self.login_type) 140 self._update_back_end_active() 141 142 def on_back_end_active_change(self, active: bool) -> None: 143 """Called when active state for the back-end is (possibly) changing. 144 145 Meant to be overridden by subclasses. 146 Being active means that the implicit login provided by the back-end 147 is actually being used by the app. It should therefore register 148 unlocked achievements, leaderboard scores, allow viewing native 149 UIs, etc. When not active it should ignore everything and behave 150 as if signed out, even if it technically is still signed in. 151 """ 152 assert _babase.in_logic_thread() 153 del active # Unused. 154 155 @final 156 def sign_in( 157 self, 158 result_cb: Callable[[LoginAdapter, SignInResult | Exception], None], 159 description: str, 160 ) -> None: 161 """Attempt to sign in via this adapter. 162 163 This can be called even if the back-end is not implicitly signed in; 164 the adapter will attempt to sign in if possible. An exception will 165 be returned if the sign-in attempt fails. 166 """ 167 168 assert _babase.in_logic_thread() 169 170 # Have been seeing multiple sign-in attempts come through 171 # nearly simultaneously which can be problematic server-side. 172 # Let's error if a sign-in attempt is made within a few seconds 173 # of the last one to try and address this. 174 now = time.monotonic() 175 appnow = _babase.apptime() 176 if self._last_sign_in_time is not None: 177 since_last = now - self._last_sign_in_time 178 if since_last < 1.0: 179 logging.warning( 180 'LoginAdapter: %s adapter sign_in() called too soon' 181 ' (%.2fs) after last; this-desc="%s", last-desc="%s",' 182 ' ba-app-time=%.2f.', 183 self.login_type.name, 184 since_last, 185 description, 186 self._last_sign_in_desc, 187 appnow, 188 ) 189 _babase.pushcall( 190 partial( 191 result_cb, 192 self, 193 RuntimeError('sign_in called too soon after last.'), 194 ) 195 ) 196 return 197 198 self._last_sign_in_desc = description 199 self._last_sign_in_time = now 200 201 if DEBUG_LOG: 202 logging.debug( 203 'LoginAdapter: %s adapter sign_in() called;' 204 ' fetching sign-in-token...', 205 self.login_type.name, 206 ) 207 208 def _got_sign_in_token_result(result: str | None) -> None: 209 import bacommon.cloud 210 211 # Failed to get a sign-in-token. 212 if result is None: 213 if DEBUG_LOG: 214 logging.debug( 215 'LoginAdapter: %s adapter sign-in-token fetch failed;' 216 ' aborting sign-in.', 217 self.login_type.name, 218 ) 219 _babase.pushcall( 220 partial( 221 result_cb, 222 self, 223 RuntimeError('fetch-sign-in-token failed.'), 224 ) 225 ) 226 return 227 228 # Got a sign-in token! Now pass it to the cloud which will use 229 # it to verify our identity and give us app credentials on 230 # success. 231 if DEBUG_LOG: 232 logging.debug( 233 'LoginAdapter: %s adapter sign-in-token fetch succeeded;' 234 ' passing to cloud for verification...', 235 self.login_type.name, 236 ) 237 238 def _got_sign_in_response( 239 response: bacommon.cloud.SignInResponse | Exception, 240 ) -> None: 241 # This likely means we couldn't communicate with the server. 242 if isinstance(response, Exception): 243 if DEBUG_LOG: 244 logging.debug( 245 'LoginAdapter: %s adapter got error' 246 ' sign-in response: %s', 247 self.login_type.name, 248 response, 249 ) 250 _babase.pushcall(partial(result_cb, self, response)) 251 else: 252 # This means our credentials were explicitly rejected. 253 if response.credentials is None: 254 result2: LoginAdapter.SignInResult | Exception = ( 255 RuntimeError('Sign-in-token was rejected.') 256 ) 257 else: 258 if DEBUG_LOG: 259 logging.debug( 260 'LoginAdapter: %s adapter got successful' 261 ' sign-in response', 262 self.login_type.name, 263 ) 264 result2 = self.SignInResult( 265 credentials=response.credentials 266 ) 267 _babase.pushcall(partial(result_cb, self, result2)) 268 269 assert _babase.app.plus is not None 270 _babase.app.plus.cloud.send_message_cb( 271 bacommon.cloud.SignInMessage( 272 self.login_type, 273 result, 274 description=description, 275 apptime=appnow, 276 ), 277 on_response=_got_sign_in_response, 278 ) 279 280 # Kick off the sign-in process by fetching a sign-in token. 281 self.get_sign_in_token(completion_cb=_got_sign_in_token_result) 282 283 def is_back_end_active(self) -> bool: 284 """Is this adapter's back-end currently active?""" 285 return self._back_end_active 286 287 def get_sign_in_token( 288 self, completion_cb: Callable[[str | None], None] 289 ) -> None: 290 """Get a sign-in token from the adapter back end. 291 292 This token is then passed to the master-server to complete the 293 sign-in process. The adapter can use this opportunity to bring 294 up account creation UI, call its internal sign_in function, etc. 295 as needed. The provided completion_cb should then be called with 296 either a token or None if sign in failed or was cancelled. 297 """ 298 299 # Default implementation simply fails immediately. 300 _babase.pushcall(partial(completion_cb, None)) 301 302 def _update_implicit_login_state(self) -> None: 303 # If we've received an implicit login state, schedule it to be 304 # sent along to the app. We wait until on-app-loading has been 305 # called so that account-client-v2 has had a chance to load 306 # any existing state so it can properly respond to this. 307 if self._implicit_login_state_dirty and self._on_app_loading_called: 308 309 if DEBUG_LOG: 310 logging.debug( 311 'LoginAdapter: %s adapter sending' 312 ' implicit-state-changed to app.', 313 self.login_type.name, 314 ) 315 316 assert _babase.app.plus is not None 317 _babase.pushcall( 318 partial( 319 _babase.app.plus.accounts.on_implicit_login_state_changed, 320 self.login_type, 321 self._implicit_login_state, 322 ) 323 ) 324 self._implicit_login_state_dirty = False 325 326 def _update_back_end_active(self) -> None: 327 was_active = self._back_end_active 328 if self._implicit_login_state is None: 329 is_active = False 330 else: 331 is_active = ( 332 self._implicit_login_state.login_id == self._active_login_id 333 ) 334 if was_active != is_active: 335 if DEBUG_LOG: 336 logging.debug( 337 'LoginAdapter: %s adapter back-end-active is now %s.', 338 self.login_type.name, 339 is_active, 340 ) 341 self.on_back_end_active_change(is_active) 342 self._back_end_active = is_active
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.
57 def __init__(self, login_type: LoginType): 58 assert _babase.in_logic_thread() 59 self.login_type = login_type 60 self._implicit_login_state: LoginAdapter.ImplicitLoginState | None = ( 61 None 62 ) 63 self._on_app_loading_called = False 64 self._implicit_login_state_dirty = False 65 self._back_end_active = False 66 67 # Which login of our type (if any) is associated with the 68 # current active primary account. 69 self._active_login_id: str | None = None 70 71 self._last_sign_in_time: float | None = None 72 self._last_sign_in_desc: str | None = None
74 def on_app_loading(self) -> None: 75 """Should be called for each adapter in on_app_loading.""" 76 77 assert not self._on_app_loading_called 78 self._on_app_loading_called = True 79 80 # Any implicit state we received up until now needs to be pushed 81 # to the app account subsystem. 82 self._update_implicit_login_state()
Should be called for each adapter in on_app_loading.
84 def set_implicit_login_state( 85 self, state: ImplicitLoginState | None 86 ) -> None: 87 """Keep the adapter informed of implicit login states. 88 89 This should be called by the adapter back-end when an account 90 of their associated type gets logged in or out. 91 """ 92 assert _babase.in_logic_thread() 93 94 # Ignore redundant sets. 95 if state == self._implicit_login_state: 96 return 97 98 if DEBUG_LOG: 99 if state is None: 100 logging.debug( 101 'LoginAdapter: %s implicit state changed;' 102 ' now signed out.', 103 self.login_type.name, 104 ) 105 else: 106 logging.debug( 107 'LoginAdapter: %s implicit state changed;' 108 ' now signed in as %s.', 109 self.login_type.name, 110 state.display_name, 111 ) 112 113 self._implicit_login_state = state 114 self._implicit_login_state_dirty = True 115 116 # (possibly) push it to the app for handling. 117 self._update_implicit_login_state() 118 119 # This might affect whether we consider that back-end as 'active'. 120 self._update_back_end_active()
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.
122 def set_active_logins(self, logins: dict[LoginType, str]) -> None: 123 """Keep the adapter informed of actively used logins. 124 125 This should be called by the app's account subsystem to 126 keep adapters up to date on the full set of logins attached 127 to the currently-in-use account. 128 Note that the logins dict passed in should be immutable as 129 only a reference to it is stored, not a copy. 130 """ 131 assert _babase.in_logic_thread() 132 if DEBUG_LOG: 133 logging.debug( 134 'LoginAdapter: %s adapter got active logins %s.', 135 self.login_type.name, 136 {k: v[:4] + '...' + v[-4:] for k, v in logins.items()}, 137 ) 138 139 self._active_login_id = logins.get(self.login_type) 140 self._update_back_end_active()
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.
142 def on_back_end_active_change(self, active: bool) -> None: 143 """Called when active state for the back-end is (possibly) changing. 144 145 Meant to be overridden by subclasses. 146 Being active means that the implicit login provided by the back-end 147 is actually being used by the app. It should therefore register 148 unlocked achievements, leaderboard scores, allow viewing native 149 UIs, etc. When not active it should ignore everything and behave 150 as if signed out, even if it technically is still signed in. 151 """ 152 assert _babase.in_logic_thread() 153 del active # Unused.
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.
155 @final 156 def sign_in( 157 self, 158 result_cb: Callable[[LoginAdapter, SignInResult | Exception], None], 159 description: str, 160 ) -> None: 161 """Attempt to sign in via this adapter. 162 163 This can be called even if the back-end is not implicitly signed in; 164 the adapter will attempt to sign in if possible. An exception will 165 be returned if the sign-in attempt fails. 166 """ 167 168 assert _babase.in_logic_thread() 169 170 # Have been seeing multiple sign-in attempts come through 171 # nearly simultaneously which can be problematic server-side. 172 # Let's error if a sign-in attempt is made within a few seconds 173 # of the last one to try and address this. 174 now = time.monotonic() 175 appnow = _babase.apptime() 176 if self._last_sign_in_time is not None: 177 since_last = now - self._last_sign_in_time 178 if since_last < 1.0: 179 logging.warning( 180 'LoginAdapter: %s adapter sign_in() called too soon' 181 ' (%.2fs) after last; this-desc="%s", last-desc="%s",' 182 ' ba-app-time=%.2f.', 183 self.login_type.name, 184 since_last, 185 description, 186 self._last_sign_in_desc, 187 appnow, 188 ) 189 _babase.pushcall( 190 partial( 191 result_cb, 192 self, 193 RuntimeError('sign_in called too soon after last.'), 194 ) 195 ) 196 return 197 198 self._last_sign_in_desc = description 199 self._last_sign_in_time = now 200 201 if DEBUG_LOG: 202 logging.debug( 203 'LoginAdapter: %s adapter sign_in() called;' 204 ' fetching sign-in-token...', 205 self.login_type.name, 206 ) 207 208 def _got_sign_in_token_result(result: str | None) -> None: 209 import bacommon.cloud 210 211 # Failed to get a sign-in-token. 212 if result is None: 213 if DEBUG_LOG: 214 logging.debug( 215 'LoginAdapter: %s adapter sign-in-token fetch failed;' 216 ' aborting sign-in.', 217 self.login_type.name, 218 ) 219 _babase.pushcall( 220 partial( 221 result_cb, 222 self, 223 RuntimeError('fetch-sign-in-token failed.'), 224 ) 225 ) 226 return 227 228 # Got a sign-in token! Now pass it to the cloud which will use 229 # it to verify our identity and give us app credentials on 230 # success. 231 if DEBUG_LOG: 232 logging.debug( 233 'LoginAdapter: %s adapter sign-in-token fetch succeeded;' 234 ' passing to cloud for verification...', 235 self.login_type.name, 236 ) 237 238 def _got_sign_in_response( 239 response: bacommon.cloud.SignInResponse | Exception, 240 ) -> None: 241 # This likely means we couldn't communicate with the server. 242 if isinstance(response, Exception): 243 if DEBUG_LOG: 244 logging.debug( 245 'LoginAdapter: %s adapter got error' 246 ' sign-in response: %s', 247 self.login_type.name, 248 response, 249 ) 250 _babase.pushcall(partial(result_cb, self, response)) 251 else: 252 # This means our credentials were explicitly rejected. 253 if response.credentials is None: 254 result2: LoginAdapter.SignInResult | Exception = ( 255 RuntimeError('Sign-in-token was rejected.') 256 ) 257 else: 258 if DEBUG_LOG: 259 logging.debug( 260 'LoginAdapter: %s adapter got successful' 261 ' sign-in response', 262 self.login_type.name, 263 ) 264 result2 = self.SignInResult( 265 credentials=response.credentials 266 ) 267 _babase.pushcall(partial(result_cb, self, result2)) 268 269 assert _babase.app.plus is not None 270 _babase.app.plus.cloud.send_message_cb( 271 bacommon.cloud.SignInMessage( 272 self.login_type, 273 result, 274 description=description, 275 apptime=appnow, 276 ), 277 on_response=_got_sign_in_response, 278 ) 279 280 # Kick off the sign-in process by fetching a sign-in token. 281 self.get_sign_in_token(completion_cb=_got_sign_in_token_result)
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.
283 def is_back_end_active(self) -> bool: 284 """Is this adapter's back-end currently active?""" 285 return self._back_end_active
Is this adapter's back-end currently active?
287 def get_sign_in_token( 288 self, completion_cb: Callable[[str | None], None] 289 ) -> None: 290 """Get a sign-in token from the adapter back end. 291 292 This token is then passed to the master-server to complete the 293 sign-in process. The adapter can use this opportunity to bring 294 up account creation UI, call its internal sign_in function, etc. 295 as needed. The provided completion_cb should then be called with 296 either a token or None if sign in failed or was cancelled. 297 """ 298 299 # Default implementation simply fails immediately. 300 _babase.pushcall(partial(completion_cb, None))
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.
44 @dataclass 45 class SignInResult: 46 """Describes the final result of a sign-in attempt.""" 47 48 credentials: str
Describes the final result of a sign-in attempt.
50 @dataclass 51 class ImplicitLoginState: 52 """Describes the current state of an implicit login.""" 53 54 login_id: str 55 display_name: str
Describes the current state of an implicit login.
25@dataclass 26class LoginInfo: 27 """Basic info about a login available in the app.plus.accounts section.""" 28 29 name: str
Basic info about a login available in the app.plus.accounts section.
489class Lstr: 490 """Used to define strings in a language-independent way. 491 492 Category: **General Utility Classes** 493 494 These should be used whenever possible in place of hard-coded 495 strings so that in-game or UI elements show up correctly on all 496 clients in their currently-active language. 497 498 To see available resource keys, look at any of the bs_language_*.py 499 files in the game or the translations pages at 500 legacy.ballistica.net/translate. 501 502 ##### Examples 503 EXAMPLE 1: specify a string from a resource path 504 >>> mynode.text = babase.Lstr(resource='audioSettingsWindow.titleText') 505 506 EXAMPLE 2: specify a translated string via a category and english 507 value; if a translated value is available, it will be used; otherwise 508 the english value will be. To see available translation categories, 509 look under the 'translations' resource section. 510 >>> mynode.text = babase.Lstr(translate=('gameDescriptions', 511 ... 'Defeat all enemies')) 512 513 EXAMPLE 3: specify a raw value and some substitutions. Substitutions 514 can be used with resource and translate modes as well. 515 >>> mynode.text = babase.Lstr(value='${A} / ${B}', 516 ... subs=[('${A}', str(score)), ('${B}', str(total))]) 517 518 EXAMPLE 4: babase.Lstr's can be nested. This example would display the 519 resource at res_a but replace ${NAME} with the value of the 520 resource at res_b 521 >>> mytextnode.text = babase.Lstr( 522 ... resource='res_a', 523 ... subs=[('${NAME}', babase.Lstr(resource='res_b'))]) 524 """ 525 526 # pylint: disable=dangerous-default-value 527 # noinspection PyDefaultArgument 528 @overload 529 def __init__( 530 self, 531 *, 532 resource: str, 533 fallback_resource: str = '', 534 fallback_value: str = '', 535 subs: Sequence[tuple[str, str | Lstr]] = [], 536 ) -> None: 537 """Create an Lstr from a string resource.""" 538 539 # noinspection PyShadowingNames,PyDefaultArgument 540 @overload 541 def __init__( 542 self, 543 *, 544 translate: tuple[str, str], 545 subs: Sequence[tuple[str, str | Lstr]] = [], 546 ) -> None: 547 """Create an Lstr by translating a string in a category.""" 548 549 # noinspection PyDefaultArgument 550 @overload 551 def __init__( 552 self, *, value: str, subs: Sequence[tuple[str, str | Lstr]] = [] 553 ) -> None: 554 """Create an Lstr from a raw string value.""" 555 556 # pylint: enable=redefined-outer-name, dangerous-default-value 557 558 def __init__(self, *args: Any, **keywds: Any) -> None: 559 """Instantiate a Lstr. 560 561 Pass a value for either 'resource', 'translate', 562 or 'value'. (see Lstr help for examples). 563 'subs' can be a sequence of 2-member sequences consisting of values 564 and replacements. 565 'fallback_resource' can be a resource key that will be used if the 566 main one is not present for 567 the current language in place of falling back to the english value 568 ('resource' mode only). 569 'fallback_value' can be a literal string that will be used if neither 570 the resource nor the fallback resource is found ('resource' mode only). 571 """ 572 # pylint: disable=too-many-branches 573 if args: 574 raise TypeError('Lstr accepts only keyword arguments') 575 576 # Basically just store the exact args they passed. 577 # However if they passed any Lstr values for subs, 578 # replace them with that Lstr's dict. 579 self.args = keywds 580 our_type = type(self) 581 582 if isinstance(self.args.get('value'), our_type): 583 raise TypeError("'value' must be a regular string; not an Lstr") 584 585 if 'subs' in self.args: 586 subs_new = [] 587 for key, value in keywds['subs']: 588 if isinstance(value, our_type): 589 subs_new.append((key, value.args)) 590 else: 591 subs_new.append((key, value)) 592 self.args['subs'] = subs_new 593 594 # As of protocol 31 we support compact key names 595 # ('t' instead of 'translate', etc). Convert as needed. 596 if 'translate' in keywds: 597 keywds['t'] = keywds['translate'] 598 del keywds['translate'] 599 if 'resource' in keywds: 600 keywds['r'] = keywds['resource'] 601 del keywds['resource'] 602 if 'value' in keywds: 603 keywds['v'] = keywds['value'] 604 del keywds['value'] 605 if 'fallback' in keywds: 606 from babase import _error 607 608 _error.print_error( 609 'deprecated "fallback" arg passed to Lstr(); use ' 610 'either "fallback_resource" or "fallback_value"', 611 once=True, 612 ) 613 keywds['f'] = keywds['fallback'] 614 del keywds['fallback'] 615 if 'fallback_resource' in keywds: 616 keywds['f'] = keywds['fallback_resource'] 617 del keywds['fallback_resource'] 618 if 'subs' in keywds: 619 keywds['s'] = keywds['subs'] 620 del keywds['subs'] 621 if 'fallback_value' in keywds: 622 keywds['fv'] = keywds['fallback_value'] 623 del keywds['fallback_value'] 624 625 def evaluate(self) -> str: 626 """Evaluate the Lstr and returns a flat string in the current language. 627 628 You should avoid doing this as much as possible and instead pass 629 and store Lstr values. 630 """ 631 return _babase.evaluate_lstr(self._get_json()) 632 633 def is_flat_value(self) -> bool: 634 """Return whether the Lstr is a 'flat' value. 635 636 This is defined as a simple string value incorporating no 637 translations, resources, or substitutions. In this case it may 638 be reasonable to replace it with a raw string value, perform 639 string manipulation on it, etc. 640 """ 641 return bool('v' in self.args and not self.args.get('s', [])) 642 643 def _get_json(self) -> str: 644 try: 645 return json.dumps(self.args, separators=(',', ':')) 646 except Exception: 647 from babase import _error 648 649 _error.print_exception('_get_json failed for', self.args) 650 return 'JSON_ERR' 651 652 @override 653 def __str__(self) -> str: 654 return '<ba.Lstr: ' + self._get_json() + '>' 655 656 @override 657 def __repr__(self) -> str: 658 return '<ba.Lstr: ' + self._get_json() + '>' 659 660 @staticmethod 661 def from_json(json_string: str) -> babase.Lstr: 662 """Given a json string, returns a babase.Lstr. Does no validation.""" 663 lstr = Lstr(value='') 664 lstr.args = json.loads(json_string) 665 return lstr
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 = 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 = 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 = Lstr(value='${A} / ${B}',
... subs=[('${A}', str(score)), ('${B}', str(total))])
EXAMPLE 4: 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
558 def __init__(self, *args: Any, **keywds: Any) -> None: 559 """Instantiate a Lstr. 560 561 Pass a value for either 'resource', 'translate', 562 or 'value'. (see Lstr help for examples). 563 'subs' can be a sequence of 2-member sequences consisting of values 564 and replacements. 565 'fallback_resource' can be a resource key that will be used if the 566 main one is not present for 567 the current language in place of falling back to the english value 568 ('resource' mode only). 569 'fallback_value' can be a literal string that will be used if neither 570 the resource nor the fallback resource is found ('resource' mode only). 571 """ 572 # pylint: disable=too-many-branches 573 if args: 574 raise TypeError('Lstr accepts only keyword arguments') 575 576 # Basically just store the exact args they passed. 577 # However if they passed any Lstr values for subs, 578 # replace them with that Lstr's dict. 579 self.args = keywds 580 our_type = type(self) 581 582 if isinstance(self.args.get('value'), our_type): 583 raise TypeError("'value' must be a regular string; not an Lstr") 584 585 if 'subs' in self.args: 586 subs_new = [] 587 for key, value in keywds['subs']: 588 if isinstance(value, our_type): 589 subs_new.append((key, value.args)) 590 else: 591 subs_new.append((key, value)) 592 self.args['subs'] = subs_new 593 594 # As of protocol 31 we support compact key names 595 # ('t' instead of 'translate', etc). Convert as needed. 596 if 'translate' in keywds: 597 keywds['t'] = keywds['translate'] 598 del keywds['translate'] 599 if 'resource' in keywds: 600 keywds['r'] = keywds['resource'] 601 del keywds['resource'] 602 if 'value' in keywds: 603 keywds['v'] = keywds['value'] 604 del keywds['value'] 605 if 'fallback' in keywds: 606 from babase import _error 607 608 _error.print_error( 609 'deprecated "fallback" arg passed to Lstr(); use ' 610 'either "fallback_resource" or "fallback_value"', 611 once=True, 612 ) 613 keywds['f'] = keywds['fallback'] 614 del keywds['fallback'] 615 if 'fallback_resource' in keywds: 616 keywds['f'] = keywds['fallback_resource'] 617 del keywds['fallback_resource'] 618 if 'subs' in keywds: 619 keywds['s'] = keywds['subs'] 620 del keywds['subs'] 621 if 'fallback_value' in keywds: 622 keywds['fv'] = keywds['fallback_value'] 623 del keywds['fallback_value']
Instantiate a Lstr.
Pass a value for either 'resource', 'translate', or 'value'. (see Lstr help for examples). 'subs' can be a sequence of 2-member sequences consisting of values and replacements. 'fallback_resource' can be a resource key that will be used if the main one is not present for the current language in place of falling back to the english value ('resource' mode only). 'fallback_value' can be a literal string that will be used if neither the resource nor the fallback resource is found ('resource' mode only).
625 def evaluate(self) -> str: 626 """Evaluate the Lstr and returns a flat string in the current language. 627 628 You should avoid doing this as much as possible and instead pass 629 and store Lstr values. 630 """ 631 return _babase.evaluate_lstr(self._get_json())
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.
633 def is_flat_value(self) -> bool: 634 """Return whether the Lstr is a 'flat' value. 635 636 This is defined as a simple string value incorporating no 637 translations, resources, or substitutions. In this case it may 638 be reasonable to replace it with a raw string value, perform 639 string manipulation on it, etc. 640 """ 641 return bool('v' in self.args and not self.args.get('s', []))
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.
54class MapNotFoundError(NotFoundError): 55 """Exception raised when an expected bascenev1.Map does not exist. 56 57 Category: **Exception Classes** 58 """
Exception raised when an expected bascenev1.Map does not exist.
Category: Exception Classes
Inherited Members
- builtins.Exception
- Exception
- builtins.BaseException
- with_traceback
- add_note
- args
49class MetadataSubsystem: 50 """Subsystem for working with script metadata in the app. 51 52 Category: **App Classes** 53 54 Access the single shared instance of this class at 'babase.app.meta'. 55 """ 56 57 def __init__(self) -> None: 58 self._scan: DirectoryScan | None = None 59 60 # Can be populated before starting the scan. 61 self.extra_scan_dirs: list[str] = [] 62 63 # Results populated once scan is complete. 64 self.scanresults: ScanResults | None = None 65 66 self._scan_complete_cb: Callable[[], None] | None = None 67 68 def start_scan(self, scan_complete_cb: Callable[[], None]) -> None: 69 """Begin the overall scan. 70 71 This will start scanning built in directories (which for vanilla 72 installs should be the vast majority of the work). This should only 73 be called once. 74 """ 75 assert self._scan_complete_cb is None 76 assert self._scan is None 77 env = _babase.app.env 78 79 self._scan_complete_cb = scan_complete_cb 80 self._scan = DirectoryScan( 81 [ 82 path 83 for path in [ 84 env.python_directory_app, 85 env.python_directory_user, 86 ] 87 if path is not None 88 ] 89 ) 90 91 Thread(target=self._run_scan_in_bg, daemon=True).start() 92 93 def start_extra_scan(self) -> None: 94 """Proceed to the extra_scan_dirs portion of the scan. 95 96 This is for parts of the scan that must be delayed until 97 workspace sync completion or other such events. This must be 98 called exactly once. 99 """ 100 assert self._scan is not None 101 self._scan.set_extras(self.extra_scan_dirs) 102 103 def load_exported_classes( 104 self, 105 cls: type[T], 106 completion_cb: Callable[[list[type[T]]], None], 107 completion_cb_in_bg_thread: bool = False, 108 ) -> None: 109 """High level function to load meta-exported classes. 110 111 Will wait for scanning to complete if necessary, and will load all 112 registered classes of a particular type in a background thread before 113 calling the passed callback in the logic thread. Errors may be logged 114 to messaged to the user in some way but the callback will be called 115 regardless. 116 To run the completion callback directly in the bg thread where the 117 loading work happens, pass completion_cb_in_bg_thread=True. 118 """ 119 Thread( 120 target=partial( 121 self._load_exported_classes, 122 cls, 123 completion_cb, 124 completion_cb_in_bg_thread, 125 ), 126 daemon=True, 127 ).start() 128 129 def _load_exported_classes( 130 self, 131 cls: type[T], 132 completion_cb: Callable[[list[type[T]]], None], 133 completion_cb_in_bg_thread: bool, 134 ) -> None: 135 from babase._general import getclass 136 137 classes: list[type[T]] = [] 138 try: 139 classnames = self._wait_for_scan_results().exports_of_class(cls) 140 for classname in classnames: 141 try: 142 classes.append(getclass(classname, cls)) 143 except Exception: 144 logging.exception('error importing %s', classname) 145 146 except Exception: 147 logging.exception('Error loading exported classes.') 148 149 completion_call = partial(completion_cb, classes) 150 if completion_cb_in_bg_thread: 151 completion_call() 152 else: 153 _babase.pushcall(completion_call, from_other_thread=True) 154 155 def _wait_for_scan_results(self) -> ScanResults: 156 """Return scan results, blocking if the scan is not yet complete.""" 157 if self.scanresults is None: 158 if _babase.in_logic_thread(): 159 logging.warning( 160 'babase.meta._wait_for_scan_results()' 161 ' called in logic thread before scan completed;' 162 ' this can cause hitches.' 163 ) 164 165 # Now wait a bit for the scan to complete. 166 # Eventually error though if it doesn't. 167 starttime = time.time() 168 while self.scanresults is None: 169 time.sleep(0.05) 170 if time.time() - starttime > 10.0: 171 raise TimeoutError( 172 'timeout waiting for meta scan to complete.' 173 ) 174 return self.scanresults 175 176 def _run_scan_in_bg(self) -> None: 177 """Runs a scan (for use in background thread).""" 178 try: 179 assert self._scan is not None 180 self._scan.run() 181 results = self._scan.results 182 self._scan = None 183 except Exception: 184 logging.exception('metascan: Error running scan in bg.') 185 results = ScanResults(announce_errors_occurred=True) 186 187 # Place results and tell the logic thread they're ready. 188 self.scanresults = results 189 _babase.pushcall(self._handle_scan_results, from_other_thread=True) 190 191 def _handle_scan_results(self) -> None: 192 """Called in the logic thread with results of a completed scan.""" 193 from babase._language import Lstr 194 195 assert _babase.in_logic_thread() 196 197 results = self.scanresults 198 assert results is not None 199 200 do_play_error_sound = False 201 202 # If we found modules needing to be updated to the newer api version, 203 # mention that specifically. 204 if results.incorrect_api_modules: 205 if len(results.incorrect_api_modules) > 1: 206 msg = Lstr( 207 resource='scanScriptsMultipleModulesNeedUpdatesText', 208 subs=[ 209 ('${PATH}', results.incorrect_api_modules[0]), 210 ( 211 '${NUM}', 212 str(len(results.incorrect_api_modules) - 1), 213 ), 214 ('${API}', str(_babase.app.env.api_version)), 215 ], 216 ) 217 else: 218 msg = Lstr( 219 resource='scanScriptsSingleModuleNeedsUpdatesText', 220 subs=[ 221 ('${PATH}', results.incorrect_api_modules[0]), 222 ('${API}', str(_babase.app.env.api_version)), 223 ], 224 ) 225 _babase.screenmessage(msg, color=(1, 0, 0)) 226 do_play_error_sound = True 227 228 # Let the user know if there's warning/errors in their log 229 # they may want to look at. 230 if results.announce_errors_occurred: 231 _babase.screenmessage( 232 Lstr(resource='scanScriptsErrorText'), color=(1, 0, 0) 233 ) 234 do_play_error_sound = True 235 236 if do_play_error_sound: 237 _babase.getsimplesound('error').play() 238 239 # Let the game know we're done. 240 assert self._scan_complete_cb is not None 241 self._scan_complete_cb()
Subsystem for working with script metadata in the app.
Category: App Classes
Access the single shared instance of this class at 'babase.app.meta'.
68 def start_scan(self, scan_complete_cb: Callable[[], None]) -> None: 69 """Begin the overall scan. 70 71 This will start scanning built in directories (which for vanilla 72 installs should be the vast majority of the work). This should only 73 be called once. 74 """ 75 assert self._scan_complete_cb is None 76 assert self._scan is None 77 env = _babase.app.env 78 79 self._scan_complete_cb = scan_complete_cb 80 self._scan = DirectoryScan( 81 [ 82 path 83 for path in [ 84 env.python_directory_app, 85 env.python_directory_user, 86 ] 87 if path is not None 88 ] 89 ) 90 91 Thread(target=self._run_scan_in_bg, daemon=True).start()
Begin the overall scan.
This will start scanning built in directories (which for vanilla installs should be the vast majority of the work). This should only be called once.
93 def start_extra_scan(self) -> None: 94 """Proceed to the extra_scan_dirs portion of the scan. 95 96 This is for parts of the scan that must be delayed until 97 workspace sync completion or other such events. This must be 98 called exactly once. 99 """ 100 assert self._scan is not None 101 self._scan.set_extras(self.extra_scan_dirs)
Proceed to the extra_scan_dirs portion of the scan.
This is for parts of the scan that must be delayed until workspace sync completion or other such events. This must be called exactly once.
103 def load_exported_classes( 104 self, 105 cls: type[T], 106 completion_cb: Callable[[list[type[T]]], None], 107 completion_cb_in_bg_thread: bool = False, 108 ) -> None: 109 """High level function to load meta-exported classes. 110 111 Will wait for scanning to complete if necessary, and will load all 112 registered classes of a particular type in a background thread before 113 calling the passed callback in the logic thread. Errors may be logged 114 to messaged to the user in some way but the callback will be called 115 regardless. 116 To run the completion callback directly in the bg thread where the 117 loading work happens, pass completion_cb_in_bg_thread=True. 118 """ 119 Thread( 120 target=partial( 121 self._load_exported_classes, 122 cls, 123 completion_cb, 124 completion_cb_in_bg_thread, 125 ), 126 daemon=True, 127 ).start()
High level function to load meta-exported classes.
Will wait for scanning to complete if necessary, and will load all registered classes of a particular type in a background thread before calling the passed callback in the logic thread. Errors may be logged to messaged to the user in some way but the callback will be called regardless. To run the completion callback directly in the bg thread where the loading work happens, pass completion_cb_in_bg_thread=True.
1272def native_stack_trace() -> str | None: 1273 """Return a native stack trace as a string, or None if not available. 1274 1275 Category: **General Utility Functions** 1276 1277 Stack traces contain different data and formatting across platforms. 1278 Only use them for debugging. 1279 """ 1280 return ''
Return a native stack trace as a string, or None if not available.
Category: General Utility Functions
Stack traces contain different data and formatting across platforms. Only use them for debugging.
75class NodeNotFoundError(NotFoundError): 76 """Exception raised when an expected Node does not exist. 77 78 Category: **Exception Classes** 79 """
Exception raised when an expected Node does not exist.
Category: Exception Classes
Inherited Members
- builtins.Exception
- Exception
- builtins.BaseException
- with_traceback
- add_note
- args
52def normalized_color(color: Sequence[float]) -> tuple[float, ...]: 53 """Scale a color so its largest value is 1; useful for coloring lights. 54 55 category: General Utility Functions 56 """ 57 color_biased = tuple(max(c, 0.01) for c in color) # account for black 58 mult = 1.0 / max(color_biased) 59 return tuple(c * mult for c in color_biased)
Scale a color so its largest value is 1; useful for coloring lights.
category: General Utility Functions
26class NotFoundError(Exception): 27 """Exception raised when a referenced object does not exist. 28 29 Category: **Exception Classes** 30 """
Exception raised when a referenced object does not exist.
Category: Exception Classes
Inherited Members
- builtins.Exception
- Exception
- builtins.BaseException
- with_traceback
- add_note
- args
1309def open_url(address: str, force_fallback: bool = False) -> None: 1310 """Open the provided URL. 1311 1312 Category: **General Utility Functions** 1313 1314 Attempts to open the provided url in a web-browser. If that is not 1315 possible (or force_fallback is True), instead displays the url as 1316 a string and/or qrcode. 1317 """ 1318 return None
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.
1321def overlay_web_browser_close() -> bool: 1322 """Close any open overlay web browser. 1323 1324 Category: **General Utility Functions** 1325 """ 1326 return bool()
Close any open overlay web browser.
Category: General Utility Functions
1329def overlay_web_browser_is_open() -> bool: 1330 """Return whether an overlay web browser is open currently. 1331 1332 Category: **General Utility Functions** 1333 """ 1334 return bool()
Return whether an overlay web browser is open currently.
Category: General Utility Functions
1337def overlay_web_browser_is_supported() -> bool: 1338 """Return whether an overlay web browser is supported here. 1339 1340 Category: **General Utility Functions** 1341 1342 An overlay web browser is a small dialog that pops up over the top 1343 of the main engine window. It can be used for performing simple 1344 tasks such as sign-ins. 1345 """ 1346 return bool()
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.
1349def overlay_web_browser_open_url(address: str) -> None: 1350 """Open the provided URL in an overlayw web browser. 1351 1352 Category: **General Utility Functions** 1353 1354 An overlay web browser is a small dialog that pops up over the top 1355 of the main engine window. It can be used for performing simple 1356 tasks such as sign-ins. 1357 """ 1358 return None
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.
89class Permission(Enum): 90 """Permissions that can be requested from the OS. 91 92 Category: Enums 93 """ 94 95 STORAGE = 0
Permissions that can be requested from the OS.
Category: Enums
Inherited Members
- enum.Enum
- name
- value
33class PlayerNotFoundError(NotFoundError): 34 """Exception raised when an expected player does not exist. 35 36 Category: **Exception Classes** 37 """
Exception raised when an expected player does not exist.
Category: Exception Classes
Inherited Members
- builtins.Exception
- Exception
- builtins.BaseException
- with_traceback
- add_note
- args
322class Plugin: 323 """A plugin to alter app behavior in some way. 324 325 Category: **App Classes** 326 327 Plugins are discoverable by the meta-tag system 328 and the user can select which ones they want to enable. 329 Enabled plugins are then called at specific times as the 330 app is running in order to modify its behavior in some way. 331 """ 332 333 def on_app_running(self) -> None: 334 """Called when the app reaches the running state.""" 335 336 def on_app_suspend(self) -> None: 337 """Called when the app enters the suspended state.""" 338 339 def on_app_unsuspend(self) -> None: 340 """Called when the app exits the suspended state.""" 341 342 def on_app_shutdown(self) -> None: 343 """Called when the app is beginning the shutdown process.""" 344 345 def on_app_shutdown_complete(self) -> None: 346 """Called when the app has completed the shutdown process.""" 347 348 def has_settings_ui(self) -> bool: 349 """Called to ask if we have settings UI we can show.""" 350 return False 351 352 def show_settings_ui(self, source_widget: Any | None) -> None: 353 """Called to show our settings UI."""
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.
342 def on_app_shutdown(self) -> None: 343 """Called when the app is beginning the shutdown process."""
Called when the app is beginning the shutdown process.
345 def on_app_shutdown_complete(self) -> None: 346 """Called when the app has completed the shutdown process."""
Called when the app has completed the shutdown process.
21class PluginSubsystem(AppSubsystem): 22 """Subsystem for plugin handling in the app. 23 24 Category: **App Classes** 25 26 Access the single shared instance of this class at `ba.app.plugins`. 27 """ 28 29 AUTO_ENABLE_NEW_PLUGINS_CONFIG_KEY = 'Auto Enable New Plugins' 30 AUTO_ENABLE_NEW_PLUGINS_DEFAULT = True 31 32 def __init__(self) -> None: 33 super().__init__() 34 35 # Info about plugins that we are aware of. This may include 36 # plugins discovered through meta-scanning as well as plugins 37 # registered in the app-config. This may include plugins that 38 # cannot be loaded for various reasons or that have been 39 # intentionally disabled. 40 self.plugin_specs: dict[str, babase.PluginSpec] = {} 41 42 # The set of live active plugin objects. 43 self.active_plugins: list[babase.Plugin] = [] 44 45 def on_meta_scan_complete(self) -> None: 46 """Called when meta-scanning is complete.""" 47 from babase._language import Lstr 48 49 config_changed = False 50 found_new = False 51 plugstates: dict[str, dict] = _babase.app.config.setdefault( 52 'Plugins', {} 53 ) 54 assert isinstance(plugstates, dict) 55 56 results = _babase.app.meta.scanresults 57 assert results is not None 58 59 auto_enable_new_plugins = ( 60 _babase.app.config.get( 61 self.AUTO_ENABLE_NEW_PLUGINS_CONFIG_KEY, 62 self.AUTO_ENABLE_NEW_PLUGINS_DEFAULT, 63 ) 64 is True 65 ) 66 67 assert not self.plugin_specs 68 assert not self.active_plugins 69 70 # Create a plugin-spec for each plugin class we found in the 71 # meta-scan. 72 for class_path in results.exports_of_class(Plugin): 73 assert class_path not in self.plugin_specs 74 plugspec = self.plugin_specs[class_path] = PluginSpec( 75 class_path=class_path, loadable=True 76 ) 77 78 # Auto-enable new ones if desired. 79 if auto_enable_new_plugins: 80 if class_path not in plugstates: 81 plugspec.enabled = True 82 config_changed = True 83 found_new = True 84 85 # If we're *not* auto-enabling, simply let the user know if we 86 # found new ones. 87 if found_new and not auto_enable_new_plugins: 88 _babase.screenmessage( 89 Lstr(resource='pluginsDetectedText'), color=(0, 1, 0) 90 ) 91 _babase.getsimplesound('ding').play() 92 93 # Ok, now go through all plugins registered in the app-config 94 # that weren't covered by the meta stuff above, either creating 95 # plugin-specs for them or clearing them out. This covers 96 # plugins with api versions not matching ours, plugins without 97 # ba_meta tags, and plugins that have since disappeared. 98 assert isinstance(plugstates, dict) 99 wrong_api_prefixes = [f'{m}.' for m in results.incorrect_api_modules] 100 101 disappeared_plugs: set[str] = set() 102 103 for class_path in sorted(plugstates.keys()): 104 # Already have a spec for it; nothing to be done. 105 if class_path in self.plugin_specs: 106 continue 107 108 # If this plugin corresponds to any modules that we've 109 # identified as having incorrect api versions, we'll take 110 # note of its existence but we won't try to load it. 111 if any( 112 class_path.startswith(prefix) for prefix in wrong_api_prefixes 113 ): 114 plugspec = self.plugin_specs[class_path] = PluginSpec( 115 class_path=class_path, loadable=False 116 ) 117 continue 118 119 # Ok, it seems to be a class we have no metadata for. Look 120 # to see if it appears to be an actual class we could 121 # theoretically load. If so, we'll try. If not, we consider 122 # the plugin to have disappeared and inform the user as 123 # such. 124 try: 125 spec = importlib.util.find_spec( 126 '.'.join(class_path.split('.')[:-1]) 127 ) 128 except Exception: 129 spec = None 130 131 if spec is None: 132 disappeared_plugs.add(class_path) 133 continue 134 135 # If plugins disappeared, let the user know gently and remove 136 # them from the config so we'll again let the user know if they 137 # later reappear. This makes it much smoother to switch between 138 # users or workspaces. 139 if disappeared_plugs: 140 _babase.getsimplesound('shieldDown').play() 141 _babase.screenmessage( 142 Lstr( 143 resource='pluginsRemovedText', 144 subs=[('${NUM}', str(len(disappeared_plugs)))], 145 ), 146 color=(1, 1, 0), 147 ) 148 149 plugnames = ', '.join(disappeared_plugs) 150 logging.info( 151 '%d plugin(s) no longer found: %s.', 152 len(disappeared_plugs), 153 plugnames, 154 ) 155 for goneplug in disappeared_plugs: 156 del _babase.app.config['Plugins'][goneplug] 157 _babase.app.config.commit() 158 159 if config_changed: 160 _babase.app.config.commit() 161 162 @override 163 def on_app_running(self) -> None: 164 # Load up our plugins and go ahead and call their on_app_running 165 # calls. 166 self.load_plugins() 167 for plugin in self.active_plugins: 168 try: 169 plugin.on_app_running() 170 except Exception: 171 from babase import _error 172 173 _error.print_exception('Error in plugin on_app_running()') 174 175 @override 176 def on_app_suspend(self) -> None: 177 for plugin in self.active_plugins: 178 try: 179 plugin.on_app_suspend() 180 except Exception: 181 from babase import _error 182 183 _error.print_exception('Error in plugin on_app_suspend()') 184 185 @override 186 def on_app_unsuspend(self) -> None: 187 for plugin in self.active_plugins: 188 try: 189 plugin.on_app_unsuspend() 190 except Exception: 191 from babase import _error 192 193 _error.print_exception('Error in plugin on_app_unsuspend()') 194 195 @override 196 def on_app_shutdown(self) -> None: 197 for plugin in self.active_plugins: 198 try: 199 plugin.on_app_shutdown() 200 except Exception: 201 from babase import _error 202 203 _error.print_exception('Error in plugin on_app_shutdown()') 204 205 @override 206 def on_app_shutdown_complete(self) -> None: 207 for plugin in self.active_plugins: 208 try: 209 plugin.on_app_shutdown_complete() 210 except Exception: 211 from babase import _error 212 213 _error.print_exception( 214 'Error in plugin on_app_shutdown_complete()' 215 ) 216 217 def load_plugins(self) -> None: 218 """(internal)""" 219 220 # Load plugins from any specs that are enabled & able to. 221 for _class_path, plug_spec in sorted(self.plugin_specs.items()): 222 plugin = plug_spec.attempt_load_if_enabled() 223 if plugin is not None: 224 self.active_plugins.append(plugin)
Subsystem for plugin handling in the app.
Category: App Classes
Access the single shared instance of this class at ba.app.plugins
.
45 def on_meta_scan_complete(self) -> None: 46 """Called when meta-scanning is complete.""" 47 from babase._language import Lstr 48 49 config_changed = False 50 found_new = False 51 plugstates: dict[str, dict] = _babase.app.config.setdefault( 52 'Plugins', {} 53 ) 54 assert isinstance(plugstates, dict) 55 56 results = _babase.app.meta.scanresults 57 assert results is not None 58 59 auto_enable_new_plugins = ( 60 _babase.app.config.get( 61 self.AUTO_ENABLE_NEW_PLUGINS_CONFIG_KEY, 62 self.AUTO_ENABLE_NEW_PLUGINS_DEFAULT, 63 ) 64 is True 65 ) 66 67 assert not self.plugin_specs 68 assert not self.active_plugins 69 70 # Create a plugin-spec for each plugin class we found in the 71 # meta-scan. 72 for class_path in results.exports_of_class(Plugin): 73 assert class_path not in self.plugin_specs 74 plugspec = self.plugin_specs[class_path] = PluginSpec( 75 class_path=class_path, loadable=True 76 ) 77 78 # Auto-enable new ones if desired. 79 if auto_enable_new_plugins: 80 if class_path not in plugstates: 81 plugspec.enabled = True 82 config_changed = True 83 found_new = True 84 85 # If we're *not* auto-enabling, simply let the user know if we 86 # found new ones. 87 if found_new and not auto_enable_new_plugins: 88 _babase.screenmessage( 89 Lstr(resource='pluginsDetectedText'), color=(0, 1, 0) 90 ) 91 _babase.getsimplesound('ding').play() 92 93 # Ok, now go through all plugins registered in the app-config 94 # that weren't covered by the meta stuff above, either creating 95 # plugin-specs for them or clearing them out. This covers 96 # plugins with api versions not matching ours, plugins without 97 # ba_meta tags, and plugins that have since disappeared. 98 assert isinstance(plugstates, dict) 99 wrong_api_prefixes = [f'{m}.' for m in results.incorrect_api_modules] 100 101 disappeared_plugs: set[str] = set() 102 103 for class_path in sorted(plugstates.keys()): 104 # Already have a spec for it; nothing to be done. 105 if class_path in self.plugin_specs: 106 continue 107 108 # If this plugin corresponds to any modules that we've 109 # identified as having incorrect api versions, we'll take 110 # note of its existence but we won't try to load it. 111 if any( 112 class_path.startswith(prefix) for prefix in wrong_api_prefixes 113 ): 114 plugspec = self.plugin_specs[class_path] = PluginSpec( 115 class_path=class_path, loadable=False 116 ) 117 continue 118 119 # Ok, it seems to be a class we have no metadata for. Look 120 # to see if it appears to be an actual class we could 121 # theoretically load. If so, we'll try. If not, we consider 122 # the plugin to have disappeared and inform the user as 123 # such. 124 try: 125 spec = importlib.util.find_spec( 126 '.'.join(class_path.split('.')[:-1]) 127 ) 128 except Exception: 129 spec = None 130 131 if spec is None: 132 disappeared_plugs.add(class_path) 133 continue 134 135 # If plugins disappeared, let the user know gently and remove 136 # them from the config so we'll again let the user know if they 137 # later reappear. This makes it much smoother to switch between 138 # users or workspaces. 139 if disappeared_plugs: 140 _babase.getsimplesound('shieldDown').play() 141 _babase.screenmessage( 142 Lstr( 143 resource='pluginsRemovedText', 144 subs=[('${NUM}', str(len(disappeared_plugs)))], 145 ), 146 color=(1, 1, 0), 147 ) 148 149 plugnames = ', '.join(disappeared_plugs) 150 logging.info( 151 '%d plugin(s) no longer found: %s.', 152 len(disappeared_plugs), 153 plugnames, 154 ) 155 for goneplug in disappeared_plugs: 156 del _babase.app.config['Plugins'][goneplug] 157 _babase.app.config.commit() 158 159 if config_changed: 160 _babase.app.config.commit()
Called when meta-scanning is complete.
162 @override 163 def on_app_running(self) -> None: 164 # Load up our plugins and go ahead and call their on_app_running 165 # calls. 166 self.load_plugins() 167 for plugin in self.active_plugins: 168 try: 169 plugin.on_app_running() 170 except Exception: 171 from babase import _error 172 173 _error.print_exception('Error in plugin on_app_running()')
Called when the app reaches the running state.
175 @override 176 def on_app_suspend(self) -> None: 177 for plugin in self.active_plugins: 178 try: 179 plugin.on_app_suspend() 180 except Exception: 181 from babase import _error 182 183 _error.print_exception('Error in plugin on_app_suspend()')
Called when the app enters the suspended state.
185 @override 186 def on_app_unsuspend(self) -> None: 187 for plugin in self.active_plugins: 188 try: 189 plugin.on_app_unsuspend() 190 except Exception: 191 from babase import _error 192 193 _error.print_exception('Error in plugin on_app_unsuspend()')
Called when the app exits the suspended state.
195 @override 196 def on_app_shutdown(self) -> None: 197 for plugin in self.active_plugins: 198 try: 199 plugin.on_app_shutdown() 200 except Exception: 201 from babase import _error 202 203 _error.print_exception('Error in plugin on_app_shutdown()')
Called when the app begins shutting down.
205 @override 206 def on_app_shutdown_complete(self) -> None: 207 for plugin in self.active_plugins: 208 try: 209 plugin.on_app_shutdown_complete() 210 except Exception: 211 from babase import _error 212 213 _error.print_exception( 214 'Error in plugin on_app_shutdown_complete()' 215 )
Called when the app completes shutting down.
Inherited Members
227class PluginSpec: 228 """Represents a plugin the engine knows about. 229 230 Category: **App Classes** 231 232 The 'enabled' attr represents whether this plugin is set to load. 233 Getting or setting that attr affects the corresponding app-config 234 key. Remember to commit the app-config after making any changes. 235 236 The 'attempted_load' attr will be True if the engine has attempted 237 to load the plugin. If 'attempted_load' is True for a PluginSpec 238 but the 'plugin' attr is None, it means there was an error loading 239 the plugin. If a plugin's api-version does not match the running 240 app, if a new plugin is detected with auto-enable-plugins disabled, 241 or if the user has explicitly disabled a plugin, the engine will not 242 even attempt to load it. 243 """ 244 245 def __init__(self, class_path: str, loadable: bool): 246 self.class_path = class_path 247 self.loadable = loadable 248 self.attempted_load = False 249 self.plugin: Plugin | None = None 250 251 @property 252 def enabled(self) -> bool: 253 """Whether the user wants this plugin to load.""" 254 plugstates: dict[str, dict] = _babase.app.config.get('Plugins', {}) 255 assert isinstance(plugstates, dict) 256 val = plugstates.get(self.class_path, {}).get('enabled', False) is True 257 return val 258 259 @enabled.setter 260 def enabled(self, val: bool) -> None: 261 plugstates: dict[str, dict] = _babase.app.config.setdefault( 262 'Plugins', {} 263 ) 264 assert isinstance(plugstates, dict) 265 plugstate = plugstates.setdefault(self.class_path, {}) 266 plugstate['enabled'] = val 267 268 def attempt_load_if_enabled(self) -> Plugin | None: 269 """Possibly load the plugin and log any errors.""" 270 from babase._general import getclass 271 from babase._language import Lstr 272 273 assert not self.attempted_load 274 assert self.plugin is None 275 276 if not self.enabled: 277 return None 278 self.attempted_load = True 279 if not self.loadable: 280 return None 281 try: 282 cls = getclass(self.class_path, Plugin, True) 283 except Exception as exc: 284 _babase.getsimplesound('error').play() 285 _babase.screenmessage( 286 Lstr( 287 resource='pluginClassLoadErrorText', 288 subs=[ 289 ('${PLUGIN}', self.class_path), 290 ('${ERROR}', str(exc)), 291 ], 292 ), 293 color=(1, 0, 0), 294 ) 295 logging.exception( 296 "Error loading plugin class '%s'.", self.class_path 297 ) 298 return None 299 try: 300 self.plugin = cls() 301 return self.plugin 302 except Exception as exc: 303 from babase import _error 304 305 _babase.getsimplesound('error').play() 306 _babase.screenmessage( 307 Lstr( 308 resource='pluginInitErrorText', 309 subs=[ 310 ('${PLUGIN}', self.class_path), 311 ('${ERROR}', str(exc)), 312 ], 313 ), 314 color=(1, 0, 0), 315 ) 316 logging.exception( 317 "Error initing plugin class: '%s'.", self.class_path 318 ) 319 return None
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.
251 @property 252 def enabled(self) -> bool: 253 """Whether the user wants this plugin to load.""" 254 plugstates: dict[str, dict] = _babase.app.config.get('Plugins', {}) 255 assert isinstance(plugstates, dict) 256 val = plugstates.get(self.class_path, {}).get('enabled', False) is True 257 return val
Whether the user wants this plugin to load.
268 def attempt_load_if_enabled(self) -> Plugin | None: 269 """Possibly load the plugin and log any errors.""" 270 from babase._general import getclass 271 from babase._language import Lstr 272 273 assert not self.attempted_load 274 assert self.plugin is None 275 276 if not self.enabled: 277 return None 278 self.attempted_load = True 279 if not self.loadable: 280 return None 281 try: 282 cls = getclass(self.class_path, Plugin, True) 283 except Exception as exc: 284 _babase.getsimplesound('error').play() 285 _babase.screenmessage( 286 Lstr( 287 resource='pluginClassLoadErrorText', 288 subs=[ 289 ('${PLUGIN}', self.class_path), 290 ('${ERROR}', str(exc)), 291 ], 292 ), 293 color=(1, 0, 0), 294 ) 295 logging.exception( 296 "Error loading plugin class '%s'.", self.class_path 297 ) 298 return None 299 try: 300 self.plugin = cls() 301 return self.plugin 302 except Exception as exc: 303 from babase import _error 304 305 _babase.getsimplesound('error').play() 306 _babase.screenmessage( 307 Lstr( 308 resource='pluginInitErrorText', 309 subs=[ 310 ('${PLUGIN}', self.class_path), 311 ('${ERROR}', str(exc)), 312 ], 313 ), 314 color=(1, 0, 0), 315 ) 316 logging.exception( 317 "Error initing plugin class: '%s'.", self.class_path 318 ) 319 return None
Possibly load the plugin and log any errors.
163def print_error(err_str: str, once: bool = False) -> None: 164 """Print info about an error along with pertinent context state. 165 166 Category: **General Utility Functions** 167 168 Prints all positional arguments provided along with various info about the 169 current context. 170 Pass the keyword 'once' as True if you want the call to only happen 171 one time from an exact calling location. 172 """ 173 import traceback 174 175 try: 176 # If we're only printing once and already have, bail. 177 if once: 178 if not _babase.do_once(): 179 return 180 181 print('ERROR:', err_str) 182 _babase.print_context() 183 184 # Basically the output of traceback.print_stack() 185 stackstr = ''.join(traceback.format_stack()) 186 print(stackstr, end='') 187 except Exception: 188 print('ERROR: exception in babase.print_error():') 189 traceback.print_exc()
Print info about an error along with pertinent context state.
Category: General Utility Functions
Prints all positional arguments provided along with various info about the current context. Pass the keyword 'once' as True if you want the call to only happen one time from an exact calling location.
122def print_exception(*args: Any, **keywds: Any) -> None: 123 """Print info about an exception along with pertinent context state. 124 125 Category: **General Utility Functions** 126 127 Prints all arguments provided along with various info about the 128 current context and the outstanding exception. 129 Pass the keyword 'once' as True if you want the call to only happen 130 one time from an exact calling location. 131 """ 132 import traceback 133 134 if keywds: 135 allowed_keywds = ['once'] 136 if any(keywd not in allowed_keywds for keywd in keywds): 137 raise TypeError('invalid keyword(s)') 138 try: 139 # If we're only printing once and already have, bail. 140 if keywds.get('once', False): 141 if not _babase.do_once(): 142 return 143 144 err_str = ' '.join([str(a) for a in args]) 145 print('ERROR:', err_str) 146 _babase.print_context() 147 print('PRINTED-FROM:') 148 149 # Basically the output of traceback.print_stack() 150 stackstr = ''.join(traceback.format_stack()) 151 print(stackstr, end='') 152 print('EXCEPTION:') 153 154 # Basically the output of traceback.print_exc() 155 excstr = traceback.format_exc() 156 print('\n'.join(' ' + l for l in excstr.splitlines())) 157 except Exception: 158 # I suppose using print_exception here would be a bad idea. 159 print('ERROR: exception in babase.print_exception():') 160 traceback.print_exc()
Print info about an exception along with pertinent context state.
Category: General Utility Functions
Prints all arguments provided along with various info about the current context and the outstanding exception. Pass the keyword 'once' as True if you want the call to only happen one time from an exact calling location.
1393def pushcall( 1394 call: Callable, 1395 from_other_thread: bool = False, 1396 suppress_other_thread_warning: bool = False, 1397 other_thread_use_fg_context: bool = False, 1398 raw: bool = False, 1399) -> None: 1400 """Push a call to the logic event-loop. 1401 Category: **General Utility Functions** 1402 1403 This call expects to be used in the logic thread, and will automatically 1404 save and restore the babase.Context to behave seamlessly. 1405 1406 If you want to push a call from outside of the logic thread, 1407 however, you can pass 'from_other_thread' as True. In this case 1408 the call will always run in the UI context_ref on the logic thread 1409 or whichever context_ref is in the foreground if 1410 other_thread_use_fg_context is True. 1411 Passing raw=True will disable thread checks and context_ref sets/restores. 1412 """ 1413 return 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.
1417def quit( 1418 confirm: bool = False, quit_type: babase.QuitType | None = None 1419) -> None: 1420 """Quit the app. 1421 1422 Category: **General Utility Functions** 1423 1424 If 'confirm' is True, a confirm dialog will be presented if conditions 1425 allow; otherwise the quit will still be immediate. 1426 See docs for babase.QuitType for explanations of the optional 1427 'quit_type' arg. 1428 """ 1429 return None
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 QuitType for explanations of the optional 'quit_type' arg.
42class QuitType(Enum): 43 """Types of input a controller can send to the game. 44 45 Category: Enums 46 47 'soft' may hide/reset the app but keep the process running, depending 48 on the platform. 49 50 'back' is a variant of 'soft' which may give 'back-button-pressed' 51 behavior depending on the platform. (returning to some previous 52 activity instead of dumping to the home screen, etc.) 53 54 'hard' leads to the process exiting. This generally should be avoided 55 on platforms such as mobile. 56 """ 57 58 SOFT = 0 59 BACK = 1 60 HARD = 2
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.
Inherited Members
- enum.Enum
- name
- value
1467def safecolor( 1468 color: Sequence[float], target_intensity: float = 0.6 1469) -> tuple[float, ...]: 1470 """Given a color tuple, return a color safe to display as text. 1471 1472 Category: **General Utility Functions** 1473 1474 Accepts tuples of length 3 or 4. This will slightly brighten very 1475 dark colors, etc. 1476 """ 1477 return (0.0, 0.0, 0.0)
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.
1480def screenmessage( 1481 message: str | babase.Lstr, 1482 color: Sequence[float] | None = None, 1483 log: bool = False, 1484) -> None: 1485 """Print a message to the local client's screen, in a given color. 1486 1487 Category: **General Utility Functions** 1488 1489 Note that this version of the function is purely for local display. 1490 To broadcast screen messages in network play, look for methods such as 1491 broadcastmessage() provided by the scene-version packages. 1492 """ 1493 return 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.
96class SessionNotFoundError(NotFoundError): 97 """Exception raised when an expected session does not exist. 98 99 Category: **Exception Classes** 100 """
Exception raised when an expected session does not exist.
Category: Exception Classes
Inherited Members
- builtins.Exception
- Exception
- builtins.BaseException
- with_traceback
- add_note
- args
40class SessionPlayerNotFoundError(NotFoundError): 41 """Exception raised when an expected session-player does not exist. 42 43 Category: **Exception Classes** 44 """
Exception raised when an expected session-player does not exist.
Category: Exception Classes
Inherited Members
- builtins.Exception
- Exception
- builtins.BaseException
- with_traceback
- add_note
- args
68class SessionTeamNotFoundError(NotFoundError): 69 """Exception raised when an expected session-team does not exist. 70 71 Category: **Exception Classes** 72 """
Exception raised when an expected session-team does not exist.
Category: Exception Classes
Inherited Members
- builtins.Exception
- Exception
- builtins.BaseException
- with_traceback
- add_note
- args
1496def set_analytics_screen(screen: str) -> None: 1497 """Used for analytics to see where in the app players spend their time. 1498 1499 Category: **General Utility Functions** 1500 1501 Generally called when opening a new window or entering some UI. 1502 'screen' should be a string description of an app location 1503 ('Main Menu', etc.) 1504 """ 1505 return 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.)
383class SimpleSound: 384 """A simple sound wrapper for internal use. 385 386 Do not use for gameplay code as it will only play locally. 387 """ 388 389 def play(self) -> None: 390 """Play the sound locally.""" 391 return None
A simple sound wrapper for internal use.
Do not use for gameplay code as it will only play locally.
98class SpecialChar(Enum): 99 """Special characters the game can print. 100 101 Category: Enums 102 """ 103 104 DOWN_ARROW = 0 105 UP_ARROW = 1 106 LEFT_ARROW = 2 107 RIGHT_ARROW = 3 108 TOP_BUTTON = 4 109 LEFT_BUTTON = 5 110 RIGHT_BUTTON = 6 111 BOTTOM_BUTTON = 7 112 DELETE = 8 113 SHIFT = 9 114 BACK = 10 115 LOGO_FLAT = 11 116 REWIND_BUTTON = 12 117 PLAY_PAUSE_BUTTON = 13 118 FAST_FORWARD_BUTTON = 14 119 DPAD_CENTER_BUTTON = 15 120 PLAY_STATION_CROSS_BUTTON = 16 121 PLAY_STATION_CIRCLE_BUTTON = 17 122 PLAY_STATION_TRIANGLE_BUTTON = 18 123 PLAY_STATION_SQUARE_BUTTON = 19 124 PLAY_BUTTON = 20 125 PAUSE_BUTTON = 21 126 OUYA_BUTTON_O = 22 127 OUYA_BUTTON_U = 23 128 OUYA_BUTTON_Y = 24 129 OUYA_BUTTON_A = 25 130 TOKEN = 26 131 LOGO = 27 132 TICKET = 28 133 GOOGLE_PLAY_GAMES_LOGO = 29 134 GAME_CENTER_LOGO = 30 135 DICE_BUTTON1 = 31 136 DICE_BUTTON2 = 32 137 DICE_BUTTON3 = 33 138 DICE_BUTTON4 = 34 139 GAME_CIRCLE_LOGO = 35 140 PARTY_ICON = 36 141 TEST_ACCOUNT = 37 142 TICKET_BACKING = 38 143 TROPHY1 = 39 144 TROPHY2 = 40 145 TROPHY3 = 41 146 TROPHY0A = 42 147 TROPHY0B = 43 148 TROPHY4 = 44 149 LOCAL_ACCOUNT = 45 150 EXPLODINARY_LOGO = 46 151 FLAG_UNITED_STATES = 47 152 FLAG_MEXICO = 48 153 FLAG_GERMANY = 49 154 FLAG_BRAZIL = 50 155 FLAG_RUSSIA = 51 156 FLAG_CHINA = 52 157 FLAG_UNITED_KINGDOM = 53 158 FLAG_CANADA = 54 159 FLAG_INDIA = 55 160 FLAG_JAPAN = 56 161 FLAG_FRANCE = 57 162 FLAG_INDONESIA = 58 163 FLAG_ITALY = 59 164 FLAG_SOUTH_KOREA = 60 165 FLAG_NETHERLANDS = 61 166 FEDORA = 62 167 HAL = 63 168 CROWN = 64 169 YIN_YANG = 65 170 EYE_BALL = 66 171 SKULL = 67 172 HEART = 68 173 DRAGON = 69 174 HELMET = 70 175 MUSHROOM = 71 176 NINJA_STAR = 72 177 VIKING_HELMET = 73 178 MOON = 74 179 SPIDER = 75 180 FIREBALL = 76 181 FLAG_UNITED_ARAB_EMIRATES = 77 182 FLAG_QATAR = 78 183 FLAG_EGYPT = 79 184 FLAG_KUWAIT = 80 185 FLAG_ALGERIA = 81 186 FLAG_SAUDI_ARABIA = 82 187 FLAG_MALAYSIA = 83 188 FLAG_CZECH_REPUBLIC = 84 189 FLAG_AUSTRALIA = 85 190 FLAG_SINGAPORE = 86 191 OCULUS_LOGO = 87 192 STEAM_LOGO = 88 193 NVIDIA_LOGO = 89 194 FLAG_IRAN = 90 195 FLAG_POLAND = 91 196 FLAG_ARGENTINA = 92 197 FLAG_PHILIPPINES = 93 198 FLAG_CHILE = 94 199 MIKIROG = 95 200 V2_LOGO = 96
Special characters the game can print.
Category: Enums
Inherited Members
- enum.Enum
- name
- value
334def storagename(suffix: str | None = None) -> str: 335 """Generate a unique name for storing class data in shared places. 336 337 Category: **General Utility Functions** 338 339 This consists of a leading underscore, the module path at the 340 call site with dots replaced by underscores, the containing class's 341 qualified name, and the provided suffix. When storing data in public 342 places such as 'customdata' dicts, this minimizes the chance of 343 collisions with other similarly named classes. 344 345 Note that this will function even if called in the class definition. 346 347 ##### Examples 348 Generate a unique name for storage purposes: 349 >>> class MyThingie: 350 ... # This will give something like 351 ... # '_mymodule_submodule_mythingie_data'. 352 ... _STORENAME = babase.storagename('data') 353 ... 354 ... # Use that name to store some data in the Activity we were 355 ... # passed. 356 ... def __init__(self, activity): 357 ... activity.customdata[self._STORENAME] = {} 358 """ 359 frame = inspect.currentframe() 360 if frame is None: 361 raise RuntimeError('Cannot get current stack frame.') 362 fback = frame.f_back 363 364 # Note: We need to explicitly clear frame here to avoid a ref-loop 365 # that keeps all function-dicts in the stack alive until the next 366 # full GC cycle (the stack frame refers to this function's dict, 367 # which refers to the stack frame). 368 del frame 369 370 if fback is None: 371 raise RuntimeError('Cannot get parent stack frame.') 372 modulepath = fback.f_globals.get('__name__') 373 if modulepath is None: 374 raise RuntimeError('Cannot get parent stack module path.') 375 assert isinstance(modulepath, str) 376 qualname = fback.f_locals.get('__qualname__') 377 if qualname is not None: 378 assert isinstance(qualname, str) 379 fullpath = f'_{modulepath}_{qualname.lower()}' 380 else: 381 fullpath = f'_{modulepath}' 382 if suffix is not None: 383 fullpath = f'{fullpath}_{suffix}' 384 return fullpath.replace('.', '_')
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 = storagename('data')
...
... # Use that name to store some data in the Activity we were
... # passed.
... def __init__(self, activity):
... activity.customdata[self._STORENAME] = {}
32class StringEditAdapter: 33 """Represents a string editing operation on some object. 34 35 Editable objects such as text widgets or in-app-consoles can 36 subclass this to make their contents editable on all platforms. 37 38 There can only be one string-edit at a time for the app. New 39 StringEdits will attempt to register themselves as the globally 40 active one in their constructor, but this may not succeed. When 41 creating a StringEditAdapter, always check its 'is_valid()' value after 42 creating it. If this is False, it was not able to set itself as 43 the global active one and should be discarded. 44 """ 45 46 def __init__( 47 self, 48 description: str, 49 initial_text: str, 50 max_length: int | None, 51 screen_space_center: tuple[float, float] | None, 52 ) -> None: 53 if not _babase.in_logic_thread(): 54 raise RuntimeError('This must be called from the logic thread.') 55 56 self.create_time = time.monotonic() 57 58 # Note: these attr names are hard-coded in C++ code so don't 59 # change them willy-nilly. 60 self.description = description 61 self.initial_text = initial_text 62 self.max_length = max_length 63 self.screen_space_center = screen_space_center 64 65 # Attempt to register ourself as the active edit. 66 subsys = _babase.app.stringedit 67 current_edit = subsys.active_adapter() 68 if current_edit is None or current_edit.can_be_replaced(): 69 subsys.active_adapter = weakref.ref(self) 70 71 @final 72 def can_be_replaced(self) -> bool: 73 """Return whether this adapter can be replaced by a new one. 74 75 This is mainly a safeguard to allow adapters whose drivers have 76 gone away without calling apply or cancel to time out and be 77 replaced with new ones. 78 """ 79 if not _babase.in_logic_thread(): 80 raise RuntimeError('This must be called from the logic thread.') 81 82 # Allow ourself to be replaced after a bit. 83 if time.monotonic() - self.create_time > 5.0: 84 if _babase.do_once(): 85 logging.warning( 86 'StringEditAdapter can_be_replaced() check for %s' 87 ' yielding True due to timeout; ideally this should' 88 ' not be possible as the StringEditAdapter driver' 89 ' should be blocking anything else from kicking off' 90 ' new edits.', 91 self, 92 ) 93 return True 94 95 # We also are always considered replaceable if we're not the 96 # active global adapter. 97 current_edit = _babase.app.stringedit.active_adapter() 98 if current_edit is not self: 99 return True 100 101 return False 102 103 @final 104 def apply(self, new_text: str) -> None: 105 """Should be called by the owner when editing is complete. 106 107 Note that in some cases this call may be a no-op (such as if 108 this StringEditAdapter is no longer the globally active one). 109 """ 110 if not _babase.in_logic_thread(): 111 raise RuntimeError('This must be called from the logic thread.') 112 113 # Make sure whoever is feeding this adapter is honoring max-length. 114 if self.max_length is not None and len(new_text) > self.max_length: 115 logging.warning( 116 'apply() on %s was passed a string of length %d,' 117 ' but adapter max_length is %d; this should not happen' 118 ' (will truncate).', 119 self, 120 len(new_text), 121 self.max_length, 122 stack_info=True, 123 ) 124 new_text = new_text[: self.max_length] 125 126 self._do_apply(new_text) 127 128 @final 129 def cancel(self) -> None: 130 """Should be called by the owner when editing is cancelled.""" 131 if not _babase.in_logic_thread(): 132 raise RuntimeError('This must be called from the logic thread.') 133 self._do_cancel() 134 135 def _do_apply(self, new_text: str) -> None: 136 """Should be overridden by subclasses to handle apply. 137 138 Will always be called in the logic thread. 139 """ 140 raise NotImplementedError('Subclasses must override this.') 141 142 def _do_cancel(self) -> None: 143 """Should be overridden by subclasses to handle cancel. 144 145 Will always be called in the logic thread. 146 """ 147 raise NotImplementedError('Subclasses must override this.')
Represents a string editing operation on some object.
Editable objects such as text widgets or in-app-consoles can subclass this to make their contents editable on all platforms.
There can only be one string-edit at a time for the app. New StringEdits will attempt to register themselves as the globally active one in their constructor, but this may not succeed. When creating a StringEditAdapter, always check its 'is_valid()' value after creating it. If this is False, it was not able to set itself as the global active one and should be discarded.
46 def __init__( 47 self, 48 description: str, 49 initial_text: str, 50 max_length: int | None, 51 screen_space_center: tuple[float, float] | None, 52 ) -> None: 53 if not _babase.in_logic_thread(): 54 raise RuntimeError('This must be called from the logic thread.') 55 56 self.create_time = time.monotonic() 57 58 # Note: these attr names are hard-coded in C++ code so don't 59 # change them willy-nilly. 60 self.description = description 61 self.initial_text = initial_text 62 self.max_length = max_length 63 self.screen_space_center = screen_space_center 64 65 # Attempt to register ourself as the active edit. 66 subsys = _babase.app.stringedit 67 current_edit = subsys.active_adapter() 68 if current_edit is None or current_edit.can_be_replaced(): 69 subsys.active_adapter = weakref.ref(self)
71 @final 72 def can_be_replaced(self) -> bool: 73 """Return whether this adapter can be replaced by a new one. 74 75 This is mainly a safeguard to allow adapters whose drivers have 76 gone away without calling apply or cancel to time out and be 77 replaced with new ones. 78 """ 79 if not _babase.in_logic_thread(): 80 raise RuntimeError('This must be called from the logic thread.') 81 82 # Allow ourself to be replaced after a bit. 83 if time.monotonic() - self.create_time > 5.0: 84 if _babase.do_once(): 85 logging.warning( 86 'StringEditAdapter can_be_replaced() check for %s' 87 ' yielding True due to timeout; ideally this should' 88 ' not be possible as the StringEditAdapter driver' 89 ' should be blocking anything else from kicking off' 90 ' new edits.', 91 self, 92 ) 93 return True 94 95 # We also are always considered replaceable if we're not the 96 # active global adapter. 97 current_edit = _babase.app.stringedit.active_adapter() 98 if current_edit is not self: 99 return True 100 101 return False
Return whether this adapter can be replaced by a new one.
This is mainly a safeguard to allow adapters whose drivers have gone away without calling apply or cancel to time out and be replaced with new ones.
103 @final 104 def apply(self, new_text: str) -> None: 105 """Should be called by the owner when editing is complete. 106 107 Note that in some cases this call may be a no-op (such as if 108 this StringEditAdapter is no longer the globally active one). 109 """ 110 if not _babase.in_logic_thread(): 111 raise RuntimeError('This must be called from the logic thread.') 112 113 # Make sure whoever is feeding this adapter is honoring max-length. 114 if self.max_length is not None and len(new_text) > self.max_length: 115 logging.warning( 116 'apply() on %s was passed a string of length %d,' 117 ' but adapter max_length is %d; this should not happen' 118 ' (will truncate).', 119 self, 120 len(new_text), 121 self.max_length, 122 stack_info=True, 123 ) 124 new_text = new_text[: self.max_length] 125 126 self._do_apply(new_text)
Should be called by the owner when editing is complete.
Note that in some cases this call may be a no-op (such as if this StringEditAdapter is no longer the globally active one).
128 @final 129 def cancel(self) -> None: 130 """Should be called by the owner when editing is cancelled.""" 131 if not _babase.in_logic_thread(): 132 raise RuntimeError('This must be called from the logic thread.') 133 self._do_cancel()
Should be called by the owner when editing is cancelled.
25class StringEditSubsystem: 26 """Full string-edit state for the app.""" 27 28 def __init__(self) -> None: 29 self.active_adapter = empty_weakref(StringEditAdapter)
Full string-edit state for the app.
47class TeamNotFoundError(NotFoundError): 48 """Exception raised when an expected bascenev1.Team does not exist. 49 50 Category: **Exception Classes** 51 """
Exception raised when an expected bascenev1.Team does not exist.
Category: Exception Classes
Inherited Members
- builtins.Exception
- Exception
- builtins.BaseException
- with_traceback
- add_note
- args
15def timestring( 16 timeval: float | int, 17 centi: bool = True, 18) -> babase.Lstr: 19 """Generate a babase.Lstr for displaying a time value. 20 21 Category: **General Utility Functions** 22 23 Given a time value, returns a babase.Lstr with: 24 (hours if > 0 ) : minutes : seconds : (centiseconds if centi=True). 25 26 WARNING: the underlying Lstr value is somewhat large so don't use this 27 to rapidly update Node text values for an onscreen timer or you may 28 consume significant network bandwidth. For that purpose you should 29 use a 'timedisplay' Node and attribute connections. 30 31 """ 32 from babase._language import Lstr 33 34 # We take float seconds but operate on int milliseconds internally. 35 timeval = int(1000 * timeval) 36 bits = [] 37 subs = [] 38 hval = (timeval // 1000) // (60 * 60) 39 if hval != 0: 40 bits.append('${H}') 41 subs.append( 42 ( 43 '${H}', 44 Lstr( 45 resource='timeSuffixHoursText', 46 subs=[('${COUNT}', str(hval))], 47 ), 48 ) 49 ) 50 mval = ((timeval // 1000) // 60) % 60 51 if mval != 0: 52 bits.append('${M}') 53 subs.append( 54 ( 55 '${M}', 56 Lstr( 57 resource='timeSuffixMinutesText', 58 subs=[('${COUNT}', str(mval))], 59 ), 60 ) 61 ) 62 63 # We add seconds if its non-zero *or* we haven't added anything else. 64 if centi: 65 # pylint: disable=consider-using-f-string 66 sval = timeval / 1000.0 % 60.0 67 if sval >= 0.005 or not bits: 68 bits.append('${S}') 69 subs.append( 70 ( 71 '${S}', 72 Lstr( 73 resource='timeSuffixSecondsText', 74 subs=[('${COUNT}', ('%.2f' % sval))], 75 ), 76 ) 77 ) 78 else: 79 sval = timeval // 1000 % 60 80 if sval != 0 or not bits: 81 bits.append('${S}') 82 subs.append( 83 ( 84 '${S}', 85 Lstr( 86 resource='timeSuffixSecondsText', 87 subs=[('${COUNT}', str(sval))], 88 ), 89 ) 90 ) 91 return Lstr(value=' '.join(bits), subs=subs)
Generate a Lstr for displaying a time value.
Category: General Utility Functions
Given a time value, returns a 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.
63class UIScale(Enum): 64 """The overall scale the UI is being rendered for. Note that this is 65 independent of pixel resolution. For example, a phone and a desktop PC 66 might render the game at similar pixel resolutions but the size they 67 display content at will vary significantly. 68 69 Category: Enums 70 71 'large' is used for devices such as desktop PCs where fine details can 72 be clearly seen. UI elements are generally smaller on the screen 73 and more content can be seen at once. 74 75 'medium' is used for devices such as tablets, TVs, or VR headsets. 76 This mode strikes a balance between clean readability and amount of 77 content visible. 78 79 'small' is used primarily for phones or other small devices where 80 content needs to be presented as large and clear in order to remain 81 readable from an average distance. 82 """ 83 84 LARGE = 0 85 MEDIUM = 1 86 SMALL = 2
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.
Inherited Members
- enum.Enum
- name
- value
96def utf8_all(data: Any) -> Any: 97 """Convert any unicode data in provided sequence(s) to utf8 bytes.""" 98 if isinstance(data, dict): 99 return dict( 100 (utf8_all(key), utf8_all(value)) 101 for key, value in list(data.items()) 102 ) 103 if isinstance(data, list): 104 return [utf8_all(element) for element in data] 105 if isinstance(data, tuple): 106 return tuple(utf8_all(element) for element in data) 107 if isinstance(data, str): 108 return data.encode('utf-8', errors='ignore') 109 return data
Convert any unicode data in provided sequence(s) to utf8 bytes.
394class Vec3(Sequence[float]): 395 """A vector of 3 floats. 396 397 Category: **General Utility Classes** 398 399 These can be created the following ways (checked in this order): 400 - with no args, all values are set to 0 401 - with a single numeric arg, all values are set to that value 402 - with a single three-member sequence arg, sequence values are copied 403 - otherwise assumes individual x/y/z args (positional or keywords) 404 """ 405 406 x: float 407 """The vector's X component.""" 408 409 y: float 410 """The vector's Y component.""" 411 412 z: float 413 """The vector's Z component.""" 414 415 # pylint: disable=function-redefined 416 417 @overload 418 def __init__(self) -> None: 419 pass 420 421 @overload 422 def __init__(self, value: float): 423 pass 424 425 @overload 426 def __init__(self, values: Sequence[float]): 427 pass 428 429 @overload 430 def __init__(self, x: float, y: float, z: float): 431 pass 432 433 def __init__(self, *args: Any, **kwds: Any): 434 pass 435 436 def __add__(self, other: Vec3) -> Vec3: 437 return self 438 439 def __sub__(self, other: Vec3) -> Vec3: 440 return self 441 442 @overload 443 def __mul__(self, other: float) -> Vec3: 444 return self 445 446 @overload 447 def __mul__(self, other: Sequence[float]) -> Vec3: 448 return self 449 450 def __mul__(self, other: Any) -> Any: 451 return self 452 453 @overload 454 def __rmul__(self, other: float) -> Vec3: 455 return self 456 457 @overload 458 def __rmul__(self, other: Sequence[float]) -> Vec3: 459 return self 460 461 def __rmul__(self, other: Any) -> Any: 462 return self 463 464 # (for index access) 465 @override 466 def __getitem__(self, typeargs: Any) -> Any: 467 return 0.0 468 469 @override 470 def __len__(self) -> int: 471 return 3 472 473 # (for iterator access) 474 @override 475 def __iter__(self) -> Any: 476 return self 477 478 def __next__(self) -> float: 479 return 0.0 480 481 def __neg__(self) -> Vec3: 482 return self 483 484 def __setitem__(self, index: int, val: float) -> None: 485 pass 486 487 def cross(self, other: Vec3) -> Vec3: 488 """Returns the cross product of this vector and another.""" 489 return Vec3() 490 491 def dot(self, other: Vec3) -> float: 492 """Returns the dot product of this vector and another.""" 493 return float() 494 495 def length(self) -> float: 496 """Returns the length of the vector.""" 497 return float() 498 499 def normalized(self) -> Vec3: 500 """Returns a normalized version of the vector.""" 501 return Vec3()
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)
487 def cross(self, other: Vec3) -> Vec3: 488 """Returns the cross product of this vector and another.""" 489 return Vec3()
Returns the cross product of this vector and another.
491 def dot(self, other: Vec3) -> float: 492 """Returns the dot product of this vector and another.""" 493 return float()
Returns the dot product of this vector and another.
499 def normalized(self) -> Vec3: 500 """Returns a normalized version of the vector.""" 501 return Vec3()
Returns a normalized version of the vector.
Inherited Members
- collections.abc.Sequence
- index
- count
15def vec3validate(value: Sequence[float]) -> Sequence[float]: 16 """Ensure a value is valid for use as a Vec3. 17 18 category: General Utility Functions 19 20 Raises a TypeError exception if not. 21 Valid values include any type of sequence consisting of 3 numeric values. 22 Returns the same value as passed in (but with a definite type 23 so this can be used to disambiguate 'Any' types). 24 Generally this should be used in 'if __debug__' or assert clauses 25 to keep runtime overhead minimal. 26 """ 27 from numbers import Number 28 29 if not isinstance(value, abc.Sequence): 30 raise TypeError(f"Expected a sequence; got {type(value)}") 31 if len(value) != 3: 32 raise TypeError(f"Expected a length-3 sequence (got {len(value)})") 33 if not all(isinstance(i, Number) for i in value): 34 raise TypeError(f"Non-numeric value passed for vec3: {value}") 35 return value
Ensure a value is valid for use as a Vec3.
category: General Utility Functions
Raises a TypeError exception if not. Valid values include any type of sequence consisting of 3 numeric values. Returns the same value as passed in (but with a definite type so this can be used to disambiguate 'Any' types). Generally this should be used in 'if __debug__' or assert clauses to keep runtime overhead minimal.
292def verify_object_death(obj: object) -> None: 293 """Warn if an object does not get freed within a short period. 294 295 Category: **General Utility Functions** 296 297 This can be handy to detect and prevent memory/resource leaks. 298 """ 299 300 try: 301 ref = weakref.ref(obj) 302 except Exception: 303 logging.exception('Unable to create weak-ref in verify_object_death') 304 return 305 306 # Use a slight range for our checks so they don't all land at once 307 # if we queue a lot of them. 308 delay = random.uniform(2.0, 5.5) 309 310 # Make this timer in an empty context; don't want it dying with the 311 # scene/etc. 312 with _babase.ContextRef.empty(): 313 _babase.apptimer(delay, Call(_verify_object_death, ref))
Warn if an object does not get freed within a short period.
Category: General Utility Functions
This can be handy to detect and prevent memory/resource leaks.
110class WidgetNotFoundError(NotFoundError): 111 """Exception raised when an expected widget does not exist. 112 113 Category: **Exception Classes** 114 """
Exception raised when an expected widget does not exist.
Category: Exception Classes
Inherited Members
- builtins.Exception
- Exception
- builtins.BaseException
- with_traceback
- add_note
- args