@idle-screens/saver-metaquarium 0.16.0 → 0.18.0

package/README.md

@@ -135,7 +135,7 @@ seed (nothing fetched); the world layers that stand on it are under
 | environment | enum | `void` | The ROOM: `void` (exactly the pre-environment scene), `abyss`, `reef`, `kelp`, `ice`, `vent`, `lagoon`, `universe`. Adds terrain and light shafts, plus a water ceiling for the rooms that have one (reef, kelp, ice, lagoon); never overrides your palette params |
 | floorKind | enum | `auto` | Override the environment's terrain: `auto`, `flat`, `dunes`, `ridges`, `basin`, `shelf` (town on a plateau), `trench` (a channel across the front), `terraces` (tiers behind the town) |
 | waterY | number | −1 | Water-ceiling height, −1–220. −1 follows the environment (step, not smooth — the sentinel can't be interpolated through) |
-| rayStrength | number | −1 | Light-shaft strength, −1–1. −1 follows the environment, 0 = off (step, same sentinel reason) |
+| rayStrength | number | −1 | Light-shaft strength, −1–1. −1 follows the environment, 0 = off (step, same sentinel reason). Shafts cost device budget: 5 on the high tier, 2 on standard, none on the lowest tier in a room with a water surface (abyss, vent and universe keep 2); `room.rayStrength` reads 0 where they were dropped |
 
 ### Palette
 
@@ -185,11 +185,11 @@ Every one of them defaults to off — 0, `none`, −1 for `followSpot`, empty fo
 | --- | --- | --- |
 | `rockDensity` | 0–1 | Crystal-root boulders, sparse satellite rocks, a distant ridge and an open arch. Any positive value provides foundations; density adds satellites. |
 | `rockVeins` | 0–1 (0.7) | How hard the crystals broke out of the stone. Each rock's crown is heaved into a pit with chips of stone on the rim and a few short dark fractures, and a colony of real crystals (druse or spire, the same shards, material, pulse and halo as `propMix`) grows out of it, rooted inside the rock. A rock under a `propMix` cluster is broken open under that cluster instead. More veins, more rocks split, and bigger colonies. The colonies add no floor light. 0 is plain stone. |
-| `geodeHomes` | 0–3 | Geode homes: a broken boulder with an agate rind and a throat of crystal teeth, and a voxel house recessed inside — round door, lit window, lamp, steps, a chimney that vents bubbles. Habits cycle cottage / hall / tower; each home lights the floor at its door. Weak devices retain at most two. |
+| `geodeHomes` | 0–3 | Geode homes: a broken boulder with an agate rind and a throat of crystal teeth, and a voxel house recessed inside — round door, lit window, lamp, steps, a chimney that vents bubbles. Habits cycle cottage / hall / tower; each home lights the floor at its door. Weak devices retain at most two: geodeHomes is capped at 2 on basic and minimal tiers (3 on standard and high); a house that is dropped takes its `homeN`/`homeNin` marks with it, and indoors (`interior: geode`) there are no `homeN` marks. |
 | `interior` | `none` · `geode` | Sets the scene INSIDE a geode home: crystal-lined dome with agate strata, plank floor and rug, voxel furniture, a chandelier / lamp / stove / window that light the floor and the fish. Use with the `void` environment; the default orbit camera stays indoors (keep `cameraDistance` ≲ 130). |
 | `followSpot` | -1…23 | A follow-spot on one fish (its cast slot; -1 off): a beam from the rig, a pool of moving caustics on the floor beneath it, a light that rides with the fish, and the house lights down — a performer on a stage. `spotStrength` 0–1, `spotColor`. Closed-form: it follows the fish's own deterministic path. |
-| `vignette` | string | A small scene for the first 2–3 fish: a preset (`tea`, `bedtime`, `seek`) or a script of beats — `a =table, b =door \| b >table @a \| a @b talk, b @a nod \| a b circle rug`. `=mark` start there, `>mark` go there, `@x` face a mark or actor, `circle x`, `follow x`, gestures `talk nod shake hop spin wiggle bow peek rest`, leading `6s:` sets a beat's length. Marks indoors: rug table bed shelf stove lamp armchair door window chest chandelier; outdoors: centre left right front back high low. Closed-form, looping; other fish swim as usual. |
-| `floraDensity` | 0–1 | Voxel plants — seventeen species (grass, tube worms, lantern bulbs, fans, kelp, anemone, staghorn, brain coral, sea whip, barrel sponge, glow caps, sea pen, bubble algae, fiddlehead curls, orb pods, and two specimens: the giant clam and the elder blossom tree). They grow in colonies that share a colour, ramp from base to tip, and one colony in thirty is a rare nacreous morph; they lean toward the nearest crystal and, on mid/high tiers, are lit by it and by follow-spots. Stony coral stands still, kelp and whips sway, tentacles writhe; a gust travels across the field, tips breathe. With `floraMix` empty the room picks the garden (coral on a reef, kelp and whips in the kelp forest, glow caps in the abyss). Plants answer passing fish: anemone crowns fold, worms duck, sea pens pull down, pods swell, lamps flare. |
+| `vignette` | string | A small scene for the first 2–3 fish: a preset (`tea`, `bedtime`, `seek`) or a script of beats — `a =table, b =door \| b >table @a \| a @b talk, b @a nod \| a b circle rug`. `=mark` places an actor with no travel (in a later beat it snaps at the start of the beat), `>mark` swims there, `@x` face a mark or actor, `circle x` (each named actor from wherever it stands onto a ring round the mark and back to its own spot by the end of the beat; actors not named stay put), `follow x`, gestures `talk nod shake hop spin wiggle bow peek rest`, and `ink` (an octopus's own: it squirts a cloud of ink on its mark; other breeds ignore it, with a warning), leading `6s:` sets a beat's length. Marks indoors: rug table bed shelf stove lamp armchair door window chest chandelier (bearings and distances in `GRAMMAR`; they scale with the room, by `max(crystalScale, 0.85)`); outdoors: centre left right front back high low. A floor creature cast as an actor keeps its feet on the floor at its marks, and maneuvers leave actors alone. Closed-form, looping; other fish swim as usual. |
+| `floraDensity` | 0–1 | Voxel plants — seventeen species (grass, tube worms, lantern bulbs, fans, kelp, anemone, staghorn, brain coral, sea whip, barrel sponge, glow caps, sea pen, bubble algae, fiddlehead curls, orb pods, and two specimens: the giant clam and the elder blossom tree). They grow in colonies that share a colour, ramp from base to tip, and one colony in thirty is a rare nacreous morph; they lean toward the nearest crystal and, on mid/high tiers, are lit by it and by follow-spots. Stony coral stands still, kelp and whips sway, tentacles writhe; a gust travels across the field, tips breathe. With `floraMix` empty the room picks the garden (coral on a reef, kelp and whips in the kelp forest, glow caps in the abyss). Plants answer passing fish: anemone crowns fold, worms duck, sea pens pull down, pods swell, lamps flare. The density sets one tank-wide plant budget (density × 36 / 72 / 108 by tier), shared round-robin among the crystals and geodes (or six bare spots when there are none): more crystals means sparser gardens, not more plants. |
 | `floraPalette` | string | One colour scheme for the garden: `world` (seeded) or up to six comma-separated `#rrggbb` values. Empty = each species' own colours. |
 | `geodes` | 0–1 | Wild geodes, few and made properly: split geodes (one in three a thunder egg), amethyst cathedrals, crystal clusters and one mega cavern geode. Agate banding drawn per pixel, crystals in real quartz habit and colour-zoned root to tip, twinkling druse, self-lit so they read in a flat tank; one in twenty is an iridescent aura morph, and their crystals wake when a fish comes close. |
 | `geodeMix` | string | Which kinds: `kind[:weight]`, comma-separated — `geode, cathedral, cluster, cavern`. |
@@ -197,6 +197,13 @@ Every one of them defaults to off — 0, `none`, −1 for `followSpot`, empty fo
 | `geodeLayout` | `field` \| `gallery` | Scattered, or one of each kind in rows. |
 | `fountain` | `none` \| `vent` \| `geode` | The town square's fountain: a hot-vent chimney or a geode basin, with a bubble column, a pebble plaza and its own light; adds a `fountain` vignette mark. |
 | `streetLamps` | 0–1 | Crystal streetlamps round the plaza and along the paths (needs `paths`). |
+| `townProps` | string | The village's small things, `kind[:count][/style], …`: `fence` (driftwood coral stone crystal) round every home's yard, `mailbox` (post, clam, bottle) by every gate, `bench[:n]` (shell stone) round the square, `sock[:n]` current socks. Fences and mailboxes need `geodeHomes`. |
+| `floorCover` | string | What the village lays on its floor, `kind[/style], …`: `lawn` (stripes checks) mown in every yard, `mosaic` (stone shell glass) a compass rose tiled round the fountain, `mat` (kelp stripe) a doormat at every door, `steps` (slate sand moss) stepping stones down the paths, `ripples` (fine broad) sand combed by the current. Lawns and mats need `geodeHomes`, steps need `paths`. |
+| `pyramids` | 0–1 | Pyramids built of cubes, as the fish are: on the floor in complexes (a great pyramid and its queens), small ones near, great ones at the back, only on flat ground (`floorKind: flat`). Standing, half sunk, one missing its capstone. |
+| `pyramidMix` | string | Their shapes and stones, `shape\|stone[:weight], …`: giza step bent djoser mayan frame · sandstone limestone obsidian jade gold lapis coral crystal nacre basalt, and the lit `led` and `neon`, every cube a lamp running a light show. |
+| `pyramidLayout` | `field` \| `stage` | `stage`: one monumental pyramid in the middle of the orbit (lit, or stone with lit trim), a small one at each side, the field behind. |
+| `pyramidShow` | string | The lit pyramids' light show: `auto` (the field as one, through every routine), `solo`, a routine (rings beam edges equalizer rainbow twinkle faces rain spiral breathe ripple), or a cue sheet `8s:rings, 8s:beam`. Live, no rebuild. |
+| `pyramidBpm` | 0–140 | The show's tempo (0 = free): the motion steps on the beat, each beat lifts the lamps under a flash. |
 | `floraLayout` | `garden` \| `gallery` | Grow round the crystals, or one plot per species to see them all. |
 | `floraMix` | string | Which plants grow: `species[:weight]`, comma-separated, e.g. `kelp:3, whip, seapen`. Bad entries are dropped with one console warning. Empty = the room's own garden. |
 | `bubbleVents` | 0–1 | Bubbles in puffs from geode chimneys, fissure crowns and crystal bases; they quicken, swell and wander as they rise. |
@@ -233,6 +240,25 @@ textures, downloads, shadow maps or additional lights. Flora, shards, snow and
 bubbles scale with the existing device prop budget. `inspect().props.scenery`
 reports actual populations; prop draw-call/triangle totals include the world.
 
+## Signs
+
+`signs` puts underwater signage in the world, one entry a sign: `kind[@place][>target][/#color][*size][:text]`, comma-separated, up to eight.
+
+| kind | what stands there |
+| --- | --- |
+| `plank` | weathered boards nailed to a post, the lettering painted on (≤ 24 characters) |
+| `arrow` | a board cut to a point, aimed at `>target` (≤ 16) |
+| `ring` | a striped life-ring hung on a post, a name plaque under it (≤ 10) |
+| `porthole` | a brass porthole set in a stone, its glass lit; a word (≤ 4) or, with none, a fish |
+| `neon` | glowing tube lettering on a dark board, a halo and light on the floor (≤ 14) |
+| `led` | a dot-matrix board in the hackerfish's pixels; a line longer than the board scrolls (≤ 64) |
+
+A sign stands beside its place — `gate`, `plaza`, `courtyard`, `hub`, `fountain`, `home1`–`home3`, or the open tank's `centre`, `left`, `right`, `front`, `back` — never on it, and faces the front. With no place it finds a clear spot across the front of the tank. Lettering is a 5×7 pixel font (capitals, digits, common punctuation, `° ♥ ★`); `/#color` colours the lettering, tubes, LEDs, glass or stripes. Signs stay outdoors (not in `interior: geode`), and fish swim round them. Lit signs (neon, LED) run on old wiring: `signFlicker` (0–1, default 0.4) sets how unstable it is — a slow hum, two-dip stutters, a dead row or tube, a row slipping sideways, now and then a reboot that wakes row by row. Each sign has its own supply (most steady, a few bad); events are one per four-second slot at most, so it stays under WCAG's three flashes a second at any setting.
+
+```ts
+signs: 'plank@gate:"Welcome to the reef", arrow@hub>gate:Castle, neon@home1/#ff4fa0:OPEN, led@plaza:TIDE 4.2M - WATER 24°'
+```
+
 ## Reading a scene back
 
 A SaverSpec explains itself; a metaquarium scene is `{id: "metaquarium"}` plus a control track. `describeMetaquarium` reads that back as parts, using the tank's own parsers and room presets, for a viewer's scene card, a channel's state, or an agent with no eyes: