Awesome DSH Pet
DSH Web GUI 内的可扩展桌面宠物插件。
jingyu-zongcai：鲸鱼总裁lulu-capybara：噜噜
安装
dsh plugin --profile web add /Users/icourt/Desktop/DSH-plugin/Awesome-DSH-Pet安装或更新后重启 web。插件会在页面右下角显示桌面宠物，菜单里可以投喂、玩耍、切换角色。
配置
settings.yaml 中使用 awesome-dsh-pet: section：
awesome-dsh-pet:
enabled: true
size: 110
opacity: 1
walk:
enabled: true
sleepAfterMs: 60000快速添加你自己的宠物
三步走：放素材 → 改 manifest → 跑门禁。
1. 起个角色 id 并放素材
角色 id 只允许 [a-z0-9-]（会当 URL 路径用）。示例用 my-cat。
把 Codex 标准 8×9 spritesheet 放到：
lib/assets/characters/my-cat/spritesheet.webpCodex atlas 规范：8 列 × 9 行，每格 192×208（像素）。行含义：
| row | 用途 |
|---|---|
| 0 | idle |
| 1 | running-right / walk / drag |
| 2 | running-left |
| 3 | waving / welcome / celebrate |
| 4 | jumping / play |
| 5 | failed / error / disappointed |
| 6 | waiting |
| 7 | running / working |
| 8 | review / think |
如果你手里只有一堆单行动作 sheet（不是 atlas），也支持——见下方"素材两种形式"。
2. 在 lib/assets/manifest.json 增加角色
在 characters 下加一个 key：
{
"characters": {
"my-cat": {
"name": "我的猫",
"credit": "你的名字",
"description": "一句话人设。",
"meta": {
"stageSize": 110,
"atlas": { "columns": 8, "rows": 9, "cellWidth": 192, "cellHeight": 208 }
},
"states": {
"idle": { "sheet": "spritesheet.webp", "row": 0, "rows": 9, "frames": 8, "fps": 4, "playback": "blink" },
"working": { "sheet": "spritesheet.webp", "row": 7, "rows": 9, "frames": 8, "fps": 6, "playback": "loop" },
"celebrate": { "sheet": "spritesheet.webp", "row": 3, "rows": 9, "frames": 8, "fps": 6, "playback": "loop" },
"error": { "sheet": "spritesheet.webp", "row": 5, "rows": 9, "frames": 8, "fps": 8, "motion": "shake", "playback": "once" },
"disappointed": { "sheet": "spritesheet.webp", "row": 5, "rows": 9, "frames": 8, "fps": 4, "playback": "loop" },
"joy": { "sheet": "spritesheet.webp", "row": 3, "rows": 9, "frames": 8, "fps": 6, "playback": "loop" },
"eat": { "sheet": "spritesheet.webp", "row": 3, "rows": 9, "frames": 8, "fps": 6, "playback": "loop" },
"play": { "sheet": "spritesheet.webp", "row": 4, "rows": 9, "frames": 8, "fps": 6, "playback": "loop" },
"drag": { "sheet": "spritesheet.webp", "row": 1, "rows": 9, "frames": 8, "fps": 8, "playback": "loop" },
"walk": { "sheet": "spritesheet.webp", "row": 1, "rows": 9, "frames": 8, "fps": 8, "playback": "pingpong" },
"sleep": { "sheet": "spritesheet.webp", "row": 0, "rows": 9, "frames": 8, "fps": 2, "playback": "loop" },
"wake": { "sheet": "spritesheet.webp", "row": 3, "rows": 9, "frames": 8, "fps": 6, "playback": "once" },
"welcome": { "sheet": "spritesheet.webp", "row": 3, "rows": 9, "frames": 8, "fps": 6, "playback": "loop" },
"think": { "sheet": "spritesheet.webp", "row": 8, "rows": 9, "frames": 8, "fps": 4, "playback": "loop" },
"wait": { "sheet": "spritesheet.webp", "row": 6, "rows": 9, "frames": 8, "fps": 4, "playback": "loop" }
}
}
}
}必备 15 状态一个都不能少：idle / working / celebrate / error / disappointed / joy / eat / play / drag / walk / sleep / wake / welcome / think / wait。
上面的 atlas 行映射是通用模板，直接复制改角色 id 即可跑起来。想让某个状态换动作（例如 eat 走单独的表情），改对应条目的 row 或 sheet 即可。
想把新角色作为默认，把顶层的 "default": "jingyu-zongcai" 改成 "my-cat"。
3. 校验并重装
node scripts/gates/verify-assets.mjs # 门禁：素材完整性 + manifest 一致性
node --test 'tests/*.test.mjs' # 单测
dsh plugin --profile web add /Users/icourt/Desktop/DSH-plugin/Awesome-DSH-Pet # 更新后重启 web门禁会告诉你缺哪个状态、sheet 文件不存在、frames/fps 不合法等——按报错逐条修就行。
素材两种形式
- Codex atlas 行（推荐）：
{ "sheet": "spritesheet.webp", "row": 0, "rows": 9, "frames": 8, "fps": 4, "playback": "loop" } - 单行动作 sheet：
{ "sheet": "idle.png", "frames": 3, "fps": 4, "playback": "loop" }
字段速查
| 字段 | 说明 |
|---|---|
sheet | 相对 lib/assets/characters/<id>/ 的文件名。允许 .png / .webp / .svg / .jpg / .jpeg / .gif / .json |
frames | 帧数（正整数）。PNG 多帧图必须满足 宽度 = frames × 高度（横排帧图） |
fps | 播放帧率 |
row / rows | atlas 行索引与总行数；row < rows |
playback | loop / pingpong / once / blink。最小帧数：pingpong≥2、blink≥2，其他 ≥1 |
motion | 可选运动配方：bob / wiggle / squash / shake / sigh / hop / tilt / float / wave。要求 frames === 1（error 是唯一例外，可以多帧 + 运动叠加） |
开发
node scripts/build-client.mjs
node scripts/gates/verify-assets.mjs
node --test 'tests/*.test.mjs'lib/client.js 是构建产物，改 lib/client/index.mjs 后运行 node scripts/build-client.mjs 重新生成。
