DockCat

自定义指引

本文介绍如何让 DockCat 使用自定义宠物图片。

DockCat 使用这样的本地资源包结构：每个资源包都是一个文件夹，里面包含一个 manifest.json 文件，以及若干透明背景 PNG 图片，用来表示不同姿势和动画帧。你可以先只放一张图预览效果，再逐渐补齐其他状态的猫猫图。

如果你还没有自己的宠物图片，可以参考 图片生成提示词.md。那里整理了我们生成默认小猫时使用的提示词。

快速开始

我们推荐首先生成和测试用于对话场景的猫咪站立形象。这个姿势可以在“设置 > 宠物设置”里预览。确认整体形象满意后，再逐渐补充其他状态的小猫图片。

1. 打开 DockCat 的“设置 > 宠物设置”。
2. 点击 打开文件夹。DockCat 会打开：

~/Library/Application Support/DockCat/CatPacks/

1. 打开里面的 my-cat/ 模板文件夹。
2. 把至少一张你想使用的小猫图片放进对应的状态文件夹，例如 poses/dialogue/stand.png。
3. 回到“设置 > 宠物设置”，选择或输入 my-cat，点击 加载所选，然后保存。

资源包 ID 就是 CatPacks/ 下面的资源包文件夹名称。你可以把 my-cat/ 改成自己猫咪的名字。

DockCat 支持加载不完整的资源包，方便你预览效果。缺少的图片会自动使用默认小猫填充。

完整资源包结构

一个完整资源包需要小猫的每种状态都至少有一张图，例如：

my-cat/
  manifest.json
  poses/
    resting/
      loaf.png
      side.png
    held/
      held.png
    dialogue/
      stand.png
    transition/
      stretch.png
  animations/
    walk/
      walk_01.png
      walk_02.png
      walk_03.png
  app_icons/
    icon_sleep.png
    icon_empty.png

app_icons/ 是可选的。其他文件夹建议在完整资源包中都准备好。

CatPacks/default-lizz/ 是默认小猫栗子的资源包副本，可以作为参考。以后如果 DockCat 新版本内置了更多栗子姿势图片，这个参考副本也会自动更新。我们建议编辑或复制 my-cat/ 来制作自己的资源包，并另外备份好自己的小猫图片。

姿势图片要求

DockCat 会扫描每个姿势文件夹，并读取里面所有可用图片。图片的文件名可以任意取，不过清楚的命名会让你的资源包更容易维护。

当小猫切换到某个姿势时，DockCat 会从对应文件夹里随机选择一张图显示。你可以给同一种状态准备很多张图，从而让小猫表现更丰富。

• poses/resting/：一个或多个休息姿势。
• poses/held/：一个或多个被鼠标拖动抱起时使用的姿势。
• poses/dialogue/：一个或多个正面姿势，用于提醒、出门消息和“设置 > 宠物设置”预览。
• poses/transition/：一个或多个短暂过渡姿势，例如伸懒腰或打哈欠。
• animations/walk/：散步动画帧。文件名顺序决定播放顺序。

当小猫需要朝向另一边时，DockCat 会自动镜像姿势图和散步动画。你不需要分别制作朝左和朝右两套图片。

图片规则

为了获得更好的显示效果，建议使用这些规则：

• 使用透明背景 PNG。
• 所有姿势图和散步帧尽量使用相同画布尺寸。
• 让小猫在所有图片中的视觉大小保持一致。
• 让爪底或身体底部位置保持一致，避免切换状态时小猫跳动。
• 给小猫周围留出透明边距，建议至少 8%。
• 文件名和文件夹名尽量使用小写英文、数字、下划线或连字符。
• 除非某个姿势确实需要，不要加入地板、阴影、场景、UI、文字或无关道具。
• 整个资源包保持统一画风：线条粗细、色彩、光照和画布位置都尽量一致。

散步动画建议

散步帧比静态姿势更需要一致性，因为 DockCat 会一边水平移动小猫，一边循环播放这些帧。

为了获得更稳定的效果，建议：

• 先创建一张侧面小猫图，并把它作为每次生成散步帧时的身份参考。
• 尽量把散步作为一组规划好的 4 帧循环生成，最好是一张包含 4 个等大单元格的横向条带图。
• 只保留一个散步方向。DockCat 会自动把同一组帧镜像到相反方向。
• 按播放顺序命名帧，例如 walk_01.png、walk_02.png、walk_03.png 和 walk_04.png。
• 加载资源包前，先把这些帧预览成循环动画。发现身体大小跳变、基线跳动、花纹变化、爪子或尾巴裁切、可见辅助线、阴影、地板或速度线时，重新生成问题帧。

推荐的散步条带提示词和质量检查清单见 图片生成提示词.md。

Manifest

manifest.json 放在资源包根目录。

如果你只是新增或替换普通姿势图，通常不需要修改 manifest.json。DockCat 会自动扫描对应文件夹，所以普通姿势图和散步帧不用一张张写进 manifest。

完整示例：

