babase

443class AccountV2Handle:
444    """Handle for interacting with a V2 account.
445
446    This class supports the 'with' statement, which is how it is
447    used with some operations such as cloud messaging.
448    """
449
450    accountid: str
451    tag: str
452    workspacename: str | None
453    workspaceid: str | None
454    logins: dict[LoginType, LoginInfo]
455
456    def __enter__(self) -> None:
457        """Support for "with" statement.
458
459        This allows cloud messages to be sent on our behalf.
460        """
461
462    def __exit__(self, exc_type: Any, exc_value: Any, traceback: Any) -> Any:
463        """Support for "with" statement.
464
465        This allows cloud messages to be sent on our behalf.
466        """

 26class AccountV2Subsystem:
 27    """Subsystem for modern account handling in the app.
 28
 29    Access the single shared instance of this class at 'ba.app.plus.accounts'.
 30    """
 31
 32    def __init__(self) -> None:
 33        assert _babase.in_logic_thread()
 34
 35        from babase._login import LoginAdapterGPGS, LoginAdapterGameCenter
 36
 37        # Register to be informed when connectivity changes.
 38        plus = _babase.app.plus
 39        self._connectivity_changed_cb = (
 40            None
 41            if plus is None
 42            else plus.cloud.on_connectivity_changed_callbacks.register(
 43                self._on_cloud_connectivity_changed
 44            )
 45        )
 46
 47        # Whether or not everything related to an initial sign in (or
 48        # lack thereof) has completed. This includes things like
 49        # workspace syncing. Completion of this is what flips the app
 50        # into 'running' state.
 51        self._initial_sign_in_completed = False
 52
 53        self._kicked_off_workspace_load = False
 54
 55        self.login_adapters: dict[LoginType, LoginAdapter] = {}
 56
 57        self._implicit_signed_in_adapter: LoginAdapter | None = None
 58        self._implicit_state_changed = False
 59        self._can_do_auto_sign_in = True
 60        self.on_primary_account_changed_callbacks: CallbackSet[
 61            Callable[[AccountV2Handle | None], None]
 62        ] = CallbackSet()
 63
 64        adapter: LoginAdapter
 65        if _babase.using_google_play_game_services():
 66            adapter = LoginAdapterGPGS()
 67            self.login_adapters[adapter.login_type] = adapter
 68        if _babase.using_game_center():
 69            adapter = LoginAdapterGameCenter()
 70            self.login_adapters[adapter.login_type] = adapter
 71
 72    def on_app_loading(self) -> None:
 73        """Should be called at standard on_app_loading time."""
 74
 75        for adapter in self.login_adapters.values():
 76            adapter.on_app_loading()
 77
 78    def have_primary_credentials(self) -> bool:
 79        """Are credentials currently set for the primary app account?
 80
 81        Note that this does not mean these credentials have been checked
 82        for validity; only that they exist. If/when credentials are
 83        validated, the 'primary' account handle will be set.
 84        """
 85        raise NotImplementedError()
 86
 87    @property
 88    def primary(self) -> AccountV2Handle | None:
 89        """The primary account for the app, or None if not logged in."""
 90        return self.do_get_primary()
 91
 92    def on_primary_account_changed(
 93        self, account: AccountV2Handle | None
 94    ) -> None:
 95        """Callback run after the primary account changes.
 96
 97        Will be called with None on log-outs and when new credentials
 98        are set but have not yet been verified.
 99        """
