@linxin666/dsh-pet 0.3.16 → 0.3.18

package/src/manifest-v2.ts

@@ -100,6 +100,43 @@ export interface PetManifestFrames2d {
   tracks: Record<string, PetManifestFrames2dTrack>
   /** ActivityPhase -> track name; idle is required, unmapped phases fall back to it. */
   phases: Partial<Record<ActivityPhase, string>> & { idle: string }
+  /**
+   * Optional selectable skins: a skin swaps the base idle target (the idle
+   * phase, unmapped phases, and every fallback back to idle) to its own
+   * looping idle track. Gameplay tracks (shy/work/sleep...) are not replaced.
+   */
+  skins?: PetManifestSkin[]
+}
+
+/** One selectable frames2d skin. */
+export interface PetManifestSkin {
+  id: string
+  label: string
+  /** A declared, looping track that becomes the base idle while selected. */
+  idleTrack: string
+  /**
+   * Optional click-triggered actions exclusive to this skin: while the skin
+   * is selected, a tap rolls each action by probability (in order) and plays
+   * its track once if hit. Misses fall through to the regular touch zones.
+   */
+  clickActions?: PetManifestSkinClickAction[]
+  /**
+   * Optional gameplay-track overrides: gameplay state name (e.g. 'sleep' or
+   * 'work') -> a declared track the skin swaps in while selected. Lets a skin
+   * restyle a gameplay loop (e.g. its own sleep animation) without touching
+   * the default pet's tracks.
+   */
+  gameplayTracks?: Record<string, string>
+}
+
+/** One probability-rolled tap action a skin may declare. */
+export interface PetManifestSkinClickAction {
+  /** A declared track played once on hit (usually non-looping). */
+  track: string
+  /** Hit probability for this action (0..1). */
+  probability: number
+  /** Optional lines spoken when the action fires. */
+  phrases?: string[]
 }
 
 /** Normalized v2 manifest the registry consumes. */
