Skip to main content

Initialization for Games on Arcadible

While your game starts, Arcadible shows its loading screen: your splash, your icon, your title, and the progress. Tell it when your game's initialization begins, how far along it is, and when it ends, with the Arcadible SDK, and the loading screen stays up until your first frame is drawn, then fades into your game.

Without the SDK, the loading screen comes down once your page has loaded, and your game shows whatever it draws while it finishes loading, so show something within a second.

The bracket​

Put your game's initialization between initBegin() and initEnd():

import { arcadible } from "@arcadible/sdk";

await arcadible.initBegin(); // first thing in your game's code
arcadible.initProgress(0.5);
// … load, build the scene, and draw the first frame …
await arcadible.initEnd();
  • initBegin() comes first. Arcadible keeps its loading screen only for a game that began before its page finished loading.
  • initProgress() is optional: how far along you are, from 0 to 1. See Progress.
  • initEnd() comes after your first frame is drawn, so the loading screen never fades into a blank page.
  • A game that fails while it starts, such as an error thrown before initEnd(), has its loading screen taken down about 30 seconds after its last call, showing the game as it is. Catch the failure, and show it with a way to retry (Best Practices › Load fast).
  • Everything between is yours: load files, decode them, generate levels, build the scene.

The starters bracket theirs: start from one, or copy how it's done.

Where each call goes​

initBegin(), first thing in your code. Static imports and sync code before it are fine, such as creating a renderer, since it all runs as the page loads. What's too late is anything that waits: a call after an await, or in a callback that runs later, such as setTimeout or requestAnimationFrame. Put initBegin() above them:

// too late: the page can finish loading while this waits
const levels = await (await fetch("/levels.json")).json();
await arcadible.initBegin();

// in time
await arcadible.initBegin();
const levels = await (await fetch("/levels.json")).json();

A call that comes too late still resolves, but the loading screen is already down, and the console says so, in a warning starting Arcadible SDK:.

initEnd(), once the first frame is drawn. In a loop you drive yourself, call it after the first frame:

requestAnimationFrame((time) => {
  frame(time); // draws
  arcadible.initEnd();
});

An engine that renders on its own loop has an event for it, such as Phaser's first postrender:

this.game.events.once("postrender", () => arcadible.initEnd());

An engine's own web export, such as Unity's or Godot's, can't call the SDK yet, since the SDK doesn't currently have a plugin for them: the loading screen comes down once the game's page has loaded. See Game Engines.

Progress​

initProgress(fraction) is optional: how much of your initialization is done, from 0 to 1. Measure it however suits your game:

  • Files: bytes loaded of the total, such as from a fetch you read in chunks.
  • Steps: each step you finish, such as decoding, generating, or compiling shaders, as a share of them all.

It only goes up: a lower value than the last is ignored, so reporting each file as it finishes, in any order, never jumps back. Without it, the loading screen's bar moves without a number.

After initEnd()​

initEnd() resolves once your game is visible, after the loading screen has faded: the moment to start music, timers, or an intro, which would otherwise start behind the loading screen.

await arcadible.initEnd();
music.play();

With saves​

initBegin() resolves once your game's saves have loaded, so after it the sync calls, such as readSync, work. It's the same promise as arcadible.ready, so a game that calls initBegin() doesn't need ready too.

ready is for a library or a plugin: it waits for the saves without beginning the initialization.

Trying it​

arc serve shows the loading screen, as Arcadible does, on the page's first load: its Play address, with your splash, icon, and title. Its Game only address is your game alone, with no loading screen, for screenshots, recordings, and checks.

Your art on it​

The loading screen shows your splash, or your banner, or your cover, the first you have, with your icon and title over it. Keep text off the splash: your title is already there. See Text in art.