Loading

Choose what your visitors wait for when your project opens, and set up the launch screen.

Visitors wait only once, at the start. What you load then has the biggest effect on how quickly your project feels to open.

How assets arrive

An asset arrives in one of three ways:

• Preloaded: fetched before the scene opens. The launch screen waits for it. Use it for anything visible in the first seconds.
• Deferred: the scene opens without it, and the asset appears when it arrives. Use it for content later in the experience.
• Streamed: played straight from the network, never downloaded whole. Use it for video and audio.

Only video and audio can stream

Only video and audio can start playing before they have fully arrived. A model, a texture or a font must arrive in full before it can be used. Deferring one only means the scene opens without waiting, and the asset appears when it is ready.

Project default and asset settings

The Project preload switch in the project settings is the default for all assets. Each asset can override it. In Project assets, hover over a file: two buttons appear on its row.

• Always preload: the scene always waits for this file, whatever the project says.
• Always stream: the scene never waits for it. Video and audio stream; other files are deferred.
• With neither on, the file follows Project preload.

Click a button again to turn it off. While one of them is on, the buttons stay visible on the row.

New video and audio assets start with Always stream on, because waiting for a whole video before the scene opens gains nothing. All other new assets follow the project setting.

Set it on the file

The loading setting belongs to the asset, not to the objects that use it. So two objects that share a file always load it the same way.

A good starting setup

For most projects:

1. Preload the first scene's models and textures, and any font you show right away.
2. Defer everything that belongs to later scenes.
3. Stream all video and audio. This is already the default.

Your visitors wait briefly once, and after that the experience never stops to load again.

Launch screen

Before your scene appears, visitors can see two screens:

• a screen they tap to begin;
• a screen that fills up while assets arrive.

Set up both in the project settings: the background, the logo, the start button and its label, the onboarding prompts and the loader style.

Keep the start button if your project has sound

Browsers do not play sound until the visitor interacts with the page. AR permissions work the same way: they are granted only inside the tap that asked for them. Without a button to press, your first sound does not play, and the camera prompt may never appear.

Your own launch screen

The built-in launch screen is a preset. To make your own, write a launch script. It controls both screens. It also defines its own settings panel, so the people who use it fill in fields instead of editing code.

init((ctx: PreloadContext) => {
  // Declare the settings panel. This runs before anything is drawn: declare only, never draw.
  ctx.on('describe', (p) => {
    p.section('look', { en: 'Look' });
    p.color('tint', { label: { en: 'Background' }, default: '#101014', section: 'look' });
    p.text('caption', { label: { en: 'Caption' }, default: '', localized: true, section: 'look' });
    p.boolean('hideWhenReady', { label: { en: 'Hide when ready' }, default: true });
  });

  ctx.on('launch', () => {
    /* show the screen they tap to begin */
  });

  ctx.on('loading', () => {
    /* show the screen that fills up */
  });

  ctx.on('progress', ({ loaded, total, percent }) => {
    /* update your own progress bar */
  });

  ctx.on('ready', () => {
    /* everything has arrived */
  });
});

Event	When it fires
describe	the settings panel is being built, in the runtime and in the editor
start	the runtime is starting up
launch	it is time to show the screen the visitor taps
loading	it is time to show the screen that fills up
progress	assets are arriving: loaded, total, percent
ready	everything needed has arrived
error	something went wrong

Settings can be localised, so one launch script works in every language your project supports.

Start the scene inside the tap

Whatever starts your scene must be called from the button's own click handler. Permissions for device orientation and the camera are granted only inside the tap that asked for them. If you start the scene on the next frame, you lose them.

A broken launch script does not lock visitors out

If your launch script throws an error, the built-in screen is shown instead.

What does not need to load

• A scene that does not use physics does not wait for it.
• Instanced copies and particles barely add to the download, however many there are.

Visitors never wait for things they do not need. More in Why AR Clip.

---

Next: Shared packages — the code packages you can import.