{
  "id": "my-cat",
  "name": "My Cat",
  "author": "Your Name",
  "canvas_width": 1024,
  "canvas_height": 1024,
  "default_anchor": { "x": 0.5, "y": 0.88 },
  "poses": {
    "resting": "poses/resting",
    "held": "poses/held",
    "dialogue": "poses/dialogue",
    "transition": "poses/transition"
  },
  "animations": {
    "walk": { "fps": 3, "frames": [] }
  },
  "app_icons": {
    "sleep": "app_icons/icon_sleep.png",
    "empty": "app_icons/icon_empty.png"
  }
}

字段说明：

• id：兼容和描述字段。DockCat 实际选择资源包时使用文件夹名，所以这里不一定要和“设置 > 宠物设置”中输入的资源包 ID 完全一致。如果你想分享自己的资源包，建议改成独特的 ID。
• name：宠物名字。
• author：作者名字。
• canvas_width 和 canvas_height：散步动画渲染用的稳定画布尺寸。如果你的散步帧使用了不同的设计画布尺寸，就修改这两个值。静态姿势图不会用这里的数值决定显示大小，而是按 PNG 实际尺寸显示。
• default_anchor：保留的资源包元数据。除非以后 DockCat 增加锚点编辑功能，否则建议保持 { "x": 0.5, "y": 0.88 }。
• poses：预览资源包中可以省略。省略后默认使用 poses/resting、poses/held、poses/dialogue 和 poses/transition。
• animations.walk.fps：散步动画播放速度。3 是一个适合开始测试的值。
• animations.walk.frames：当前 DockCat 会忽略这个字段；散步帧会从 animations/walk/ 中扫描，并按文件名排序。
• app_icons：可选。如果资源包不提供自定义应用图标，可以省略。

应用图标

DockCat 可以从你的资源包中加载自定义应用图标：

my-cat/app_icons/
  icon_sleep.png
  icon_empty.png

• icon_sleep.png：睡在垫子上的小猫。
• icon_empty.png：同一个垫子，但没有小猫。
• 建议使用 1024 x 1024 px PNG 源图。
• 两张图应当看起来属于同一套图标：垫子、比例、色彩和光照都应一致。

当 DockCat 成功加载一组有效图标后，会把它们复制到：

~/Library/Application Support/DockCat/AppIcon/

DockCat 会使用这个缓存副本作为持久自定义图标。替换或更新 DockCat App 不会删除这些本地图标。如果替换 App 后，在 DockCat 未运行时短暂显示了内置图标，启动一次 DockCat，它会重新把缓存的睡眠图标应用到当前 .app 文件图标上。

睡眠状态的程序坞图标还会受到 macOS Dock 图标缓存影响。DockCat 可以把自定义图标重新应用到 App 本身，但无法可靠地强制 Dock 进程立刻刷新缓存图片。如果重启 DockCat 后 icon_sleep.png 仍未显示，可能需要重启 Dock 或重启 Mac。

图标文件不会热更新。添加、替换或编辑 app_icons/icon_sleep.png 或 app_icons/icon_empty.png 后，请重启 DockCat。

加载和更新

添加或修改自定义资源包后：

1. 打开“设置 > 宠物设置”。
2. 如需访问 Finder，点击 打开文件夹。
3. 选择或输入文件夹 ID，例如 my-cat。
4. 点击 加载资源包，让 DockCat 重新扫描并验证资源包。
5. 保存。

如果只是修改设置项，直接保存即可。如果修改了资源包里的图片文件，请点击 加载资源包，让资源扫描器看到新文件。如果修改了 manifest.json，请重启 DockCat，让应用重新加载 manifest。图标文件更新后也需要重启 DockCat。

常见问题

如果资源包没有出现：

• 确认文件夹直接放在 ~/Library/Application Support/DockCat/CatPacks/ 下面。
• 确认 manifest.json 是有效 JSON。
• 确认文件夹名和“设置 > 宠物设置”里输入的 ID 一致。
• 确认图片文件是可读取的 PNG。
• 修改文件后点击 加载资源包。

如果只有部分状态显示你的小猫：

• 缺失状态正在使用默认小猫作为补充。
• 检查对应文件夹里的图片：resting、held、dialogue、transition 或 animations/walk。

如果小猫切换姿势时会跳动：

• 让每张 PNG 使用相近或相同的画布尺寸。
• 让小猫身体和爪底在所有姿势图中对齐。
• 保持透明边距一致。

如果散步动画播放顺序不对：

• 重命名动画帧，让文件名排序符合播放顺序，例如 walk_01.png、walk_02.png、walk_03.png。

如果替换图片后 DockCat 仍显示旧图：

• 修改姿势图或散步帧后，在“设置 > 宠物设置”中点击 加载资源包。
• 修改 manifest.json 或应用图标文件后，重启 DockCat。

如果散步状态的小猫比其他状态大或者小很多：

• 打开 manifest.json，调整 canvas_width 和 canvas_height，让它们符合散步动画的设计画布。
• 例如，如果你的散步帧是按 1500 x 1500 px 画布设计的，就把这两个值都设为 1500。
• 修改 manifest.json 后，请重启 DockCat。

This site is open source. Improve this page.