Skip to content

CHELSEADOPAMIN/CodexPetss

BranchesTags

Repository files navigation

CodexPet English Guide

This section is written for non-technical users.

CodexPet is a small pixel-style character for Codex. It is based on a business-suit character design and can appear inside Codex as a personal pet.

CodexPet preview

What To Send To Someone

If someone only wants to install the pet, they only need these two files:

pet.json
spritesheet.webp

In this project, those files are here:

pets/codexpet/pet.json
pets/codexpet/spritesheet.webp

They do not need the plugin folder, demo page, source images, or any developer files.

Reusable Pet Generator Agent

This repo also includes a reusable Codex skill/agent:

skills/codexpet-generator/

It captures the method used to make this pet. In future, you can send Codex a character image or sprite sheet and ask:

Use codexpet-generator to turn this character into a Codex pet.

If you only have a normal photo of a person, you can also ask:

Use codexpet-generator to generate an 8-bit platformer sprite sheet for this person, then turn it into a Codex pet.

The agent is designed to produce:

  • an 8-bit platformer sprite sheet from a single photo when needed
  • transparent pose PNGs
  • pet.json
  • spritesheet.webp
  • a preview/contact sheet
  • a small install package that only needs the two runtime files

I have also installed it locally at:

~/.codex/skills/codexpet-generator/

So on this computer, future Codex sessions can reuse the same workflow directly.

Photo Upload Web App

This repo now includes a local web app for friends or students:

web/petforge/

It lets someone upload a photo, generate an 8-bit platformer sprite sheet, and download a Codex pet install zip.

To run it:

cd web/petforge
cp .env.example .env

Open .env and add an OpenAI API key:

OPENAI_API_KEY=sk-your-key-here
IMAGE_MODEL=gpt-image-2
PETFORGE_DAILY_LIMIT=5
PETFORGE_JOBS_DIR=

Then start the app:

npm run dev

Open:

http://localhost:4177

For real photo-to-pet generation, the server needs OPENAI_API_KEY. If you intentionally want to test the interface with the bundled sample character, start with:

PETFORGE_DEMO_ONLY=1 npm run dev

Demo mode always uses the original sample CodexPet character. It does not use the uploaded photo.

By default, each client IP can generate up to 5 pets per day. Change PETFORGE_DAILY_LIMIT if you need a different daily cap. Generated files are written to the system temp directory by default, which keeps hosted deployments from trying to write into the read-only app bundle. Set PETFORGE_JOBS_DIR only if your host provides another writable directory.

Deploy To Vercel

Deploy web/petforge as the Vercel project root directory. Set these environment variables in Vercel:

OPENAI_API_KEY=sk-your-key-here
IMAGE_MODEL=gpt-image-2
PETFORGE_DAILY_LIMIT=5

PETFORGE_JOBS_DIR can stay empty on Vercel. The app writes runtime files to /tmp. Files in /tmp are temporary, so generated download links are intended for immediate use. Use object storage such as Vercel Blob if you need persistent historical downloads.

Simple Installation On Mac

  1. Create a new folder called:
codexpet
  1. Put these two files inside that folder:
pet.json
spritesheet.webp

  1. Open Finder.

  2. Open your home folder. On a Mac, it usually looks like this:

/Users/your-name/
  1. Find or create this folder:
.codex/pets/

If you cannot see .codex, press Command + Shift + . in Finder to show hidden folders.

  1. Put the whole codexpet folder inside .codex/pets/.

The final result should look exactly like this:

.codex/
  pets/
    codexpet/
      pet.json
      spritesheet.webp

  1. Restart Codex.

  2. If your Codex version supports custom pets, you should be able to choose:

CodexPet

What The Pet Does

Codex chooses different animations depending on what is happening in the app. You do not need to control these manually.

Situation in Codex What CodexPet does
Codex is idle Stands calmly and waits
Codex is working or moving through a task Runs
Codex is greeting or acknowledging something Waves
Codex is thinking or waiting Looks thoughtful
Codex is jumping into action Jumps
Codex needs attention or has a failed state Uses a lower/crouched pose
Codex is pointing something out Points forward
Codex finishes something successfully Celebrates

