@idle-screens/saver-metaquarium 0.6.0 → 0.7.0

package/README.md

@@ -58,12 +58,15 @@ frame loop (rAF or renderFrame(t)):
 | swimSpeed | number | 1 | Swim time-scale multiplier |
 | fogColor | color | #030009 | Atmosphere / background |
 | fishUrl | string | ipfs://…/fish_257_….glb | GLB model URL, single-breed mode (playground can override to a local asset) |
-| fishMix | string | "" | Mixed population DSL: `id[:count]` comma-separated, catalog ids or breed aliases (`"257:2,100:1"`). Non-empty overrides fishUrl + fishCount; counts absolute, tier-capped |
+| fishMix | string | "" | Mixed population DSL: `id[:count][@style]` comma-separated, catalog ids or breed aliases (`"257:2,100:1"`, `"457:3@hover,257:6@school"` — per-token swim style; untagged tokens follow `swimStyle`). Non-empty overrides fishUrl + fishCount; counts absolute, tier-capped |
 | fogNear | number | 60 | Fog start distance (the old hardcoded Fog near) |
 | fogFar | number | 500 | Fog full-opacity distance; tank enforces > near + 20 |
 | moteDensity | number | 0 | Plankton motes, 0–1 of the tier budget (400/250/120). 0 = off |
 | moteColor | color | #7fd6ff | Mote tint |
 | floorColor | color | #0a1d33 | Floor disc color (the old hardcoded navy) |
+| swimStyle | enum | loop | `loop` (pre-style), `school`, `drift`, `hover`, `patrol`, `bottom`, `surface`; relationship styles `follow` / `pair` / `chase` bond a fish to the nearest preceding unbonded fish in the mix (and swim in its depth band); `auto` gives each untagged token its breed's default |
+| lightSeek | number | 0 | Free fish drawn toward the room's light shafts, each to its own pool (needs rays) |
+| formationBreathe | number | 0 | The school relaxes outward and back on a ~15 s cycle; only ever expands |
 
 ## File map
 

package/dist/{chunk-O676ILL6.js → chunk-RTUYWDDZ.js}

@@ -94,8 +94,44 @@ var SWIM_STYLES = [
   { name: "hover", label: "Hover", speedMul: 0.55, band: "free", bobAmp: 7, bobHz: 0.3, formation: false, travel: 0.12 },
   { name: "patrol", label: "Patrol", speedMul: 0.55, band: "mid", bobAmp: 1, bobHz: 0.09, formation: false, travel: 1 },
   { name: "bottom", label: "Bottom-hugger", speedMul: 0.7, band: "floor", bobAmp: 2, bobHz: 0.4, formation: false, travel: 1 },
-  { name: "surface", label: "Surface-skimmer", speedMul: 0.9, band: "ceiling", bobAmp: 3, bobHz: 0.55, formation: false, travel: 1 }
+  { name: "surface", label: "Surface-skimmer", speedMul: 0.9, band: "ceiling", bobAmp: 3, bobHz: 0.55, formation: false, travel: 1 },
+  // Relationships (MQ31). A bonded fish has no route of its own: it rides
+  // its leader's plan at a lag, so a `@follow` trio behind a turtle is a
+  // file, a `@pair` couple orbits a shared point, and a `@chase` closes on
+  // its leader and falls back. All three stay pure in t because the leader
+  // is — the follower samples the SAME closed form at `d - lag`.
+  { name: "follow", label: "Follower", speedMul: 1, band: "free", bobAmp: 1.2, bobHz: 0.5, formation: false, travel: 1, bond: "follow" },
+  { name: "pair", label: "Pair", speedMul: 0.8, band: "free", bobAmp: 2.5, bobHz: 0.35, formation: false, travel: 1, bond: "pair" },
+  { name: "chase", label: "Chaser", speedMul: 1, band: "free", bobAmp: 1, bobHz: 0.6, formation: false, travel: 1, bond: "chase" }
 ];
