今回は、Codex Desktop 用のカスタムPetを作ってみました。

題材は、うちの三毛猫の凜ちゃんです。

Codex Desktop には Pet と呼ばれる作業相棒キャラクター機能があり、設定画面の Custom pets セクションからオリジナルのものも登録できます。

まだ少し実験的な雰囲気がありますが、hatch-pet というSkillを使うと、参考画像からアニメーション付きのカスタムPet素材を作れました。

この記事では、今日実際にやった流れをそのまま残しておきます。

最終的にできたもの

最終的には、以下のようなCodex用Petパッケージができました。

~/.codex/pets/rin-chan/
  pet.json
  spritesheet.webp

pet.json はPetのメタ情報、spritesheet.webp はアニメーション用のスプライトシートです。

今回の凜ちゃんPetには、以下の状態アニメーションが入りました。

  • idle: 普段の待機
  • running-right: 右向きに走る
  • running-left: 左向きに走る
  • waving: 手を振る
  • jumping: 跳ねる
  • failed: 失敗・しょんぼり
  • waiting: 待機中
  • running: 汎用の走り
  • review: 確認・レビュー中

Codexアプリ側が対応していれば、作業状態に合わせて小さい凜ちゃんが動く、という感じですね。

凜ちゃんカスタムPetのコンタクトシート（全10アニメーション行の一覧）

使ったもの

使ったものはこんな感じです。

  • Codex Desktop
  • skill-installer
  • hatch-pet
  • 凜ちゃんの参考写真

最初に skill-installer で hatch-pet を入れました。

[$skill-installer] hatch-pet

これで以下にSkillが入りました。

~/.codex/skills/hatch-pet/

その後、Codexを再起動するとSkillとして使えるようになります。

Codex DesktopでSkill Installerがhatch-petをインストールし、hatch-pet Skillが起動した画面

参考画像を渡した

写真を複数枚渡しました。

正面の顔、全身、寝転び、ジャンプ、首輪が見える写真などです。

お願いの仕方は単純で、「三毛猫の凜ちゃんのペットがいい。添付画像を参考に作ってほしい」というだけです。

特徴を細かく指定したりはしていません。写真を投げて、お任せした感じです。

凜ちゃんの参考写真10枚をCodexに渡している様子

まずベース画像を作る

hatch-pet は、最初にPetの基準になるベース画像を作ります。

ここで作ったベース画像が、以降の全アニメーション行の「正解」になります。

スタイルはhatch-pet側が自動で設定してくれました。ざっくり言うと、写真っぽいリアルな猫ではなく、Codexの小さいデジタルPetとして読めるちびキャラスタイルです。

できあがったベース画像を見て、ちょっと嬉しかったのがピンクの首輪です。

凜ちゃんが最初の写真で付けていた首輪と同じ、ピンクの首輪がちゃんと反映されていました。

白い胸、三毛の顔、グリーンの目、口元の小さい模様も入っていて、「あ、ちゃんと凜ちゃんだ」という感じです。

凜ちゃんの参考写真10枚を渡した後、hatch-petが生成したベース画像（ちびキャラ・ピクセルアートスタイル）

作業フォルダを作る

裏側では、hatch-petが作業フォルダとジョブ定義を自動で用意してくれました。

こんな感じのコマンドが走っていました。

python ~/.codex/skills/hatch-pet/scripts/prepare_pet_run.py \
  --pet-name "Rin-chan" \
  --pet-id rin-chan \
  --display-name "凜ちゃん" \
  --description "三毛猫の凜ちゃんを元にしたCodex用デジタルペット。" \
  --reference /path/to/rin-photo-01.jpg \
  --reference /path/to/rin-photo-02.jpg \
  --output-dir /tmp/hatch-rin-chan \
  --force

このとき、--pet-name "凜ちゃん" のように日本語だけで指定しようとしたところ、スクリプト側でエラーになりました。

pet id must contain at least one letter or digit

なので、表示名は 凜ちゃん のままにしつつ、内部IDは rin-chan にする形になりました。

