mochi-avatar 1.0.0

package/dist/core/looks.js

@@ -0,0 +1,168 @@
+/**
+ * How each emotion deforms the neutral face.
+ *
+ * Every Emotion gets an entry, enforced by `Record<Emotion, Look>`. Letting one
+ * fall through to neutral would make `caps.presetExpressions` a lie: the
+ * backend would claim to support an expression it renders identically to no
+ * expression at all, and the caller has no way to discover that.
+ *
+ * Values are multipliers on the tuned base geometry rather than absolute sizes,
+ * so retuning the face in the tuner does not invalidate the table.
+ */
+import { clamp01 } from './vocabulary.js';
+export const NEUTRAL = {
+    eyeUpper: 1,
+    eyeLower: 1,
+    eyeWidth: 1,
+    eyeTilt: 0,
+    mouthUpper: 1,
+    mouthLower: 1,
+    mouthWidth: 1,
+    mouthAlpha: 1,
+    cheek: 0,
+    sparkle: 0,
+    gazeX: 0,
+    gazeY: 0,
+    squash: 0,
+    lean: 0,
+};
+export const LOOKS = {
+    neutral: NEUTRAL,
+    happy: {
+        ...NEUTRAL,
+        eyeUpper: 1.1,
+        // Negative: the bottom edge lifts past the baseline and the eye becomes ^.
+        eyeLower: -0.62,
+        eyeWidth: 1.06,
+        mouthUpper: 0,
+        mouthLower: 2.8,
+        mouthWidth: 1.35,
+        cheek: 0.6,
+        sparkle: 1,
+        squash: 0.13,
+    },
+    shy: {
+        ...NEUTRAL,
+        eyeUpper: 0.72,
+        eyeLower: -0.28,
+        eyeWidth: 0.96,
+        mouthUpper: 0,
+        mouthLower: 0.7,
+        mouthWidth: 0.66,
+        cheek: 1,
+        gazeX: -0.38,
+        gazeY: 0.28,
+        squash: 0.07,
+        lean: -0.06,
+    },
+    sad: {
+        ...NEUTRAL,
+        eyeUpper: 0.82,
+        eyeLower: 1.14,
+        eyeTilt: -0.17,
+        mouthUpper: 3,
+        mouthLower: -0.3,
+        mouthWidth: 0.9,
+        gazeY: 0.34,
+        squash: -0.11,
+    },
+    angry: {
+        ...NEUTRAL,
+        eyeUpper: 0.55,
+        eyeLower: 0.92,
+        eyeWidth: 1.06,
+        eyeTilt: 0.28,
+        mouthUpper: 2,
+        mouthLower: 0,
+        mouthWidth: 0.84,
+        cheek: 0.28,
+        gazeY: -0.14,
+        squash: 0.16,
+    },
+    surprised: {
+        ...NEUTRAL,
+        eyeUpper: 1.7,
+        eyeLower: 1.7,
+        eyeWidth: 1.16,
+        mouthUpper: 0,
+        mouthLower: 2.6,
+        mouthWidth: 0.62,
+        cheek: 0.12,
+        sparkle: 1,
+        gazeY: -0.2,
+        // -0.16, down from -0.24. This is the waking perk: `main.ts` wears
+        // `surprised` the instant she is told to wake, on top of a poke. At -0.24
+        // the pair drove the squash target past -0.34, which stretches her to
+        // roughly one and a half times her height -- a launch rather than an "oh!".
+        squash: -0.16,
+    },
+    thinking: {
+        ...NEUTRAL,
+        eyeUpper: 0.9,
+        eyeLower: 0.72,
+        eyeTilt: 0.09,
+        mouthUpper: 1,
+        mouthLower: 0.3,
+        mouthWidth: 0.58,
+        gazeX: -0.52,
+        gazeY: -0.42,
+        lean: 0.07,
+    },
+    sleepy: {
+        ...NEUTRAL,
+        eyeUpper: 0.16,
+        eyeLower: 0.16,
+        eyeTilt: -0.11,
+        mouthUpper: 0,
+        mouthLower: 1.5,
+        mouthWidth: 0.52,
+        // Gone. She is asleep; a mouth is the difference between resting and quiet.
+        mouthAlpha: 0,
+        cheek: 0.22,
+        gazeY: 0.34,
+        /*
+          0.11, up from 0.09, which had itself been cut from 0.19.
+    
+          `sleepy` is what she wears for the whole time she is asleep, which is most
+          of her life, so it is the pose she is judged on -- and at 0.19 plus a
+          breath she spread to 1.24 times her width and read as a puddle rather than
+          as something resting. The cut was applied HERE, to the resting pose,
+          because the breath it was summed with reached +0.045 and could not be
+          argued with.
+    
+          Back to 0.09, and the round trip is worth recording. It was raised to 0.11
+          when the breath became one-sided and small, on the argument that the same
+          0.135 ceiling bought a fuller resting pose. That argument was sound and the
+          premise did not survive: at the waking amplitude she moved 2px asleep and
+          read as switched off, so the asleep breath is twice as deep again (see
+          `ASLEEP_BREATH_GAIN`). With an excursion of 0.048 the base has to come back
+          down for the ceiling to stay where it was — 0.09 + 0.048 is 0.138, against
+          the 0.135 the pose plus breath already peaked at before any of this.
+    
+          The pose is the same as it ever was, then. What changed is that the
+          movement on top of it is now all swell and no stretch.
+        */
+        squash: 0.09,
+    },
+};
+const KEYS = Object.keys(NEUTRAL);
+/**
+ * Neutral blended toward the named emotion by intensity.
+ *
+ * Intensity 0 is exactly neutral for every emotion, which is what lets a signal
+ * decay smoothly rather than snapping when it expires.
+ */
+export function blendLook(emotion, intensity) {
+    const target = LOOKS[emotion];
+    const t = clamp01(intensity);
+    const out = {};
+    // `a*(1-t) + b*t`, not `a + (b-a)*t`. The two are equivalent in real
+    // arithmetic and not in floating point: the second form returns
+    // 1.1000000000000001 rather than 1.1 at t = 1, so a fully applied emotion is
+    // never quite the look that was tuned. The endpoints are the values a human
+    // chose in the tuner, and they should survive the trip exactly.
+    for (const key of KEYS)
+        out[key] = NEUTRAL[key] * (1 - t) + target[key] * t;
+    return out;
+}
+//# sourceMappingURL=looks.js.map

package/dist/core/looks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"looks.js","sourceRoot":"","sources":["../../src/core/looks.ts"],"names":[],"mappings":"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"}

package/dist/core/motion.d.ts

@@ -0,0 +1,168 @@
+/**
+ * A motion: the layer between idle and expression.
+ *
+ * ## Why this format exists now, having been refused twice
+ *
+ * The argument for not writing it was that a format designed against ONE
+ * motion set comes out shaped like that set. That was right, and it made the
+ * missing input sound external when it was not: the answer is to author a
+ * second motion, not to wait for one. So there are two below, deliberately
+ * unalike — `nod` is short, one-shot and postural; `sway` loops and moves her
+ * gaze. Everything here is a thing both of them needed.
+ *
+ * What that shook out, which one clip would not have:
+ *
+ *   - `loop`, because one of them does and one must not
+ *   - keys with OPTIONAL channels, because `nod` never touches gaze and a
+ *     format forcing it to write zeros would make every clip claim every
+ *     channel, and then "unset" and "zero" would be the same thing
+ *   - normalised time, because the two differ in duration by 6x and keys
+ *     written in milliseconds cannot be retimed without rewriting them all
+ *
+ * ## Four channels, and the mouth is not among them
+ *
+ * The layer order is idle -> motion -> expression -> mouth, and no layer may
+ * overwrite the mouth. A motion that could write `mouthOpen` would be able to
+ * hold her jaw shut while audio is playing, which reads as broken. The
+ * channels here are POSTURAL -- squash, lean, and where she is looking -- so
+ * the rule is a property of the vocabulary rather than something each clip has
+ * to respect.
+ */
+/**
+ * Everything a motion is allowed to move. See the header.
+ *
+ * ## The three that were added, and why they are not more
+ *
+ * `squash`, `lean`, `gazeX`, `gazeY` are postural and could not express a
+ * character who goes anywhere: a hop with no vertical channel is a crouch, and
+ * a wander with no horizontal one is a lean. So:
+ *
+ * - `lift` — up, in fractions of her body HEIGHT. Positive leaves the ground.
+ * - `shift` — right, in fractions of her body WIDTH.
+ * - `turn` — -1..1, how far her features have slid toward one side.
+ *
+ * `turn` is NOT a rotation and cannot become one. One front-facing silhouette
+ * is drawn; there is no second view and no yaw. What it does is slide the
+ * features across the body, and everything is clipped to the silhouette
+ * already, so the far eye passes out of sight around her edge. That reads as
+ * turning to look at something and does not read as turning around. Anyone
+ * wanting the second thing has to draw her from behind, which is art rather
+ * than a channel.
+ *
+ * The mouth is still not among these, for the reason the header gives.
+ *
+ * ## Translation is a channel, not a window move
+ *
+ * `lift` and `shift` move her INSIDE her own window, and `paint` applies them
+ * by offsetting the origin every other coordinate is derived from -- so the
+ * outline, the features and the hit-test silhouette all travel together, and
+ * click-through keeps following her painted pixels for free.
+ *
+ * Moving the WINDOW was the alternative and is worse: `setPosition` from main
+ * on every frame of a renderer-driven animation is two processes disagreeing
+ * about where she is sixty times a second, which is the problem `drag.ts`
+ * already needs a cursor poll to solve.
+ */
+export declare const MOTION_CHANNELS: readonly ['squash', 'lean', 'gazeX', 'gazeY', 'lift', 'shift', 'turn'];
+export type MotionChannel = (typeof MOTION_CHANNELS)[number];
+/** What the layer contributes at one instant. Absent means "not moved". */
+export type MotionPose = Partial<Record<MotionChannel, number>>;
+export interface MotionKey extends MotionPose {
+    /**
+     * Where in the clip, 0..1.
+     *
+     * NORMALISED rather than milliseconds. The two built-ins differ in length by
+     * six times, and a clip timed in absolute units cannot be slowed down
+     * without rewriting every key in it.
+     */
+    readonly t: number;
+}
+export interface MotionClip {
+    readonly durationMs: number;
+    /** Whether it starts again. `sway` does; `nod` must not. */
+    readonly loop: boolean;
+    /** Sorted by `t`, which `parseMotionClip` checks rather than assumes. */
+    readonly keys: readonly MotionKey[];
+}
+/**
+ * How far through a clip we are, or null once a one-shot has finished.
+ *
+ * Null rather than 1: a finished one-shot contributes NOTHING, and holding its
+ * last key would leave her permanently leaning if a clip happened to end away
+ * from neutral. The caller stops mixing the layer in at all.
+ */
+export declare function progress(clip: MotionClip, elapsedMs: number): number | null;
+/**
+ * The pose at a moment, interpolated between the keys around it.
+ *
+ * Per CHANNEL, not per key. A key that omits `gazeX` is not saying "zero", it
+ * is saying nothing -- so the interpolation for that channel runs between the
+ * nearest keys that DO mention it, and a channel no key mentions is absent
+ * from the result. Blending toward an implied zero instead would make every
+ * clip fight every other layer over channels it never meant to touch.
+ */
+export declare function poseAt(clip: MotionClip, at: number): MotionPose;
+/**
+ * A short agreement, and a long one that repeats.
+ *
+ * Two, and unalike on purpose -- see the header. They are also the only
+ * motions this app has, which is why `caps.supportsMotions` can finally be
+ * true: a backend claiming the capability with an empty library would be the
+ * flag lying, and `playMotion` would report success over a face that never
+ * moved.
+ */
+export declare const BUILT_IN_MOTIONS: Readonly<Record<string, MotionClip>>;
+/**
+ * How far a clip takes her from where she stands, as fractions of her body.
+ *
+ * The room for a translation has to exist in her window BEFORE she uses it, or
+ * she walks into the edge of a transparent rectangle and is clipped by it. This
+ * is what `face.ts` reserves against, and it is derived from the keys rather
+ * than declared beside them: a number an author has to keep in step with the
+ * clip is a number that goes stale the first time somebody retimes it.
+ *
+ * `up` only, for `lift`. She hops; she does not sink through the floor, and
+ * reserving room below her would push her down inside her own window for a
+ * clearance nothing uses.
+ */
+export declare function motionReach(clip: MotionClip): {
+    readonly x: number;
+    readonly up: number;
+};
+/**
+ * The worst case across every built-in, PLUS the drift, which is what a window
+ * has to hold.
+ *
+ * The drift is continuous and additive -- she is always a little off her spot,
+ * and a clip starts from wherever that is rather than from centre. So the two
+ * reaches SUM: reserving only the clip's would clip her by a couple of pixels
+ * at whichever extreme the two happened to agree on, intermittently, which is
+ * the least debuggable kind of wrong.
+ */
+export declare function builtInReach(): {
+    readonly x: number;
+    readonly up: number;
+};
+export type MotionParse = {
+    readonly ok: true;
+    readonly clip: MotionClip;
+} | {
+    readonly ok: false;
+    readonly problems: readonly string[];
+};
+/**
+ * Turn something off disk into a clip, or say what is wrong with all of it.
+ *
+ * A package may carry motions, so this is a trust boundary and takes the same
+ * treatment `parseFaceSpec` gets: every problem reported at once
+ * rather than the first, unknown keys refused rather than dropped, and every
+ * number range-checked -- `t: 5` and `squash: 400` are both valid JSON numbers
+ * that throw nothing and produce a mochi somewhere off the screen.
+ *
+ * The ordering and loop-closure rules are checked HERE rather than trusted,
+ * because `poseAt` is written against them: keys out of order make the
+ * interpolation pick the wrong pair, and a loop whose ends differ jumps once
+ * per cycle for as long as it plays.
+ */
+export declare function parseMotionClip(value: unknown): MotionParse;
+//# sourceMappingURL=motion.d.ts.map

