펫 / 사용 가이드

시트 한 장.
9가지 상태, 설정 제로.

모든 펫은 스프라이트 시트 한 장만 제공합니다: Codex 데스크톱 앱에는 그대로 넣고, 어떤 엔진에서도 깔끔하게 분할됩니다 — 애니메이션 상태마다 한 행, 행마다 8칸.

Codex에 설치하기

Codex(OpenAI의 코딩 에이전트 앱)는 에이전트의 작업 상태를 반영하는 펫 오버레이를 보여줍니다. 이 펫들은 추가 설정 없이 바로 연동됩니다:

1.아무 펫 페이지에서 "Codex에 설치" zip을 다운로드하고 압축을 풉니다.
2.pet.json과 spritesheet.webp를 ~/.codex/pets/<이름>/ 폴더에 복사합니다(폴더가 없으면 생성).
3.Codex를 재시작하고 설정 → 모양 → 펫에서 해당 펫을 선택합니다.
4.아무 스레드에서 /pet을 실행해 깨우세요 — 다른 앱을 쓰는 동안에도 플로팅 오버레이로 계속 함께합니다.

~/.codex/pets/shibe/
├── pet.json            { id, displayName, description,
│                         spritesheetPath: "spritesheet.webp" }
└── spritesheet.webp    1536 × 1872 · 8 × 9 · 192 × 208 per cell

9가지 상태는 Codex 앱 계약과 정확히 일치합니다(idle, running, running-left, running-right, jumping, waving, failed, waiting, review). 내장 펫과 동일한 방식으로 동작합니다.

시트 구조

각 시트는 1536×1872 px입니다: 8열 × 9행, 각 셀은 192×208 px의 투명 배경 프레임입니다. 0행은 항상 각 펫 페이지 상태 목록의 첫 번째 상태에 해당하며, 프레임은 왼쪽에서 오른쪽으로 읽습니다. 어떤 상태가 8프레임 미만이면 그 행의 남은 셀은 비어 있습니다 — 펫 페이지에 표시된 프레임 수만큼만 루프시키세요.

sheet.webp  1536 × 1872
┌──────── 8 columns ────────┐
│ f0  f1  f2  f3  f4  …  f7 │ ← row 0 · idle
│ f0  f1  f2  f3  ·   ·   · │ ← row 1 · next state
│ …                         │
└──────── 9 rows ───────────┘  192 × 208 per cell

번들 zip에는 README.txt도 포함되어 각 상태의 정확한 행 번호와 프레임 수를 안내합니다 — 추측할 필요가 없습니다.

애니메이션 상태

433마리 펫 모두 동일한 9가지 상태를 공유하므로 스프라이트만 교체하면 상태 머신은 손대지 않아도 됩니다.

idle

기본 대기 루프. 펫이 플레이어 옆에 가만히 있을 때 사용합니다.

running

앞으로 이동. 플레이어 추종용 측면 달리기 사이클.

running-left

명시적인 왼쪽 달리기. 프레임을 미러링하지 않는 엔진용.

running-right

명시적인 오른쪽 달리기. 프레임을 미러링하지 않는 엔진용.

jumping

공중 포즈 루프. 펫이 점프 중이거나 낙하 중일 때 재생합니다.

waving

인사 이모트. 등장, 레벨업, 상호작용 시 트리거하세요.

failed

부정적 반응 — 빗나감, 충돌, 액션 실패.

waiting

긴 대기 변형. 일정 시간 입력이 없으면 이 상태로 전환하세요.

review

QA에서 사용하는 쇼케이스 루프. 대체 대기 상태으로도 사용 가능.

엔진 설정

Godot 4

시트를 임포트하고 영역 (col×192, row×208, 192, 208)으로 AtlasTexture 프레임을 만든 뒤 상태별 AnimatedSprite2D에 넣습니다.

var frames := SpriteFrames.new()
for col in range(FRAME_COUNT[idle]):
    var tex := AtlasTexture.new()
    tex.atlas = sheet
    tex.region = Rect2(col * 192, ROW[idle] * 208, 192, 208)
    frames.add_frame("idle", tex)

Unity

Project 창에서 텍스처를 선택하고 Sprite Mode를 Multiple로 설정한 뒤, Sprite Editor에서 Grid By Cell Size를 선택하고 192 × 208을 입력합니다. 각 행이 하나의 애니메이션 클립이 됩니다.

Phaser 3

// rows differ per state — see the pet page for row indices
this.anims.create({
  key: "idle",
  frames: this.anims.generateFrameNumbers("pet-sheet", {
    start: ROW.idle * 8, end: ROW.idle * 8 + FRAMES.idle - 1,
  }),
  frameRate: 10, repeat: -1,
});

순수 CSS

루프 미리보기만 필요하다면 상태마다 GIF 한 장이면 됩니다:

<img src="https://r2.favori.dev/codexpet/pets/black-kitty/gif/idle.gif"
     alt="Black Kitty idling" width="192" height="208" />

알아두면 좋은 점

프레임은 192×208로 그려져 있습니다 — 정수배로 축소(96×104, 48×52)하고 최근접 이웃 필터링을 사용하면 픽셀이 또렷하게 유지됩니다.
running-left / running-right는 미러링이 아닌 실제 사이클입니다 — 이동 방향에 맞는 쪽을 쓰거나, 한쪽을 뒤집어 메모리를 아낄 수 있습니다.
웹 프로젝트에서는 WEBP 시트를 권장합니다(다운로드 용량이 작음). WEBP를 디코딩할 수 없는 환경에서는 PNG를 쓰세요.
모든 번들의 README.txt에 행 번호와 프레임 수가 적혀 있습니다 — 펫 페이지에 표시되는 숫자와 동일합니다.

펫 둘러보기 라이선스 읽기