このあたりは、カスタムPetを作る時にハマりそうなポイントですね。

ベース画像を正式に記録する

画像生成でできたベース画像は、hatch-petが record_imagegen_result.py でジョブ結果として記録してくれました。

python ~/.codex/skills/hatch-pet/scripts/record_imagegen_result.py \
  --run-dir /tmp/hatch-rin-chan \
  --job-id base \
  --source ~/.codex/generated_images/.../ig_xxx.png

これで以下が作られました。

/tmp/hatch-rin-chan/decoded/base.png
/tmp/hatch-rin-chan/references/canonical-base.png

canonical-base.png が、以降のアニメーション生成で参照される基準画像になります。

アニメーション行はサブエージェントに分担

ベース画像ができたら、hatch-petがアニメーション行の生成をサブエージェントに分担させていきます。

まず以下の2つから作りました。

  • idle
  • running-right

この2つで、Petとしての一貫性を最初に確認する流れになっているようです。

idle で顔や雰囲気が崩れていないかを見て、running-right で走りのシルエットが成立しているかを確認しました。

サブエージェントには、画像生成だけを担当させています。

記録・ミラー・最終化・パッケージングは親側のCodexが引き受ける、という役割分担です。

running-left はミラーで作った

running-right がいい感じにできたので、running-left はミラーで作ってくれました。

python ~/.codex/skills/hatch-pet/scripts/derive_running_left_from_running_right.py \
  --run-dir /tmp/hatch-rin-chan \
  --confirm-appropriate-mirror \
  --decision-note "Rin-chan has no readable text or side-specific prop..."

凜ちゃんの場合、文字や左右固定の小道具はないので、左右反転でPetとして成立すると判断してくれたようです。

もしロゴや片側だけのアクセサリーがあるキャラなら、ミラーは避けた方がよさそうですね。

残りのポーズを作る

その後、残りの行もサブエージェントが分担して生成しました。

  • waving
  • jumping
  • failed
  • waiting
  • running
  • review

同時に起動しすぎると、サブエージェントの上限に当たりました。

なので、最初に4本動かして、完了したものを閉じてから残り2本を起動する流れになっていました。

各行では、かなり細かい禁止事項が設定されています。

例えば waving なら、手を振る線や波マークを出さない。jumping なら、影や着地エフェクトを出さない。running なら、スピード線や砂ぼこりを出さない。

Petのスプライトでは、キャラ本体だけをきれいに切り抜けることが大事なので、余計な装飾は基本的に邪魔になるようです。

最終化する

全10ジョブが完了したら、finalize_pet_run.py を実行して最終化してくれました。

python ~/.codex/skills/hatch-pet/scripts/finalize_pet_run.py \
  --run-dir /tmp/hatch-rin-chan

この処理では、だいたい以下をやってくれています。

  • 各行画像からフレームを抽出
  • 192x208 のセルに整形
  • 8x9 のスプライトシートに合成
  • WebPを書き出し
  • validationを実行
  • contact sheetを生成
  • preview videoを生成
  • pet.json と spritesheet.webp を ~/.codex/pets/rin-chan/ に保存

最終的なスプライトシートは以下のサイズでした。

1536 x 1872

これは 192 x 208 のセルを、横8列・縦9行に並べたサイズです。

完成した凜ちゃんスプライトシート（1536×1872、全アニメーション行）

ハマったところ

今回ハマったところは3つありました。

1. 日本語名だけだとPet IDで落ちた

表示名は 凜ちゃん で大丈夫でした。

ただ、内部IDは英数字を含む必要がありました。

なので以下のように分けました。

pet-id: rin-chan
display-name: 凜ちゃん

これは今後も使いそうなパターンです。

2. 古いPythonで動画生成が落ちた

最初に finalize_pet_run.py を実行したとき、preview videoの生成で落ちました。

原因は、macOS標準のPython 3.9が zip(strict=True) に対応していなかったためです。

TypeError: zip() takes no keyword arguments

Codex bundled runtime の Python 3.12 で再実行したら、動画生成まで通りました。