package/dist/core/motion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"motion.d.ts","sourceRoot":"","sources":["../../src/core/motion.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAIH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,eAAO,MAAM,eAAe,YAC1B,QAAQ,EACR,MAAM,EACN,OAAO,EACP,OAAO,EACP,MAAM,EACN,OAAO,EACP,MAAM,CACE,CAAA;AACV,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,CAAC,CAAA;AAE5D,2EAA2E;AAC3E,MAAM,MAAM,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,aAAa,EAAE,MAAM,CAAC,CAAC,CAAA;AAE/D,MAAM,WAAW,SAAU,SAAQ,UAAU;IAC3C;;;;;;OAMG;IACH,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,4DAA4D;IAC5D,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;IACtB,yEAAyE;IACzE,QAAQ,CAAC,IAAI,EAAE,SAAS,SAAS,EAAE,CAAA;CACpC;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAK3E;AAED;;;;;;;;GAQG;AACH,wBAAgB,MAAM,CAAC,IAAI,EAAE,UAAU,EAAE,EAAE,EAAE,MAAM,GAAG,UAAU,CAO/D;AAwID;;;;;;;;GAQG;AACH,eAAO,MAAM,gBAAgB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAyJjE,CAAA;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,UAAU,GAAG;IAAE,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;CAAE,CAQzF;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,IAAI;IAAE,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;CAAE,CAS1E;AAED,MAAM,MAAM,WAAW,GACnB;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;CAAE,GAChD;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,CAAA;AAEhE;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,WAAW,CA0F3D"}