Core · class

LoadTracker

What an app is waiting on, as one weighted number.

Explained in The loop.

class LoadTracker

import { LoadTracker } from '@driftengine/core';

In depth

Why this is in the engine. Every consumer builds this, and every one of them builds it slightly wrong in the same way: a bar driven by whichever load happens to report last, or a fraction over a task count that jumps in sevenths, or a spinner that says nothing at all. None of that is a game's decision — it is arithmetic over a set of things with sizes — so it belongs here beside the things that produce the sizes. What stays with the consumer is every word: this hands back ids and numbers, because what to call a stage depends entirely on who is reading.

It holds no clock and no DOM. A caller polls summary in its own frame, so a tracker works the same in a browser, a test and a headless bake.

Deliberately small. It does not start work, own promises, retry, or time out: a task is something the caller is already doing, and all this knows is how big it is and how far along. Anything more would be a scheduler, which is a different thing with different failure modes.

Accessors

Name	Type	Description
`summary`get	`LoadSummary`	Nothing to wait for. A tracker with no tasks is done, which is the useful answer.
`entries`get	`readonly LoadTask[]`	Every task, for a caller that wants to show a line each rather than one bar.

Methods

`add`

add(id: string, weight: number): void

Declare something to wait for, or re-declare it with a new weight.

Parameter	Type	Description
`id`	`string`
`weight`	`number`

Registering the same id twice is deliberately allowed and is not a reset: a caller frequently learns the real size of a thing after starting it — a fetch that finally reports its Content-Length, a model whose manifest says how many parts are coming — and having to choose between a wrong weight and a lost fraction would be a bad choice to force.

`report`

report(id: string, fraction: number): void

How far along one task is, 0 to 1. Unknown ids are ignored rather than thrown at.

Parameter	Type	Description
`id`	`string`
`fraction`	`number`

`finish`

finish(id: string): void

Mark one finished, whatever it last reported.

Parameter	Type	Description
`id`	`string`

`drop`

drop(id: string): void

A task that turned out not to be needed: dropped from the total rather than completed.

Parameter	Type	Description
`id`	`string`

The distinction matters for the number. An optional asset that is absent — no model baked, a track with no audio — is not 100% loaded, it is not part of this load at all, and counting it as finished makes the bar say a thing arrived that never did.

`clear`

clear(): void