100        assert _babase.in_logic_thread()
101
102        # Fire any registered callbacks.
103        for call in self.on_primary_account_changed_callbacks.getcalls():
104            try:
105                call(account)
106            except Exception:
107                logging.exception('Error in primary-account-changed callback.')
108
109        # Currently don't do anything special on sign-outs.
110        if account is None:
111            return
112
113        # If this new account has a workspace, update it and ask to be
114        # informed when that process completes.
115        if account.workspaceid is not None:
116            assert account.workspacename is not None
117            if (
118                not self._initial_sign_in_completed
119                and not self._kicked_off_workspace_load
120            ):
121                self._kicked_off_workspace_load = True
122                _babase.app.workspaces.set_active_workspace(
123                    account=account,
124                    workspaceid=account.workspaceid,
125                    workspacename=account.workspacename,
126                    on_completed=self._on_set_active_workspace_completed,
127                )
128            else:
129                # Don't activate workspaces if we've already told the
130                # game that initial-log-in is done or if we've already
131                # kicked off a workspace load.
132                _babase.screenmessage(
133                    f'\'{account.workspacename}\''
134                    f' will be activated at next app launch.',
135                    color=(1, 1, 0),
136                )
137                _babase.getsimplesound('error').play()
138            return
139
140        # Ok; no workspace to worry about; carry on.
141        if not self._initial_sign_in_completed:
142            self._initial_sign_in_completed = True
143            _babase.app.on_initial_sign_in_complete()
144
145    def on_active_logins_changed(self, logins: dict[LoginType, str]) -> None:
146        """Should be called when logins for the active account change."""
147
148        for adapter in self.login_adapters.values():
149            adapter.set_active_logins(logins)
150
151    def on_implicit_sign_in(
152        self, login_type: LoginType, login_id: str, display_name: str
153    ) -> None:
154        """An implicit sign-in happened (called by native layer)."""
155        from babase._login import LoginAdapter
156
157        assert _babase.in_logic_thread()
158
159        with _babase.ContextRef.empty():
160            self.login_adapters[login_type].set_implicit_login_state(
161                LoginAdapter.ImplicitLoginState(
162                    login_id=login_id, display_name=display_name
163                )
164            )
165
166    def on_implicit_sign_out(self, login_type: LoginType) -> None:
167        """An implicit sign-out happened (called by native layer)."""
168        assert _babase.in_logic_thread()
169        with _babase.ContextRef.empty():
170            self.login_adapters[login_type].set_implicit_login_state(None)
171
172    def on_no_initial_primary_account(self) -> None:
173        """Callback run if the app has no primary account after launch.
174
175        Either this callback or on_primary_account_changed will be called
176        within a few seconds of app launch; the app can move forward
177        with the startup sequence at that point.
178        """
179        if not self._initial_sign_in_completed:
180            self._initial_sign_in_completed = True
181            _babase.app.on_initial_sign_in_complete()
182
183    @staticmethod
184    def _hashstr(val: str) -> str:
185        md5 = hashlib.md5()
186        md5.update(val.encode())
187        return md5.hexdigest()
188
189    def on_implicit_login_state_changed(
190        self,
191        login_type: LoginType,
192        state: LoginAdapter.ImplicitLoginState | None,
193    ) -> None:
194        """Called when implicit login state changes.
195
196        Login systems that tend to sign themselves in/out in the
197        background are considered implicit. We may choose to honor or
198        ignore their states, allowing the user to opt for other login
199        types even if the default implicit one can't be explicitly
200        logged out or otherwise controlled.
201        """
202        from babase._language import Lstr
203
204        assert _babase.in_logic_thread()
205
206        cfg = _babase.app.config
207        cfgkey = 'ImplicitLoginStates'
208        cfgdict = _babase.app.config.setdefault(cfgkey, {})
209
210        # Store which (if any) adapter is currently implicitly signed
211        # in. Making the assumption there will only ever be one implicit
212        # adapter at a time; may need to revisit this logic if that
213        # changes.
214        prev_state = cfgdict.get(login_type.value)
215        if state is None:
216            self._implicit_signed_in_adapter = None
217            new_state = cfgdict[login_type.value] = None
218        else:
219            self._implicit_signed_in_adapter = self.login_adapters[login_type]
220            new_state = cfgdict[login_type.value] = self._hashstr(
221                state.login_id
222            )
223
224            # Special case: if the user is already signed in but not
225            # with this implicit login, let them know that the 'Welcome
226            # back FOO' they likely just saw is not actually accurate.
227            if (
228                self.primary is not None
229                and not self.login_adapters[login_type].is_back_end_active()
230            ):
231                service_str: Lstr | None
232                if login_type is LoginType.GPGS:
233                    service_str = Lstr(resource='googlePlayText')
234                elif login_type is LoginType.GAME_CENTER:
235                    # Note: Apparently Game Center is just called 'Game
236                    # Center' in all languages. Can revisit if not true.
237                    # https://developer.apple.com/forums/thread/725779
238                    service_str = Lstr(value='Game Center')
239                elif login_type is LoginType.EMAIL:
240                    # Not possible; just here for exhaustive coverage.
241                    service_str = None
242                else:
243                    assert_never(login_type)
244                if service_str is not None:
245                    _babase.apptimer(
246                        2.0,
247                        partial(
248                            _babase.screenmessage,
249                            Lstr(
250                                resource='notUsingAccountText',
251                                subs=[
252                                    ('${ACCOUNT}', state.display_name),
253                                    ('${SERVICE}', service_str),
254                                ],
255                            ),
256                            (1, 0.5, 0),
257                        ),
258                    )
259
260        cfg.commit()
261
262        # We want to respond any time the implicit state changes;
263        # generally this means the user has explicitly signed in/out or
264        # switched accounts within that back-end.
265        if prev_state != new_state:
266            logger.debug(
267                'Implicit state changed (%s -> %s);'
268                ' will update app sign-in state accordingly.',
269                prev_state,
270                new_state,
271            )
272            self._implicit_state_changed = True
273
274        # We may want to auto-sign-in based on this new state.
275        self._update_auto_sign_in()
276
277    def _on_cloud_connectivity_changed(self, connected: bool) -> None:
278        """Should be called with cloud connectivity changes."""
279        del connected  # Unused.
280        assert _babase.in_logic_thread()
281
282        # We may want to auto-sign-in based on this new state.
283        self._update_auto_sign_in()
284
285    def do_get_primary(self) -> AccountV2Handle | None:
286        """Internal; should be overridden by subclass.
287
288        :meta private:
289        """
290        raise NotImplementedError()
291
292    def set_primary_credentials(self, credentials: str | None) -> None:
293        """Set credentials for the primary app account."""
294        raise NotImplementedError()
295
296    def _update_auto_sign_in(self) -> None:
297        plus = _babase.app.plus
298        assert plus is not None
299
300        # If implicit state has changed, try to respond.
301        if self._implicit_state_changed:
302            if self._implicit_signed_in_adapter is None:
303                # If implicit back-end has signed out, we follow suit
304                # immediately; no need to wait for network connectivity.
305                logger.debug(
306                    'Signing out as result of implicit state change...',
307                )
308                plus.accounts.set_primary_credentials(None)
309                self._implicit_state_changed = False
310
311                # Once we've made a move here we don't want to
312                # do any more automatic stuff.
313                self._can_do_auto_sign_in = False
314
315            else:
316                # Ok; we've got a new implicit state. If we've got
317                # connectivity, let's attempt to sign in with it.
318                # Consider this an 'explicit' sign in because the
319                # implicit-login state change presumably was triggered
320                # by some user action (signing in, signing out, or
321                # switching accounts via the back-end). NOTE: should
322                # test case where we don't have connectivity here.
323                if plus.cloud.is_connected():
324                    logger.debug(
325                        'Signing in as result of implicit state change...',
326                    )
327                    self._implicit_signed_in_adapter.sign_in(
328                        self._on_explicit_sign_in_completed,
329                        description='implicit state change',
330                    )
331                    self._implicit_state_changed = False
332
333                    # Once we've made a move here we don't want to
334                    # do any more automatic stuff.
335                    self._can_do_auto_sign_in = False
336
337        if not self._can_do_auto_sign_in:
338            return
339
340        # If we're not currently signed in, we have connectivity, and
341        # we have an available implicit login, auto-sign-in with it once.
342        # The implicit-state-change logic above should keep things
343        # mostly in-sync, but that might not always be the case due to
344        # connectivity or other issues. We prefer to keep people signed
345        # in as a rule, even if there are corner cases where this might
346        # not be what they want (A user signing out and then restarting
347        # may be auto-signed back in).
348        connected = plus.cloud.is_connected()
349        signed_in_v1 = plus.get_v1_account_state() == 'signed_in'
350        signed_in_v2 = plus.accounts.have_primary_credentials()
351        if (
352            connected
353            and not signed_in_v1
354            and not signed_in_v2
355            and self._implicit_signed_in_adapter is not None
356        ):
357            logger.debug(
358                'Signing in due to on-launch-auto-sign-in...',
359            )
360            self._can_do_auto_sign_in = False  # Only ATTEMPT once
361            self._implicit_signed_in_adapter.sign_in(
362                self._on_implicit_sign_in_completed, description='auto-sign-in'
363            )
364
365    def _on_explicit_sign_in_completed(
366        self,
367        adapter: LoginAdapter,
368        result: LoginAdapter.SignInResult | Exception,
369    ) -> None:
370        """A sign-in has completed that the user asked for explicitly."""
371        from babase._language import Lstr
372
373        del adapter  # Unused.
374
375        plus = _babase.app.plus
376        assert plus is not None
377
378        # Make some noise on errors since the user knows a
379        # sign-in attempt is happening in this case (the 'explicit' part).
380        if isinstance(result, Exception):
381            # We expect the occasional communication errors;
382            # Log a full exception for anything else though.
383            if not isinstance(result, CommunicationError):
384                logging.warning(
385                    'Error on explicit accountv2 sign in attempt.',
386                    exc_info=result,
387                )
388
389            # For now just show 'error'. Should do better than this.
390            _babase.screenmessage(
391                Lstr(resource='internal.signInErrorText'),
392                color=(1, 0, 0),
393            )
394            _babase.getsimplesound('error').play()
395
396            # Also I suppose we should sign them out in this case since
397            # it could be misleading to be still signed in with the old
398            # account.
399            plus.accounts.set_primary_credentials(None)
400            return
401
402        plus.accounts.set_primary_credentials(result.credentials)
403
404    def _on_implicit_sign_in_completed(
405        self,
406        adapter: LoginAdapter,
407        result: LoginAdapter.SignInResult | Exception,
408    ) -> None:
409        """A sign-in has completed that the user didn't ask for explicitly."""
410        plus = _babase.app.plus
411        assert plus is not None
412
413        del adapter  # Unused.
414
415        # Log errors but don't inform the user; they're not aware of this
416        # attempt and ignorance is bliss.
417        if isinstance(result, Exception):
418            # We expect the occasional communication errors;
419            # Log a full exception for anything else though.
420            if not isinstance(result, CommunicationError):
421                logging.warning(
422                    'Error on implicit accountv2 sign in attempt.',
423                    exc_info=result,
424                )
425            return
426
427        # If we're still connected and still not signed in,
428        # plug in the credentials we got. We want to be extra cautious
429        # in case the user has since explicitly signed in since we
430        # kicked off.
431        connected = plus.cloud.is_connected()
432        signed_in_v1 = plus.get_v1_account_state() == 'signed_in'
433        signed_in_v2 = plus.accounts.have_primary_credentials()
434        if connected and not signed_in_v1 and not signed_in_v2:
435            plus.accounts.set_primary_credentials(result.credentials)
436
437    def _on_set_active_workspace_completed(self) -> None:
438        if not self._initial_sign_in_completed:
439            self._initial_sign_in_completed = True
440            _babase.app.on_initial_sign_in_complete()

