# moodKit.Mood
Gives the whole scene, or the area round its entity, a mood on each machine. Put it on any entity: `mood` (any moodKit mood, alias or `mood.palette`), `palette`, `fade` (seconds to blend in), `priority` (highest wins) and `radius` (0 = the whole scene; above 0 only while this machine's camera is within that many metres, so a zone blends its mood in and out as you walk through). `preview` shows it in the editor. Needs no sibling components; it drives worldClockKit, alpineKit, styleKit and the scene's ProceduralSky / sun when they are there.
# moodKit.LevelMoods
Each level its own mood, per player. Put ONE on any entity of the scene. On every machine it asks the level sources which level that machine's player is on (`Moods.setLevelSource(fn)` for your own game; moodKitBridges' PlatformerBridge for platformer3dKit levels and CampaignBridge for campaignKit's send-off and results) and blends in that level's mood; with no level it shows `fallback` (title, menus). Moods per level come from `levels` (`"meadows=dawn, gorge=midday"`, one change to swap) and/or a `levelMoods` data file in `set` (hour / weather / overrides per level, the menu mood, the blend time and the style stack). `palette` draws every level in one palette; `preview` shows a level's mood in the editor. Nothing is synced.
# moodKitBridges.StyleBridge
Connects moodKit to a styleKit stack (toonBlocks, inkBlocks and other look blocks). It keeps the stack named in LevelMoods' `levelMoods` data file on the scene (synced, the same blocks for everyone; `keepStack` turns that off), and lays each mood's toon ramp, ink and paper colours on the stack's entries for THIS machine only through `StyleKit.setLocal`. Add it next to `moodKit.LevelMoods`. Needs styleKit 1.4.9+.
# 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.
# levelMoods (dataType)
The mood of every level of a game, as data: which library mood each level shows, with the few
changes it makes to it, the mood with no level running, the blend time and (optionally) the
synced style stack the moods paint on. A `.data` bound to this contract is what the
`moodKit.LevelMoods` component reads through its `set` field, so a game keeps its look as one
data file and swapping a level's mood is one value.
```yaml
contract: levelMoods
values:
fallback: twilight # title screen, menus
fade: 3 # seconds to blend between levels
levels:
- { level: meadows, mood: dawn, hour: 8 }
- { level: gorge, mood: midday }
- { level: lake, mood: goldenHour, palette: cartoon }
- { level: ridge, mood: dusk, weather: snow }
- { level: summit, mood: starryNight }
- { level: cave, mood: night, overrides: '{"haze":0.006,"grade":{"exposure":1.4}}' }
stack: # optional styleKit stack (toonBlocks / inkBlocks entries)
- { id: light, block: toonRamp, settings: '{"rampStrength":1}' }
- { id: line, block: inkPenLine, settings: '{"width":1.25}' }
- { id: paper, block: inkPaper }
```
Per level: `mood` is any moodKit mood, alias ("storm", "rain", "golden") or "mood.palette";
`palette` draws it in storybook / realistic / cartoon / moody / pastel / noir; `hour`, `weather`,
`stars` and `skyLook` change those fields (-1 / empty keeps the mood's own); `overrides` is a JSON
object deep-merged over the mood for anything else (grade, sky, haze, ramp, ink, paper). Stack
`settings` and `stackOptions` are JSON objects.
# 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.
# moodKitBridges — plug moodKit into the kits your world has
[moodKit](../moodKit.package) gives each level its own time of day, weather and lighting mood, per
player, and names no other kit, so it installs on its own and runs on the engine's sky, sun,
fog and grade. These bridges hand each mood to the kits a world already has, so a mood also
moves worldClockKit's hour and weather, alpineKit's grade and haze and the toon ramp of a
styleKit stack — on this machine only.
| component | kit | what a mood does through it |
|---|---|---|
| `ClockBridge` | worldClockKit | this machine's hour (`Clock.setLocal`), weather — falling rain, snow, storm with lightning, fog (`Weather.setLocal`) — and sky look (`Sky.setLocal`); while a `WorldClock` runs, its director paints the sun, sky and fog |
| `AlpineBridge` | alpineKit | colour grade, valley haze, painted sky gradient and snow deck (`Atmos.setMood`) while an `AlpineAtmosphere` runs |
| `StyleBridge` | styleKit (toonBlocks, inkBlocks) | keeps the stack LevelMoods' data names on the scene, and lays each mood's toon ramp, ink and paper on it per machine (`StyleKit.setLocal`) |
| `PlatformerBridge` | platformer3dKit | tells LevelMoods which level the local player is running |
| `CampaignBridge` | campaignKit | keeps a level's mood through its send-off, results and finale |
Put the ones you need on the same entity as `moodKit.LevelMoods` (or anywhere in the scene):
```lua
local e = entity.spawn("LevelMood")
e.component.add("moodKit.LevelMoods", { set = asset.resolve("myGame.levelMoods", "data") })
e.component.add("moodKitBridges.ClockBridge", {})
e.component.add("moodKitBridges.StyleBridge", {})
e.component.add("moodKitBridges.PlatformerBridge", {})
```
Install only the bridges whose kits you have: each component installs on its own with the kit it
names. The per-machine setters (`Clock/Weather/Sky.setLocal`, `Atmos.setMood`, `StyleKit.setLocal`)
arrived in worldClockKit 1.4.8, alpineKit 1.0.12 and styleKit 1.4.9; on an older kit the bridge
says so once and the shared clock and look stay as they are.