# moodKit.Moods
The API for giving a level, a zone or a scene a mood on THIS machine: `Moods.apply(name, opts)` ("goldenHour", "storm", "sunset.cartoon"; `fade`, `palette`, `overrides`), `Moods.get` / `define` / `list` / `palettes` / `info`, the priority stack of requests (`request(source, name, opts)` / `release(source)`, highest priority wins, `apply` asks at 100), `clear`, `current`, `on(fn)`, and the level source (`setLevelSource(fn)`, `levelNow()`). The `Mood` and `LevelMoods` components call `Moods.tick(dt)` to run the blend; with none in the scene it runs on its own task. Nothing is synced.
# moodKit.library
The mood library as data: twenty-one named moods (dawn, sunrise, morning, midday, afternoon, goldenHour, sunset, dusk, blueHour, twilight, lanternNight, night, starryNight, moonlit, auroraNight, overcast, foggyMorning, rainy, thunderstorm, snowfall, blizzard), each authored in the storybook palette: hour, weather, painted sky gradient, colour grade, haze, stars, the kind of light its toon ramp takes, ink and paper. `ALIASES` maps other names (storm, rain, golden, fog, snow, lantern...) onto them; `SURFACE` says how wet or snowy the ground looks per weather. Read through `moodKit.Moods`.
# 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:
```lua
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):
```lua
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:
```lua
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:**
```lua
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.