babase

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

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

89class ActivityNotFoundError(NotFoundError):
90    """Exception raised when an expected bascenev1.Activity does not exist.
91
92    Category: **Exception Classes**
93    """

82class ActorNotFoundError(NotFoundError):
83    """Exception raised when an expected actor does not exist.
84
85    Category: **Exception Classes**
86    """

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