How to customize the loading screen

For World Builder Projects

Introduction

Previously, this tutorial referenced a custom data asset called World Builder Data as the main way to set an override image from within your project. As of 26/03/2024, this has been deprecated in favour of customising via Project Settings.

By default, when launching from a client into a World Builder world you’re met with this screen:

Update: as of 11/10/23, webp support has been added to clients. This means that the default splash image will be the image set as pictureUrl on the launch context regardless of format. If no image set, a default black background will be used instead.

If your launch context has an image set as its pictureUrl, this will be displayed instead of the default black background. This image will be set across all loading screens up until your world is ready. This image will also be shown across instances of world travel.

When starting an experience from https://showcase.m2worlds.io/mods, the image used will match the image provided for the experience's map in your World Builder Data asset. If no image is provided, the image shown will be downloaded from the default url set for your specific organisation.

The image shown for each map here is what will override the splash screen image. If this is not provided, the Url set for the organisation will be used as a default.

It is advised that you use this default launch context image flow for simplicity, as there is no additional setup required other than setting your image for the launch context. If you only wish to override UI with an image, the launch context flow should be the default way of doing this, and you should unset the override image in your Project Settings (found under M2 World Builder Data heading).

However, the below flow using project settings will override the launch context UI flow. If this is not set, the launch context/mod map image will be shown during startup entry.

This doc covers how to customise this view using Project Settings over this default flow.

---

Using Project Settings to Set your Splash Image

How it works

Setting the override image is straightforwardly achievable by modifying Project Settings:

1. Add the image you want to set to your content/plugin mod folder.

2. Go to Project Settings

3. If your project contains the now deprecated World Builder Data data asset:

   1. Copy across the info from the PDA into the M2 World Builder Data section

4. If this is a new project, without World Builder Data present:

   1. Navigate to M2 World Builder Data under Game in project settings, and set the override image to an image you have imported into your project.

5. It's recommended to also delete the world builder data asset as it won't be used at all for anything in projects now.

   1. Note: not deleting the asset won't break anything, but the pda will not be used at all so it is safe to remove once the settings are copied across.

The image can be set in the Override Image section (see bottom of image)

---

(Deprecated) Using World Builder Data

As of 26/03/2024, this feature is no longer available and has been replaced by Project Settings. Please see above on how to replicate the below functionality using project settings.

If you are on an origin version that does not yet contain the above change, the below is still relevant.

How it works

WorldBuilderData uses a custom data asset to mark all referenced content as part of a different content bundle. When this content is packaged and uploaded, these bundles separate.

When a player starts to connect to your server, we can then check if this special bundle is present. If it is we download this asset bundle first, load its contents to override the UI, and then continue with downloading the main game assets.

Due to this implementation, there are a few key reminders as you author your content.

Key reminders

1. It is very important that any assets you use as part of WorldBuilderData do not overlap with the main game’s assets. This is particularly important for the streamed level. When the server loads the map, it will not load the plugin customization content; meaning any assets assigned will not be loaded and the server will fail to start. The primary problem case is with the streamed level. Ensure the world settings and game mode are not the same, particularly the “Player Spawner Class”.

2. Aim to make the content used in the WorldBuilderData as small as possible. The larger this content is, the longer it will take to download initially so the UI will be less seamless.

Setup your project to use WorldBuilderData

In the content browser, go to the content directory of your plugin. Create a new data asset with the class M2_WorldBuilderData and name it something meaningful.

If you have more than one of these assets in your plugin, packaging & uploading will fail.

Set customization settings

Now the project is setup, you can open the M2_WorldBuilderData asset you just created. It should show this screen:

Intro Splashscreen Text	Adds custom text to WBP_WBL_StatusDisplay(this is currently deprecated and will not be displayed on startup)
Intro Splashscreen Image	Adds a custom background image to WBP_WBL_StatusDisplay. It is stretched to fit the entire background.
Intro Splashscreen Override Widget	If set, overrides the entire WBP_WBL_StatusDisplay widget so the text and image settings are ignored. This widget should implement the WBP_WBL_StatusDisplayInterface. The easiest way to create an override widget is to copy WBP_WBL_StatusDisplay and modify the UI to your liking.
Experimental: Level to Stream	If set, the level will be streamed in to WBL_StartMap. The widget settings will still be used, meaning if a background image is set you cannot see the level. Useful for showing more complicated graphics than a widget. Currently, the map is only for viewing via the player camera. No interaction or movement is possible. It is recommended to use NewMapTemplate as a starting point for this streaming level.

Examples

Example of custom text and image:

Example of override widget:

Example of level to stream with an override widget: