textmode.js / loading / LoadingPhase

Class: LoadingPhase

Represents a loading phase tracked by a LoadingPhaseTracker.

Allows reporting progress, completion, and failure of the phase.

Also provides a method to track asynchronous tasks within the phase.

Implements

• ILoadingPhase

Properties

Property	Modifier	Type	Description
id	readonly	string	The unique identifier for this loading phase
label	readonly	string	The human-readable label for this loading phase

Methods

complete()

complete(): void;

Mark the loading phase as complete.

Returns

void

Example

const t = textmode.create({ width: 800, height: 600, loadingScreen: { message: 'prepping...' } });

t.setup(() => {
  const phase = t.loading.addPhase('init', 1);
  // Finish phase when work is done
  phase.complete();
});

Implementation of

ILoadingPhase.complete

---

fail()

fail(error?): void;

Mark the loading phase as failed.

This will put the loading manager into an error state, displaying the error on the loading screen.

Parameters

Parameter	Type	Description
error?	string | Error	An optional error object or message describing the failure.

Returns

void

Example

const t = textmode.create({ width: 800, height: 600 });

t.setup(async () => {
  const phase = t.loading.addPhase('fetch', 1);
  try {
    // simulate failure
    throw new Error('network error');
  } catch (err) {
    phase.fail(err instanceof Error ? err : String(err));
  }
});

Implementation of

ILoadingPhase.fail

---

report()

report(progress): void;

Update the progress of the loading phase.

Parameters

Parameter	Type	Description
progress	number	A number between 0 and 1 representing the phase's progress.

Returns

void

Example

const t = textmode.create({ width: 800, height: 600, loadingScreen: { message: 'prepping...' } });

// Create a phase and report progress as work proceeds
t.setup(async () => {
  const phase = t.loading.addPhase('assets', 1);
  phase.report(0.25);
  // ...load assets...
  phase.report(0.75);
  phase.complete();
});

Implementation of

ILoadingPhase.report

---

track()

track<T>(task): Promise<T>;

Track a task within this loading phase.

Type Parameters

Type Parameter
T

Parameters

Parameter	Type	Description
task	Promise<T> | () => T | Promise<T>	A promise or function representing the task to track.

Returns

Promise<T>

A promise that resolves with the task's result.

Example

const t = textmode.create({ width: 800, height: 600, loadingScreen: { message: 'loading...' } });

t.setup(async () => {
  const phase = t.loading.addPhase('video', 2);
  await phase.track(async () => {
    // do async work and report updates
    for (let i = 0; i <= 10; i++) {
      phase.report(i / 10);
      await new Promise((r) => setTimeout(r, 30));
    }
  });
});

Implementation of

ILoadingPhase.track