~/.cache/codex-runtimes/.../python/bin/python3 \
  ~/.codex/skills/hatch-pet/scripts/finalize_pet_run.py \
  --run-dir /tmp/hatch-rin-chan

こういうところ、地味にありますね汗

3. ~/.codex/pets への保存で権限が必要だった

最終パッケージを ~/.codex/pets/rin-chan/ に保存するところで、サンドボックスに止められました。

PermissionError: Operation not permitted: '~/.codex/pets/rin-chan'

これは、Codexの作業サンドボックス外に書き込むためです。

最後のパッケージ作成だけ、権限付きで実行しました。

python ~/.codex/skills/hatch-pet/scripts/package_custom_pet.py \
  --pet-name rin-chan \
  --display-name 凜ちゃん \
  --description 三毛猫の凜ちゃんを元にしたCodex用デジタルペット。 \
  --spritesheet /tmp/hatch-rin-chan/final/spritesheet.webp \
  --force

これで無事に以下へ保存されました。

~/.codex/pets/rin-chan/

QAで確認したこと

最終的に以下を確認しました。

  • validation.json に errors がない
  • review.json に errors がない
  • contact sheetで全行を目視確認
  • unused cell が透明になっている
  • running-left が running-right の自然な反転になっている
  • waving に余計な波線がない
  • jumping に影や着地エフェクトがない
  • failed の涙や星が本体から離れていない
  • review に紙・UI・記号などの余計な小道具がない

contact sheetを見ると、凜ちゃんの三毛、グリーンの目、ピンクの首輪は全体的に保たれていました。

failed はちょっとしょんぼり感が強めでしたが、状態表現としては成立しているかなと思っています。

Codex PetはどうやってONにするのか

完成したPetは、Codex Desktop の Appearance → Personalization を開くと、Custom pets セクションにすでに出てきていました。

「凜ちゃん」を選んだら、そのままSelectedになりました。

再起動が必要かどうかは正直分かりませんが、もし出てこない場合は一度再起動してから確認してみると良いと思います。

Codex Desktop の Appearance 設定でカスタムペット「凜ちゃん」が Selected になっている画面

やってみた感想

結論から言うと、かなりいいです！

まず、凜ちゃんがちっちゃくなって作業画面のところにいて、走ったり落ち込んだりするのが、単純にかわいいです。

なんかそれだけで作業環境への愛着がわきますね。

Codex Desktopで凜ちゃんが走っている様子

あと、想像より全然簡単でした。

今回やったことといえば、写真を投げて「凜ちゃんのペットを作ってほしい」とお願いしただけです。ベース画像の生成も、アニメーションの分担も、スプライトシートへの最終化も、ほぼ全部hatch-petとCodexがやってくれました。

Codexなかなかやるな、という感じです笑

それから、これはCodexアプリ内だけの話じゃないんですよね。

Pet素材はローカルファイルとして完成しているので、デスクトップ上に置いたり、ブラウザ上に配置したりもできるみたいです。どこでも凜ちゃんが走ってくれる、というのはなかなかいいなと思いました。

VS Code上でも走ってくれています。

VS Code上で凜ちゃんが走っている様子

AIの直の実用機能というよりは、作業環境に愛着を足す機能です。でも、これはこれでありかなと。

自分のペットや好きなキャラクターを、小さい作業相棒にしてみたい方にはおすすめです。

まとめ

今回は、Codexの hatch-pet Skillを使って、愛猫の凜ちゃんをカスタムPet化してみました。

流れをまとめると、こんな感じです。

  1. skill-installer で hatch-pet を入れる
  2. 参考写真を渡してお願いする
  3. hatch-petがベース画像を作る
  4. サブエージェントで各アニメーション行を生成する
  5. running-left は必要ならミラーで作る
  6. finalize_pet_run.py でスプライトシート化する
  7. package_custom_pet.py で ~/.codex/pets/ に保存する
  8. Appearance → Custom pets で選択する

写真を投げてお願いするだけで、ここまでやってくれるのは割と驚きでした。

参考になれば幸いです。