@@ -153,9 +190,35 @@ export const KNOWN_SPRITE2D = new Set(['spritesheetPath', 'cell', 'columns', 'at
 /** live2d block field allow-list (drift-locked to the schema file). */
 export const KNOWN_LIVE2D = new Set(['model', 'scale', 'translate', 'motions', 'expressions', 'hitAreas', 'lipSync'])
 /** frames2d block field allow-list (drift-locked to the schema file). */
-export const KNOWN_FRAMES2D = new Set(['dir', 'defaultFrameMs', 'tracks', 'phases'])
+export const KNOWN_FRAMES2D = new Set(['dir', 'defaultFrameMs', 'tracks', 'phases', 'skins'])
 /** frames2d track field allow-list (drift-locked to the schema file). */
 export const KNOWN_FRAMES2D_TRACK = new Set(['frames', 'frameMs', 'loop', 'fallback'])
+/** frames2d skin entry field allow-list (drift-locked to the schema file). */
+export const KNOWN_SKIN = new Set(['id', 'label', 'idleTrack', 'clickActions', 'gameplayTracks'])
+/** frames2d skin click-action field allow-list (drift-locked to the schema file). */
+export const KNOWN_SKIN_CLICK = new Set(['track', 'probability', 'phrases'])
+/** Max selectable skins a frames2d manifest may declare. */
+export const FRAMES2D_MAX_SKINS = 16
+/** Max click actions one skin may declare. */
+export const FRAMES2D_MAX_SKIN_CLICKS = 8
+/** Max gameplay-state overrides one skin may declare. */
+export const FRAMES2D_MAX_SKIN_GAMEPLAY = 8
+/** Max spoken lines one skin click action may declare. */
+const SKIN_CLICK_MAX_PHRASES = 5
+/** Max length of one spoken line. */
+const SKIN_CLICK_PHRASE_MAX_LENGTH = 120
+
+/** Validate a skin click action's optional phrase pool (same spirit as gameplay phrases). */
+function parseSkinPhrases(raw: unknown, field: string, diag: Diagnostics): string[] | undefined {
+  if (raw === undefined) return undefined
+  if (!Array.isArray(raw) || raw.length === 0 || raw.length > SKIN_CLICK_MAX_PHRASES
+    || raw.some(line => typeof line !== 'string' || line.trim() === '' || line.length > SKIN_CLICK_PHRASE_MAX_LENGTH)) {
+    diag.error(field + ' must be 1..' + SKIN_CLICK_MAX_PHRASES + ' non-empty lines of at most '
+      + SKIN_CLICK_PHRASE_MAX_LENGTH + ' chars')
+    return undefined
+  }
+  return raw as string[]
+}
 
 class Diagnostics {
   readonly list: PetManifestDiagnostic[] = []
@@ -451,6 +514,109 @@ function parseFrames2dBlock(raw: unknown, diag: Diagnostics): PetManifestFrames2
       diag.error('frames2d.tracks.' + name + '.fallback references unknown track ' + JSON.stringify(track.fallback))
     }
   }
+  // Optional skins: each selects a declared looping idle track as the base
+  // idle while active (id/label are UI-facing, idleTrack is structure).
+  if (raw.skins !== undefined) {
+    if (!Array.isArray(raw.skins) || raw.skins.length === 0 || raw.skins.length > FRAMES2D_MAX_SKINS) {
+      diag.error('frames2d.skins must be an array of 1..' + FRAMES2D_MAX_SKINS + ' skins')
+    } else {
+      const skins: PetManifestSkin[] = []
+      const seen = new Set<string>()
+      for (const [index, entry] of raw.skins.entries()) {
+        const field = 'frames2d.skins[' + index + ']'
+        if (!isRecord(entry)) {
+          diag.error(field + ' must be an object')
+          continue
+        }
+        const extra = unknownKeys(entry, KNOWN_SKIN)
+        if (extra.length > 0) diag.error(field + ': unknown field(s) ' + extra.map(k => JSON.stringify(k)).join(', '))
+        const id = typeof entry.id === 'string' ? entry.id.trim() : ''
+        if (id === '' || id.length > 24 || !FRAMES2D_TRACK_NAME.test(id)) {
+          diag.error(field + '.id must be a lowercase kebab id of at most 24 chars')
+          continue
+        }
+        if (seen.has(id)) {
+          diag.error(field + ': duplicate skin id ' + JSON.stringify(id))
+          continue
+        }
+        seen.add(id)
+        const label = typeof entry.label === 'string' ? entry.label.trim() : ''
+        if (label === '' || label.length > 40) {
+          diag.error(field + '.label must be a non-empty string of at most 40 chars')
+          continue
+        }
+        const idleTrack = typeof entry.idleTrack === 'string' ? entry.idleTrack : ''
+        if (!validTrackName(idleTrack) || tracks[idleTrack] === undefined) {
+          diag.error(field + '.idleTrack must name a declared frames2d track')
+          continue
+        }
+        // Optional click actions: each names a declared track and a hit
+        // probability; phrases reuse the gameplay phrase constraints.
+        let clickActions: PetManifestSkinClickAction[] | undefined
+        if (entry.clickActions !== undefined) {
+          if (!Array.isArray(entry.clickActions) || entry.clickActions.length === 0 || entry.clickActions.length > FRAMES2D_MAX_SKIN_CLICKS) {
+            diag.error(field + '.clickActions must be an array of 1..' + FRAMES2D_MAX_SKIN_CLICKS + ' actions')
+          } else {
+            const resolved: PetManifestSkinClickAction[] = []
+            for (const [cIndex, action] of entry.clickActions.entries()) {
+              const cField = field + '.clickActions[' + cIndex + ']'
+              if (!isRecord(action)) {
+                diag.error(cField + ' must be an object')
+                continue
+              }
+              const cExtra = unknownKeys(action, KNOWN_SKIN_CLICK)
+              if (cExtra.length > 0) diag.error(cField + ': unknown field(s) ' + cExtra.map(k => JSON.stringify(k)).join(', '))
+              const trackName = typeof action.track === 'string' ? action.track : ''
+              if (!validTrackName(trackName) || tracks[trackName] === undefined) {
+                diag.error(cField + '.track must name a declared frames2d track')
+                continue
+              }
+              if (typeof action.probability !== 'number' || !Number.isFinite(action.probability)
+                || action.probability <= 0 || action.probability > 1) {
+                diag.error(cField + '.probability must be a number in (0, 1]')
+                continue
+              }
+              const phrases = parseSkinPhrases(action.phrases, cField + '.phrases', diag)
+              resolved.push({ track: trackName, probability: action.probability, ...(phrases === undefined ? {} : { phrases }) })
+            }
+            if (resolved.length > 0) clickActions = resolved
+          }
+        }
+        // Optional gameplay-track overrides: gameplay state name -> declared
+        // track swapped in while this skin is selected (e.g. a skin variant of
+        // the sleep loop). State names mirror gameplay blocks (sleep/work...);
+        // values must reference declared tracks.
+        let gameplayTracks: Record<string, string> | undefined
+        if (entry.gameplayTracks !== undefined) {
+          if (!isRecord(entry.gameplayTracks)) {
+            diag.error(field + '.gameplayTracks must be an object mapping gameplay state names to tracks')
+          } else {
+            const states = Object.keys(entry.gameplayTracks)
+            if (states.length === 0 || states.length > FRAMES2D_MAX_SKIN_GAMEPLAY) {
+              diag.error(field + '.gameplayTracks must map 1..' + FRAMES2D_MAX_SKIN_GAMEPLAY + ' gameplay states')
+            } else {
+              const resolvedTracks: Record<string, string> = {}
+              for (const state of states) {
+                if (!/^[a-z0-9][a-z0-9-]*$/.test(state)) {
+                  diag.error(field + '.gameplayTracks key ' + JSON.stringify(state) + ' must be a lowercase kebab state name')
+                  continue
+                }
+                const gTrack = entry.gameplayTracks[state as keyof typeof entry.gameplayTracks]
+                if (typeof gTrack !== 'string' || !validTrackName(gTrack) || tracks[gTrack] === undefined) {
+                  diag.error(field + '.gameplayTracks[' + JSON.stringify(state) + '] must name a declared frames2d track')
+                  continue
+                }
+                resolvedTracks[state] = gTrack
+              }
+              if (Object.keys(resolvedTracks).length > 0) gameplayTracks = resolvedTracks
+            }
+          }
+        }
+        skins.push({ id, label, idleTrack, ...(clickActions === undefined ? {} : { clickActions }), ...(gameplayTracks === undefined ? {} : { gameplayTracks }) })
+      }
+      if (skins.length > 0) block.skins = skins
+    }
+  }
   return diag.hasErrors ? undefined : block
 }
 