+var AUTO_STYLE_BY_BREED = {
+  angelfish: "school",
+  betafish: "drift",
+  seahorse: "hover",
+  seaturtle: "surface",
+  // The unminted NPC set.
+  blowfish: "hover",
+  hackerfish: "loop",
+  glowfish: "drift",
+  babyfish: "school",
+  shark: "patrol",
+  crab: "bottom",
+  jellyfish: "drift",
+  dori: "school"
+};
+function autoStyleFor(breed) {
+  const name = breed ? AUTO_STYLE_BY_BREED[breed.toLowerCase()] : void 0;
+  return swimStyleOf(name ?? "loop");
+}
+function formationBreathe(tSec, amount) {
+  const a = Math.max(0, Math.min(1, amount));
+  if (a <= 0) return 1;
+  return 1 + a * 0.22 * (0.5 + 0.5 * Math.sin(tSec * 0.42));
+}
+function idleSway(style, tSec, phase) {
+  if (style.travel >= 1 || style.formation) return 0;
+  return (1 - style.travel) * 0.5 * Math.sin(tSec * 0.45 + phase);
+}
 var SWIM_STYLE_NAMES = SWIM_STYLES.map((s) => s.name);
 function swimStyleOf(name) {
   return SWIM_STYLES.find((s) => s.name === name) ?? SWIM_STYLES[0];
@@ -128,7 +164,7 @@ function anchorFraction(style, index, variance) {
 }
 var FISH_LENGTH = 18;
 var FORMATION_HALF_WIDTH = 62;
-var FORMATION_SHAPES = ["phalanx", "line", "ring", "wedge", "ball"];
+var FORMATION_SHAPES = ["phalanx", "line", "ring", "wedge", "ball", "wheel"];
 function formationSlot(index, count, variance, halfWidth = FORMATION_HALF_WIDTH, shape = "phalanx") {
   const j = 0.35 + 0.65 * Math.max(0, Math.min(1, variance));
   if (shape === "line") {
@@ -152,6 +188,15 @@ function formationSlot(index, count, variance, halfWidth = FORMATION_HALF_WIDTH,
       back: Math.sin(a) * r
     };
   }
+  if (shape === "wheel") {
+    const r = Math.max(FISH_LENGTH * 1.6, count * FISH_LENGTH * 1.35 / (Math.PI * 2));
+    const a = index / Math.max(1, count) * Math.PI * 2;
+    return {
+      side: Math.cos(a) * r,
+      up: Math.sin(a) * Math.min(r * 0.55, 24) + (fishHash(index, 5) - 0.5) * FISH_LENGTH * 0.3 * j,
+      back: Math.sin(a) * r
+    };
+  }
   if (shape === "wedge") {
     const VSIZE = 9;
     const layers = Math.ceil(Math.max(1, count) / VSIZE);
@@ -210,6 +255,12 @@ function formationExtent(count, variance, shape = "phalanx") {
   }
   return { side, up, back, reach };
 }
+function fitBreath(extent, lattice, bounds, margin = FISH_LENGTH * 0.5) {
+  let fit = lattice;
+  if (extent.up > 0) fit = Math.min(fit, Math.max(1, (bounds.yRange / 2 - margin) / extent.up));
+  if (extent.reach > 0) fit = Math.min(fit, Math.max(1, (bounds.radius - margin) / extent.reach));
+  return fit;
+}
 function bandRange(band) {
   switch (band) {
     // Tight, because 0..0.3 of a 57-unit volume is nearly two body lengths of
@@ -247,10 +298,32 @@ function splineAt(points, g) {
     catmullRom(p0[2], p1[2], p2[2], p3[2], u)
   ];
 }
-var PATH_SHAPES = ["wander", "orbit", "eight", "helix", "canyon"];
-function shapeWaypoints(shape, rng, bounds) {
+var PATH_SHAPES = ["wander", "orbit", "eight", "helix", "canyon", "crossing"];
+function shapeWaypoints(shape, rng, bounds, opts = {}) {
   const points = [];
   const ySpan = bounds.yMax - bounds.yMin;
+  if (shape === "crossing") {
+    const n2 = 16;
+    const az = (opts.cameraAzimuthDeg ?? 0) * Math.PI / 180;
+    const rx = Math.cos(az), rz = -Math.sin(az);
+    const dx = Math.sin(az), dz = Math.cos(az);
+    const len = bounds.radius * 0.9;
+    const depth = bounds.radius * rng.range(0.18, 0.3);
+    const y0 = bounds.yMin + ySpan * rng.range(0.35, 0.6);
+    const lift = ySpan * rng.range(0.04, 0.1);
+    for (let i = 0; i < n2; i++) {
+      const u = i / n2 * Math.PI * 2;
+      const along = Math.sin(u) * len;
+      const toward = Math.cos(u) * depth;
+      points.push([
+        rx * along + dx * toward,
+        // The far leg rides a little higher so it never hides behind the near one.
+        y0 + (toward < 0 ? lift : 0) + ySpan * rng.range(0, 0.04),
+        rz * along + dz * toward
+      ]);
+    }
+    return points;
+  }
   if (shape === "orbit") {
     const n2 = 14 + rng.int(0, 4);
     const r0 = bounds.radius * rng.range(0.45, 0.8);
@@ -325,8 +398,8 @@ function shapeWaypoints(shape, rng, bounds) {
   }
   return points;
 }
-function compileSwimPlan(rng, bounds, shape = "wander") {
-  const points = shapeWaypoints(shape, rng, bounds);
+function compileSwimPlan(rng, bounds, shape = "wander", opts = {}) {
+  const points = shapeWaypoints(shape, rng, bounds, opts);
   const n = points.length;
   const arc = new Float32Array(ARC_SAMPLES + 1);
   let prev = splineAt(points, 0);
@@ -1126,6 +1199,20 @@ function parseFishMix(mix, catalog = FISH_CATALOG) {
   const problems = [];
   const unique = catalog === FISH_CATALOG;
   const used = /* @__PURE__ */ new Set();
+  const resolvesAsToken = (core) => {
+    const [idRaw, countRaw, ...extra] = core.split(":");
+    if (extra.length > 0) return false;
+    if (countRaw !== void 0) {
+      const count = Number(countRaw.trim());
+      if (!Number.isInteger(count) || count < 1) return false;
+    }
+    const key = (idRaw ?? "").trim().toLowerCase();
+    if (/^\d+$/.test(key)) {
+      if (catalog.some((fish) => fish.id === Number(key))) return true;
+      return catalog === FISH_CATALOG && fishAsset(Number(key), "3d") !== null && breedOf(Number(key)) !== null;
+    }
+    return catalog.some((fish) => fish.breed.toLowerCase() === key);
+  };
   const allocate = (breed, want) => {
     const b = BREEDS.find((x) => x.breed === breed);
     if (!b?.range) return null;
@@ -1147,7 +1234,22 @@ function parseFishMix(mix, catalog = FISH_CATALOG) {
   for (const rawToken of mix.split(",")) {
     const token = rawToken.trim();
     if (token === "") continue;
-    const [idRaw, countRaw, ...extra] = token.split(":");
+    let style;
+    let core = token;
+    const at = token.lastIndexOf("@");
+    if (at >= 0) {
+      const styleRaw = token.slice(at + 1).trim().toLowerCase();
+      const styledCore = token.slice(0, at).trim();
+      if (resolvesAsToken(token)) {
+      } else if (SWIM_STYLE_NAMES.includes(styleRaw)) {
+        core = styledCore;
+        style = styleRaw;
+      } else if (resolvesAsToken(styledCore)) {
+        core = styledCore;
+        problems.push(`"${token}": unknown style "${styleRaw}" (${SWIM_STYLE_NAMES.join(", ")}) \u2014 swimming with the scene's swimStyle`);
+      }
+    }
+    const [idRaw, countRaw, ...extra] = core.split(":");
     if (extra.length > 0) {
       problems.push(`"${token}": too many ':' \u2014 expected id[:count]`);
       continue;
@@ -1187,12 +1289,12 @@ function parseFishMix(mix, catalog = FISH_CATALOG) {
       }
     }
     if (!unique || fish.id > TOTAL_SUPPLY) {
-      entries.push({ id: fish.id, url, count });
+      entries.push({ id: fish.id, breed: fish.breed, url, count, ...style ? { style } : {} });
       continue;
     }
     const breed = breedOf(fish.id);
     if (!breed) {
-      entries.push({ id: fish.id, url, count });
+      entries.push({ id: fish.id, breed: fish.breed, url, count, ...style ? { style } : {} });
       continue;
     }
     const isAlias = !/^\d+$/.test(key);
@@ -1212,17 +1314,22 @@ function parseFishMix(mix, catalog = FISH_CATALOG) {
         problems.push(`fish ${got}: no asset URL`);
         continue;
       }
-      entries.push({ id: got, url: gotUrl, count: 1 });
+      entries.push({ id: got, breed: fish.breed, url: gotUrl, count: 1, ...style ? { style } : {} });
     }
   }
   return { entries, problems };
 }
 function expandFishMix(entries, cap) {
-  const urls = [];
+  return expandFishMixSlots(entries, cap).map((s) => s.url);
+}
+function expandFishMixSlots(entries, cap) {
+  const slots = [];
   for (const e of entries) {
-    for (let i = 0; i < e.count && urls.length < cap; i++) urls.push(e.url);
+    for (let i = 0; i < e.count && slots.length < cap; i++) {
+      slots.push(e.style ? { url: e.url, breed: e.breed, style: e.style } : { url: e.url, breed: e.breed });
+    }
   }
-  return urls;
+  return slots;
 }
 
 // src/manifest.ts
@@ -1254,7 +1361,10 @@ var METAQUARIUM_PARAMS = {
    *  different angelfish). A custom catalog is a closed world (no farm/IPFS
    *  fallback, no uniqueness — NPC entries are species). Counts are
    *  absolute; the expanded total clamps to the device tier's fish cap.
-   *  Non-empty mix OVERRIDES fishUrl and fishCount; empty string = single-
+   *  A token may carry its own swim style — `id[:count]@style`, e.g.
+   *  "457:3@hover,257:6@school,497:1@surface" — so one tank holds several
+   *  behaviours; untagged tokens follow `swimStyle`. Non-empty mix
+   *  OVERRIDES fishUrl and fishCount; empty string = single-
    *  breed mode. Unknown ids/bad counts degrade (good tokens still parse);
    *  raw URLs are not accepted here — use fishUrl for a custom single-breed GLB. */
   fishMix: { type: "string", default: "", ease: "step" },
@@ -1296,15 +1406,23 @@ var METAQUARIUM_PARAMS = {
   rayStrength: { type: "number", default: -1, min: -1, max: 1, ease: "step" },
   /** How the fish move. `loop` is exactly the pre-style behaviour, so the
    *  default changes nothing. A small named set on purpose: a silhouette of
-   *  movement you can name is one you can choose from. */
-  swimStyle: { type: "enum", default: "loop", options: [...SWIM_STYLE_NAMES], ease: "step" },
+   *  movement you can name is one you can choose from. `auto` lets each
+   *  untagged fishMix token swim the way its breed does (seahorse hover,
+   *  turtle skim the surface, angelfish school, betafish drift); a token's
+   *  `@style` still wins. The relationship styles — `follow`, `pair`,
+   *  `chase` — bond a fish to the nearest preceding unbonded fish in the mix
+   *  (`seaturtle:1, 257:3@follow` is a turtle with an escort). */
+  swimStyle: { type: "enum", default: "loop", options: [...SWIM_STYLE_NAMES, "auto"], ease: "step" },
   /** The shape a fish's loop is drawn on. `wander` is the original roaming
    *  itinerary, so the default changes nothing. `orbit` laps, `eight` crosses
-   *  the middle, `helix` tours the water column, `canyon` sweeps low — same
-   *  spline engine, different itinerary. */
+   *  the middle, `helix` tours the water column, `canyon` sweeps low,
+   *  `crossing` is a camera-relative parade lane (across the frame in front,
+   *  back the other way behind; laid against cameraAzimuth when chosen) —
+   *  same spline engine, different itinerary. */
   pathShape: { type: "enum", default: "wander", options: [...PATH_SHAPES], ease: "step" },
   /** How a `school` holds together: the original lattice, single file, a
-   *  carousel ring, the migratory V, or a bait-ball. Ignored by every
+   *  carousel ring, the migratory V, a bait-ball, or the ring tilted into a
+   *  `wheel` that reads from a side camera. Ignored by every
    *  non-formation style; the same no-pair-inside-a-body-length law holds
    *  for all of them. */
   formationShape: { type: "enum", default: "phalanx", options: [...FORMATION_SHAPES], ease: "step" },
@@ -1333,7 +1451,18 @@ var METAQUARIUM_PARAMS = {
    *  behaviour, and a scene already on someone's wall should not start moving
    *  differently because a dependency was bumped. 0.3–0.4 is the recommended
    *  value for a clip-less cast — the studio swim variants all set it. */
-  bodyWiggle: { type: "number", default: 0, min: 0, max: 1, ease: "smooth" }
+  bodyWiggle: { type: "number", default: 0, min: 0, max: 1, ease: "smooth" },
+  /** Light-seeking: free-swimming fish are drawn toward the room's light
+   *  shafts, each fish to its own pool. 0 (default) leaves every route
+   *  where it was; 1 pulls a fish most of the way into its shaft, so the
+   *  cast gathers in the light and a `rayStrength` dial becomes a staging
+   *  dial too. Needs a room with rays; formations are steered by their
+   *  carrier and ignore it. */
+  lightSeek: { type: "number", default: 0, min: 0, max: 1, ease: "smooth" },
+  /** Formation breathing: the school relaxes outward and draws back in on a
+   *  slow (~15 s) cycle. 0 (default) is the rigid lattice; 1 opens it by up
+   *  to a fifth. Only ever expands, so the spacing guarantee holds. */
+  formationBreathe: { type: "number", default: 0, min: 0, max: 1, ease: "smooth" }
 };
 var MIAMI_VICE_COLORS = [
   "#ff6ad5",
@@ -1431,6 +1560,10 @@ export {
   RAY_COUNT,
   affordableLayers,
   SWIM_STYLES,
+  AUTO_STYLE_BY_BREED,
+  autoStyleFor,
+  formationBreathe,
+  idleSway,
   SWIM_STYLE_NAMES,
   swimStyleOf,
   fishHash,
@@ -1440,6 +1573,7 @@ export {
   FORMATION_SHAPES,
   formationSlot,
   formationExtent,
+  fitBreath,
   bandRange,
   PATH_SHAPES,
   compileSwimPlan,
@@ -1467,6 +1601,7 @@ export {
   NPC_CATALOG,
   parseFishMix,
   expandFishMix,
+  expandFishMixSlots,
   METAQUARIUM_PARAMS,
   MIAMI_VICE_COLORS,
   BLOOM_COLORS,
@@ -1475,4 +1610,4 @@ export {
   paramSpaceWith,
   coerceNum
 };
-//# sourceMappingURL=chunk-O676ILL6.js.map
+//# sourceMappingURL=chunk-RTUYWDDZ.js.map