Visual Examples

Idle Wave Run Thinking Celebrate
Idle Wave Run Thinking Celebrate

Common Mistakes

If the pet does not appear in Codex, check these things:

  1. The folder name should be codexpet.
  2. The folder must be inside .codex/pets/.
  3. The files must be named exactly pet.json and spritesheet.webp.
  4. There should not be an extra folder inside another folder.

Wrong:

.codex/pets/codexpet/codexpet/pet.json

Correct:

.codex/pets/codexpet/pet.json

After fixing the files, restart Codex.

CodexPet 中文安装说明

CodexPet 是一个基于像素商务人物生成的 Codex 自定义 pet。这个仓库同时包含：

  • Codex 自定义 pet 运行文件
  • CodexPet 插件资源包
  • 单独 PNG 动作素材
  • HTML 预览 demo

发送给朋友的文件

如果朋友只是想把这个形象导入 Codex 当 pet，只需要发下面两个文件：

pets/codexpet/pet.json
pets/codexpet/spritesheet.webp

这两个文件必须放在同一个文件夹里，文件夹名建议就叫：

codexpet

最终朋友电脑上的结构应该是：

~/.codex/pets/codexpet/pet.json
~/.codex/pets/codexpet/spritesheet.webp

也就是说：安装 pet 本身不需要 plugins/、.agents/、assets/、examples/、README.md 或其他文件。

如果你想把完整素材包、插件说明和 demo 一起发给朋友，再发送这个压缩包：

dist/codexpet-plugin.zip

这个完整压缩包里包含：

plugins/codexpet/
.agents/plugins/marketplace.json
pets/codexpet/

可复用 Pet 生成 Agent

这个仓库里也放了一个可复用的 Codex skill/agent：

skills/codexpet-generator/

它把这次做 pet 的方法固定成流程。以后你只要给 Codex 一张角色图、头像图或 sprite sheet，然后说：

Use codexpet-generator to turn this character into a Codex pet.

如果你只有一张真人照片，也可以说：

Use codexpet-generator to generate an 8-bit platformer sprite sheet for this person, then turn it into a Codex pet.

它会按这套流程生成：

  • 从单张照片生成 8-bit platformer sprite sheet
  • 透明动作 PNG
  • pet.json
  • spritesheet.webp
  • 预览图/contact sheet
  • 只包含两个核心运行文件的小安装包

我也已经把它安装到本机：

~/.codex/skills/codexpet-generator/

所以以后你在这台电脑上发素材给 Codex，就可以直接复用这个生成流程。

照片上传网页

这个仓库现在也包含一个本地网页应用：

web/petforge/

它可以让别人上传照片，生成 8-bit platformer sprite sheet，然后下载 Codex pet 安装包。

启动方式：

cd web/petforge
cp .env.example .env

打开 .env，填入 OpenAI API key：

OPENAI_API_KEY=sk-your-key-here
IMAGE_MODEL=gpt-image-2
PETFORGE_DAILY_LIMIT=5
PETFORGE_JOBS_DIR=

然后启动：

npm run dev

打开：

http://localhost:4177

真正从照片生成 pet 时，服务器必须有 OPENAI_API_KEY。如果你只是想测试网页界面，可以手动启动 demo 模式：

PETFORGE_DEMO_ONLY=1 npm run dev

demo 模式永远使用原来的 CodexPet 示例角色，不会使用你上传的新照片。

默认情况下，同一个客户端 IP 每天最多生成 5 次。如果想改每日上限，可以调整 PETFORGE_DAILY_LIMIT。 生成文件默认写入系统临时目录，避免部署环境尝试写入只读的应用目录。只有当部署平台提供其他可写目录时，才需要设置 PETFORGE_JOBS_DIR。

部署到 Vercel

在 Vercel 里把项目根目录设置成 web/petforge。然后在 Vercel 的环境变量里设置：

OPENAI_API_KEY=sk-your-key-here
IMAGE_MODEL=gpt-image-2
PETFORGE_DAILY_LIMIT=5

