Log inGet started
Package

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)

  1. Install paintedSkies from ZeroMind (search "painted anime sky").
  2. In your scene's build.luau, inside content():
local skyEnt = entity.spawn("PaintedSky")
skyEnt.component.add("PaintedSky", { preset = "summerClouds" })
  1. The sky appears at once in the editor. Change preset in 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

idwhat it is
summerCloudsThe classic anime summer sky: towering cumulonimbus, deep saturated blue, white tops, blue-grey shading.
clearBlueClean blue gradient, faint high wisps, bright sun.
goldenSunsetOrange and gold horizon, pink-lit clouds, a low sun disc.
pastelDawnPink, peach and lavender, soft low cloud banks.
purpleDuskWarm 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).
starryNightDeep navy, dense painted star field, milky way band, full moon.
rainyGreyOvercast, layered grey stratus, muted colour.
stormA gathering storm: slate-violet cumulonimbus towers, a dark rolling deck and a pale break of light low on the horizon (no lightning flashes).
toweringCloudsThe big anime-film summer sky: a deep blue gradient and enormous sunlit cumulonimbus towers on the horizon.
neonNight80s80s 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

FieldDefaultMeaning
presetsummerCloudsThe preset shown.
matchLightingtrueSet the scene's directional light (direction, colour, intensity) and ambient light to the preset's suggestion.
transition2.5Seconds 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 }.
followClockfalseFollow a day-night kit: the sky changes with its time of day and weather (see below).
clockPresetsdawn pastelDawn, day summerClouds, dusk goldenSunset, night starryNight, overcast rainyGrey, storm stormThe 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:

  1. On the kit's WorldClock, set skyMode = "off": the kit keeps its shared clock, weather, sun, moon and lamps, and leaves the sky to you.
  2. On the PaintedSky, set followClock = 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")

CallDoes
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 with renderer.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/ProceduralSky should 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 update drives them); in edit mode a change shows at once.
  • Towering-cloud presets cost more per sky pixel than a plain gradient (summerClouds, toweringClouds and storm search a grid of billows).
  • followClock reads the kit's WorldClock by its component, found by the name WorldClock or a scan at most every ten seconds; a kit that names its clock differently is found within ten seconds of appearing.
  • lighting.get and a content sky. The PaintedSky carries kind and material fields only so the engine's lighting.get tool can read it (reported upstream); a sky restore through lighting.setSky logs that no material matches paintedSkies.sky, which is harmless.