babase

426class AccountV2Handle:
427    """Handle for interacting with a V2 account.
428
429    This class supports the 'with' statement, which is how it is
430    used with some operations such as cloud messaging.
431    """
432
433    accountid: str
434    tag: str
435    workspacename: str | None
436    workspaceid: str | None
437    logins: dict[LoginType, LoginInfo]
438
439    def __enter__(self) -> None:
440        """Support for "with" statement.
441
442        This allows cloud messages to be sent on our behalf.
443        """
444
445    def __exit__(self, exc_type: Any, exc_value: Any, traceback: Any) -> Any:
446        """Support for "with" statement.
447
448        This allows cloud messages to be sent on our behalf.
449        """

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

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    """

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