@linxin666/dsh-pet 0.3.3 → 0.3.5

package/lib/types/gameplay.d.ts

@@ -0,0 +1,182 @@
+/**
+ * Pet gameplay — the optional manifest 'gameplay' block and its host engine.
+ * The block layers an opt-in mini-game over any frames2d pet: decaying stat
+ * bars, currencies, a weighted idle director, touch zones, a work loop, a
+ * sleep loop, passive income and a shop (issue: miku-pet generalization).
+ *
+ * Discipline split matches manifest-v2: STRUCTURE is fail-closed (types,
+ * ranges, references into stats/tracks); the host engine is pure — every
+ * verb takes an explicit clock and rng so tests stay deterministic. Decay,
+ * passive income and sleep restore are lazy-settled on read (the treats.ts
+ * discipline): the host runs no timers for gameplay.
+ * @module @linxin666/dsh-pet/gameplay
+ */
+/** One gameplay effect: add amount to a declared stat or a currency. */
+export interface PetGameplayEffect {
+    stat?: string;
+    currency?: string;
+    amount: number;
+}
+/** One roll branch inside a touch zone; uncovered roll mass is a no-op. */
+export interface PetGameplayTouchBranch {
+    probability: number;
+    effects?: PetGameplayEffect[];
+    /** Track played on hit (held for stateMs, then the renderer settles). */
+    state?: string;
+    stateMs?: number;
+    /** Bubble phrase pool; one is picked on hit. */
+    phrases?: string[];
+}
+export interface PetGameplayTouchZone {
+    name: string;
+    /** Vertical slice of the hit box (fractions, y0 < y1). */
+    y0: number;
+    y1: number;
+    branches: PetGameplayTouchBranch[];
+}
+export interface PetGameplayStatDef {
+    max: number;
+    initial?: number;
+    decayPerMinute?: number;
+    /** Decay rate while the work mode is active (defaults to decayPerMinute). */
+    workingDecayPerMinute?: number;
+    /** Extra decay rate while no session is active. */
+    idleDecayPerMinute?: number;
+}
+export interface PetGameplayShopItem {
+    id: string;
+    label: string;
+    /** Optional frame path (manifest-relative) shown as the item icon. */
+    image?: string;
+    price: number;
+    currency: string;
+    effects?: PetGameplayEffect[];
+    lottery?: {
+        effects?: PetGameplayEffect[];
+        /** Default currency the prize is paid in (tiers may override). */
+        currency?: string;
+        tiers: {
+            probability: number;
+            prize: number;
+            currency?: string;
+        }[];
+    };
+}
+/** The validated manifest 'gameplay' block. */
+export interface PetGameplayManifest {
+    idleDirector?: {
+        intervalMs: number;
+        maxMiss: number;
+        idleWeight: number;
+        acts: {
+            track: string;
+            weight: number;
+            phrases?: string[];
+        }[];
+    };
+    stats?: Record<string, PetGameplayStatDef>;
+    /** Click hit box inside the sprite box (fractions). */
+    hitBox?: {
+        x0: number;
+        y0: number;
+        x1: number;
+        y1: number;
+    };
+    touch?: {
+        zones: PetGameplayTouchZone[];
+        /** Plain-click effect while a touch animation holds (miku: mood +0..3). */
+        clickBoost?: {
+            stat: string;
+            min: number;
+            max: number;
+        };
+    };
+    work?: {
+        state: string;
+        successState: string;
+        failState: string;
+        tickMs: number;
+        /** Hold time of the result track before the next round. */
+        resultMs?: {
+            success: number;
+            fail: number;
+        };
+        successProbability: number;
+        success?: {
+            effects: PetGameplayEffect[];
+        };
+        fail?: {
+            effects: PetGameplayEffect[];
+        };
+    };
+    sleep?: {
+        state: string;
+        wakeState?: string;
+        restore: {
+            stat: string;
+            amount: number;
+            intervalMs: number;
+        };
+    };
+    passiveIncome?: {
+        currency: string;
+        amount: number;
+        intervalMs: number;
+    };
+    shop?: {
+        state?: string;
+        items: PetGameplayShopItem[];
+    };
+    /** Track played while the chrome reports dragging (default 'drag'). */
+    dragState?: string;
+    /** Track played once when a drag ends (miku: standup), before settling. */
+    dragEndState?: string;
+}
+export interface GameplayParseHooks {
+    /** State names the renderer can play (frames2d track ids). */
+    stateNames: ReadonlySet<string>;
+    error: (message: string) => void;
+}
+/**
+ * Validate the manifest 'gameplay' block (fail-closed). Only frames2d pets
+ * may declare gameplay today: every state reference checks against the
+ * declared track names.
+ */
+export declare function parseGameplayManifest(raw: unknown, hooks: GameplayParseHooks): PetGameplayManifest | undefined;
+/** Persisted per-pet gameplay state (pet.json 'gameplay' map values). */
+export interface PetGameplayState {
+    stats: Record<string, number>;
+    currencies: Record<string, number>;
+    mode: 'work' | 'sleep' | null;
+    /** Epoch ms of the last lazy settle. */
+    settledAt: number;
+}
+/** Fresh state for one pet: stats at their initial (default max), no currency. */
+export declare function initialGameplayState(manifest: PetGameplayManifest, now: number): PetGameplayState;
+/** Clamp one stat value into [0, max]; currencies into [0, CURRENCY_MAX]. */
+export declare function clampGameplay(state: PetGameplayState, manifest: PetGameplayManifest): void;
+/**
+ * Lazy settle: apply stat decay, passive income and sleep restore for the
+ * elapsed wall time since the last settle. Mirrors the treats.ts discipline
+ * (no host timers; read paths settle). Returns whether anything changed.
+ */
+export declare function settleGameplay(state: PetGameplayState, manifest: PetGameplayManifest, now: number, options: {
+    sessionActive: boolean;
+}): boolean;
+/** Apply one effect vector (touch/work/shop), clamped. */
+export declare function applyGameplayEffects(state: PetGameplayState, manifest: PetGameplayManifest, effects: readonly PetGameplayEffect[]): void;
+/** Roll one touch zone branch; undefined when the roll lands in no-op mass. */
+export declare function rollTouchBranch(zone: PetGameplayTouchZone, rng: () => number): PetGameplayTouchBranch | undefined;
+/** Roll one work tick outcome. */
+export declare function rollWorkOutcome(work: NonNullable<PetGameplayManifest['work']>, rng: () => number): 'success' | 'fail';
+/** Draw one lottery prize tier; uncovered mass falls through to the last tier. */
+export declare function drawLotteryTier(lottery: NonNullable<PetGameplayShopItem['lottery']>, rng: () => number): {
+    probability: number;
+    prize: number;
+    currency?: string;
+};
+/** The zone one normalized hit-box point lands in, if any. */
+export declare function touchZoneAt(touch: {
+    zones: PetGameplayTouchZone[];
+}, yFraction: number): PetGameplayTouchZone | undefined;
+//# sourceMappingURL=gameplay.d.ts.map

