world.loading

The screen somebody looks at while your world arrives.

The panel is the usual way

Most creators never touch this page. The loading screen lives in World settings → Entry, where it is a form with the picture, the headline, the description, the tips and the colour — and that is the right place for something you set once and change a few times a year.

world.loading is the same setting through a script, for the cases a form cannot cover: a seasonal event, a headline that follows the world's own state, a tip list built from what is actually happening. It writes to exactly the same place the panel does.

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 — 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

field	type	what it is
background	text	Full-bleed image. A library path (world/telas/entrada) or a content hash.
dim	number 0–1	How much black is laid over the image. Default 0.45.
logo	text	Your own mark, drawn small in the top-left corner.

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.

No background is not an error

Nothing set, image still downloading, or a path pointing at nothing — the screen falls back to your world's thumbnail, and then to a gradient built from your accent. There is always a screen, and a broken picture can never stop somebody entering.

The words

field	type	what it is
headline	text, ≤ 80 chars	The big line. Empty = your world's name, which is what most worlds want.
subtitle	text, ≤ 160 chars	One quiet line under it.
tips	list of text, ≤ 8 items, ≤ 160 chars each	Rotated one at a time, low on the screen.
tip_secs	number 2–30	How long each tip is held. Default 6.

Asking for more than eight tips is refused, not truncated — 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

field	type	what it is
accent	text "#rrggbb"	The progress bar and the rule above the headline.
layout	"center" | "bottom_left" | "card"	Where the text block sits.
show_progress	boolean	Draw the bar at all. Default true.
show_bytes	boolean	Show "18 / 42 MB" next to it. Default false.

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

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

card — 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.

show_progress = false hides a widget, not the loader

The percentage still exists and the client still holds the door on it. Turning this off gives you a still frame with no chrome — it does not make your world load sooner, and it does not let anybody in earlier.

---

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 — the world only writes when the value actually changes, so a script that does this on every boot is free.

Testing locally

Running without a hub (a solo fork, a dev world), the screen works for that session but has nowhere to be stored — you will see a line in the console saying so. That is the setup, not your script.

---

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 — what is downloaded before you are let in, and why it is not everything
• world.build — the library your background path points into
• permissions — environment, which this needs