moodKit
moodKit gives each level, zone or scene of your world its own **mood**: the hour, the weather, the painted sky, the colour grade, the haze, the stars and the toon ramp / ink / paper colours, all at once, from one name. Swapping a level's mood is one setting (`gorge=goldenHour`),…
moodKit — time of day, weather and light per level, per player
moodKit gives each level, zone or scene of your world its own mood: the hour, the weather,
the painted sky, the colour grade, the haze, the stars and the toon ramp / ink / paper colours,
all at once, from one name. Swapping a level's mood is one setting (gorge=goldenHour), moods
blend smoothly into each other, and each machine shows its own player's mood: two friends on
different levels each see their own time of day, and nothing shared is overwritten.
It ships 21 moods, each in 6 palettes:
| moods | |
|---|---|
| day | dawn, sunrise, morning, midday, afternoon, goldenHour, sunset, dusk |
| evening & night | blueHour, twilight, lanternNight (warm lantern-lit night), night, starryNight, moonlit, auroraNight |
| weather | overcast, foggyMorning, rainy, thunderstorm, snowfall, blizzard |
Aliases work too: storm, rain, golden, fog, snow, stars, moon, aurora, lantern, noon.
Palettes: storybook (as authored), realistic, cartoon, moody, pastel, noir, picked
as "sunset.cartoon" or { palette = "noir" }.

moods-sheet.jpg shows all 21 in order, left to right and top to bottom (dawn … twilight, lantern night … aurora night, overcast … blizzard), from the kit world's MoodShowcase scene: a meadow with a hut and a row of 21 lantern stations you walk along ([ / ] step through the moods, P the palettes).
Use it
One mood for a scene — a component:
entity.spawn("Mood").component.add("moodKit.Mood", { mood = "goldenHour" })
A zone with its own mood (walk in, it blends in; walk out, it blends back):
entity.spawn("Cave", { position = { 40, 0, 12 } }).component.add("moodKit.Mood",
{ mood = "night", radius = 25, priority = 10 })
Each level its own mood, per player — one LevelMoods in the scene:
entity.spawn("LevelMoods").component.add("moodKit.LevelMoods", {
levels = "meadows=dawn, gorge=midday, lake=goldenHour, ridge=dusk, summit=starryNight",
fallback = "twilight", -- title screen and menus
})
It follows a running platformer3dKit level on its own (and campaignKit's send-off / results
screens); any other game tells it with Moods.setLevelSource(function() return myLevelId end).
For hour / weather changes per level, your own overrides and the style stack, keep the moods in
a levelMoods data file (set field) — see levelMoods.dataType.
From code:
local Moods = require("moodKit.Moods")
Moods.apply("storm") -- blends in over 3 s, this machine only
Moods.apply("sunset", { palette = "cartoon", fade = 6 })
Moods.apply("dusk", { overrides = { weather = "snow" } })
Moods.define("myLevel", { base = "dawn", hour = 8 }) -- your own mood on a library one
Moods.request("cutscene", "moonlit", { priority = 200 }) ; Moods.release("cutscene")
Moods.clear() -- back to the shared clock and weather
What it drives
moodKit re-implements no sky, weather or post effect, and names no other kit, so it installs on
its own. Out of the box it lays each mood on the engine: every ProceduralSky (hour, gradient,
stars), the scene's sun, height fog, surface weather (wet ground, settled snow) and its own
colorGrade pass. The kits a world already has plug in through moodKitBridges (same world),
one small component per kit, all per machine:
ClockBridge— worldClockKit: local hour, weather (rain, storm with lightning, snow, blizzard, fog) and sky look throughClock/Weather/Sky.setLocal(worldClockKit 1.4.8+).AlpineBridge— alpineKitAtmos.setMood: colour grade, valley haze, painted sky, snow deck.StyleBridge— styleKit (toonBlocks / inkBlocks stacks): keeps the stack in place and lays the toon ramp, ink and paper per machine withStyleKit.setLocal.PlatformerBridge/CampaignBridge— platformer3dKit / campaignKit: which level the local player is on.
Any other kit plugs in with Moods.adapters().register(name, { apply, clear, ready, ownsLight, ownsGrade });
Moods.adapters().available() says which apply in your world.
Cost
Blending writes to the kits about 30 times a second; one write costs ~0.2 ms. Starting a new mood sweeps the scene once to find its sky and sun (tens of ms in a scene of thousands of entities), and that sweep is cached.
Parts
Moods— the API above, the priority stack of requests, the blend driver.Moodcomponent — a scene or zone mood.LevelMoodscomponent — a mood per level.library— the 21 moods as data.palettes— the 6 palettes.ramps— 6 × 7 toon ramps.blend— how two moods blend (hour the short way round the clock, colours eased).adapters— where a mood lands on this machine, and the registry kits plug into.stack— which style stack entry takes the ramp, ink and paper.levelMoods.dataType— the contract for a game's level-mood data file.guides/— how to give each level its own time of day, weather and lighting mood.tests/moodKit.testSuite— the library, aliases, palettes, blending and the request stack.
Scoped to this part · feeds back into the world's score.