Brighterscript Game Engine

AssetLoader

Runs LoadTasks a little at a time, within a per-frame time budget, so long loads don't freeze the game. A scene gets one in GameScene.onLoad(); game.assets is one you can use at any time for background loading.

Once every queued task has finished, onComplete(loader) is called. Adding a task after that starts a new batch: progress and errors start again from scratch.

A built-in load given a http(s):// URL downloads it first, caching it in cachefs: (see download()).

Properties

  • onComplete (function) — Called once when the queue drains, with this loader
  • timer (BGE.GameTimer) — Measures each update()'s budget
  • stallWarningSeconds (float) — Seconds a task can wait on a task in another loader, with nothing else to do, before a warning is logged
  • maxConcurrentDownloads (integer) — Most downloads this loader runs at once (each loader, including game.assets, has its own

Constructor

new AssetLoader(game: BGE.Game): AssetLoader

Parameters

Instance Methods

addTask(task: BGE.LoadTask): BGE.LoadTask

Queues a task.

Parameters

Returns

addStep( stepFunction: function, context?: dynamic, weight?: float, oncePerFrame?: boolean, ): BGE.LoadTask

Queues a function to be called once per step until it's done. It's passed context and returns true when done, or a number from 0 to 1 for its progress (done at 1). Anything else means "not done yet".

Parameters

  • stepFunction (function) — called as stepFunction(context)
  • context (dynamic, optional, default: "invalid") — passed to every call
  • weight (float, optional, default: "1.0") — its share of overall progress
  • oncePerFrame (boolean, optional, default: false) — call it at most once a frame (e.g. to show a level building), instead of as often as the frame's budget allows

Returns

loadBitmap( bitmapName: string, pathOrUrl: string, options?: BGE.BitmapLoadOptions, ): BGE.LoadTask

Queues loading a bitmap. A http(s):// URL is downloaded first (see download() for caching). On a Roku the image is decoded off the main thread, so even a large one doesn't stall a frame, and it can be resized as it loads.

Parameters

  • bitmapName (string) — the name to get it by later (game.getBitmap())
  • pathOrUrl (string) — local file path or URL
  • options (BGE.BitmapLoadOptions, optional, default: "{}") — resizing and drawable, plus for a URL: caching, timeout and retries

Returns

loadSound( soundName: string, pathOrUrl: string, options?: BGE.DownloadOptions, ): BGE.LoadTask

Queues loading a sound, as game.loadSound() would. A http(s):// URL is downloaded first (see download() for caching).

Parameters

  • soundName (string) — the name to play it by later (game.playSound())
  • pathOrUrl (string) — local file path or URL
  • options (BGE.DownloadOptions, optional, default: "{}") — for a URL: caching, timeout and retries

Returns

load3dModel( modelName: string, pathOrUrl: string, options?: BGE.Model3dLoadOptions, downloadOptions?: BGE.DownloadOptions, ): BGE.LoadTask

Queues loading a .obj or .stl model, parsed a slice at a time so a big model doesn't freeze the screen. A http(s):// URL is downloaded first; an .obj from a URL also downloads its .mtl and texture, found relative to the model's URL. Set the returned task's weight higher than other tasks' for a big model, so the progress bar reflects how long it takes.

Parameters

  • modelName (string) — the name to get it by later (game.get3dModel())
  • pathOrUrl (string) — local file path or URL
  • options (BGE.Model3dLoadOptions, optional, default: "{}") — same options as game.load3dModel(); texturePath may be a URL
  • downloadOptions (BGE.DownloadOptions, optional, default: "{}") — caching, timeout and retries for every download this model needs

Returns

registerFont( pathOrUrl: string, options?: BGE.DownloadOptions, ): BGE.LoadTask

Queues registering a font, as game.registerFont() would. A http(s):// URL is downloaded first (see download() for caching).

Parameters

  • pathOrUrl (string) — local file path or URL
  • options (BGE.DownloadOptions, optional, default: "{}") — for a URL: caching, timeout and retries

Returns

download( url: string, options?: BGE.DownloadOptions, ): BGE.DownloadTask

Queues a download of a URL to a local file. It's saved in the cachefs: cache, so a later download of the same URL (even after a relaunch) uses that file without a request. The OS may clear the cache when space runs low. Once done, the task's localPath is the file.

Parameters

  • url (string) — a http:// or https:// URL
  • options (BGE.DownloadOptions, optional, default: "{}") — cache: false for tmp: instead, refresh: true to download again, timeoutSeconds, retries

Returns

getDownloadTask( url: string, options: BGE.DownloadOptions, ): BGE.DownloadTask

Returns a DownloadTask for a URL, without queueing it. If this loader is already downloading that URL to the same file, the task waits for that download instead of making another request. Otherwise it's a new task from newDownloadTask().

Parameters

Returns

newDownloadTask( url: string, options: BGE.DownloadOptions, ): BGE.DownloadTask

Creates (but doesn't queue) a new DownloadTask for a URL. Used by every download this loader makes - override it to change how downloads are made.

Parameters

Returns

getDownloadSlots(): BGE.DownloadSlots

The slots this loader's downloads share, for a newDownloadTask() override.

Returns

clearCache(): void

Deletes every file in the download cache, so later downloads make a fresh request. Don't call it while downloads are running.

Returns

  • void

hasTasks(): boolean

Whether any tasks are queued in the current batch.

Returns

  • boolean

isDone(): boolean

Whether every queued task has finished (true when nothing is queued).

Returns

  • boolean

getProgress(): float

Overall progress of the current batch, weighted by each task's weight.

Returns

  • float — 0 to 1 (1 when nothing is queued)

getErrors(): Array.<string>

Error messages from tasks in the current batch that failed.

Returns

  • Array.<string>

update(budgetMs: integer): void

Runs task steps until every task is done or budgetMs has been used. Called by Game.

Parameters

  • budgetMs (integer)

Returns

  • void