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