world.loading#

The screen somebody looks at while your world arrives.

local world = require("world") world.loading:set({    background = "world/telas/entrada",    headline   = "Vila do Porto",    subtitle   = "Chuva a noite toda",    accent     = "#ffb454",    layout     = "bottom_left",    tips       = { "Aperte E para pegar", "F acende a lanterna" },})

Until this existed, the first thing anyone saw of your world was the one part of it you could not touch: a small grey card with three dots, identical for every world on the grid.

Everything on this page#

set · get · clear · The fields · What you cannot change · When it takes effect

What you own, and what you do not#

You own the picture. The client owns the truth.

You supply the background, the words, the colour and the tips. The progress bar, the percentage, the line that says what is happening and the way out are drawn by the client, in the player's own language, and no world can move them, hide the exit or make the bar look finished when it is not.

That line is not there to limit you. It is what lets a player trust a loading screen at all, including yours.

set#

world.loading:set(opts) → true, or nil, reason

Every field is optional, and an omitted one keeps its value. Changing one line does not mean restating the picture:

world.loading:set({ background = "world/telas/entrada", headline = "Vila do Porto" }) -- …later, for the night event. The background is untouched.world.loading:set({ headline = "Noite de Festa", accent = "#c05cff" })

Needs the world's environment permission, the same one that lets you change the sky. Your own world's scripts have it.

A field of the wrong type is refused, not coerced:

local ok, why = world.loading:set({ headline = 3 })print(ok, why)   --> nil   headline must be a string

That is deliberate. Luau would happily turn 3 into "3", and a headline reading "3" because a variable was not what you thought is a bug every visitor sees and you never do.

get#

world.loading:get() → table, or nil

What is set right now, or nil if this world has never chosen. Needs no permission, because what the front door looks like is not a secret.

Useful for adding to what somebody already set, rather than replacing it:

local cur = world.loading:get()if cur then    local tips = cur.tips    table.insert(tips, "Hoje tem feira na praça")    world.loading:set({ tips = tips })end

accent comes back as the string you wrote ("#ffb454"), and background as the path you wrote, not as a hash.

clear#

world.loading:clear() → true, or nil, reason

Back to the built-in screen. Same permission as set.

The fields#

The picture#

The background is cover-fitted: it always fills the screen and is cropped symmetrically on whichever axis does not fit. Author it at 16:9 and nothing gets cut that matters. It may be up to 4096 px on its longest side.

dim exists because you pick the image and we pick the text colour. Without a scrim, white type on a bright photograph is unreadable, and you have no way to see that from where you are sitting. Lower it for a dark image; raise it for a busy one.

The words#

Asking for more than eight tips is refused, not truncated, because silently dropping the last four of your twelve would be a bug you would look for in the wrong place for an hour.

The dressing#

center puts the text and bar centred over the picture. Works with any image, and the safe choice if you are not sure.

bottom_left anchors them low and left, the picture left clear above it. The cinematic one; use it when the image is the point.

card is a panel over the picture, for a background too busy for bare type.

A misspelt layout is refused with the list of valid ones. You are looking at the console right now; the visitor who would otherwise inherit the wrong arrangement is not.

When it takes effect#

On the next join, not for the people already inside. By definition everyone who could see this screen is someone who has not arrived yet.

The screen is stored with your world, so it survives restarts and moving to another machine. The usual place to set it is world:on_start:

local world = require("world") world:on_start(function()    world.loading:set({        background = "world/telas/entrada",        headline   = "Vila do Porto",        tips       = { "Aperte E para pegar", "F acende a lanterna" },    })end)

Setting the same screen twice costs nothing, because the world only writes when the value actually changes, so a script that does this on every boot is free.

What you cannot change#

Drawn by the client, always, over whatever you set:

• the progress bar and the percentage, measured in bytes against what has to land before the door opens, so 100% and the door opening are the same moment;
• the line that says what is happening, in the player's language, not yours;
• the Cancel button, in the same corner in every world, so nobody has to hunt for it because a world chose a busy layout;
• how long the wait is. You cannot make it longer, and you cannot make it shorter by hiding the bar. See how a world loads.

See also#

• how a world loads is what gets downloaded before you are let in, and why it is not everything
• world.build is the library your background path points into
• permissions covers environment, which this needs

Updated 17 October 2026