Preloader API
RUN.world shows a loading screen while your game boots. Use this API to report progress while it is up, and to bring it back for heavy work after startup — scene changes, large downloads.
Quick Start
import RundotGameAPI from '@series-inc/rundot-game-sdk/api'
await RundotGameAPI.preloader.showLoadScreen()
await loadCriticalAssets()
await RundotGameAPI.preloader.hideLoadScreen()By default the host hides its loading screen as soon as your game is ready, and you do not need to call hideLoadScreen() at startup. Titles deployed with uses-preloader true instead keep the loading screen up until they call hideLoadScreen() themselves — see below.
CLI Configuration (deprecated)
rundot --configure uses-preloader truetrue makes the host keep its loading screen up until your game calls hideLoadScreen(). false (the default) lets the host reveal your game as soon as it is ready.
This flag is deprecated. If your game needs cover past startup, prefer drawing your own in-game loading screen: it renders identically across every RUN surface and cannot leave players stuck if your load path fails. On current RUN clients, a title that sets true and never calls hideLoadScreen() is failed to an error screen within about 5 minutes rather than loading forever.
Progress Updates
Show loading progress to keep players informed:
Scene Transitions
Use the preloader for heavy scene transitions:
API Reference
preloader.showLoadScreen()
Promise<void>
Show the native loading screen
preloader.hideLoadScreen()
Promise<void>
Hide the loading screen
preloader.setLoaderText(text)
Promise<void>
Update the loading message
preloader.setLoaderProgress(progress)
Promise<void>
Update progress (0.0 to 1.0)
Best Practices
Always wrap show/hide in
try/catch: the host might already be transitioning.Use
showLoadScreen()when navigating between scenes that require large downloads.Pair hide calls with your own readiness checks to avoid flashing unpopulated UI.
Consider chaining with
assetLibrary.loadAssetsBundleto ensure large bundles are ready before dismissal.Avoid leaving the preloader up for long-standing idle states; fade to your own UI for parking experiences.
Dismiss the loader from
onResumeif you paused during loading to prevent stale spinners.
Last updated