桌宠包制作与导入
桌宠包是一个 ZIP 文件，包含角色图片、可选的动画图集和配置文件。你可以从一张透明图片开始，再逐步加入待机、工作、鼠标视线、成功、失败与拖拽动画。
桌宠以独立悬浮窗口显示，可拖到桌面其他位置；主窗口最小化后仍可显示，退出 AUTO-MAS 时关闭。主题包可以附带桌宠，也可以单独制作和导入桌宠包。主题的配色、背景等配置见自定义外观包。
适用客户端
本教程适用于已有「设置 → 界面设置 → 外观配置 → 导入桌宠」入口的客户端。旧版本如果没有独立桌宠入口，需要先使用支持该功能的客户端。
专属拖拽图集还需要客户端支持 mascot.animation.dragPath。仅支持较早桌宠格式的客户端请省略该字段和对应图片，继续使用通用拖动效果。
导入与切换
- 打开「设置 → 界面设置」，找到「外观配置」。
- 点击「导入桌宠」，选择 ZIP 文件，不需要手动解压。
- 导入成功后会选中该桌宠；确认「显示桌面桌宠」已开启。
- 以后可以在「桌宠选择」下拉框中切换已安装的桌宠。
- 更新同一个桌宠时，保持配置中的
id不变，重新导入并确认替换。
「跟随当前主题」表示使用主题包附带的桌宠；主题没有附带桌宠时不显示。选中独立桌宠后，切换主题会保留所选桌宠。关闭「显示桌面桌宠」可以隐藏它，不必删除资源包。
本地「导入桌宠」也可以选择带桌宠的旧主题包：客户端只提取桌宠素材，不会应用该主题的配色和背景。用于单独分享的桌宠包则应按下面的 mascot.json 格式制作。
在主题包中附带桌宠
主题包继续使用根目录的 theme.json。把下文示例中的整个 mascot 对象放入 theme.json，保留主题的 mode、tokens 等字段，并把对应图片放入主题包的 assets/ 目录。需要动画时，在同一个 mascot.animation 中配置；图片排布和字段与独立桌宠相同，不需要另放 mascot.json。
主题的其他字段和打包方式见自定义外观包。通过「导入外观」应用主题后，将「桌宠选择」设为「跟随当前主题」并开启「显示桌面桌宠」。主题可以省略 mascot，不影响配色、背景等功能。
制作一个最简桌宠包
1 建立目录
创建一个工作文件夹，放入配置文件和角色图片：
my-mascot/ ← 工作目录，这一层不放进 ZIP
├── mascot.json ← 必需，独立桌宠配置
└── assets/
└── mascot.png ← 必需，角色静态图建议文件名使用英文字母、数字和短横线。图片路径统一使用正斜杠 /，例如 assets/mascot.png。
2 准备透明图片
推荐使用透明 PNG：角色、尾巴和道具完整，四周留适量空白，边缘不要有杂点。静态图也支持 JPEG、WebP，但 JPEG 不支持透明背景。
例如，计划显示约 192 像素宽时，可以准备 384 像素宽的原图。画布留白越多，角色实际看起来越小；透明留白也属于显示尺寸的一部分。
棋盘格只是图片软件显示透明区域的方式，不应画进图片。把图片分别放在浅色和深色底上检查，可以发现白边、黑边和残留背景。
3 编写 mascot.json
保存为 UTF-8 编码的纯文本文件，文件名必须是 mascot.json，不要变成 mascot.json.txt。
下面是可以直接改写的最简配置：
{
"formatVersion": 1,
"id": "my-mascot",
"name": "我的桌宠",
"mascot": {
"path": "assets/mascot.png",
"width": 192
},
"preview": "assets/mascot.png"
}先只改 id、name 和图片。独立桌宠不需要填写主题的 mode、tokens 或 background。
4 打包
进入 my-mascot 文件夹，选中 mascot.json 和 assets，再压缩成 ZIP。打开 ZIP 时应直接看到这两项，而不是先看到外层的 my-mascot 文件夹。
可以使用资源管理器、7-Zip、Bandizip，或在工作文件夹中打开终端，使用 Windows 自带的 tar：
tar -a -c -f ..\my-mascot.zip mascot.json assetsZIP 内必须使用 / 分隔路径。遇到「Windows 路径」或反斜杠相关的导入错误时，换用上述打包方式重新压缩。外观包教程中也提醒避免使用 Windows PowerShell 5.1 的 Compress-Archive 打包。
5 导入验证
导入后检查角色是否完整、透明区域是否干净、显示大小是否合适。修改图片或配置后，重新打包并导入相同 id 的 ZIP，确认替换即可。
加入动画与鼠标视线
这些素材均为可选项。需要哪种能力，就准备对应图片并填写对应字段；没有准备的素材不要引用，也不要放进 ZIP。
| 素材 | 排布 | 用途 |
|---|---|---|
mascot.png | 单张图片 | 静态显示和基础角色图，始终保留 |
animation.png | 两行，列数由 columns 决定 | 第一行待机，第二行工作 |
look.png | 固定三行三列 | 鼠标方向对应的九张静态视线图 |
results.png | 两行，列数与主动画一致 | 第一行失败，第二行成功 |
drag.png | 一行，列数与主动画一致 | 拖动时循环播放的专属姿态 |
待机与工作动画
把连续动作帧拼成一张普通 PNG 图集。客户端按格子切换，不是直接播放 GIF 或视频。
以每行 8 帧、每帧 256×256 像素为例，animation.png 应为 2048×512 像素：
第一行：待机0 待机1 待机2 待机3 待机4 待机5 待机6 待机7
第二行：工作0 工作1 工作2 工作3 工作4 工作5 工作6 工作7各格必须等宽等高，不留额外分隔线或格子间距。人物的大小、中心和脚底位置尽量一致；只有动作本身需要的部分发生变化。循环最后一帧应自然接回第一帧。
columns 是每行的帧数，可以写 2 到 16 的整数。把它从 8 改成 16 不会自动增加动作帧，图片也必须相应变成每行 16 格。
九方向静态视线
look.png 固定为 3×3 九宫格，方向以观看图片的人为准，按下面的位置排布：
| 左上 | 上 | 右上 |
|---|---|---|
| 左 | 正前方 | 右 |
| 左下 | 下 | 右下 |
每格与主动画使用相同的帧尺寸最方便。主动画每帧为 256×256 像素时，视线图就是 768×768 像素；它不随 columns 改变。
九张图可以只改变眼睛方向，也可以加入轻微转头。角色、道具、画布和基准线保持一致，避免切换方向时突然变大或跳动。
视线跟随在待机时启用。鼠标停下片刻或远离后会恢复待机；工作、拖拽和任务结果反馈期间不切换视线。视线图是静态的，选中某个方向时整张图片都会定格，包括画在它后面的代码、粒子或其他装饰。
成功与失败动画
results.png 的列数与主动画一致，第一行放失败动作，第二行放成功动作：
第一行：失败0 失败1 失败2 失败3 失败4 失败5 失败6 失败7
第二行：成功0 成功1 成功2 成功3 成功4 成功5 成功6 成功7上面的例子仍为 2048×512 像素。建议每格与主动画使用相同尺寸。收到对应任务反馈时，客户端会选择相应的一行，并按 workingFps 播放；反馈结束后恢复原状态。
完整配置示例
完整目录如下：
my-mascot/
├── mascot.json
└── assets/
├── mascot.png
├── animation.png
├── look.png
├── results.png
└── drag.png下面的例子要求主动画与结果动画都是每行 8 帧：
{
"formatVersion": 1,
"id": "my-mascot",
"name": "我的桌宠",
"description": "包含待机、工作、静态视线、成功、失败和拖拽动作。",
"mascot": {
"path": "assets/mascot.png",
"width": 192,
"opacity": 1,
"position": "bottom-right",
"animation": {
"path": "assets/animation.png",
"columns": 8,
"idleFps": 6,
"workingFps": 10,
"lookPath": "assets/look.png",
"resultPath": "assets/results.png",
"dragPath": "assets/drag.png"
}
},
"preview": "assets/mascot.png"
}如果只做待机和工作，删除 lookPath、resultPath、dragPath，并从 ZIP 中移除相应图片。如果完全不做动画，删除整个 animation 对象，只保留最简配置。
专属拖拽动画
需要在拖动时切换成被提起、悬空或挣扎等姿态，可以准备 drag.png，并在 mascot.animation.dragPath 中引用。
拖拽图集只有一行，列数与 columns 一致。例如主动画为 8 列、每格 256×256 像素时，拖拽图集为 2048×256 像素：
拖拽0 拖拽1 拖拽2 拖拽3 拖拽4 拖拽5 拖拽6 拖拽7建议保持每格画布尺寸、人物比例和基准位置与主动画一致。拖动期间，客户端优先播放这张图集，使用 workingFps，不再叠加通用摇晃；松开后恢复当前待机、工作或尚未结束的任务结果状态。拖拽期间不切换鼠标视线。
没有配置 dragPath 时，继续使用客户端原有的通用拖动效果，不需要额外素材。暂停动画、低性能模式或系统减少动态效果生效时，拖拽图集显示第一帧，不继续播放。主题附带和独立桌宠使用相同配置。
手动停止的当前支持范围
手动停止后的疑惑效果由客户端提供，不需要额外素材。当前格式没有专属停止动画字段，不要添加 stoppedPath 或混入未引用的备用图片。
手动停止任务后的疑惑反馈，与右键「暂停动画」不同：前者表示任务被人为中止，后者控制桌宠是否继续播放。
字段说明
基本信息
| 字段 | 必填 | 说明 |
|---|---|---|
formatVersion | 是 | 固定为数字 1 |
id | 是 | 唯一标识，最长 64 个字符；使用小写字母、数字、_、-，以字母或数字开头；避开 con、nul、com1 等 Windows 保留名 |
name | 是 | 桌宠显示名称，最长 80 个字符 |
description | 否 | 简短说明，最长 300 个字符；没有说明时省略 |
mascot | 是 | 角色图片和显示配置 |
preview | 否 | 预览图片路径，可以复用 assets/mascot.png，也可以引用单独准备的预览图 |
角色显示
| 字段 | 默认值 | 说明 |
|---|---|---|
mascot.path | 无，必填 | 图片路径，必须位于 assets/ 下 |
mascot.width | 144 | 整张角色画布的目标显示宽度，16 到 1024 像素 |
mascot.opacity | 1 | 不透明度，范围 0 到 1；设为 0 时不显示 |
mascot.position | bottom-right | 初始位置，可选 top-left、top-right、bottom-left、bottom-right |
实际显示尺寸还会受当前显示器工作区限制：宽不超过工作区的 35%，高不超过 30%。拖动后客户端会记住位置，修改 position 不等于清除已经记住的位置。
动画
| 字段 | 默认值 | 说明 |
|---|---|---|
mascot.animation.path | 无，配置动画时必填 | 两行主动画 PNG 的路径 |
mascot.animation.columns | 无，配置动画时必填 | 每行帧数，2 到 16 的整数 |
mascot.animation.idleFps | 4 | 待机每秒帧数，范围 1 到 24 |
mascot.animation.workingFps | 8 | 工作、结果和拖拽动画每秒帧数，范围 1 到 24 |
mascot.animation.lookPath | 不启用视线跟随 | 静态 3×3 视线 PNG 路径 |
mascot.animation.resultPath | 不使用专属结果图 | 两行结果动画 PNG 路径，先失败后成功 |
mascot.animation.dragPath | 使用通用拖动效果 | 单行拖拽 PNG 路径，列数与主动画一致，使用 workingFps |
以上动画图片都必须放在 assets/ 下，扩展名为 .png。lookPath 和 resultPath 都写在 animation 内，并配合主动画使用。
制作后方滚动代码
滚动代码可以直接画进动画帧，不需要在桌宠包里放脚本。
- 准备一段可以首尾循环的代码文字图层，保留字符之外的透明区域。
- 按帧把同一段文字向上移动固定距离，并在下方接上重复内容。
- 把角色每帧的动作叠在代码前方，文字不要盖住脸和身体。
- 将合成好的帧拼成两行主动画；需要在成功、失败时继续滚动，就在结果帧里也做相同处理。
例如，一个循环的文字高度为 80 像素，每行 8 帧，则各帧向上偏移 0、10、20、30、40、50、60、70 像素。下一步偏移 80 像素时，画面应与第一帧接上。不要每帧重新生成不同代码，否则看起来会闪烁，无法形成连续滚动。
黑色背景不是必需的：只保留有颜色的文字像素和前方角色即可。进入静态视线图或暂停动画时，代码也会停止移动，这是当前整帧播放方式的正常表现。
导入后的使用
- 拖动角色可以调整桌面位置，不会挤压主界面布局。
- 右键「暂停动画」可以停止播放，恢复后继续显示动画。
- 右键「暂停留言」控制待机留言；留言和任务提醒由客户端提供，包里不用绘制说话框或填写留言内容。
- 选择其他独立桌宠或「跟随当前主题」可以切换来源。
- 导入相同
id时选择替换，可以保留原来使用的桌宠标识；要同时保留两个不同作品，使用不同id。
限制
| 项目 | 上限或要求 |
|---|---|
| ZIP 大小 | 16 MiB |
| 解压后总大小 | 32 MiB |
| ZIP 条目数 | 32，文件夹条目也计算在内 |
| 单个文件 | 8 MiB |
mascot.json 大小 | 256 KiB |
| ZIP 内路径长度 | 240 个字符 |
| 主动画和结果图集宽高 | 每个方向不超过 8192 像素；宽度能被 columns 整除，高度能被 2 整除 |
| 拖拽图集宽高 | 每个方向不超过 8192 像素；只有一行，宽度能被 columns 整除 |
| 文件内容 | 每张图片都必须被配置引用；不能有空文件、多余文件或伪装格式的文件 |
PNG、JPEG、WebP 是图片的真实编码格式，不是随便改一个文件扩展名就能转换。ZIP 里也不要混入 Thumbs.db、desktop.ini、.DS_Store、说明文档或备用素材。
常见问题
| 现象或提示 | 检查方法 |
|---|---|
| 找不到独立桌宠导入入口 | 确认客户端已支持独立桌宠；旧版只有外观导入时不能直接使用此包 |
缺少 mascot.json | 配置文件应位于 ZIP 根目录，名称使用小写，不要多套一层文件夹 |
| 配置无法解析 | 检查中文引号、注释、末尾逗号以及是否误存为 .txt |
| 包含未声明文件 | 删除没有引用的图片、系统隐藏文件、说明文档和备用素材 |
| 缺少资源 | 检查文件名、扩展名和配置路径是否一致 |
| 动画无效或切到错误部位 | 检查两行布局、实际列数和 columns；不要带格子间距 |
| 动画一直不播放 | 检查右键菜单是否暂停动画，以及是否开启了低性能模式或系统的“减少动态效果” |
| 鼠标视线方向不对 | 按本文的 3×3 排布检查，左和右按观看者方向定义 |
| 跟踪鼠标时动画和代码不动 | 静态视线图会定格；鼠标停下片刻后恢复待机 |
| 成功时播放失落表情 | 结果图第一行是失败，第二行才是成功 |
| 桌宠突然变大、变小或抖动 | 统一画布、主体尺寸、中心和脚底位置，不要给各帧分别自动裁边后直接拼接 |
| 桌宠没有显示 | 开启显示开关，检查 opacity 是否为 0；跟随主题时，主题本身要带桌宠 |
| 黑底、白底或棋盘格跟着角色显示 | 检查这些内容是否已经画进图片，重新导出带透明通道的 PNG |
用 AI 辅助制作
生成配置文件
把已有素材路径和实际排布写清楚，让 AI 只引用真实文件。下面的提示词可以直接复制，再替换尖括号中的内容：
请为 AUTO-MAS 生成独立桌宠包的 mascot.json，只输出有效 JSON。
名称：<桌宠名称>
id：<小写字母、数字、下划线、短横线，以字母或数字开头，最多64字符>
已有文件：
- 静态图：assets/mascot.png
- 主动画：<assets/animation.png 或 无>，<每行帧数>列、2行，先待机后工作
- 视线图：<assets/look.png 或 无>，固定3×3
- 结果图：<assets/results.png 或 无>，列数与主动画一致，先失败后成功
- 拖拽图：<assets/drag.png 或 无>，单行，列数与主动画一致
显示宽度：<例如192>
要求：formatVersion 为1；name 最多80字符；有 description 时最多300字符。
mascot.path 必填；animation.path 和 columns 在配置动画时必填。
columns 为2至16的整数；idleFps、workingFps 为1至24，建议先用6和10。
所有角色与动画素材路径以 assets/ 开头，动画素材必须是 PNG。
有主动画时，才在 animation 中填写实际存在的 lookPath、resultPath、dragPath。
没有的素材整段省略；不生成主题配色或背景字段，不添加 stoppedPath。
preview 复用 assets/mascot.png。不要编造素材、注释或额外字段。生成角色动画
为<角色描述>制作透明背景的游戏桌宠精灵图。
画布为<总宽度>×<总高度>，严格8列2行，每格<单帧宽度>×<单帧高度>。
第一行8帧：呼吸、眨眼、轻微尾巴摆动的待机循环。
第二行8帧：<工作动作>的连续循环。
每格一个完整角色，外观、比例、画布中心和脚底基准线保持一致。
不要裁切角色和道具，不画格线、帧号、文字、水印、阴影底座或不透明背景。
第一帧与最后一帧自然衔接，使用干净的真实透明通道。图片模型生成的尺寸、格子数量和一致性都需要人工检查。尺寸不准确时，用图片软件重新排列成等宽等高的格子；最后核对实际图片尺寸再填写 columns，不能只依赖提示词。
分享与更新
在支持分类的「资源商店」中，下载桌宠选择「桌宠」入口；上传独立桌宠时也选择桌宠分类，使用根目录含 mascot.json 的纯桌宠 ZIP。
旧主题包可以在本地提取桌宠，不代表它可以直接作为独立桌宠上传。想单独分享时，应只保留桌宠图片，另写 mascot.json，不携带主题配色和背景资源。
发布前确认：
- [ ] 全新导入和相同
id的替换导入都成功。 - [ ] 浅色、深色桌面背景下，角色轮廓和透明边缘正常。
- [ ] 主动画循环自然，待机和工作各在正确的一行。
- [ ] 九方向视线排布正确，静止后能恢复待机。
- [ ] 结果动画先失败后成功，帧数与主动画一致。
- [ ] 配置了拖拽图集时，拖动切换姿态，松开后恢复；未配置时通用拖动效果正常。
- [ ] ZIP 只含已引用文件，没有额外目录层或备用素材。
主题包附带桌宠时，配色和背景等字段继续使用自定义外观包的格式；单独分享桌宠时使用本教程的 mascot.json 格式。