# Released under the MIT License. See LICENSE for details.
#
"""A dummy stub module for the real _babase.
The real _babase is a compiled extension module and only available
in the live engine. This dummy-module allows Pylint/Mypy/etc. to
function reasonably well outside of that environment.
Make sure this file is never included in dirs seen by the engine!
In the future perhaps this can be a stub (.pyi) file, but we will need
to make sure that it works with all our tools (mypy, pylint, pycharm).
NOTE: This file was autogenerated by batools.dummymodule; do not edit by hand.
"""
# I'm sorry Pylint. I know this file saddens you. Be strong.
# pylint: disable=useless-suppression
# pylint: disable=unnecessary-pass
# pylint: disable=use-dict-literal
# pylint: disable=use-list-literal
# pylint: disable=unused-argument
# pylint: disable=missing-docstring
# pylint: disable=too-many-locals
# pylint: disable=redefined-builtin
# pylint: disable=too-many-lines
# pylint: disable=redefined-outer-name
# pylint: disable=invalid-name
# pylint: disable=no-value-for-parameter
# pylint: disable=unused-import
# pylint: disable=too-many-positional-arguments
from __future__ import annotations
from typing import TYPE_CHECKING, overload, override, Sequence, TypeVar
if TYPE_CHECKING:
from typing import Any, Callable
from babase import App
import babase
_T = TypeVar('_T')
app: App
def _uninferrable() -> Any:
"""Get an "Any" in mypy and "uninferrable" in Pylint."""
# pylint: disable=undefined-variable
return _not_a_real_variable # type: ignore
[docs]
class AppTimer:
"""Timers are used to run code at later points in time.
This class encapsulates a timer based on app-time.
The underlying timer will be destroyed when this object is no longer
referenced. If you do not want to worry about keeping a reference to
your timer around, use the :meth:`~babase.apptimer()` function instead
to get a one-off timer.
Args:
time:
Length of time in seconds that the timer will wait before firing.
call:
A callable Python object. Remember that the timer will retain a
strong reference to the callable for as long as it exists, so you
may want to look into concepts such as :class:`~babase.WeakCall`
if that is not desired.
repeat:
If True, the timer will fire repeatedly, with each successive
firing having the same delay as the first.
Example: Use a timer object to print repeatedly for a few seconds::
def say_it():
babase.screenmessage('BADGER!')
def stop_saying_it():
global g_timer
g_timer = None
babase.screenmessage('MUSHROOM MUSHROOM!')
# Create our timer; it will run as long as we keep its ref alive.
g_timer = babase.AppTimer(0.3, say_it, repeat=True)
# Now fire off a one-shot timer to kill the ref.
babase.apptimer(3.89, stop_saying_it)
"""
def __init__(
self, time: float, call: Callable[[], Any], repeat: bool = False
) -> None:
pass
[docs]
class ContextCall:
"""A context-preserving callable.
This wraps a callable object along with a reference to the current
context (see :class:`~babase.ContextRef`); it handles restoring the
context when run and automatically clears itself if the context it
belongs to dies.
Generally you should not need to use this directly; all standard
Ballistica callbacks involved with timers, materials, UI functions,
etc. handle this under-the-hood so you don't have to worry about it.
The only time it may be necessary is if you are implementing your
own callbacks, such as a worker thread that does some action and then
runs some engine code when done. By wrapping said callback in one of
these, you can ensure that you will not inadvertently be keeping the
current activity alive or running code in a torn-down (expired)
:class:`~babase.ContextRef`.
You can also use :class:`~babase.WeakCall` for similar functionality,
but ContextCall has the added bonus that it will not run during
:class:`~babase.ContextRef` shutdown, whereas
:class:`~babase.WeakCall` simply looks at whether the target object
instance still exists.
**Example A:** Code like this can inadvertently prevent our activity
(self) from ending until the operation completes, since the bound
method we're passing (self.dosomething) contains a strong-reference
to self)::
start_some_long_action(callback_when_done=self.dosomething)
**Example B:** In this case our activity (self) can still die
properly; the callback will clear itself when the activity starts
shutting down, becoming a harmless no-op and releasing the reference
to our activity::
start_long_action(
callback_when_done=babase.ContextCall(self.mycallback))
"""
def __init__(self, call: Callable) -> None:
pass
def __call__(self) -> None:
"""Support for calling."""
pass
[docs]
class ContextRef:
"""Store or use a Ballistica context.
Many operations such as :meth:`bascenev1.newnode()` or
:meth:`bascenev1.gettexture()` operate implicitly on a current
'context'. A context is some sort of state that functionality can
implicitly use. Context determines, for example, which scene new nodes
or textures get added to without having to specify that explicitly in
the newnode()/gettexture() call. Contexts can also affect object
lifecycles; for example a :class:`~babase.ContextCall` will instantly
become a no-op and release any references it is holding when the context it belongs to is destroyed.
In general, if you are a modder, you should not need to worry about
contexts; mod code should mostly be getting run in the correct
context and timers and other callbacks will take care of saving
and restoring contexts automatically. There may be rare cases,
however, where you need to deal directly with contexts, and that is
where this class comes in.
Creating a context-ref will capture a reference to the current
context. Other modules may provide ways to access their contexts; for
example a :class:`bascenev1.Activity` instance has a
:attr:`~bascenev1.Activity.context` attribute. You can also use
the :meth:`~babase.ContextRef.empty()` classmethod to create a
reference to *no* context. Some code such as UI calls may expect
to be run with no context set and may complain if you try to use
them within a context.
Usage
=====
Context-refs are generally used with the Python ``with`` statement, which
sets the context they point to as current on entry and resets it to
the previous value on exit.
Example: Explicitly clear context while working with UI code from
gameplay (UI stuff may complain if called within a context)::
import bauiv1 as bui
def _callback_called_from_gameplay():
# We are probably called with a game context as current, but
# this makes UI stuff unhappy. So we clear the context while
# doing our thing.
with bui.ContextRef.empty():
my_container = bui.containerwidget()
"""
def __init__(
self,
) -> None:
pass
def __enter__(self) -> None:
"""Support for "with" statement."""
pass
def __exit__(self, exc_type: Any, exc_value: Any, traceback: Any) -> Any:
"""Support for "with" statement."""
pass
[docs]
@classmethod
def empty(cls) -> ContextRef:
"""Return a context-ref pointing to no context.
This is useful when code should be run free of a context.
For example, UI code generally insists on being run this way.
Otherwise, callbacks set on the UI could inadvertently stop working
due to a game activity ending, which would be unintuitive behavior.
"""
# This is a dummy stub; the actual implementation is native code.
return ContextRef()
[docs]
def is_empty(self) -> bool:
"""Whether the context was created as empty."""
# This is a dummy stub; the actual implementation is native code.
return bool()
[docs]
def is_expired(self) -> bool:
"""Whether the context has expired.
Returns False for refs created as empty.
"""
# This is a dummy stub; the actual implementation is native code.
return bool()
[docs]
class DisplayTimer:
"""Timers are used to run code at later points in time.
This class encapsulates a timer based on display-time.
The underlying timer will be destroyed when this object is no longer
referenced. If you do not want to worry about keeping a reference to
your timer around, use the :meth:`~babase.displaytimer()` function
instead to get a one-off timer.
Display-time is a time value intended to be used for animation and
other visual purposes. It will generally increment by a consistent
amount each frame. It will pass at an overall similar rate to AppTime,
but trades accuracy for smoothness.
Args:
time:
Length of time in seconds that the timer will wait before firing.
call:
A callable Python object. Remember that the timer will retain a
strong reference to the callable for as long as it exists, so you
may want to look into concepts such as :class:`~babase.WeakCall`
if that is not desired.
repeat:
If True, the timer will fire repeatedly, with each successive
firing having the same delay as the first.
Example: Use a Timer object to print repeatedly for a few seconds::
def say_it():
babase.screenmessage('BADGER!')
def stop_saying_it():
global g_timer
g_timer = None
babase.screenmessage('MUSHROOM MUSHROOM!')
# Create our timer; it will run as long as we keep its ref alive.
g_timer = babase.DisplayTimer(0.3, say_it, repeat=True)
# Now fire off a one-shot timer to kill the ref.
babase.displaytimer(3.89, stop_saying_it)
"""
def __init__(
self, time: float, call: Callable[[], Any], repeat: bool = False
) -> None:
pass
[docs]
class Env:
"""Unchanging values for the current running app instance.
Access the single shared instance of this class through the
:attr:`~babase.App.env` attr on the :class:`~babase.App` class.
"""
android: bool
"""Is this build targeting an Android based OS?"""
api_version: int
"""The app's api version.
Only Python modules and packages associated with the current API
version number will be detected by the game (see the
:class:`babase.MetadataSubsystem`). This value will change whenever
substantial backward-incompatible changes are introduced to
Ballistica APIs. When that happens, modules/packages should be updated
accordingly and set to target the newer API version number."""
arcade: bool
"""Whether the app is targeting an arcade-centric experience."""
config_file_path: str
"""Where the app's config file is stored on disk."""
data_directory: str
"""Where bundled static app data lives."""
debug: bool
"""Whether the app is running in debug mode.
Debug builds generally run substantially slower than non-debug
builds due to compiler optimizations being disabled and extra
checks being run."""
demo: bool
"""Whether the app is targeting a demo experience."""
device_name: str
"""Human readable name of the device running this app."""
engine_build_number: int
"""Integer build number for the engine.
This value increases by at least 1 with each release of the engine.
It is independent of the human readable `version` string."""
engine_version: str
"""Human-readable version string for the engine; something like '1.3.24'.
This should not be interpreted as a number; it may contain
string elements such as 'alpha', 'beta', 'test', etc.
If a numeric version is needed, use `build_number`."""
gui: bool
"""Whether the app is running with a gui.
This is the opposite of `headless`."""
headless: bool
"""Whether the app is running headlessly (without a gui).
This is the opposite of `gui`."""
python_directory_app: str | None
"""Path where the app expects its bundled modules to live.
Be aware that this value may be None if Ballistica is running in
a non-standard environment, and that python-path modifications may
cause modules to be loaded from other locations."""
python_directory_app_site: str | None
"""Path where the app expects its bundled pip modules to live.
Be aware that this value may be None if Ballistica is running in
a non-standard environment, and that python-path modifications may
cause modules to be loaded from other locations."""
python_directory_user: str | None
"""Path where the app expects its user scripts (mods) to live.
Be aware that this value may be None if Ballistica is running in
a non-standard environment, and that python-path modifications may
cause modules to be loaded from other locations."""
supports_soft_quit: bool
"""Whether the running app supports 'soft' quit options.
This generally applies to mobile derived OSs, where an act of
'quitting' may leave the app running in the background waiting
in case it is used again."""
test: bool
"""Whether the app is running in test mode.
Test mode enables extra checks and features that are useful for
release testing but which do not slow the game down significantly."""
tv: bool
"""Whether the app is targeting a TV-centric experience."""
vr: bool
"""Whether the app is currently running in VR."""
pass
class FeatureSetData:
"""Internal."""
pass
class SimpleSound:
"""A simple sound wrapper for internal use.
Do not use for gameplay code as it will only play locally.
:meta private:
"""
def play(self) -> None:
"""Play the sound locally."""
# This is a dummy stub; the actual implementation is native code.
return None
[docs]
class Vec3(Sequence[float]):
"""A vector of 3 floats.
These can be created the following ways (checked in this order):
- With no args, all values are set to 0.
- With a single numeric arg, all values are set to that value.
- With a three-member sequence arg, sequence values are copied.
- Otherwise assumes individual x/y/z args (positional or keywords).
"""
x: float
"""The vector's X component."""
y: float
"""The vector's Y component."""
z: float
"""The vector's Z component."""
# pylint: disable=function-redefined
@overload
def __init__(self) -> None:
pass
@overload
def __init__(self, value: float):
pass
@overload
def __init__(self, values: Sequence[float]):
pass
@overload
def __init__(self, x: float, y: float, z: float):
pass
def __init__(self, *args: Any, **kwds: Any):
pass
def __add__(self, other: Vec3) -> Vec3:
return self
def __sub__(self, other: Vec3) -> Vec3:
return self
@overload
def __mul__(self, other: float) -> Vec3:
return self
@overload
def __mul__(self, other: Sequence[float]) -> Vec3:
return self
def __mul__(self, other: Any) -> Any:
return self
@overload
def __rmul__(self, other: float) -> Vec3:
return self
@overload
def __rmul__(self, other: Sequence[float]) -> Vec3:
return self
def __rmul__(self, other: Any) -> Any:
return self
# (for index access)
@override
def __getitem__(self, typeargs: Any) -> Any:
return 0.0
@override
def __len__(self) -> int:
return 3
# (for iterator access)
@override
def __iter__(self) -> Any:
return self
def __next__(self) -> float:
return 0.0
def __neg__(self) -> Vec3:
return self
def __setitem__(self, index: int, val: float) -> None:
pass
[docs]
def cross(self, other: Vec3) -> Vec3:
"""Returns the cross product of this vector and another."""
# This is a dummy stub; the actual implementation is native code.
return Vec3()
[docs]
def dot(self, other: Vec3) -> float:
"""Returns the dot product of this vector and another."""
# This is a dummy stub; the actual implementation is native code.
return float()
[docs]
def length(self) -> float:
"""Returns the length of the vector."""
# This is a dummy stub; the actual implementation is native code.
return float()
[docs]
def normalized(self) -> Vec3:
"""Returns a normalized version of the vector."""
# This is a dummy stub; the actual implementation is native code.
return Vec3()
def add_clean_frame_callback(call: Callable) -> None:
"""Run code once the next non-progress-bar frame draws.
Useful for queueing things to load in the background without elongating
any current progress-bar-load.
:meta private:
"""
# This is a dummy stub; the actual implementation is native code.
return None
def allows_ticket_sales() -> bool:
""":meta private:"""
# This is a dummy stub; the actual implementation is native code.
return bool()
def android_get_external_files_dir() -> str:
"""Return the android external storage path, or None if there is none.
:meta private:
"""
# This is a dummy stub; the actual implementation is native code.
return str()
def app_instance_uuid() -> str:
""":meta private:"""
# This is a dummy stub; the actual implementation is native code.
return str()
def app_is_active() -> bool:
""":meta private:"""
# This is a dummy stub; the actual implementation is native code.
return bool()
[docs]
def appname() -> str:
"""Return current app name (all lowercase)."""
# This is a dummy stub; the actual implementation is native code.
return str()
[docs]
def appnameupper() -> str:
"""Return current app name with capitalized characters."""
# This is a dummy stub; the actual implementation is native code.
return str()
[docs]
def apptime() -> babase.AppTime:
"""Return the current app-time in seconds.
App-time is a monotonic time value; it starts at 0.0 when the app
launches and will never jump by large amounts or go backwards, even if
the system time changes. Its progression will pause when the app is in
a suspended state.
Note that the AppTime returned here is simply float; it just has a
unique type in the type-checker's eyes to help prevent it from being
accidentally used with time functionality expecting other time types.
"""
# This is a dummy stub; the actual implementation is native code.
import babase # pylint: disable=cyclic-import
return babase.AppTime(0.0)
[docs]
def apptimer(time: float, call: Callable[[], Any]) -> None:
"""Schedule a callable object to run based on app-time.
This function creates a one-off timer which cannot be canceled or
modified once created. If you require the ability to do so, or need
a repeating timer, use the babase.AppTimer class instead.
Args:
time: Length of time in seconds that the timer will wait before
firing.
call: A callable Python object. Note that the timer will retain a
strong reference to the callable for as long as the timer
exists, so you may want to look into concepts such as
:class:`~babase.WeakCall` if that is not desired.
Example: Print some stuff through time::
import babase
babase.screenmessage('hello from now!')
babase.apptimer(1.0, babase.Call(babase.screenmessage,
'hello from the future!'))
babase.apptimer(2.0, babase.Call(babase.screenmessage,
'hello from the future 2!'))
"""
# This is a dummy stub; the actual implementation is native code.
return None
def asset_loads_allowed() -> bool:
""":meta private:"""
# This is a dummy stub; the actual implementation is native code.
return bool()
def audio_shutdown_begin() -> None:
""":meta private:"""
# This is a dummy stub; the actual implementation is native code.
return None
def audio_shutdown_is_complete() -> bool:
""":meta private:"""
# This is a dummy stub; the actual implementation is native code.
return bool()
[docs]
def can_display_chars(text: str) -> bool:
"""Is this build able to display all chars in the provided string?
See also: :meth:`~babase.supports_unicode_display()`.
"""
# This is a dummy stub; the actual implementation is native code.
return bool()
[docs]
def charstr(char_id: babase.SpecialChar) -> str:
"""Return a unicode string representing a special character.
Note that these utilize the private-use block of unicode characters
(U+E000-U+F8FF) and are specific to the game; exporting or rendering
them elsewhere will be meaningless.
See :class:`~babase.SpecialChar` for the list of available characters.
"""
# This is a dummy stub; the actual implementation is native code.
return str()
[docs]
def clipboard_get_text() -> str:
"""Return text currently on the system clipboard.
Ensure that :meth:`~babase.clipboard_has_text()` returns True before
calling this function.
"""
# This is a dummy stub; the actual implementation is native code.
return str()
[docs]
def clipboard_has_text() -> bool:
"""Return whether there is currently text on the clipboard.
This will return False if no system clipboard is available; no need
to call :meth:`~babase.clipboard_is_supported()` separately.
"""
# This is a dummy stub; the actual implementation is native code.
return bool()
[docs]
def clipboard_is_supported() -> bool:
"""Return whether this platform supports clipboard operations at all.
If this returns False, UIs should not show 'copy to clipboard'
buttons, etc.
"""
# This is a dummy stub; the actual implementation is native code.
return bool()
[docs]
def clipboard_set_text(value: str) -> None:
"""Copy a string to the system clipboard.
Ensure that :meth:`~babase.clipboard_is_supported()` returns True before
adding buttons/etc. that make use of this functionality.
"""
# This is a dummy stub; the actual implementation is native code.
return None
def commit_config(config: str) -> None:
""":meta private:"""
# This is a dummy stub; the actual implementation is native code.
return None
def complete_shutdown() -> None:
"""Complete the shutdown process, triggering the app to exit."""
# This is a dummy stub; the actual implementation is native code.
return None
def contains_python_dist() -> bool:
""":meta private:"""
# This is a dummy stub; the actual implementation is native code.
return bool()
def debug_print_py_err() -> None:
"""Debugging func for tracking leaked Python errors in the C++ layer.
:meta private:
"""
# This is a dummy stub; the actual implementation is native code.
return None
def dev_console_add_button(
label: str,
x: float,
y: float,
width: float,
height: float,
call: Callable[[], Any] | None,
h_anchor: str,
label_scale: float,
corner_radius: float,
style: str,
disabled: bool,
) -> None:
""":meta private:"""
# This is a dummy stub; the actual implementation is native code.
return None
def dev_console_add_python_terminal() -> None:
""":meta private:"""
# This is a dummy stub; the actual implementation is native code.
return None
def dev_console_add_text(
text: str,
x: float,
y: float,
h_anchor: str,
h_align: str,
v_align: str,
scale: float,
) -> None:
""":meta private:"""
# This is a dummy stub; the actual implementation is native code.
return None
def dev_console_base_scale() -> float:
""":meta private:"""
# This is a dummy stub; the actual implementation is native code.
return float()
def dev_console_input_adapter_finish() -> None:
""":meta private:"""
# This is a dummy stub; the actual implementation is native code.
return None
def dev_console_request_refresh() -> None:
""":meta private:"""
# This is a dummy stub; the actual implementation is native code.
return None
def dev_console_tab_height() -> float:
""":meta private:"""
# This is a dummy stub; the actual implementation is native code.
return float()
def dev_console_tab_width() -> float:
""":meta private:"""
# This is a dummy stub; the actual implementation is native code.
return float()
[docs]
def displaytime() -> babase.DisplayTime:
"""Return the current display-time in seconds.
Display-time is a time value intended to be used for animation and other
visual purposes. It will generally increment by a consistent amount each
frame. It will pass at an overall similar rate to app-time, but trades
accuracy for smoothness.
Note that the value returned here is simply a float; it just has a
unique type in the type-checker's eyes to help prevent it from being
accidentally used with time functionality expecting other time types.
"""
# This is a dummy stub; the actual implementation is native code.
import babase # pylint: disable=cyclic-import
return babase.DisplayTime(0.0)
[docs]
def displaytimer(time: float, call: Callable[[], Any]) -> None:
"""Schedule a callable object to run based on display-time.
This function creates a one-off timer which cannot be canceled or
modified once created. If you require the ability to do so, or need
a repeating timer, use the :class:`~babase.DisplayTimer` class instead.
Display-time is a time value intended to be used for animation and other
visual purposes. It will generally increment by a consistent amount each
frame. It will pass at an overall similar rate to app-time, but trades
accuracy for smoothness.
Args:
time:
Length of time in seconds that the timer will wait before firing.
call:
A callable Python object. Note that the timer will retain a
strong reference to the callable for as long as the timer exists, so
you may want to look into concepts such as :class:`~babase.WeakCall`
if that is not desired.
Example: Print some stuff through time::
babase.screenmessage('hello from now!')
babase.displaytimer(1.0, babase.Call(babase.screenmessage,
'hello from the future!'))
babase.displaytimer(2.0, babase.Call(babase.screenmessage,
'hello from the future 2!'))
"""
# This is a dummy stub; the actual implementation is native code.
return None
def do_apply_app_config() -> None:
""":meta private:"""
# This is a dummy stub; the actual implementation is native code.
return None
[docs]
def do_once() -> bool:
"""Return whether this is the first time running a line of code.
This is used by ``print_once()`` type calls to keep from overflowing
logs. The call functions by registering the filename and line where
The call is made from. Returns True if this location has not been
registered already, and False if it has.
Example: This print will only fire for the first loop iteration::
for i in range(10):
if babase.do_once():
print('HelloWorld once from loop!')
"""
# This is a dummy stub; the actual implementation is native code.
return bool()
def ehv() -> None:
""":meta private:"""
# This is a dummy stub; the actual implementation is native code.
return None
def emit_log(name: str, level: str, timestamp: float, message: str) -> None:
"""Sends a log message to the in-app console/etc.
This also includes any per-platform log destinations (Android log,
etc.). This generally is not called directly and should instead be
fed Python logging output.
:meta private:
"""
# This is a dummy stub; the actual implementation is native code.
return None
def empty_app_mode_activate() -> None:
""":meta private:"""
# This is a dummy stub; the actual implementation is native code.
return None
def empty_app_mode_deactivate() -> None:
""":meta private:"""
# This is a dummy stub; the actual implementation is native code.
return None
def empty_app_mode_handle_app_intent_default() -> None:
""":meta private:"""
# This is a dummy stub; the actual implementation is native code.
return None
def empty_app_mode_handle_app_intent_exec(command: str) -> None:
""":meta private:"""
# This is a dummy stub; the actual implementation is native code.
return None
def env() -> dict:
"""Return a dict containing general env info.
This has been superseded by :class:`~babase.Env` for most purposes.
:meta private:
"""
# This is a dummy stub; the actual implementation is native code.
return dict()
def evaluate_lstr(value: str) -> str:
""":meta private:"""
# This is a dummy stub; the actual implementation is native code.
return str()
def exec_arg() -> str | None:
""":meta private:"""
# This is a dummy stub; the actual implementation is native code.
return ''
def fade_screen(
to: int = 0, time: float = 0.25, endcall: Callable[[], None] | None = None
) -> None:
"""Fade the screen in or out.
Fade the local game screen in our out from black over a duration of
time. if "to" is 0, the screen will fade out to black. Otherwise
it will fade in from black. If endcall is provided, it will be run after
a completely faded frame is drawn.
:meta private:
"""
# This is a dummy stub; the actual implementation is native code.
return None
[docs]
def fatal_error(message: str) -> None:
"""Trigger a fatal error. Use this in situations where it is not possible
for the engine to continue on in a useful way. This can sometimes
help provide more clear information at the exact source of a problem
as compared to raising an :class:`Exception`. In the vast majority of
cases, however, exceptions should be preferred.
"""
# This is a dummy stub; the actual implementation is native code.
return None
def fullscreen_control_available() -> bool:
""":meta private:"""
# This is a dummy stub; the actual implementation is native code.
return bool()
def fullscreen_control_get() -> bool:
""":meta private:"""
# This is a dummy stub; the actual implementation is native code.
return bool()
def fullscreen_control_key_shortcut() -> str | None:
""":meta private:"""
# This is a dummy stub; the actual implementation is native code.
return ''
def fullscreen_control_set(val: bool) -> None:
""":meta private:"""
# This is a dummy stub; the actual implementation is native code.
return None
def get_appconfig_builtin_keys() -> list[str]:
""":meta private:"""
# This is a dummy stub; the actual implementation is native code.
return ['blah', 'blah2']
def get_appconfig_default_value(key: str) -> Any:
""":meta private:"""
# This is a dummy stub; the actual implementation is native code.
return _uninferrable()
def get_camera_position() -> tuple[float, float, float]:
"""Return current camera position.
WARNING: these camera controls will not apply to network clients
and may behave unpredictably in other ways. Use them only for
tinkering.
:meta private:
"""
# This is a dummy stub; the actual implementation is native code.
return (0.0, 0.0, 0.0)
def get_camera_target() -> tuple[float, float, float]:
"""Return the current camera target point.
WARNING: these camera controls will not apply to network clients
and may behave unpredictably in other ways. Use them only for
tinkering.
:meta private:
"""
# This is a dummy stub; the actual implementation is native code.
return (0.0, 0.0, 0.0)
def get_dev_console_input_text() -> str:
""":meta private:"""
# This is a dummy stub; the actual implementation is native code.
return str()
def get_display_resolution() -> tuple[int, int] | None:
"""Return currently selected display resolution for fullscreen display.
Returns None if resolutions cannot be directly set.
:meta private:
"""
# This is a dummy stub; the actual implementation is native code.
return (0, 0)
def get_draw_virtual_safe_area_bounds() -> bool:
""":meta private:"""
# This is a dummy stub; the actual implementation is native code.
return bool()
def get_idle_time() -> int:
"""Returns the amount of time since any game input has been received.
:meta private:
"""
# This is a dummy stub; the actual implementation is native code.
return int()
def get_immediate_return_code() -> int | None:
""":meta private:"""
# This is a dummy stub; the actual implementation is native code.
return 0
def get_initial_app_config() -> dict:
""":meta private:"""
# This is a dummy stub; the actual implementation is native code.
return dict()
def get_input_idle_time() -> float:
"""Return seconds since any local input occurred (touch, keypress, etc.).
:meta private:
"""
# This is a dummy stub; the actual implementation is native code.
return float()
def get_low_level_config_value(key: str, default_value: int) -> int:
""":meta private:"""
# This is a dummy stub; the actual implementation is native code.
return int()
def get_max_graphics_quality() -> str:
"""Return the max graphics-quality supported on the current hardware.
:meta private:
"""
# This is a dummy stub; the actual implementation is native code.
return str()
def get_replays_dir() -> str:
""":meta private:"""
# This is a dummy stub; the actual implementation is native code.
return str()
def get_string_height(string: str, suppress_warning: bool = False) -> float:
"""Given a string, returns its height with the standard small app font.
:meta private:
"""
# This is a dummy stub; the actual implementation is native code.
return float()
def get_string_width(string: str, suppress_warning: bool = False) -> float:
"""Given a string, returns its width in the standard small app font.
:meta private:
"""
# This is a dummy stub; the actual implementation is native code.
return float()
def get_thread_name() -> str:
"""Return the name of the current thread.
This may vary depending on platform and should not be used in logic;
only for debugging.
:meta private:
"""
# This is a dummy stub; the actual implementation is native code.
return str()
def get_ui_scale() -> str:
""":meta private:"""
# This is a dummy stub; the actual implementation is native code.
return str()
def get_v1_cloud_log() -> str:
""":meta private:"""
# This is a dummy stub; the actual implementation is native code.
return str()
def get_v1_cloud_log_file_path() -> str:
"""Return the path to the app log file.
:meta private:
"""
# This is a dummy stub; the actual implementation is native code.
return str()
[docs]
def get_virtual_safe_area_size() -> tuple[float, float]:
"""Return the size of the area on screen that will always be visible."""
# This is a dummy stub; the actual implementation is native code.
return (0.0, 0.0)
[docs]
def get_virtual_screen_size() -> tuple[float, float]:
"""Return the current virtual size of the display."""
# This is a dummy stub; the actual implementation is native code.
return (0.0, 0.0)
def get_volatile_data_directory() -> str:
"""Return the path to the app volatile data directory.
This directory is for data generated by the app that does not
need to be backed up and can be recreated if necessary.
:meta private:
"""
# This is a dummy stub; the actual implementation is native code.
return str()
def getapp() -> babase.App:
""":meta private:"""
# This is a dummy stub; the actual implementation is native code.
import babase # pylint: disable=cyclic-import
return babase.App()
def getsimplesound(name: str) -> SimpleSound:
""":meta private:"""
# This is a dummy stub; the actual implementation is native code.
return SimpleSound()
def graphics_shutdown_begin() -> None:
""":meta private:"""
# This is a dummy stub; the actual implementation is native code.
return None
def graphics_shutdown_is_complete() -> bool:
""":meta private:"""
# This is a dummy stub; the actual implementation is native code.
return bool()
def has_user_run_commands() -> bool:
""":meta private:"""
# This is a dummy stub; the actual implementation is native code.
return bool()
def hastouchscreen() -> bool:
"""Return whether a touchscreen is present on the current device.
:meta private:
"""
# This is a dummy stub; the actual implementation is native code.
return bool()
def have_permission(permission: babase.Permission) -> bool:
""":meta private:"""
# This is a dummy stub; the actual implementation is native code.
return bool()
[docs]
def in_logic_thread() -> bool:
"""Return whether the current thread is the logic thread.
The logic thread is where a large amount of app code runs, and
various functionality expects to only be used from there.
"""
# This is a dummy stub; the actual implementation is native code.
return bool()
def in_main_menu() -> bool:
"""Are we currently in a main-menu (as opposed to gameplay)?
:meta private:
"""
# This is a dummy stub; the actual implementation is native code.
return bool()
def increment_analytics_count(name: str, increment: int = 1) -> None:
""":meta private:"""
# This is a dummy stub; the actual implementation is native code.
return None
def increment_analytics_count_raw_2(
name: str, uses_increment: bool = True, increment: int = 1
) -> None:
""":meta private:"""
# This is a dummy stub; the actual implementation is native code.
return None
def increment_analytics_counts_raw(name: str, increment: int = 1) -> None:
""":meta private:"""
# This is a dummy stub; the actual implementation is native code.
return None
def invoke_main_menu() -> None:
"""High level call to bring up the main menu if it is not present.
This is essentially the same as pressing the menu button on a
controller.
:meta private:
"""
# This is a dummy stub; the actual implementation is native code.
return None
def is_log_full() -> bool:
""":meta private:"""
# This is a dummy stub; the actual implementation is native code.
return bool()
def is_os_playing_music() -> bool:
"""Return whether the OS is currently playing music of some sort.
Used to determine whether the app should avoid playing its own.
:meta private:
"""
# This is a dummy stub; the actual implementation is native code.
return bool()
def is_xcode_build() -> bool:
""":meta private:"""
# This is a dummy stub; the actual implementation is native code.
return bool()
def lock_all_input() -> None:
"""Prevent all keyboard, mouse, and gamepad events from being processed.
:meta private:
"""
# This is a dummy stub; the actual implementation is native code.
return None
def login_adapter_back_end_active_change(login_type: str, active: bool) -> None:
""":meta private:"""
# This is a dummy stub; the actual implementation is native code.
return None
def login_adapter_get_sign_in_token(login_type: str, attempt_id: int) -> None:
""":meta private:"""
# This is a dummy stub; the actual implementation is native code.
return None
def mac_music_app_get_playlists() -> list[str]:
""":meta private:"""
# This is a dummy stub; the actual implementation is native code.
return ['blah', 'blah2']
def mac_music_app_get_volume() -> int:
""":meta private:"""
# This is a dummy stub; the actual implementation is native code.
return int()
def mac_music_app_init() -> None:
""":meta private:"""
# This is a dummy stub; the actual implementation is native code.
return None
def mac_music_app_play_playlist(playlist: str) -> bool:
""":meta private:"""
# This is a dummy stub; the actual implementation is native code.
return bool()
def mac_music_app_set_volume(volume: int) -> None:
""":meta private:"""
# This is a dummy stub; the actual implementation is native code.
return None
def mac_music_app_stop() -> None:
""":meta private:"""
# This is a dummy stub; the actual implementation is native code.
return None
def mark_log_sent() -> None:
""":meta private:"""
# This is a dummy stub; the actual implementation is native code.
return None
def music_player_play(files: Any) -> None:
"""Start internal music file playback.
:meta private:
"""
# This is a dummy stub; the actual implementation is native code.
return None
def music_player_set_volume(volume: float) -> None:
"""Set internal music player volume.
:meta private:
"""
# This is a dummy stub; the actual implementation is native code.
return None
def music_player_shutdown() -> None:
"""Finalize internal music file playback.
:meta private:
"""
# This is a dummy stub; the actual implementation is native code.
return None
def music_player_stop() -> None:
"""Stops internal music file playback.
:meta private:
"""
# This is a dummy stub; the actual implementation is native code.
return None
def native_review_request() -> None:
""":meta private:"""
# This is a dummy stub; the actual implementation is native code.
return None
def native_review_request_supported() -> bool:
""":meta private:"""
# This is a dummy stub; the actual implementation is native code.
return bool()
[docs]
def native_stack_trace() -> str | None:
"""Return a native stack trace as a string, or None if not available.
Stack traces contain different data and formatting across platforms.
Only use them for debugging.
"""
# This is a dummy stub; the actual implementation is native code.
return ''
def on_app_running() -> None:
""":meta private:"""
# This is a dummy stub; the actual implementation is native code.
return None
def on_initial_app_mode_set() -> None:
""":meta private:"""
# This is a dummy stub; the actual implementation is native code.
return None
def open_dir_externally(path: str) -> None:
"""Open the provided dir in the default external app.
:meta private:
"""
# This is a dummy stub; the actual implementation is native code.
return None
def open_file_externally(path: str) -> None:
"""Open the provided file in the default external app.
:meta private:
"""
# This is a dummy stub; the actual implementation is native code.
return None
[docs]
def open_url(address: str, force_fallback: bool = False) -> None:
"""Open the provided URL.
Attempts to open the provided url in a web-browser. If that is not
possible (or ``force_fallback`` is True), instead displays the url as
a string and/or qrcode.
"""
# This is a dummy stub; the actual implementation is native code.
return None
def overlay_web_browser_close() -> bool:
"""Close any open overlay web browser.
:meta private:
"""
# This is a dummy stub; the actual implementation is native code.
return bool()
def overlay_web_browser_is_open() -> bool:
"""Return whether an overlay web browser is open currently.
:meta private:
"""
# This is a dummy stub; the actual implementation is native code.
return bool()
def overlay_web_browser_is_supported() -> bool:
"""Return whether an overlay web browser is supported here.
An overlay web browser is a small dialog that pops up over the top
of the main engine window. It can be used for performing simple
tasks such as sign-ins.
:meta private:
"""
# This is a dummy stub; the actual implementation is native code.
return bool()
def overlay_web_browser_open_url(address: str) -> None:
"""Open the provided URL in an overlay web browser.
An overlay web browser is a small dialog that pops up over the top
of the main engine window. It can be used for performing simple
tasks such as sign-ins.
:meta private:
"""
# This is a dummy stub; the actual implementation is native code.
return None
def pre_env() -> dict:
"""Return a dict containing general env info.
This has been superseded by :class:`~babase.Env` for most purposes.
:meta private:
"""
# This is a dummy stub; the actual implementation is native code.
return dict()
def print_context() -> None:
"""Prints info about the current context state; for debugging.
:meta private:
"""
# This is a dummy stub; the actual implementation is native code.
return None
def print_load_info() -> None:
""":meta private:"""
# This is a dummy stub; the actual implementation is native code.
return None
def push_back_press() -> None:
""":meta private:"""
# This is a dummy stub; the actual implementation is native code.
return None
[docs]
def pushcall(
call: Callable,
from_other_thread: bool = False,
suppress_other_thread_warning: bool = False,
other_thread_use_fg_context: bool = False,
raw: bool = False,
) -> None:
"""Push a call to the logic-thread's event loop.
This function expects to be called from the logic thread, and will automatically save and restore the context to behave seamlessly.
To push a call from outside of the logic thread, pass
``from_other_thread=True``. In that case the call will run with no
context set. To instead run in whichever context is currently active
on the logic thread, pass ``other_thread_use_fg_context=True``.
Passing ``raw=True`` will skip thread checks and context
saves/restores altogether.
"""
# This is a dummy stub; the actual implementation is native code.
return None
# noinspection PyShadowingBuiltins
[docs]
def quit(
confirm: bool = False, quit_type: babase.QuitType | None = None
) -> None:
"""Quit the app.
If ``confirm`` is True, a confirm dialog will be presented if conditions
allow; otherwise the quit will still be immediate.
See docs for :class:`~babase.QuitType` for explanations of the optional
``quit_type`` arg.
"""
# This is a dummy stub; the actual implementation is native code.
return None
def reached_end_of_babase() -> None:
"""A simple user-agent-string that should be used in any web requests made
on behalf of the engine.
"""
# This is a dummy stub; the actual implementation is native code.
return None
def reload_media() -> None:
"""Reload all currently loaded game media.
Mainly for development/debugging.
:meta private:
"""
# This is a dummy stub; the actual implementation is native code.
return None
def request_permission(permission: babase.Permission) -> None:
""":meta private:"""
# This is a dummy stub; the actual implementation is native code.
return None
def resolve_appconfig_value(key: str) -> Any:
""":meta private:"""
# This is a dummy stub; the actual implementation is native code.
return _uninferrable()
def run_app() -> None:
"""Run the app to completion.
Note that this only works on platforms/builds where ballistica
manages its own event loop.
"""
# This is a dummy stub; the actual implementation is native code.
return None
[docs]
def safecolor(
color: Sequence[float], target_intensity: float = 0.6
) -> tuple[float, ...]:
"""Given a color tuple, return a color safe to display as text.
Accepts tuples of length 3 or 4. This will slightly brighten very
dark colors, etc.
"""
# This is a dummy stub; the actual implementation is native code.
return (0.0, 0.0, 0.0)
[docs]
def screenmessage(
message: str | babase.Lstr,
color: Sequence[float] | None = None,
log: bool = False,
) -> None:
"""Print a message to the local client's screen in a given color.
Note that this function is purely for local display. To broadcast
screen-messages during gameplay, look for methods such as
:meth:`bascenev1.broadcastmessage()`.
"""
# This is a dummy stub; the actual implementation is native code.
return None
def set_analytics_screen(screen: str) -> None:
"""Used for analytics to see where in the app players spend their time.
Generally called when opening a new window or entering some UI.
'screen' should be a string description of an app location
('Main Menu', etc.)
:meta private:
"""
# This is a dummy stub; the actual implementation is native code.
return None
def set_app_config(config: dict) -> None:
""":meta private:"""
# This is a dummy stub; the actual implementation is native code.
return None
def set_camera_manual(value: bool) -> None:
"""Set camera manual mode on or off.
WARNING: these camera controls will not apply to network clients
and may behave unpredictably in other ways. Use them only for
tinkering.
:meta private:
"""
# This is a dummy stub; the actual implementation is native code.
return None
def set_camera_position(x: float, y: float, z: float) -> None:
"""Set camera position.
WARNING: these camera controls will not apply to network clients
and may behave unpredictably in other ways. Use them only for
tinkering.
:meta private:
"""
# This is a dummy stub; the actual implementation is native code.
return None
def set_camera_target(x: float, y: float, z: float) -> None:
"""Set the camera target.
WARNING: these camera controls will not apply to network clients
and may behave unpredictably in other ways. Use them only for
tinkering.
:meta private:
"""
# This is a dummy stub; the actual implementation is native code.
return None
def set_dev_console_input_text(val: str) -> None:
""":meta private:"""
# This is a dummy stub; the actual implementation is native code.
return None
def set_draw_virtual_safe_area_bounds(value: bool) -> None:
""":meta private:"""
# This is a dummy stub; the actual implementation is native code.
return None
def set_internal_language_keys(
listobj: list[tuple[str, str]], random_names_list: list[tuple[str, str]]
) -> None:
""":meta private:"""
# This is a dummy stub; the actual implementation is native code.
return None
def set_low_level_config_value(key: str, value: int) -> None:
""":meta private:"""
# This is a dummy stub; the actual implementation is native code.
return None
def set_platform_misc_read_vals(mode: str) -> None:
""":meta private:"""
# This is a dummy stub; the actual implementation is native code.
return None
def set_thread_name(name: str) -> None:
"""Set the name of the current thread (on platforms where available).
Thread names are only for debugging and should not be used in logic,
as naming behavior can vary across platforms.
:meta private:
"""
# This is a dummy stub; the actual implementation is native code.
return None
def set_ui_account_state(signed_in: bool, name: str | None = None) -> None:
""":meta private:"""
# This is a dummy stub; the actual implementation is native code.
return None
def set_ui_input_device(input_device_id: int | None) -> None:
"""Sets the input-device that currently owns the user interface.
:meta private:
"""
# This is a dummy stub; the actual implementation is native code.
return None
def set_ui_scale(scale: str) -> None:
""":meta private:"""
# This is a dummy stub; the actual implementation is native code.
return None
def setup_sigint() -> None:
""":meta private:"""
# This is a dummy stub; the actual implementation is native code.
return None
def show_progress_bar() -> None:
""":meta private:"""
# This is a dummy stub; the actual implementation is native code.
return None
def shutdown_suppress_begin() -> bool:
""":meta private:"""
# This is a dummy stub; the actual implementation is native code.
return bool()
def shutdown_suppress_count() -> int:
""":meta private:"""
# This is a dummy stub; the actual implementation is native code.
return int()
def shutdown_suppress_end() -> None:
""":meta private:"""
# This is a dummy stub; the actual implementation is native code.
return None
def submit_analytics_counts() -> None:
""":meta private:"""
# This is a dummy stub; the actual implementation is native code.
return None
def supports_max_fps() -> bool:
""":meta private:"""
# This is a dummy stub; the actual implementation is native code.
return bool()
def supports_open_dir_externally() -> bool:
"""Return whether current app/platform supports opening dirs externally.
(Via the Mac Finder, Windows Explorer, etc.)
:meta private:
"""
# This is a dummy stub; the actual implementation is native code.
return bool()
[docs]
def supports_unicode_display() -> bool:
"""Return whether we can display all unicode characters in the gui."""
# This is a dummy stub; the actual implementation is native code.
return bool()
def supports_vsync() -> bool:
""":meta private:"""
# This is a dummy stub; the actual implementation is native code.
return bool()
def temp_testing() -> bool:
""":meta private:"""
# This is a dummy stub; the actual implementation is native code.
return bool()
def unlock_all_input() -> None:
"""Resume normal keyboard, mouse, and gamepad event processing.
:meta private:
"""
# This is a dummy stub; the actual implementation is native code.
return None
def update_internal_logger_levels() -> None:
"""Update the native layer to re-cache Python logger levels.
The native layer caches logger levels so it can efficiently
avoid making Python log calls for disabled logger levels. If any
logger levels are changed at runtime, call this method after to
instruct the native layer to regenerate its cache so the change
is properly reflected in logs originating from the native layer.
:meta private:
"""
# This is a dummy stub; the actual implementation is native code.
return None
def user_agent_string() -> str:
""":meta private:"""
# This is a dummy stub; the actual implementation is native code.
return str()
def user_ran_commands() -> None:
""":meta private:"""
# This is a dummy stub; the actual implementation is native code.
return None
def using_game_center() -> bool:
""":meta private:"""
# This is a dummy stub; the actual implementation is native code.
return bool()
def using_google_play_game_services() -> bool:
""":meta private:"""
# This is a dummy stub; the actual implementation is native code.
return bool()
def v1_cloud_log(message: str) -> None:
"""Push messages to the old v1 cloud log.
:meta private:
"""
# This is a dummy stub; the actual implementation is native code.
return None
def workspaces_in_use() -> bool:
"""Return whether workspace functionality was ever enabled this run.
:meta private:
"""
# This is a dummy stub; the actual implementation is native code.
return bool()
# Docs-generation hack; import some stuff that we likely only forward-declared
# in our actual source code so that docs tools can find it.
from typing import (Coroutine, Any, Literal, Callable,
Generator, Awaitable, Sequence, Self)
import asyncio
from concurrent.futures import Future