world.sky#

The backdrop, the light and the haze of your world — as one thing a script can change, and as an item you can keep.

The panel is the usual way

Most creators never touch this page. The sky lives in the scene, one click from the thing it lights: open the outliner and select Sky, or go to World settings → Scenery → Sky. There you get every dial on this page as a slider, plus the two buttons that make a sky an item — Save this sky and Wear one of your skies.

world.sky is the same setting through a script, for the cases a form cannot cover: a day that actually passes, a storm that arrives, a ritual that changes the sky when somebody lights the brazier.

Luau

local world = require("world") -- One dial, live.world.sky.time_of_day = 18.5 -- Several at once, and an omitted one keeps its value.world.sky:set({ fog_aerial = 0.8, brightness = 1.2 }) -- Arrive there over eight seconds instead of cutting.world.sky:tween({ time_of_day = 21.0, fog_max = 0.6, secs = 8 }) -- Or wear a sky somebody authored and published on this world's shelf.world.sky = "world/ceus/entardecer"

Everything on this page#

A sky is a stamp · set · tween · wear · get · clear · The fields · The hour · What you cannot change here

A sky is a STAMP, not a link#

This is the one idea the whole page rests on.

When your world wears a sky — from a script or from the panel — the sky's values are copied into your world. The item is not consulted again. Three things follow from that, and all three are the point:

You can adjust it afterwards. Wear Entardecer, then push the haze up a little. You are editing your world, not somebody else's asset, and the asset is untouched.
It cannot break. A sky whose author deleted it, or whose owner is offline, goes on drawing, because your world never needed to fetch anything.
Everyone sees the same sky. The values travel with the world, on the same wire that has carried them since worlds could be graded at all.

What is kept is the sky's name, so the panel can say what you are wearing. The moment you move any dial, that name is dropped — the numbers no longer match the item, and a label that claimed otherwise would be a lie you could not see.

set#

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

Every field is optional, and an omitted one keeps its value. Changing the hour does not reset your haze.

Luau

world.sky:set({ time_of_day = 6.5, fog_height = 0.035, fog_aerial = 0.6 })

Needs the world.weather capability — the same one world:set_weather needs, because it is the same sentence: somebody trusted to start a storm is trusted to move the sun.

tween#

world.sky:tween(opts) → true, or nil, reason

The same fields as set, plus secs — how long to take getting there. Default 4 seconds, ceiling 10 minutes.

Luau

world.sky:tween({ time_of_day = 21.0, fog_max = 0.55, secs = 20 })

The numbers glide; the picture does not. If the tween also changes which image is in the sky, the image swaps at the END. Two photographs cannot be faded into each other without holding both in memory at once, which is a cost every world would pay so that one world could dissolve — and the movement people actually notice is in the hour, the haze and the brightness anyway.

A tween that is interrupted continues from what is on screen, not from where the last one was heading.

For a day that simply passes, use day_minutes instead

A tween is a server-side glide: the zone sends the sky to everybody a few times a second while it moves. day_minutes costs nothing at all — each client's own clock advances the sun. Use tween for an event, day_minutes for a cycle.

wear#

world.sky:wear(path) → true, or nil, reason world.sky:wear(path, secs) — the same, arrived at over secs.

Wears a sky published on this world's shelf. world.sky = path is the short form of wear(path) with no glide.

Luau

world.sky:wear("world/ceus/entardecer")world.sky:wear("world/ceus/noite", 15)   -- fifteen seconds of dusk

A bad path is refused immediately, by name, so a typo shows up in the console instead of as a sky that never arrives. A path that names something which is not a sky is refused the same way.

The sky itself lands a moment later: the document has to be downloaded, and a script cannot wait for a download. Everything else on this page is immediate.

get#

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

Reads the sky back. nil means no script has spoken for it and the world is showing whatever its creator set in the panel.

Luau

local sky = world.sky:get()if sky and sky.time_of_day and sky.time_of_day > 20 then    world:message("Está escurecendo.")end

Reading needs no capability — what the sky looks like is not a secret from anybody, exactly as the weather is not.

During a tween this answers with where the sky is going, not with the frame it happens to be passing through, so two consecutive lines cannot read two different skies.

clear#

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

The script stops speaking for the sky, and the world goes back to what its creator set in the panel.

The fields#

field	what it is
`image`	a built-in sky by name, or `false` for the procedural atmosphere
`yaw`	which way the image faces, degrees — this is what aims its sun at your build
`brightness`	how bright the image is, backdrop and cast light alike
`blur`	softens the BACKDROP only; the light it casts never changes
`time_of_day`	the hour, 0–24, or `false` to leave the clock alone
`day_minutes`	real minutes for a whole day; 0 stops the clock
`fog_height`	how fast the haze thins with altitude (0 = uniform)
`fog_base`	the altitude the haze is measured from, metres
`fog_aerial`	haze glowing when the sun is behind it, 0–1
`fog_max`	how opaque the horizon may get, 0–1

Every one of them is clamped on the way in. A value out of range is brought back to the range; a value that is not a number is refused with a sentence.

The hour#

time_of_day is the field that makes a sky mean something without a photograph in it. The sun and the moon ride a great circle, sunrise is around 6 and sunset around 18, and a world that never sets it keeps the light it has always had.

Luau

-- A world where a day takes twenty real minutes.world.sky:set({ time_of_day = 7.0, day_minutes = 20 })

It only reaches the procedural sky. With a photograph in the air, the sun in that photograph is where the light comes from — that is what yaw aims — and moving an hour would light the world from somewhere the picture contradicts.

What you cannot change here#

The colour grade. Exposure, contrast, saturation, bloom, vignette and grain belong to World settings → Colour. That grades the picture the sky produced, and it is a different job: a "sky" that quietly re-graded the whole frame would be a look preset wearing a sky's name.

The player's own limits. Whether the post chain runs, how many shadow taps, what resolution the shadow maps are — those are decisions about what somebody's machine can afford, and no world gets to make them.

The player's refusal. Anybody can override which sky lights the scene from their own graphics settings. A world may insist on a look; it may not insist somebody look at it.