dsh-pet 0.1.6 → 0.1.7

package/src/client/config.ts

@@ -1,122 +1,98 @@
-// 配置层：拉取 / 解析 config.jsonc，构建运行时动作配置（唯一事实来源）。
-import { DEFAULT_PETS } from './settings';
-import type { PetConfigUI } from './settings';
-import type { AnimConfig, Corner } from './types';
+// 配置层：剥注释、校验 config.jsonc。运行时（ANIM）直接使用与 jsonc 同构的 ClientConfig，
+// 不做字段转换；缺失/非法一律视为配置错误（throw，由加载层显式报错）。
+import type { Animations, ClientConfig, Corner, Pet, Weights } from './types';
 
-/** 安全兜底待机名：用于初始渲染 / 配置缺失时宠物不至于空白 */
-export const FALLBACK_IDLE = '待机呼吸休闲';
-/** 移动默认参数（仅当 config.jsonc 未提供 moves.default 时兜底） */
-export const DEFAULT_MOVE_PARAMS: Record<string, number> = {
-  minDist: 60,
-  maxDist: 240,
-  margin: 20,
-  leadSec: 2,
-  tailSec: 2,
-};
-
-/** 剥除 JSONC 注释（行注释 // 与块注释），得到纯 JSON 字符串。仅用于插件自带配置（无含 // 的 URL 值） */
+/** 剥除 JSONC 注释（行注释 // 与块注释），得到纯 JSON 字符串 */
 export const stripJsonc = (src: string): string =>
   src
     .replace(/\/\*[\s\S]*?\*\//g, '')
     .replace(/(^|[^\\:])\/\/.*$/gm, '$1')
     .trim();
 
-/** 最小兜底配置：仅当 config.jsonc 缺失时使用，保证宠物不至于空白 */
-export const buildMinimalAnim = (): AnimConfig => ({
-  idle: [FALLBACK_IDLE],
-  turn: [],
-  drag: [],
-  clicks: [],
-  moves: {
-    default: { ...DEFAULT_MOVE_PARAMS },
-    actions: [],
-  },
-  categories: [],
-  weights: { idle: 100, turn: 0, move: 0 },
-});
-
-/** 从 config.jsonc 解析出的对象构建运行时动作配置（缺字段/写错尽量安全兜底） */
-export const buildAnim = (obj: unknown): AnimConfig => {
-  const a = (obj as any)?.animations;
-  const w = (obj as any)?.animationWeights ?? {};
-  const strArr = (x: unknown): string[] => (Array.isArray(x) ? x.map(String).filter(Boolean) : []);
-  const idle = strArr(a?.idle);
-  if (!idle.length) idle.push(FALLBACK_IDLE);
-  const turn = strArr(a?.turn);
-  const drag = strArr(a?.drag);
-  const clicks = strArr(a?.clicks);
-  let mdef: Record<string, number> = { ...DEFAULT_MOVE_PARAMS };
-  let mActs: { name: string; params?: Record<string, number> }[] = [];
-  if (a?.moves && typeof a.moves === 'object') {
-    if (a.moves.default && typeof a.moves.default === 'object') mdef = { ...mdef, ...a.moves.default };
-    if (Array.isArray(a.moves.actions)) {
-      const list = a.moves.actions
-        .filter((x: any) => x && x.name)
-        .map((x: any) => ({ name: String(x.name), params: x.params && typeof x.params === 'object' ? { ...x.params } : undefined }));
-      if (list.length) mActs = list;
-    }
-  }
-  let cats: { id: string; weight: number; noMirror?: boolean; actions: string[] }[] = [];
-  if (Array.isArray(a?.categories)) {
-    const list = a.categories
-      .filter((c: any) => c && c.id && Array.isArray(c.actions) && c.actions.length)
-      .map((c: any) => ({ id: String(c.id), weight: Number(c.weight), noMirror: !!c.noMirror, actions: c.actions.map(String) }));
-    if (list.length) cats = list;
-  }
-  return {
-    idle,
-    turn,
-    drag,
-    clicks,
-    moves: { default: mdef, actions: mActs },
-    categories: cats,
-    weights: {
-      idle: Number(w.idle) >= 0 ? Number(w.idle) : 10,
-      turn: Number(w.turn) >= 0 ? Number(w.turn) : 5,
-      move: Number(w.move) >= 0 ? Number(w.move) : 5,
-    },
-  };
-};
-
-// ============================================================================
-// 多开宠物配置解析（纯函数，不依赖 React）
-// ============================================================================
 /** 支持的角落白名单 */
 export const CORNERS: Corner[] = ['top-left', 'top-right', 'bottom-left', 'bottom-right'];
+/** corner 合法性检查用的 string 集合（Corner[] 的 includes 要求 Corner 参数，无法接收未知 string） */
+const CORNER_SET: ReadonlySet<string> = new Set(CORNERS);
 
-/** 归一化一个宠物条目（缺字段回落默认） */
-export function normalizePet(p: any): PetConfigUI {
-  const pos = p && p.position && typeof p.position === 'object' ? p.position : {};
-  return {
-    id: String(p && p.id ? p.id : 'main'),
-    size: Number(p && p.size) > 0 ? Number(p.size) : DEFAULT_PETS[0].size,
-    corner: CORNERS.indexOf(pos.corner) !== -1 ? (pos.corner as Corner) : DEFAULT_PETS[0].corner,
-    marginX: Number.isFinite(Number(pos.marginX)) ? Number(pos.marginX) : DEFAULT_PETS[0].marginX,
-    marginY: Number.isFinite(Number(pos.marginY)) ? Number(pos.marginY) : DEFAULT_PETS[0].marginY,
-  };
-}
+/** ClientConfig 类型占位（data-less；PetMulti 加载后由 assertClientConfig 赋真实值） */
+export const EMPTY_CONF: ClientConfig = {
+  pets: [],
+  animations: { idle: [], turn: [], drag: [], clicks: [], moves: { default: {}, actions: [] }, categories: [] },
+  animationWeights: { idle: 0, turn: 0, move: 0 },
+};
 
-/** 从 config.jsonc 对象提取默认宠物列表：必须为 pets 数组；缺失/为空回落代码兜底 DEFAULT_PETS */
-export function extractDefaultPets(obj: any): PetConfigUI[] {
-  const arr = obj && Array.isArray(obj.pets) ? obj.pets.filter((p: any) => p && p.id) : [];
-  if (!arr.length) return DEFAULT_PETS.map((p) => ({ ...p }));
+/** 校验 config.jsonc 解析结果并返回 ClientConfig；任一字段缺失/非法即视为配置错误抛出 */
+export function assertClientConfig(raw: unknown): ClientConfig {
+  if (!raw || typeof raw !== 'object') throw new Error('dsh-pet: config 非对象');
+  // raw 是 unknown 输入（jsonc 解析产物），按 Record 读取后逐字段手工校验，字段读写无法静态定型
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const cfg = raw as Record<string, any>;
+
+  // ---- pets ----
+  const petsArr = cfg.pets;
+  if (!Array.isArray(petsArr) || !petsArr.length) throw new Error('dsh-pet: 缺少 pets');
   const seen = new Set<string>();
-  const out: PetConfigUI[] = [];
-  for (const p of arr) {
-    const id = String(p.id);
-    if (!seen.has(id)) {
-      seen.add(id);
-      out.push(normalizePet(p));
-    }
+  const pets: Pet[] = [];
+  for (const p of petsArr) {
+    const id = String(p?.id ?? '');
+    if (!id || seen.has(id)) throw new Error('dsh-pet: pet id 非法或重复「' + id + '」');
+    const size = Number(p?.size);
+    if (!Number.isFinite(size) || size <= 0) throw new Error('dsh-pet: pet「' + id + '」大小非法');
+    const corner = p?.position?.corner;
+    if (typeof corner !== 'string' || !CORNER_SET.has(corner)) throw new Error('dsh-pet: pet「' + id + '」corner 非法');
+    const marginX = Number(p?.position?.marginX);
+    const marginY = Number(p?.position?.marginY);
+    if (!Number.isFinite(marginX) || !Number.isFinite(marginY)) throw new Error('dsh-pet: pet「' + id + '」边距非法');
+    seen.add(id);
+    pets.push({ id, size, position: { corner: corner as Corner, marginX, marginY } });
   }
-  return out.length ? out : DEFAULT_PETS.map((p) => ({ ...p }));
-}
 
-/** 合并最终宠物列表：用户层（{ pets: 完整列表 }）全量替换默认；无用户层回落默认 */
-export function resolvePets(defaults: PetConfigUI[], user: any): PetConfigUI[] {
-  if (user && Array.isArray(user.pets)) {
-    const list = user.pets.filter((p: any) => p && p.id).map(normalizePet);
-    return list.length ? list : defaults; // 用户层空数组视为无覆盖
+  // ---- animations ----
+  const a = cfg.animations;
+  if (!a || typeof a !== 'object') throw new Error('dsh-pet: 缺少 animations');
+  for (const key of ['idle', 'turn', 'drag', 'clicks']) {
+    if (!Array.isArray(a[key])) throw new Error('dsh-pet: animations.' + key + ' 缺失');
   }
+  if (
+    !a.moves ||
+    typeof a.moves !== 'object' ||
+    typeof a.moves.default !== 'object' ||
+    a.moves.default === null ||
+    !Array.isArray(a.moves.actions)
+  ) {
+    throw new Error('dsh-pet: animations.moves 结构非法');
+  }
+  if (!Array.isArray(a.categories)) throw new Error('dsh-pet: animations.categories 缺失');
+
+  // ---- animationWeights ----
+  const w = cfg.animationWeights;
+  if (!w || typeof w !== 'object') throw new Error('dsh-pet: 缺少 animationWeights');
+  for (const key of ['idle', 'turn', 'move']) {
+    const v = Number(w[key]);
+    if (!Number.isFinite(v) || v < 0) throw new Error('dsh-pet: animationWeights.' + key + ' 非法');
+    w[key] = v;
+  }
+
+  return { pets, animations: a, animationWeights: w };
+}
+
+/** 合并宠物：用户层（{ pets }，与 jsonc 同构）全量替换默认；无用户层回落默认 */
+export function resolvePets(defaults: Pet[], user: { pets?: Pet[] }): Pet[] {
+  if (user && Array.isArray(user.pets)) return user.pets.length ? user.pets : defaults;
   return defaults;
 }
+
+/** 用户覆盖片段（与 jsonc 同构；高级用户直接编辑 pet-config.json，缺省字段回落默认） */
+export interface UserOverrides {
+  pets?: Pet[];
+  animations?: Animations;
+  animationWeights?: Weights;
+}
+
+/** 合并用户覆盖片段到完全体配置：pets / animations / animationWeights 有则整体替换，缺省回落默认 */
+export function applyUserOverrides(base: ClientConfig, user: UserOverrides): ClientConfig {
+  const next: ClientConfig = { ...base, pets: resolvePets(base.pets, user) };
+  if (user.animations) next.animations = user.animations;
+  if (user.animationWeights) next.animationWeights = user.animationWeights;
+  return next;
+}

package/src/client/index.ts

@@ -5,6 +5,7 @@ import { makeFactory } from './app';
 
 declare const window: {
   __ModuleLoader__: {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- DSH 全局注入的模块系统契约（f(require) => module）
     load(info: { id: string; factory: (require: (m: string) => any) => any }): void;
   };
 };

package/src/client/motion.ts

@@ -0,0 +1,36 @@
+// 移动几何：纯计算（无 DOM / ref），可独立单测。
+// 所有坐标归一化为视口比例（ratio），px 换算由调用方（rAF 驱动 / customPos）完成。
+import { randomBetween } from './pickers';
+
+/** 一次移动的几何参数（比例坐标） */
+export interface MovePlan {
+  startRatio: number;
+  startYRatio: number;
+  targetRatio: number;
+  totalRatio: number;
+}
+
+/** 计算一次移动的起点/终点比例坐标；目标越出视口边缘（含边距）时返回 null */
+export const planMove = (o: {
+  cx: number;
+  cy: number;
+  W: number;
+  H: number;
+  dir: 1 | -1;
+  minDist: number;
+  maxDist: number;
+  margin: number;
+  halfW: number;
+}): MovePlan | null => {
+  const distance = randomBetween(o.minDist, o.maxDist);
+  const target = o.cx + o.dir * distance;
+  const leftBound = o.margin + o.halfW;
+  const rightBound = o.W - o.margin - o.halfW;
+  if (target < leftBound || target > rightBound) return null;
+  return {
+    startRatio: o.cx / o.W,
+    startYRatio: o.cy / o.H,
+    targetRatio: target / o.W,
+    totalRatio: Math.abs(target - o.cx) / o.W,
+  };
+};