package/lib/types/gameplay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gameplay.d.ts","sourceRoot":"","sources":["../../src/gameplay.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,wEAAwE;AACxE,MAAM,WAAW,iBAAiB;IAChC,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,MAAM,EAAE,MAAM,CAAA;CACf;AAED,2EAA2E;AAC3E,MAAM,WAAW,sBAAsB;IACrC,WAAW,EAAE,MAAM,CAAA;IACnB,OAAO,CAAC,EAAE,iBAAiB,EAAE,CAAA;IAC7B,yEAAyE;IACzE,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,gDAAgD;IAChD,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;CACnB;AAED,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAA;IACZ,0DAA0D;IAC1D,EAAE,EAAE,MAAM,CAAA;IACV,EAAE,EAAE,MAAM,CAAA;IACV,QAAQ,EAAE,sBAAsB,EAAE,CAAA;CACnC;AAED,MAAM,WAAW,kBAAkB;IACjC,GAAG,EAAE,MAAM,CAAA;IACX,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,6EAA6E;IAC7E,qBAAqB,CAAC,EAAE,MAAM,CAAA;IAC9B,mDAAmD;IACnD,kBAAkB,CAAC,EAAE,MAAM,CAAA;CAC5B;AAED,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,MAAM,CAAA;IACV,KAAK,EAAE,MAAM,CAAA;IACb,sEAAsE;IACtE,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,CAAC,EAAE,iBAAiB,EAAE,CAAA;IAC7B,OAAO,CAAC,EAAE;QACR,OAAO,CAAC,EAAE,iBAAiB,EAAE,CAAA;QAC7B,kEAAkE;QAClE,QAAQ,CAAC,EAAE,MAAM,CAAA;QACjB,KAAK,EAAE;YAAE,WAAW,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,CAAC;YAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;SAAE,EAAE,CAAA;KACnE,CAAA;CACF;AAED,+CAA+C;AAC/C,MAAM,WAAW,mBAAmB;IAClC,YAAY,CAAC,EAAE;QACb,UAAU,EAAE,MAAM,CAAA;QAClB,OAAO,EAAE,MAAM,CAAA;QACf,UAAU,EAAE,MAAM,CAAA;QAClB,IAAI,EAAE;YAAE,KAAK,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,MAAM,CAAC;YAAC,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;SAAE,EAAE,CAAA;KAC9D,CAAA;IACD,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAA;IAC1C,uDAAuD;IACvD,MAAM,CAAC,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,CAAA;IAC3D,KAAK,CAAC,EAAE;QACN,KAAK,EAAE,oBAAoB,EAAE,CAAA;QAC7B,2EAA2E;QAC3E,UAAU,CAAC,EAAE;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,GAAG,EAAE,MAAM,CAAC;YAAC,GAAG,EAAE,MAAM,CAAA;SAAE,CAAA;KACxD,CAAA;IACD,IAAI,CAAC,EAAE;QACL,KAAK,EAAE,MAAM,CAAA;QACb,YAAY,EAAE,MAAM,CAAA;QACpB,SAAS,EAAE,MAAM,CAAA;QACjB,MAAM,EAAE,MAAM,CAAA;QACd,2DAA2D;QAC3D,QAAQ,CAAC,EAAE;YAAE,OAAO,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAA;SAAE,CAAA;QAC5C,kBAAkB,EAAE,MAAM,CAAA;QAC1B,OAAO,CAAC,EAAE;YAAE,OAAO,EAAE,iBAAiB,EAAE,CAAA;SAAE,CAAA;QAC1C,IAAI,CAAC,EAAE;YAAE,OAAO,EAAE,iBAAiB,EAAE,CAAA;SAAE,CAAA;KACxC,CAAA;IACD,KAAK,CAAC,EAAE;QACN,KAAK,EAAE,MAAM,CAAA;QACb,SAAS,CAAC,EAAE,MAAM,CAAA;QAClB,OAAO,EAAE;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,MAAM,CAAC;YAAC,UAAU,EAAE,MAAM,CAAA;SAAE,CAAA;KAC9D,CAAA;IACD,aAAa,CAAC,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAA;IACxE,IAAI,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,mBAAmB,EAAE,CAAA;KAAE,CAAA;IACvD,uEAAuE;IACvE,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,2EAA2E;IAC3E,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB;AAuCD,MAAM,WAAW,kBAAkB;IACjC,8DAA8D;IAC9D,UAAU,EAAE,WAAW,CAAC,MAAM,CAAC,CAAA;IAC/B,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;CACjC;AA0ED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,kBAAkB,GAAG,mBAAmB,GAAG,SAAS,CA+U9G;AAMD,yEAAyE;AACzE,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC7B,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAClC,IAAI,EAAE,MAAM,GAAG,OAAO,GAAG,IAAI,CAAA;IAC7B,wCAAwC;IACxC,SAAS,EAAE,MAAM,CAAA;CAClB;AAED,kFAAkF;AAClF,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,mBAAmB,EAAE,GAAG,EAAE,MAAM,GAAG,gBAAgB,CAMjG;AAED,6EAA6E;AAC7E,wBAAgB,aAAa,CAAC,KAAK,EAAE,gBAAgB,EAAE,QAAQ,EAAE,mBAAmB,GAAG,IAAI,CAS1F;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,gBAAgB,EACvB,QAAQ,EAAE,mBAAmB,EAC7B,GAAG,EAAE,MAAM,EACX,OAAO,EAAE;IAAE,aAAa,EAAE,OAAO,CAAA;CAAE,GAClC,OAAO,CAqCT;AAED,0DAA0D;AAC1D,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,gBAAgB,EAAE,QAAQ,EAAE,mBAAmB,EAAE,OAAO,EAAE,SAAS,iBAAiB,EAAE,GAAG,IAAI,CASxI;AAED,+EAA+E;AAC/E,wBAAgB,eAAe,CAAC,IAAI,EAAE,oBAAoB,EAAE,GAAG,EAAE,MAAM,MAAM,GAAG,sBAAsB,GAAG,SAAS,CAQjH;AAED,kCAAkC;AAClC,wBAAgB,eAAe,CAAC,IAAI,EAAE,WAAW,CAAC,mBAAmB,CAAC,MAAM,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,MAAM,GAAG,SAAS,GAAG,MAAM,CAErH;AAED,kFAAkF;AAClF,wBAAgB,eAAe,CAC7B,OAAO,EAAE,WAAW,CAAC,mBAAmB,CAAC,SAAS,CAAC,CAAC,EACpD,GAAG,EAAE,MAAM,MAAM,GAChB;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,CAQ3D;AAED,8DAA8D;AAC9D,wBAAgB,WAAW,CAAC,KAAK,EAAE;IAAE,KAAK,EAAE,oBAAoB,EAAE,CAAA;CAAE,EAAE,SAAS,EAAE,MAAM,GAAG,oBAAoB,GAAG,SAAS,CAEzH"}