61class ActivityNotFoundError(NotFoundError):
62    """Exception raised when an expected bascenev1.Activity does not exist."""

57class ActorNotFoundError(NotFoundError):
58    """Exception raised when an expected actor does not exist."""

506def allows_ticket_sales() -> bool:
507    """:meta private:"""
508    return bool()

  52class App:
  53    """High level Ballistica app functionality and state.
  54
  55    Access the single shared instance of this class via the "app" attr
  56    available on various high level modules such as :mod:`bauiv1` and
  57    :mod:`bascenev1`.
  58    """
  59
  60    # pylint: disable=too-many-public-methods
  61
  62    class State(Enum):
  63        """High level state the app can be in."""
  64
  65        #: The app has not yet begun starting and should not be used in
  66        #: any way.
  67        NOT_STARTED = 0
  68
  69        #: The native layer is spinning up its machinery (screens,
  70        #: renderers, etc.). Nothing should happen in the Python layer
  71        #: until this completes.
  72        NATIVE_BOOTSTRAPPING = 1
  73
  74        #: Python app subsystems are being inited but should not yet
  75        #: interact or do any work.
  76        INITING = 2
  77
  78        #: Python app subsystems are inited and interacting, but the app
  79        #: has not yet embarked on a high level course of action. It is
  80        #: doing initial account logins, workspace & asset downloads,
  81        #: etc.
  82        LOADING = 3
  83
  84        #: All pieces are in place and the app is now doing its thing.
  85        RUNNING = 4
  86
  87        #: Used on platforms such as mobile where the app basically needs
  88        #: to shut down while backgrounded. In this state, all event
  89        #: loops are suspended and all graphics and audio must cease
  90        #: completely. Be aware that the suspended state can be entered
  91        #: from any other state including NATIVE_BOOTSTRAPPING and
  92        #: SHUTTING_DOWN.
  93        SUSPENDED = 5
  94
  95        #: The app is shutting down. This process may involve sending
  96        #: network messages or other things that can take up to a few
  97        #: seconds, so ideally graphics and audio should remain
  98        #: functional (with fades or spinners or whatever to show
  99        #: something is happening).
 100        SHUTTING_DOWN = 6
 101
 102        #: The app has completed shutdown. Any code running here should
 103        #: be basically immediate.
 104        SHUTDOWN_COMPLETE = 7
 105
 106    class DefaultAppModeSelector(AppModeSelector):
 107        """Decides which AppMode to use to handle AppIntents.
 108
 109        This default version is generated by the project updater based
 110        on the 'default_app_modes' value in the projectconfig.
 111
 112        It is also possible to modify app mode selection behavior by
 113        setting app.mode_selector to an instance of a custom
 114        AppModeSelector subclass. This is a good way to go if you are
 115        modifying app behavior dynamically via a plugin instead of
 116        statically in a spinoff project.
 117        """
 118
 119        @override
 120        def app_mode_for_intent(
 121            self, intent: AppIntent
 122        ) -> type[AppMode] | None:
 123            # pylint: disable=cyclic-import
 124
 125            # __DEFAULT_APP_MODE_SELECTION_BEGIN__
 126            # This section generated by batools.appmodule; do not edit.
 127
 128            # Ask our default app modes to handle it.
 129            # (generated from 'default_app_modes' in projectconfig).
 130            import baclassic
 131            import babase
 132
 133            for appmode in [
 134                baclassic.ClassicAppMode,
 135                babase.EmptyAppMode,
 136            ]:
 137                if appmode.can_handle_intent(intent):
 138                    return appmode
 139
 140            return None
 141
 142            # __DEFAULT_APP_MODE_SELECTION_END__
 143
 144    # A few things defined as non-optional values but not actually
 145    # available until the app starts.
 146    plugins: PluginSubsystem
 147    lang: LanguageSubsystem
 148    health_monitor: AppHealthMonitor
 149
 150    # Define some other types here in the class-def so docs-generators
 151    # are more likely to know about them.
 152    config: AppConfig
 153    env: babase.Env
 154    state: State
 155    threadpool: ThreadPoolExecutorPlus
 156    meta: MetadataSubsystem
 157    net: NetworkSubsystem
 158    workspaces: WorkspaceSubsystem
 159    components: AppComponentSubsystem
 160    stringedit: StringEditSubsystem
 161    devconsole: DevConsoleSubsystem
 162    fg_state: int
 163
 164    #: How long we allow shutdown tasks to run before killing them.
 165    #: Currently the entire app hard-exits if shutdown takes 15 seconds,
 166    #: so we need to keep it under that. Staying above 10 should allow
 167    #: 10 second network timeouts to happen though.
 168    SHUTDOWN_TASK_TIMEOUT_SECONDS = 12
 169
 170    def __init__(self) -> None:
 171        """(internal)
 172
 173        Do not instantiate this class. You can access the single shared
 174        instance of it through various high level packages: 'babase.app',
 175        'bascenev1.app', 'bauiv1.app', etc.
 176        """
 177
 178        # Hack for docs-generation: we can be imported with dummy modules
 179        # instead of our actual binary ones, but we don't function.
 180        if os.environ.get('BA_RUNNING_WITH_DUMMY_MODULES') == '1':
 181            return
 182
 183        # Wrap our raw app config in our special wrapper and pass it to
 184        # the native layer.
 185        self.config = AppConfig(_babase.get_initial_app_config())
 186        _babase.set_app_config(self.config)
 187
 188        self.env = _babase.Env()
 189        self.state = self.State.NOT_STARTED
 190
 191        # Default executor which can be used for misc background
 192        # processing. It should also be passed to any additional asyncio
 193        # loops we create so that everything shares the same single set
 194        # of worker threads.
 195        self.threadpool = ThreadPoolExecutorPlus(
 196            thread_name_prefix='baworker',
 197            initializer=self._thread_pool_thread_init,
 198        )
 199        self.meta = MetadataSubsystem()
 200        self.net = NetworkSubsystem()
 201        self.workspaces = WorkspaceSubsystem()
 202        self.components = AppComponentSubsystem()
 203        self.stringedit = StringEditSubsystem()
 204        self.devconsole = DevConsoleSubsystem()
 205
 206        # This is incremented any time the app is backgrounded or
 207        # foregrounded; can be a simple way to determine if network data
 208        # should be refreshed/etc.
 209        self.fg_state = 0
 210
 211        self._subsystems: list[AppSubsystem] = []
 212        self._native_bootstrapping_completed = False
 213        self._init_completed = False
 214        self._meta_scan_completed = False
 215        self._native_start_called = False
 216        self._native_suspended = False
 217        self._native_shutdown_called = False
 218        self._native_shutdown_complete_called = False
 219        self._initial_sign_in_completed = False
 220        self._called_on_initing = False
 221        self._called_on_loading = False
 222        self._called_on_running = False
 223        self._subsystem_registration_ended = False
 224        self._pending_apply_app_config = False
 225        self._asyncio_loop: asyncio.AbstractEventLoop | None = None
 226        self._asyncio_tasks: set[asyncio.Task] = set()
 227        self._asyncio_timer: babase.AppTimer | 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 mode(self) -> AppMode | None:
 275        """The app's current mode."""
 276        assert _babase.in_logic_thread()
 277        return self._mode
 278
 279    @property
 280    def asyncio_loop(self) -> asyncio.AbstractEventLoop:
 281        """The logic thread's asyncio event loop.
 282
 283        This allow async tasks to be run in the logic thread.
 284
 285        Generally you should call App.create_async_task() to schedule
 286        async code to run instead of using this directly. That will
 287        handle retaining the task and logging errors automatically.
 288        Only schedule tasks onto asyncio_loop yourself when you intend
 289        to hold on to the returned task and await its results. Releasing
 290        the task reference can lead to subtle bugs such as unreported
 291        errors and garbage-collected tasks disappearing before their
 292        work is done.
 293
 294        Note that, at this time, the asyncio loop is encapsulated
 295        and explicitly stepped by the engine's logic thread loop and
 296        thus things like asyncio.get_running_loop() will unintuitively
 297        *not* return this loop from most places in the logic thread;
 298        only from within a task explicitly created in this loop.
 299        Hopefully this situation will be improved in the future with a
 300        unified event loop.
 301        """
 302        assert _babase.in_logic_thread()
 303        assert self._asyncio_loop is not None
 304        return self._asyncio_loop
 305
 306    def create_async_task(
 307        self, coro: Coroutine[Any, Any, T], *, name: str | None = None
 308    ) -> None:
 309        """Create a fully managed async task.
 310
 311        This will automatically retain and release a reference to the task
 312        and log any exceptions that occur in it. If you need to await a task
 313        or otherwise need more control, schedule a task directly using
 314        App.asyncio_loop.
 315        """
 316        assert _babase.in_logic_thread()
 317
 318        # We hold a strong reference to the task until it is done.
 319        # Otherwise it is possible for it to be garbage collected and
 320        # disappear midway if the caller does not hold on to the
 321        # returned task, which seems like a great way to introduce
 322        # hard-to-track bugs.
 323        task = self.asyncio_loop.create_task(coro, name=name)
 324        self._asyncio_tasks.add(task)
 325        task.add_done_callback(self._on_task_done)
 326
 327    def _on_task_done(self, task: asyncio.Task) -> None:
 328        # Report any errors that occurred.
 329        try:
 330            exc = task.exception()
 331            if exc is not None:
 332                logging.error(
 333                    "Error in async task '%s'.", task.get_name(), exc_info=exc
 334                )
 335        except Exception:
 336            logging.exception('Error reporting async task error.')
 337
 338        self._asyncio_tasks.remove(task)
 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        :py:const:`SHUTDOWN_TASK_TIMEOUT_SECONDS` if they are still
 485        running.
 486        """
 487        if (
 488            self.state is self.State.SHUTTING_DOWN
 489            or self.state is self.State.SHUTDOWN_COMPLETE
 490        ):
 491            stname = self.state.name
 492            raise RuntimeError(
 493                f'Cannot add shutdown tasks with current state {stname}.'
 494            )
 495        self._shutdown_tasks.append(coro)
 496
 497    def run(self) -> None:
 498        """Run the app to completion.
 499
 500        Note that this only works on builds where Ballistica manages
 501        its own event loop.
 502        """
 503        _babase.run_app()
 504
 505    def set_intent(self, intent: AppIntent) -> None:
 506        """Set the intent for the app.
 507
 508        Intent defines what the app is trying to do at a given time.
 509        This call is asynchronous; the intent switch will happen in the
 510        logic thread in the near future. If set_intent is called
 511        repeatedly before the change takes place, the final intent to be
 512        set will be used.
 513        """
 514
 515        # Mark this one as pending. We do this synchronously so that the
 516        # last one marked actually takes effect if there is overlap
 517        # (doing this in the bg thread could result in race conditions).
 518        self._pending_intent = intent
 519
 520        # Do the actual work of calcing our app-mode/etc. in a bg thread
 521        # since it may block for a moment to load modules/etc.
 522        self.threadpool.submit_no_wait(self._set_intent, intent)
 523
 524    def push_apply_app_config(self) -> None:
 525        """Internal. Use app.config.apply() to apply app config changes."""
 526        # To be safe, let's run this by itself in the event loop.
 527        # This avoids potential trouble if this gets called mid-draw or
 528        # something like that.
 529        self._pending_apply_app_config = True
 530        _babase.pushcall(self._apply_app_config, raw=True)
 531
 532    def on_native_start(self) -> None:
 533        """Called by the native layer when the app is being started."""
 534        assert _babase.in_logic_thread()
 535        assert not self._native_start_called
 536        self._native_start_called = True
 537        self._update_state()
 538
 539    def on_native_bootstrapping_complete(self) -> None:
 540        """Called by the native layer once its ready to rock."""
 541        assert _babase.in_logic_thread()
 542        assert not self._native_bootstrapping_completed
 543        self._native_bootstrapping_completed = True
 544        self._update_state()
 545
 546    def on_native_suspend(self) -> None:
 547        """Called by the native layer when the app is suspended."""
 548        assert _babase.in_logic_thread()
 549        assert not self._native_suspended  # Should avoid redundant calls.
 550        self._native_suspended = True
 551        self._update_state()
 552
 553    def on_native_unsuspend(self) -> None:
 554        """Called by the native layer when the app suspension ends."""
 555        assert _babase.in_logic_thread()
 556        assert self._native_suspended  # Should avoid redundant calls.
 557        self._native_suspended = False
 558        self._update_state()
 559
 560    def on_native_shutdown(self) -> None:
 561        """Called by the native layer when the app starts shutting down."""
 562        assert _babase.in_logic_thread()
 563        self._native_shutdown_called = True
 564        self._update_state()
 565
 566    def on_native_shutdown_complete(self) -> None:
 567        """Called by the native layer when the app is done shutting down."""
 568        assert _babase.in_logic_thread()
 569        self._native_shutdown_complete_called = True
 570        self._update_state()
 571
 572    def on_native_active_changed(self) -> None:
 573        """Called by the native layer when the app active state changes."""
 574        assert _babase.in_logic_thread()
 575        if self._mode is not None:
 576            self._mode.on_app_active_changed()
 577
 578    def handle_deep_link(self, url: str) -> None:
 579        """Handle a deep link URL."""
 580        from babase._language import Lstr
 581
 582        assert _babase.in_logic_thread()
 583
 584        appname = _babase.appname()
 585        if url.startswith(f'{appname}://code/'):
 586            code = url.replace(f'{appname}://code/', '')
 587            if self.classic is not None:
 588                self.classic.accounts.add_pending_promo_code(code)
 589        else:
 590            try:
 591                _babase.screenmessage(
 592                    Lstr(resource='errorText'), color=(1, 0, 0)
 593                )
 594                _babase.getsimplesound('error').play()
 595            except ImportError:
 596                pass
 597
 598    def on_initial_sign_in_complete(self) -> None:
 599        """Called when initial sign-in (or lack thereof) completes.
 600
 601        This normally gets called by the plus subsystem. The
 602        initial-sign-in process may include tasks such as syncing
 603        account workspaces or other data so it may take a substantial
 604        amount of time.
 605        """
 606        assert _babase.in_logic_thread()
 607        assert not self._initial_sign_in_completed
 608
 609        # Tell meta it can start scanning extra stuff that just showed
 610        # up (namely account workspaces).
 611        self.meta.start_extra_scan()
 612
 613        self._initial_sign_in_completed = True
 614        self._update_state()
 615
 616    def set_ui_scale(self, scale: babase.UIScale) -> None:
 617        """Change ui-scale on the fly.
 618
 619        Currently this is mainly for debugging and will not be called as
 620        part of normal app operation.
 621        """
 622        assert _babase.in_logic_thread()
 623
 624        # Apply to the native layer.
 625        _babase.set_ui_scale(scale.name.lower())
 626
 627        # Inform all subsystems that something screen-related has
 628        # changed. We assume subsystems won't be added at this point so
 629        # we can use the list directly.
 630        assert self._subsystem_registration_ended
 631        for subsystem in self._subsystems:
 632            try:
 633                subsystem.on_ui_scale_change()
 634            except Exception:
 635                logging.exception(
 636                    'Error in on_ui_scale_change() for subsystem %s.', subsystem
 637                )
 638
 639    def on_screen_size_change(self) -> None:
 640        """Screen size has changed."""
 641
 642        # Inform all app subsystems in the same order they were inited.
 643        # Operate on a copy of the list here because this can be called
 644        # while subsystems are still being added.
 645        for subsystem in self._subsystems.copy():
 646            try:
 647                subsystem.on_screen_size_change()
 648            except Exception:
 649                logging.exception(
 650                    'Error in on_screen_size_change() for subsystem %s.',
 651                    subsystem,
 652                )
 653
 654    def _set_intent(self, intent: AppIntent) -> None:
 655        from babase._appmode import AppMode
 656
 657        # This should be happening in a bg thread.
 658        assert not _babase.in_logic_thread()
 659        try:
 660            # Ask the selector what app-mode to use for this intent.
 661            if self.mode_selector is None:
 662                raise RuntimeError('No AppModeSelector set.')
 663
 664            modetype: type[AppMode] | None
 665
 666            # Special case - for testing we may force a specific
 667            # app-mode to handle this intent instead of going through our
 668            # usual selector.
 669            forced_mode_type = getattr(intent, '_force_app_mode_handler', None)
 670            if isinstance(forced_mode_type, type) and issubclass(
 671                forced_mode_type, AppMode
 672            ):
 673                modetype = forced_mode_type
 674            else:
 675                modetype = self.mode_selector.app_mode_for_intent(intent)
 676
 677            # NOTE: Since intents are somewhat high level things,
 678            # perhaps we should do some universal thing like a
 679            # screenmessage saying 'The app cannot handle the request'
 680            # on failure.
 681
 682            if modetype is None:
 683                raise RuntimeError(
 684                    f'No app-mode found to handle app-intent'
 685                    f' type {type(intent)}.'
 686                )
 687
 688            # Make sure the app-mode the selector gave us *actually*
 689            # supports the intent.
 690            if not modetype.can_handle_intent(intent):
 691                raise RuntimeError(
 692                    f'Intent {intent} cannot be handled by AppMode type'
 693                    f' {modetype} (selector {self.mode_selector}'
 694                    f' incorrectly thinks that it can be).'
 695                )
 696
 697            # Ok; seems legit. Now instantiate the mode if necessary and
 698            # kick back to the logic thread to apply.
 699            mode = self._mode_instances.get(modetype)
 700            if mode is None:
 701                self._mode_instances[modetype] = mode = modetype()
 702            _babase.pushcall(
 703                partial(self._apply_intent, intent, mode),
 704                from_other_thread=True,
 705            )
 706        except Exception:
 707            logging.exception('Error setting app intent to %s.', intent)
 708            _babase.pushcall(
 709                partial(self._display_set_intent_error, intent),
 710                from_other_thread=True,
 711            )
 712
 713    def _apply_intent(self, intent: AppIntent, mode: AppMode) -> None:
 714        assert _babase.in_logic_thread()
 715
 716        # ONLY apply this intent if it is still the most recent one
 717        # submitted.
 718        if intent is not self._pending_intent:
 719            return
 720
 721        # If the app-mode for this intent is different than the active
 722        # one, switch modes.
 723        if type(mode) is not type(self._mode):
 724            if self._mode is None:
 725                is_initial_mode = True
 726            else:
 727                is_initial_mode = False
 728                try:
 729                    self._mode.on_deactivate()
 730                except Exception:
 731                    logging.exception(
 732                        'Error deactivating app-mode %s.', self._mode
 733                    )
 734
 735            # Reset all subsystems. We assume subsystems won't be added
 736            # at this point so we can use the list directly.
 737            assert self._subsystem_registration_ended
 738            for subsystem in self._subsystems:
 739                try:
 740                    subsystem.reset()
 741                except Exception:
 742                    logging.exception(
 743                        'Error in reset() for subsystem %s.', subsystem
 744                    )
 745
 746            self._mode = mode
 747            try:
 748                mode.on_activate()
 749            except Exception:
 750                # Hmm; what should we do in this case?...
 751                logging.exception('Error activating app-mode %s.', mode)
 752
 753            # Let the world know when we first have an app-mode; certain
 754            # app stuff such as input processing can proceed at that
 755            # point.
 756            if is_initial_mode:
 757                _babase.on_initial_app_mode_set()
 758
 759        try:
 760            mode.handle_intent(intent)
 761        except Exception:
 762            logging.exception(
 763                'Error handling intent %s in app-mode %s.', intent, mode
 764            )
 765
 766    def _display_set_intent_error(self, intent: AppIntent) -> None:
 767        """Show the *user* something went wrong setting an intent."""
 768        from babase._language import Lstr
 769
 770        del intent
 771        _babase.screenmessage(Lstr(resource='errorText'), color=(1, 0, 0))
 772        _babase.getsimplesound('error').play()
 773
 774    def _on_initing(self) -> None:
 775        """Called when the app enters the initing state.
 776
 777        Here we can put together subsystems and other pieces for the
 778        app, but most things should not be doing any work yet.
 779        """
 780        # pylint: disable=cyclic-import
 781        from babase import _asyncio
 782        from babase import _appconfig
 783        from babase._apputils import AppHealthMonitor
 784        from babase import _env
 785
 786        assert _babase.in_logic_thread()
 787
 788        _env.on_app_state_initing()
 789
 790        self._asyncio_loop = _asyncio.setup_asyncio()
 791        self.health_monitor = AppHealthMonitor()
 792
 793        # __FEATURESET_APP_SUBSYSTEM_CREATE_BEGIN__
 794        # This section generated by batools.appmodule; do not edit.
 795
 796        # Poke these attrs to create all our subsystems.
 797        _ = self.plus
 798        _ = self.classic
 799        _ = self.ui_v1
 800
 801        # __FEATURESET_APP_SUBSYSTEM_CREATE_END__
 802
 803        # We're a pretty short-lived state. This should flip us to
 804        # 'loading'.
 805        self._init_completed = True
 806        self._update_state()
 807
 808    def _on_loading(self) -> None:
 809        """Called when we enter the loading state.
 810
 811        At this point, all built-in pieces of the app should be in place
 812        and can start talking to each other and doing work. Though at a
 813        high level, the goal of the app at this point is only to sign in
 814        to initial accounts, download workspaces, and otherwise prepare
 815        itself to really 'run'.
 816        """
 817        assert _babase.in_logic_thread()
 818
 819        # Get meta-system scanning built-in stuff in the bg.
 820        self.meta.start_scan(scan_complete_cb=self._on_meta_scan_complete)
 821
 822        # Inform all app subsystems in the same order they were inited.
 823        # Operate on a copy of the list here because subsystems can
 824        # still be added at this point.
 825        for subsystem in self._subsystems.copy():
 826            try:
 827                subsystem.on_app_loading()
 828            except Exception:
 829                logging.exception(
 830                    'Error in on_app_loading() for subsystem %s.', subsystem
 831                )
 832
 833        # Normally plus tells us when initial sign-in is done. If plus
 834        # is not present, however, we just do it ourself so we can
 835        # proceed on to the running state.
 836        if self.plus is None:
 837            _babase.pushcall(self.on_initial_sign_in_complete)
 838
 839    def _on_meta_scan_complete(self) -> None:
 840        """Called when meta-scan is done doing its thing."""
 841        assert _babase.in_logic_thread()
 842
 843        # Now that we know what's out there, build our final plugin set.
 844        self.plugins.on_meta_scan_complete()
 845
 846        assert not self._meta_scan_completed
 847        self._meta_scan_completed = True
 848        self._update_state()
 849
 850    def _on_running(self) -> None:
 851        """Called when we enter the running state.
 852
 853        At this point, all workspaces, initial accounts, etc. are in place
 854        and we can actually get started doing whatever we're gonna do.
 855        """
 856        assert _babase.in_logic_thread()
 857
 858        # Let our native layer know.
 859        _babase.on_app_running()
 860
 861        # Set a default app-mode-selector if none has been set yet
 862        # by a plugin or whatnot.
 863        if self._mode_selector is None:
 864            self._mode_selector = self.DefaultAppModeSelector()
 865
 866        # Inform all app subsystems in the same order they were
 867        # registered. Operate on a copy here because subsystems can
 868        # still be added at this point.
 869        #
 870        # NOTE: Do we need to allow registering still at this point? If
 871        # something gets registered here, it won't have its
 872        # on_app_running callback called. Hmm; I suppose that's the only
 873        # way that plugins can register subsystems though.
 874        for subsystem in self._subsystems.copy():
 875            try:
 876                subsystem.on_app_running()
 877            except Exception:
 878                logging.exception(
 879                    'Error in on_app_running() for subsystem %s.', subsystem
 880                )
 881
 882        # Cut off new subsystem additions at this point.
 883        self._subsystem_registration_ended = True
 884
 885        # If 'exec' code was provided to the app, always kick that off
 886        # here as an intent.
 887        exec_cmd = _babase.exec_arg()
 888        if exec_cmd is not None:
 889            self.set_intent(AppIntentExec(exec_cmd))
 890        elif self._pending_intent is None:
 891            # Otherwise tell the app to do its default thing *only* if a
 892            # plugin hasn't already told it to do something.
 893            self.set_intent(AppIntentDefault())
 894
 895    def _apply_app_config(self) -> None:
 896        assert _babase.in_logic_thread()
 897
 898        lifecyclelog.info('apply-app-config')
 899
 900        # If multiple apply calls have been made, only actually apply
 901        # once.
 902        if not self._pending_apply_app_config:
 903            return
 904
 905        _pending_apply_app_config = False
 906
 907        # Inform all app subsystems in the same order they were inited.
 908        # Operate on a copy here because subsystems may still be able to
 909        # be added at this point.
 910        for subsystem in self._subsystems.copy():
 911            try:
 912                subsystem.do_apply_app_config()
 913            except Exception:
 914                logging.exception(
 915                    'Error in do_apply_app_config() for subsystem %s.',
 916                    subsystem,
 917                )
 918
 919        # Let the native layer do its thing.
 920        _babase.do_apply_app_config()
 921
 922    def _update_state(self) -> None:
 923        # pylint: disable=too-many-branches
 924        assert _babase.in_logic_thread()
 925
 926        # Shutdown-complete trumps absolutely all.
 927        if self._native_shutdown_complete_called:
 928            if self.state is not self.State.SHUTDOWN_COMPLETE:
 929                self.state = self.State.SHUTDOWN_COMPLETE
 930                lifecyclelog.info('app-state is now %s', self.state.name)
 931                self._on_shutdown_complete()
 932
 933        # Shutdown trumps all. Though we can't start shutting down until
 934        # init is completed since we need our asyncio stuff to exist for
 935        # the shutdown process.
 936        elif self._native_shutdown_called and self._init_completed:
 937            # Entering shutdown state:
 938            if self.state is not self.State.SHUTTING_DOWN:
 939                self.state = self.State.SHUTTING_DOWN
 940                applog.info('Shutting down...')
 941                lifecyclelog.info('app-state is now %s', self.state.name)
 942                self._on_shutting_down()
 943
 944        elif self._native_suspended:
 945            # Entering suspended state:
 946            if self.state is not self.State.SUSPENDED:
 947                self.state = self.State.SUSPENDED
 948                self._on_suspend()
 949        else:
 950            # Leaving suspended state:
 951            if self.state is self.State.SUSPENDED:
 952                self._on_unsuspend()
 953
 954            # Entering or returning to running state
 955            if self._initial_sign_in_completed and self._meta_scan_completed:
 956                if self.state != self.State.RUNNING:
 957                    self.state = self.State.RUNNING
 958                    lifecyclelog.info('app-state is now %s', self.state.name)
 959                    if not self._called_on_running:
 960                        self._called_on_running = True
 961                        self._on_running()
 962
 963            # Entering or returning to loading state:
 964            elif self._init_completed:
 965                if self.state is not self.State.LOADING:
 966                    self.state = self.State.LOADING
 967                    lifecyclelog.info('app-state is now %s', self.state.name)
 968                    if not self._called_on_loading:
 969                        self._called_on_loading = True
 970                        self._on_loading()
 971
 972            # Entering or returning to initing state:
 973            elif self._native_bootstrapping_completed:
 974                if self.state is not self.State.INITING:
 975                    self.state = self.State.INITING
 976                    lifecyclelog.info('app-state is now %s', self.state.name)
 977                    if not self._called_on_initing:
 978                        self._called_on_initing = True
 979                        self._on_initing()
 980
 981            # Entering or returning to native bootstrapping:
 982            elif self._native_start_called:
 983                if self.state is not self.State.NATIVE_BOOTSTRAPPING:
 984                    self.state = self.State.NATIVE_BOOTSTRAPPING
 985                    lifecyclelog.info('app-state is now %s', self.state.name)
 986            else:
 987                # Only logical possibility left is NOT_STARTED, in which
 988                # case we should not be getting called.
 989                logging.warning(
 990                    'App._update_state called while in %s state;'
 991                    ' should not happen.',
 992                    self.state.value,
 993                    stack_info=True,
 994                )
 995
 996    async def _shutdown(self) -> None:
 997        import asyncio
 998
 999        _babase.lock_all_input()
1000        try:
1001            async with asyncio.TaskGroup() as task_group:
1002                for task_coro in self._shutdown_tasks:
1003                    # Note: Mypy currently complains if we don't take
1004                    # this return value, but we don't actually need to.
1005                    # https://github.com/python/mypy/issues/15036
1006                    _ = task_group.create_task(
1007                        self._run_shutdown_task(task_coro)
1008                    )
1009        except* Exception:
1010            logging.exception('Unexpected error(s) in shutdown.')
1011
1012        # Note: ideally we should run this directly here, but currently
1013        # it does some legacy stuff which blocks, so running it here
1014        # gives us asyncio task-took-too-long warnings. If we can
1015        # convert those to nice graceful async tasks we should revert
1016        # this to a direct call.
1017        _babase.pushcall(_babase.complete_shutdown)
1018
1019    async def _run_shutdown_task(
1020        self, coro: Coroutine[None, None, None]
1021    ) -> None:
1022        """Run a shutdown task; report errors and abort if taking too long."""
1023        import asyncio
1024
1025        task = asyncio.create_task(coro)
1026        try:
1027            await asyncio.wait_for(task, self.SHUTDOWN_TASK_TIMEOUT_SECONDS)
1028        except Exception:
1029            logging.exception('Error in shutdown task (%s).', coro)
1030
1031    def _on_suspend(self) -> None:
1032        """Called when the app goes to a suspended state."""
1033        assert _babase.in_logic_thread()
1034
1035        # Suspend all app subsystems in the opposite order they were inited.
1036        for subsystem in reversed(self._subsystems):
1037            try:
1038                subsystem.on_app_suspend()
1039            except Exception:
1040                logging.exception(
1041                    'Error in on_app_suspend() for subsystem %s.', subsystem
1042                )
1043
1044    def _on_unsuspend(self) -> None:
1045        """Called when unsuspending."""
1046        assert _babase.in_logic_thread()
1047        self.fg_state += 1
1048
1049        # Unsuspend all app subsystems in the same order they were inited.
1050        for subsystem in self._subsystems:
1051            try:
1052                subsystem.on_app_unsuspend()
1053            except Exception:
1054                logging.exception(
1055                    'Error in on_app_unsuspend() for subsystem %s.', subsystem
1056                )
1057
1058    def _on_shutting_down(self) -> None:
1059        """(internal)"""
1060        assert _babase.in_logic_thread()
1061
1062        # Inform app subsystems that we're shutting down in the opposite
1063        # order they were inited.
1064        for subsystem in reversed(self._subsystems):
1065            try:
1066                subsystem.on_app_shutdown()
1067            except Exception:
1068                logging.exception(
1069                    'Error in on_app_shutdown() for subsystem %s.', subsystem
1070                )
1071
1072        # Now kick off any async shutdown task(s).
1073        assert self._asyncio_loop is not None
1074        self._shutdown_task = self._asyncio_loop.create_task(self._shutdown())
1075
1076    def _on_shutdown_complete(self) -> None:
1077        """(internal)"""
1078        assert _babase.in_logic_thread()
1079
1080        # Deactivate any active app-mode. This allows things like saving
1081        # state to happen naturally without needing to handle
1082        # app-shutdown as a special case.
1083        if self._mode is not None:
1084            try:
1085                self._mode.on_deactivate()
1086            except Exception:
1087                logging.exception(
1088                    'Error deactivating app-mode %s at app shutdown.',
1089                    self._mode,
1090                )
1091            self._mode = None
1092
1093        # Inform app subsystems that we're done shutting down in the opposite
1094        # order they were inited.
1095        for subsystem in reversed(self._subsystems):
1096            try:
1097                subsystem.on_app_shutdown_complete()
1098            except Exception:
1099                logging.exception(
1100                    'Error in on_app_shutdown_complete() for subsystem %s.',
1101                    subsystem,
1102                )
1103
1104    async def _wait_for_shutdown_suppressions(self) -> None:
1105        import asyncio
1106
1107        # Spin and wait for anything blocking shutdown to complete.
1108        starttime = _babase.apptime()
1109        lifecyclelog.info('shutdown-suppress-wait begin')
1110        while _babase.shutdown_suppress_count() > 0:
1111            await asyncio.sleep(0.001)
1112        lifecyclelog.info('shutdown-suppress-wait end')
1113        duration = _babase.apptime() - starttime
1114        if duration > 1.0:
1115            logging.warning(
1116                'Shutdown-suppressions lasted longer than ideal '
1117                '(%.2f seconds).',
1118                duration,
1119            )
1120
1121    async def _fade_and_shutdown_graphics(self) -> None:
1122        import asyncio
1123
1124        # Kick off a short fade and give it time to complete.
1125        lifecyclelog.info('fade-and-shutdown-graphics begin')
1126        _babase.fade_screen(False, time=0.15)
1127        await asyncio.sleep(0.15)
1128
1129        # Now tell the graphics system to go down and wait until
1130        # it has done so.
1131        _babase.graphics_shutdown_begin()
1132        while not _babase.graphics_shutdown_is_complete():
1133            await asyncio.sleep(0.01)
1134        lifecyclelog.info('fade-and-shutdown-graphics end')
1135
1136    async def _fade_and_shutdown_audio(self) -> None:
1137        import asyncio
1138
1139        # Tell the audio system to go down and give it a bit of
1140        # time to do so gracefully.
1141        lifecyclelog.info('fade-and-shutdown-audio begin')
1142        _babase.audio_shutdown_begin()
1143        await asyncio.sleep(0.15)
1144        while not _babase.audio_shutdown_is_complete():
1145            await asyncio.sleep(0.01)
1146        lifecyclelog.info('fade-and-shutdown-audio end')
1147
1148    def _thread_pool_thread_init(self) -> None:
1149        # Help keep things clear in profiling tools/etc.
1150        self._pool_thread_count += 1
1151        _babase.set_thread_name(f'ballistica worker-{self._pool_thread_count}')