package/src/persist.ts

@@ -36,7 +36,7 @@ export const defaultDisplayConfig: PetDisplayConfig = {
 
 /** Display value bounds (shared by load-time validation and setConfig). */
 export const DISPLAY_SIZE_MIN = 32
-export const DISPLAY_SIZE_MAX = 512
+export const DISPLAY_SIZE_MAX = 1024
 export const DISPLAY_INSET_MAX = 10_000
 
 /** Everything persisted for the pet. */

package/src/registry.test.ts

@@ -314,18 +314,32 @@ describe('loadPetRegistry', () => {
       dshPetsDir: '',
     })
 
-    // The repo checkout also resolves miku (frames2d gameplay pet) and
-    // starry-doll (community sprite2d pet) from assets/; the npm files
-    // whitelist excludes them (Workshop delivery), so npm installs see the
-    // three atlas pets until a Workshop install lands them under
-    // $DSH_HOME/pets.
+    // The repo checkout also resolves miku (frames2d gameplay pet), jyn
+    // (frames2d gameplay pet) and starry-doll (community sprite2d pet) from
+    // assets/; the npm files whitelist excludes them (Workshop delivery), so
+    // npm installs see the atlas pets until a Workshop install lands them
+    // under $DSH_HOME/pets. blue-throated-bee-eater ships bundled alongside
+    // the other atlas pets.
     expect(registry.entries.map(entry => entry.id)).toEqual([
+      'blue-throated-bee-eater',
+      'jyn',
       'miku',
       'ouo-neko',
       'starry-doll',
       'whale-girl',
       'whale-girl-refined',
     ])
+    expect(registry.byId('blue-throated-bee-eater')).toMatchObject({
+      displayName: '蓝喉蜂虎',
+      atlasRows: 9,
+      columns: 8,
+      rows: [6, 8, 8, 4, 5, 8, 6, 6, 6],
+    })
+    expect(existsSync(petAtlasFile(registry.byId('blue-throated-bee-eater')!))).toBe(true)
+    expect(registry.byId('jyn')).toMatchObject({
+      displayName: '女仆鲸鱼娘',
+      renderer: 'frames2d',
+    })
     expect(registry.byId('ouo-neko')).toMatchObject({
       displayName: 'OUO Neko',
       atlasRows: 11,

package/src/registry.ts

@@ -215,6 +215,30 @@ export interface PetFrames2dDefinition {
   tracks: Record<string, PetFrames2dTrackView>
   /** ActivityPhase -> track id; unmapped phases fall back to idle. */
   phases: Partial<Record<ActivityPhase, string>> & { idle: string }
+  /** Selectable skins; each swaps the base idle target to its idleTrack. */
+  skins?: PetSkinDefinition[]
+}
+
+/** One selectable frames2d skin as served to the browser half. */
+export interface PetSkinDefinition {
+  id: string
+  label: string
+  /** A declared looping track that becomes the base idle while selected. */
+  idleTrack: string
+  /** Click actions exclusive to this skin (roll by probability; miss → touch zones). */
+  clickActions?: PetSkinClickActionDefinition[]
+  /** Gameplay-state overrides (state -> track) swapped in while selected. */
+  gameplayTracks?: Record<string, string>
+}
+
+/** One probability-rolled tap action a skin may declare. */
+export interface PetSkinClickActionDefinition {
+  /** A declared track played once on hit. */
+  track: string
+  /** Hit probability (0..1). */
+  probability: number
+  /** Optional lines spoken when the action fires. */
+  phrases?: string[]
 }
 
 /** A normalized pet as served to the browser half. */
@@ -719,6 +743,47 @@ function resolveFrames2dEntry(
       phases[phase as ActivityPhase] = idleTrack
     }
   }
+  // Skins: keep only entries whose idleTrack survived track resolution, and
+  // drop click actions whose track did not (the skin itself stays usable).
+  let skins: PetSkinDefinition[] | undefined
+  if (block.skins !== undefined) {
+    const resolved: PetSkinDefinition[] = []
+    for (const skin of block.skins) {
+      if (tracks[skin.idleTrack] === undefined) {
+        record('warning', 'pet ' + manifest.id + ': frames2d skin ' + JSON.stringify(skin.id) + ' idleTrack dropped; skipping')
+        continue
+      }
+      let clickActions: PetSkinClickActionDefinition[] | undefined
+      if (skin.clickActions !== undefined) {
+        const kept: PetSkinClickActionDefinition[] = []
+        for (const action of skin.clickActions) {
+          if (tracks[action.track] === undefined) {
+            record('warning', 'pet ' + manifest.id + ': frames2d skin ' + JSON.stringify(skin.id)
+              + ' click action track ' + JSON.stringify(action.track) + ' dropped')
+            continue
+          }
+          kept.push(action)
+        }
+        if (kept.length > 0) clickActions = kept
+      }
+      // Gameplay track overrides: drop entries whose track did not survive.
+      let gameplayTracks: Record<string, string> | undefined
+      if (skin.gameplayTracks !== undefined) {
+        const kept: Record<string, string> = {}
+        for (const [state, gTrack] of Object.entries(skin.gameplayTracks)) {
+          if (tracks[gTrack] === undefined) {
+            record('warning', 'pet ' + manifest.id + ': frames2d skin ' + JSON.stringify(skin.id)
+              + ' gameplay track override ' + JSON.stringify(state) + ' -> ' + JSON.stringify(gTrack) + ' dropped')
+            continue
+          }
+          kept[state] = gTrack
+        }
+        if (Object.keys(kept).length > 0) gameplayTracks = kept
+      }
+      resolved.push({ ...skin, ...(clickActions === undefined ? {} : { clickActions }), ...(gameplayTracks === undefined ? {} : { gameplayTracks }) })
+    }
+    if (resolved.length > 0) skins = resolved
+  }
   const remarks = normalizePetRemarks(manifest.remarks, message => record('warning', 'pet ' + manifest.id + ': ' + message))
   // Gameplay layer: shop item icons are manifest-relative frame paths —
   // verify them, promote them to browser URLs, and add them to the servable
@@ -756,7 +821,7 @@ function resolveFrames2dEntry(
     displayName: manifest.displayName,
     description: manifest.description ?? '',
     renderer: 'frames2d' as const,
-    frames2d: { tracks, phases },
+    frames2d: { tracks, phases, ...(skins === undefined ? {} : { skins }) },
     ...(gameplay === undefined ? {} : { gameplay }),
     cell,
     columns: DEFAULT_PET_COLUMNS,