babase

416class AccountV2Handle:
417    """Handle for interacting with a V2 account.
418
419    This class supports the 'with' statement, which is how it is
420    used with some operations such as cloud messaging.
421    """
422
423    def __init__(self) -> None:
424        self.tag = '?'
425
426        self.workspacename: str | None = None
427        self.workspaceid: str | None = None
428
429        # Login types and their display-names associated with this account.
430        self.logins: dict[LoginType, str] = {}
431
432    def __enter__(self) -> None:
433        """Support for "with" statement.
434
435        This allows cloud messages to be sent on our behalf.
436        """
437
438    def __exit__(self, exc_type: Any, exc_value: Any, traceback: Any) -> Any:
439        """Support for "with" statement.
440
441        This allows cloud messages to be sent on our behalf.
442        """

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

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