paintedSkies.package
README.md
paintedSkies
Hand-painted anime skies for any world, like anime background art: towering summer cumulonimbus, clear blue, golden sunset, pastel dawn, warm dusk, starry night with a milky way and moon, rainy grey, storm and an 80s neon city night. Ten presets, swapped with one call; the sky also lights the scene to match, and every player sees the same sky. Stands on its own: no other package needed.
Get started: install paintedSkies, then
require("~paintedSkies.PaintedSkies").use("summerClouds")
Version 1.0.7 (1.0.7: a short description and a lead that says what it gives and how to start; 1.0.6: brighter night skies and a warm purple dusk; 1.0.5: its presets and shader arrive when another package installs it).
How it is painted
Big, cinematic, hand-painted skies like anime background art, for any world. Towering summer cumulonimbus with bright white tops and blue-grey painted shading, clean blue gradients, golden sunsets with pink-lit clouds, pastel dawns, warm dusks with an orange horizon and the first stars, deep starry nights with a milky way and moon, rainy grey overcast, and an 80s anime city night with a neon horizon glow and a skyline. Everything is painted per pixel by one sky shader: cumulus are stacks of round billows lit like balls and posterised into soft painted bands with brush grain, with a cel rim on the edges toward the sun and haze toward the horizon.
It stands on its own: no other package is needed.
First example (a fresh world, a few minutes)
- Install paintedSkies from ZeroMind (search "painted anime sky").
- In your scene's
build.luau, insidecontent():
local skyEnt = entity.spawn("PaintedSky")
skyEnt.component.add("PaintedSky", { preset = "summerClouds" })
- The sky appears at once in the editor. Change
presetin the Inspector, or from any script during play:
local Skies = require("~paintedSkies.PaintedSkies")
Skies.use("goldenSunset") -- cross-fades for every player
Remove any other sky component (Skybox, ProceduralSky) from the scene:
the engine shows whichever sky was set up last. The package also ships
paintedSkiesGallery, a meadow scene under a PaintedSky, to look at the
presets.
Presets
| id | what it is |
|---|---|
summerClouds | The classic anime summer sky: towering cumulonimbus, deep saturated blue, white tops, blue-grey shading. |
clearBlue | Clean blue gradient, faint high wisps, bright sun. |
goldenSunset | Orange and gold horizon, pink-lit clouds, a low sun disc. |
pastelDawn | Pink, peach and lavender, soft low cloud banks. |
purpleDusk | Warm dusk after sunset: an orange horizon under deep indigo, crescent moon, first stars (since 1.0.6; before, violet and magenta, too close to neonNight80s). |
starryNight | Deep navy, dense painted star field, milky way band, full moon. |
rainyGrey | Overcast, layered grey stratus, muted colour. |
storm | A gathering storm: slate-violet cumulonimbus towers, a dark rolling deck and a pale break of light low on the horizon (no lightning flashes). |
toweringClouds | The big anime-film summer sky: a deep blue gradient and enormous sunlit cumulonimbus towers on the horizon. |
neonNight80s | 80s anime city night: magenta into a cyan horizon glow, purple haze, big sparkling stars, distant lit skyline. |
Skies.presets() lists every preset the world has, yours included.
Your own presets
A preset is a .data asset bound to the skyPreset contract: a
values.yaml holding only the fields that differ from the defaults (colours
as sRGB hex, angles in degrees). Copy one from presets/, rename the folder,
and it is listed and usable by its folder name:
contract: skyPreset
values:
label: Alien noon
zenith: "#2a0a5a"
horizon: "#7affc8"
towers: 0.9
cloudShade: "#5a3a8a"
Every field and its range is in skyPreset.dataType/README.md.
The component: PaintedSky
| Field | Default | Meaning |
|---|---|---|
preset | summerClouds | The preset shown. |
matchLighting | true | Set the scene's directional light (direction, colour, intensity) and ambient light to the preset's suggestion. |
transition | 2.5 | Seconds a change cross-fades over during play (0 = at once; in edit mode changes are always instant). |
overrides | {} | Preset fields replaced on top of the preset, e.g. { towers = 1, sunElevation = 20 }. |
followClock | false | Follow a day-night kit: the sky changes with its time of day and weather (see below). |
clockPresets | dawn pastelDawn, day summerClouds, dusk goldenSunset, night starryNight, overcast rainyGrey, storm storm | The preset for each time of day and weather while following. |
All fields are Synced and saved with the scene. sky:use(id) on the
component is the same as setting preset and clearing overrides.
With a day and night kit (Skyclock / worldClockKit)
paintedSkies works beside the day-night kits people already use rather than replacing them. With worldClockKit (the Skyclock kit) in the scene:
- On the kit's
WorldClock, setskyMode = "off": the kit keeps its shared clock, weather, sun, moon and lamps, and leaves the sky to you. - On the
PaintedSky, setfollowClock = true.
The painted sky now follows the kit: pastel dawn, summer clouds by day, a
golden sunset at dusk, a starry night, grey overcast in rain, cloud, snow and
fog, and the storm sky in storms, cross-fading over at least six seconds. Change
the pairing with clockPresets ({ day = "toweringClouds" }). Every machine
reads the kit's synced clock and weather off its WorldClock component, so
every player sees the same sky with no extra traffic, and paintedSkies needs
nothing of the kit installed. While following, matchLighting is left to the
kit, which lights the scene. Any other day-night system: leave followClock
off and call Skies.use(id) when your time of day changes.
The module: require("~paintedSkies.PaintedSkies")
| Call | Does |
|---|---|
use(id, { transition?, keepOverrides? }) | Swap the whole sky for every player. Spawns a synced PaintedSky entity if the scene has none. Returns false for an unknown id. |
presets() | Sorted list of preset ids. |
current() | { preset, values, overrides } of the sky being shown. |
set(overrides) | Change preset fields on top of the current preset, shared. set({}) clears them. |
clear() | Take the painted sky off for every player: the PaintedSky entity goes, the scene's own sky shows again, and every machine puts back the sun and ambient light the scene had before the sky set them (matchLighting). Any player can call it. |
preset(id) | The resolved values of one preset (defaults filled in). |
toProperties(values) | The sky shader properties those values produce. |
Multiplayer
The PaintedSky fields are Synced: use, set and Inspector edits replicate
to every player, and every peer paints the same sky from the same preset
(clouds drift on the shared world clock). matchLighting writes the scene's
sun and ambient light on each peer from the same values, so lighting agrees.
Any player can change the sky (since 1.0.3). The PaintedSky entity belongs to
one player, usually the room's host, and only its owner can write it, so
use, set and clear on any other player's machine send the change to the
room on the paintedSkies.op channel and the owner applies it for everyone.
Before 1.0.3 a sky picked by a player who was not the host was accepted on
that machine and changed nothing.
Cost
One fullscreen sky pass, no textures, no render targets, no extra draw calls,
and no per-frame Luau work while the sky holds still (properties are written
only on a change or during a cross-fade). Per pixel it evaluates the gradient
and stars, and where a preset turns them on: a 3x3 cell search of sphere
billows at two scales for the towering clouds (only between the horizon and
the tallest tower) and for deck puffs (only above the horizon), and a
5-octave fbm for stratus and wisps. Layers at 0 are skipped, so clearBlue,
purpleDusk and starryNight are the cheapest and summerClouds the
dearest.
GPU time of the sky pass, measured in the Anime Looks showcase at 2097 x 1453
on the development machine's GPU (zero profiler gpu, row scene.sky):
0.39 to 0.40 ms with clearBlue and storm up, where the engine's own
deferred lighting pass took 2.16 ms on the same frame. The sky pass only
draws where no geometry covers the screen, so a scene seen through trees
pays for less of it. Read yours with zero profiler gpu.
Known limits
- Engine issue #4701 (a runtime sky change is not followed by the sky
pass). The package never swaps the sky material: it creates ONE runtime
material (
paintedSkies.sky) once, binds it once through the native Sky component, and every preset change or cross-fade pushes property values onto that same material withrenderer.material.setProperty. Runtime swaps (use,set, Inspector edits, cross-fades) are followed every time. - One sky per scene. The engine draws the sky that was set up last; a
scene that also carries
Skybox/ProceduralSkyshould drop them. Removing a PaintedSky does not hand the sky back to an older sky component: the engine falls back to its default sky until another sky is set up. - Clouds are painted, not volumetric. They are a backdrop: flying into them or above them does not work, and they do not cast shadows on the world.
- Ground below the horizon is painted as a plain colour band; it is meant to sit behind your terrain.
- Cross-fades need play mode (the component's
updatedrives them); in edit mode a change shows at once. - Towering-cloud presets cost more per sky pixel than a plain gradient
(
summerClouds,toweringCloudsandstormsearch a grid of billows). - followClock reads the kit's
WorldClockby its component, found by the nameWorldClockor a scan at most every ten seconds; a kit that names its clock differently is found within ten seconds of appearing. lighting.getand a content sky. The PaintedSky carrieskindandmaterialfields only so the engine'slighting.gettool can read it (reported upstream); a sky restore throughlighting.setSkylogs that no material matchespaintedSkies.sky, which is harmless.