simvx.core.resource_loader

Background resource loading – threaded loading with progress tracking.

Provides a Godot-style interface for background resource loading with status polling, suitable for loading screens and smooth level transitions.

Public API: from simvx.core.resource_loader import ResourceLoader

ResourceLoader.load_threaded_request("mesh://sphere")
while True:
    status, progress = ResourceLoader.load_threaded_get_status()
    if status == "loaded":
        resource = ResourceLoader.load_threaded_get()
        break
    update_loading_bar(progress)

Module Contents

Classes

LoadStatus	Status of a background load request.
ResourceLoader	Singleton threaded resource loader with progress tracking.

Data

log
__all__

API

simvx.core.resource_loader.log

‘getLogger(…)’

simvx.core.resource_loader.__all__

[‘ResourceLoader’, ‘LoadStatus’]

class simvx.core.resource_loader.LoadStatus

Bases: enum.StrEnum

Status of a background load request.

Initialization

Initialize self. See help(type(self)) for accurate signature.

IDLE

‘idle’

LOADING

‘loading’

LOADED

‘loaded’

ERROR

‘error’

CANCELLED

‘cancelled’

__new__(*values)

__add__()

__contains__()

__delattr__()

__dir__()

__eq__()

__format__()

__ge__()

__getattribute__()

__getitem__()

__getnewargs__()

__getstate__()

__gt__()

__hash__()

__iter__()

__le__()

__len__()

__lt__()

__mod__()

__mul__()

__ne__()

__reduce__()

__reduce_ex__()

__repr__()

__rmod__()

__rmul__()

__setattr__()

__sizeof__()

__str__()

__subclasshook__()

capitalize()

casefold()

center()

count()

encode()

endswith()

expandtabs()

find()

format()

format_map()

index()

isalnum()

isalpha()

isascii()

isdecimal()

isdigit()

isidentifier()

islower()

isnumeric()

isprintable()

isspace()

istitle()

isupper()

join()

ljust()

lower()

lstrip()

partition()

removeprefix()

removesuffix()

replace()

rfind()

rindex()

rjust()

rpartition()

rsplit()

rstrip()

split()

splitlines()

startswith()

strip()

swapcase()

title()

translate()

upper()

zfill()

__deepcopy__(memo)

__copy__()

name()

value()

class simvx.core.resource_loader.ResourceLoader

Singleton threaded resource loader with progress tracking.

Supports loading any resource type via registered loaders. Built-in loaders handle mesh:// and audio:// URIs via ResourceCache.

Pool size and a default per-load timeout can be configured via

Meth:

configure before first use. Call :meth:reset first if the singleton has already been created.

Initialization

classmethod configure(*, max_workers: int = 2, default_timeout: float | None = None) → None

Set pool size and default per-load timeout.

Must be called before the singleton is first accessed. Call

Meth:

reset first to reconfigure an existing instance.

Args: max_workers: Thread pool size (must be >= 1). default_timeout: Default timeout in seconds for all loads, or None for no timeout.

classmethod get() → simvx.core.resource_loader.ResourceLoader

Return the singleton instance.

classmethod reset()

Reset the singleton (for tests). Shuts down the thread pool.

register_loader(scheme: str, loader: collections.abc.Callable[[str], Any]) → None

Register a custom loader for a URI scheme.

Args: scheme: URI scheme (e.g., “texture”, “model”). loader: Callable that takes a URI string and returns the loaded resource.

classmethod load_threaded_request(path: str, loader: collections.abc.Callable[[str], Any] | None = None, *, timeout: float | None = None) → None

Start loading a resource in the background.

Args: path: Resource URI (e.g., “mesh://sphere”, “audio://sfx/boom.wav”). loader: Optional custom loader function. If None, uses registered loader. timeout: Optional per-request timeout in seconds. Overrides the configured default. A waiting load_threaded_get() call will raise TimeoutError once this deadline is exceeded; the worker thread itself is not hard-cancelled.

classmethod cancel(path: str) → bool

Cancel a pending load request.

If the worker has not yet started, the future is cancelled and the request removed. Otherwise the cancellation is best-effort: the loader continues to completion but its result is discarded.

Returns: True if the request was cancelled before it started, False if it was already running or did not exist.

classmethod load_threaded_get_status(path: str = '') → tuple[str, float]

Check the status of a background load.

Args: path: Resource URI. If empty, returns status of the most recent request.

Returns: Tuple of (status_string, progress_float). Status is one of: “idle”, “loading”, “loaded”, “error”, “cancelled”.

classmethod load_threaded_get(path: str = '', *, timeout: float | None = None) → Any

Get the loaded resource (blocks if still loading).

Args: path: Resource URI. If empty, gets the most recent request. timeout: Optional blocking timeout in seconds. Overrides any deadline set on the request at submission time.

Returns: The loaded resource object.

Raises: TimeoutError: If the wait exceeds timeout or the request’s submission-time deadline. RuntimeError: If loading failed or no request exists.

classmethod is_loading() → bool

Check if any resources are currently loading.

classmethod get_progress() → float

Get overall loading progress across all pending requests (0.0 to 1.0).