PETFORGE_JOBS_DIR 在 Vercel 上可以留空，应用会把运行时文件写入 /tmp。 /tmp 里的文件是临时文件，所以生成后的下载链接适合马上下载。如果需要长期保存历史生成结果，需要接入 Vercel Blob 或其他对象存储。

安装方式一：只安装成 Codex Pet

适合只想把 CodexPet 作为 Codex 里的 pet 使用。

  1. 新建一个文件夹，命名为：
codexpet
  1. 把这两个文件放进去：
pet.json
spritesheet.webp

如果你收到的是完整压缩包 codexpet-plugin.zip，就先解压，然后找到：

pets/codexpet/

这个目录里也只有 pet 安装真正需要的两个文件。

  1. 打开自己的用户目录。

macOS 通常是：

/Users/你的用户名/
  1. 找到或创建这个目录：
~/.codex/pets/

如果没有 .codex 或 pets 文件夹，就手动创建。

  1. 把 codexpet 整个文件夹复制进去。

最终文件结构必须是：

~/.codex/pets/codexpet/pet.json
~/.codex/pets/codexpet/spritesheet.webp

不要变成下面这种多套了一层的结构：

~/.codex/pets/codexpet/codexpet/pet.json

这是错误的。

  1. 重启 Codex。

  2. 如果当前 Codex 版本支持自定义 pet，就可以在 pet 选择里看到：

CodexPet

两个文件安装版示例

朋友安装完后，codexpet 文件夹里应该只有这两个核心文件：

codexpet/
  pet.json
  spritesheet.webp

安装方式二：同时安装插件资源包

适合想让 Codex 也能识别这个素材包、技能说明和 demo 的朋友。

  1. 解压 codexpet-plugin.zip。

  2. 复制插件目录。

从解压目录里找到：

plugins/codexpet/

复制到：

~/plugins/codexpet/

最终结构：

~/plugins/codexpet/.codex-plugin/plugin.json
~/plugins/codexpet/assets/
~/plugins/codexpet/skills/
~/plugins/codexpet/README.md
  1. 配置本地插件 marketplace。

打开或创建：

~/.agents/plugins/marketplace.json

如果文件不存在，可以写入：

{
  "name": "local-user-plugins",
  "interface": {
    "displayName": "Local User Plugins"
  },
  "plugins": [
    {
      "name": "codexpet",
      "source": {
        "source": "local",
        "path": "./plugins/codexpet"
      },
      "policy": {
        "installation": "AVAILABLE",
        "authentication": "ON_INSTALL"
      },
      "category": "Productivity"
    }
  ]
}

如果这个文件已经存在，就只需要把下面这段加入 plugins 数组：

{
  "name": "codexpet",
  "source": {
    "source": "local",
    "path": "./plugins/codexpet"
  },
  "policy": {
    "installation": "AVAILABLE",
    "authentication": "ON_INSTALL"
  },
  "category": "Productivity"
}
  1. 同时安装 pet 文件。

把解压出来的：

pets/codexpet/

复制到：

~/.codex/pets/codexpet/
  1. 重启 Codex。

快速检查

安装完成后，检查这两个文件是否存在：

~/.codex/pets/codexpet/pet.json
~/.codex/pets/codexpet/spritesheet.webp

pet.json 内容应该类似：

{
  "id": "codexpet",
  "displayName": "CodexPet",
  "description": "Your personal pixel companion generated from your suited character.",
  "spritesheetPath": "spritesheet.webp"
}

常见问题

如果 Codex 里没显示：

  1. 确认路径没有多套一层 codexpet。
  2. 确认已经重启 Codex。
  3. 确认当前 Codex 版本支持自定义 pet。
  4. 确认文件名是 pet.json 和 spritesheet.webp。
  5. 确认 pet.json 里的 "spritesheetPath": "spritesheet.webp" 和实际文件名一致。

本地预览

项目里也有一个 HTML 预览页：

examples/codexpet-demo.html

插件包内的预览页是：

plugins/codexpet/examples/index.html

直接用浏览器打开即可查看和切换 CodexPet 的动作状态。

About

codexpet-character.vercel.app/

Resources

Readme
Activity

Stars

5 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages