这篇文章记录我如何制作一个可以在 Codex 设置里切换使用的自定义桌宠dyt。它不是简单贴一张图片而是一个符合 Codex pet 格式的 9 状态动画桌宠包含待机、跑动、挥手、跳跃、失败、等待、审核等任务状态。项目地址GitHub - ymhlap/codex-pet-dyt: A cute dyt Codex custom pet · GitHub最终效果预览一、为什么要做 Codex 桌宠Codex 本身是一个很强的代码协作工具但长时间使用时界面会比较工具化。我希望给它加一个更有陪伴感的小角色让它能根据任务状态做出不同动作比如空闲时安静待机Codex 正在执行任务时开始跑动等待用户输入时做等待动作任务失败时出现低落表情代码 review 时切换成检查状态所以这次我做了一个名字叫dyt的 Codex 桌宠。角色风格参考了偏二次元 Q 版、小体积、高辨识度的方向最终保持成统一的 9 种动作状态。二、最终实现目标这次制作的桌宠需要满足几个要求可以被 Codex 识别为一个可切换的 pet。在 Codex 设置里能选择dyt。使用统一角色风格不同状态不能像 9 个不同角色。一共包含 9 种动作状态。图片需要透明背景方便叠加在 Codex 界面上。跑动方向需要自然尤其是向左跑、向右跑时头发和身体细节不能明显错位。最终可以打包上传到 GitHub方便其他人安装。三、Codex pet 的资源格式这个桌宠最终由两个核心文件组成pets/dyt/ ├─ pet.json └─ spritesheet.webp其中pet.json是桌宠配置文件。spritesheet.webp是包含所有动作帧的透明精灵图。完整项目结构如下codex-pet-dyt/ ├─ README.md ├─ LICENSE ├─ pets/ │ └─ dyt/ │ ├─ pet.json │ └─ spritesheet.webp ├─ qa/ │ ├─ contact-sheet.png │ ├─ previews/ │ │ ├─ idle.gif │ │ ├─ running-right.gif │ │ ├─ running-left.gif │ │ ├─ waving.gif │ │ ├─ jumping.gif │ │ ├─ failed.gif │ │ ├─ waiting.gif │ │ ├─ running.gif │ │ └─ review.gif │ ├─ review.json │ └─ validation.json └─ scripts/ └─ install.ps1pet.json内容非常简单{ id: dyt, displayName: dyt, description: A cute chibi anime girl Codex pet with 9 animated task states., spritesheetPath: spritesheet.webp }这里最重要的是id桌宠唯一标识。displayName在 Codex 设置里显示的名字。spritesheetPath指向真正的精灵图文件。四、9 种动作状态设计Codex pet 使用一张大图来承载所有动作。这次dyt的精灵图规格是8 列 x 9 行 每格 192 x 208 总尺寸 1536 x 1872也就是说横向 8 列代表同一个动作的 8 帧动画。纵向 9 行代表 9 种不同状态。9 种状态如下行号状态说明0idle默认待机状态1running-right向右跑动2running-left向左跑动3waving挥手4jumping跳跃5failed任务失败6waiting等待用户输入7running通用运行状态8review代码审核/检查状态每一行都需要保持同一个角色只是姿态、表情、发丝、服装动态发生变化。五、每个状态的预览1. idle待机待机状态要尽量自然不需要过度夸张。主要做轻微呼吸感、头发轻微浮动让角色停在界面里时不会显得僵硬。2. running-right向右跑这个状态用于鼠标悬停或任务推进时向右侧移动。重点是身体重心、头发方向和腿部节奏需要一致。3. running-left向左跑向左跑最容易出问题。我在后期专门重新修过这一行因为最开始头发丝在移动过程中有些碎、不完整跑动时会显得头发和身体不是一个整体。修正思路是保持头发主体轮廓连续。发梢可以动但不能每帧随机漂移。刘海、侧发和身体朝向要同步。不要简单镜像后直接使用需要检查细节。4. waving挥手挥手状态适合表示任务完成、欢迎或者轻提示。这个动作要可爱但不能幅度太大否则在 Codex 界面里会抢注意力。5. jumping跳跃跳跃状态用于强调兴奋、成功、切换等反馈。这里要注意角色落地后的稳定感不能像整个人漂起来。6. failed失败失败状态用于任务报错、执行失败等情况。我没有把它做得过分夸张而是偏向委屈、低落一点这样在工作界面里不会太打扰。7. waiting等待等待状态表示 Codex 正在等用户回复、授权或者下一步输入。动作节奏可以比 idle 稍微明显一点比如轻微晃动、看向一侧。8. running通用运行通用 running 状态通常用于任务处理中。它和左右跑动不同不强调明确方向而是表达“正在忙”。9. review审核review 状态用于代码检查、分析或者审阅阶段。这个状态适合做成更专注的表情比如低头看文件、思考、检查内容。六、制作流程第 1 步确定角色风格制作桌宠前最先要确定的是角色统一风格而不是直接生成 9 张图。我这次给dyt定的方向是Q 版比例二次元少女风格头发和服装有明确辨识度适合小尺寸显示动作轻快但不过分花哨背景透明桌宠显示尺寸通常不大所以角色不能有太多细碎装饰。如果细节太复杂缩小后会糊成一团动作也很难看清。第 2 步先生成基础角色先做基础角色图也就是确定脸型发型发色服装眼睛风格整体比例角色名字和气质这一步很关键。后面的 9 个动作都必须围绕这个基础角色展开。如果基础角色没定稳后面每个动作看起来都会像重新抽卡。第 3 步拆分 9 个动作行确定基础角色后再按 9 个状态分别设计动作。推荐顺序是idlerunning-rightrunning-leftwavingjumpingfailedwaitingrunningreview我不建议一开始就把所有动作混在一起做。更好的方式是每一行单独检查角色一致性然后再合成完整 spritesheet。第 4 步统一帧尺寸每一帧都固定为192 x 208这个尺寸需要严格统一。如果某一帧尺寸不一致后面合成 spritesheet 后Codex 播放动画时就可能出现抖动、错位、裁切。第 5 步合成 spritesheet最终精灵图是1536 x 1872计算方式宽度 192 x 8 1536 高度 208 x 9 1872排列方式第 0 行idle 的 8 帧 第 1 行running-right 的 8 帧 第 2 行running-left 的 8 帧 第 3 行waving 的 8 帧 第 4 行jumping 的 8 帧 第 5 行failed 的 8 帧 第 6 行waiting 的 8 帧 第 7 行running 的 8 帧 第 8 行review 的 8 帧最终产物就是pets/dyt/spritesheet.webp七、安装到 Codex方法一使用安装脚本下载项目后在项目根目录运行powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\install.ps1脚本会把pets/dyt复制到%USERPROFILE%\.codex\pets\dyt安装完成后如果 Codex 设置里没有马上出现dyt重启 Codex 即可。方法二手动安装也可以手动复制。把项目中的pets/dyt复制到C:\Users\你的用户名\.codex\pets\dyt最终目录应该是C:\Users\你的用户名\.codex\pets\dyt\pet.json C:\Users\你的用户名\.codex\pets\dyt\spritesheet.webp然后打开 Codex 设置在 pet 选项里选择dyt。八、质量检查桌宠不是只要能显示就算完成。我建议至少检查下面几项1. 透明背景是否正常如果背景不是透明的放到 Codex 界面里会出现白底或色块非常明显。2. 角色是否一致9 个状态要看起来像同一个角色。尤其注意发型眼睛服装身高比例头身比主色调3. 跑动方向是否自然向右跑和向左跑是最容易暴露问题的。这次我重点修了向左跑时的头发丝问题。检查方式连续播放running-left.gif观察头发主体有没有断裂观察发梢有没有随机跳动观察身体和头发方向是否一致4. 动画是否抖动如果某些帧角色位置偏移太大播放时就会像在闪烁。需要保证每一帧角色的脚底、身体中心大致稳定。5. 小尺寸是否清晰桌宠最终显示不会特别大。所以要把预览图缩小看一次确认五官和动作还能看清。九、发布到 GitHub我最后把项目整理成了一个独立仓库ymhlap/codex-pet-dyt发布前建议至少包含README.md说明项目是什么、如何安装、有什么状态。LICENSE开源协议。pets/dyt/pet.jsonCodex pet 配置。pets/dyt/spritesheet.webp核心资源。qa/contact-sheet.png总览图。qa/previews/*.gif每个状态的单独预览。scripts/install.ps1Windows 一键安装脚本。GitHub 推送流程大致是git init git add . git commit -m Add dyt Codex pet git branch -M main git remote add origin https://github.com/ymhlap/codex-pet-dyt.git git push -u origin main如果 GitHub 仓库创建时已经带了README或LICENSE首次推送可能会提示远端已有提交。这时可以先拉取并 rebasegit pull --rebase origin main如果有冲突解决后继续git add . git rebase --continue git push -u origin main十、常见问题1. 为什么 Codex 里看不到 dyt先检查目录是否正确%USERPROFILE%\.codex\pets\dyt里面必须直接包含pet.json spritesheet.webp不要多套一层目录。如果路径没错重启 Codex 再看设置。2. 为什么动作播放错位通常是 spritesheet 的尺寸或排列不对。需要确认每帧192 x 208 列数8 行数9 总图1536 x 18723. 为什么某个状态看起来不像同一个角色这是生成多状态角色时最常见的问题。解决办法不是一次性生成所有图而是先固定基础角色再逐个动作修正。4. 为什么向左跑比向右跑更容易出问题因为很多时候向左跑是由向右跑镜像或重绘得到的。镜像之后头发、衣服、手臂方向可能看起来不自然需要单独检查。这次dyt就是后期专门修正了running-left的头发丝完整性。总结这次dytCodex 桌宠制作完成后最终得到了一个可以真实安装、可以在 Codex 设置里切换、并且包含 9 种动作状态的完整 pet 项目。项目地址GitHub - ymhlap/codex-pet-dyt: A cute dyt Codex custom pet · GitHub如果你也想做自己的 Codex 桌宠建议按这个顺序来先确定角色风格。再设计 9 个状态。保证每帧尺寸统一。合成透明 spritesheet。写好pet.json。安装到.codex/pets测试。做 GIF 预览和总览图。整理 README 后发布到 GitHub。只要格式正确Codex 就可以把它当成一个真正可切换的桌宠来使用。
