Log inGet started
Package

moodKit.package

README.md

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
daydawn, sunrise, morning, midday, afternoon, goldenHour, sunset, dusk
evening & nightblueHour, twilight, lanternNight (warm lantern-lit night), night, starryNight, moonlit, auroraNight
weatherovercast, 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" }.

every mood

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 through Clock/Weather/Sky.setLocal (worldClockKit 1.4.8+).
  • AlpineBridge — alpineKit Atmos.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 with StyleKit.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.
  • Mood component — a scene or zone mood. LevelMoods component — 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.