gotchi-finder

# Gotchi Finder Skill

Find and display any Aavegotchi by ID with complete traits and image.

## Features

- ✅ **Instant ID lookup** - Fetch any gotchi by ID number
- ✅ Fetch any gotchi by ID from Base mainnet
- ✅ Display full traits (BRS, Kinship, Level, XP, Haunt, Name, Owner)
- ✅ **TOTAL BRS** - Shows base + wearables modifiers (true power level)
- ✅ Generate PNG images (standard 512x512 or hi-res 1024x1024)
- ✅ Export as SVG (scalable vector graphics)
- ✅ Flexible format options (PNG, hi-res, SVG, or all)
- ✅ Support for all gotchi states (Portal, Gotchi, etc.)
- ✅ Automatic image conversion and delivery

## Usage

### Default Behavior (ALWAYS)

**When you run gotchi-finder, it ALWAYS outputs:**

1. **🖼️ Gotchi PNG image** (512×512) - sent as photo/media
2. **📊 Stats as caption** - displayed below the image

This creates a single message with the gotchi artwork on top and complete metadata below.

**Example:**
```bash
bash scripts/find-gotchi.sh 9638
```

**Output:** One Telegram message with:
- Image at top (PNG)
- Caption below with all stats, traits, and info

### Additional Format Options (Optional)

After seeing the default output, users can request additional formats:

```bash
# Hi-res PNG (1024×1024)
bash scripts/find-gotchi.sh 9638 --format hires

# SVG vector
bash scripts/find-gotchi.sh 9638 --format svg

# All formats
bash scripts/find-gotchi.sh 9638 --format all
```

### Format Options

- `preview` - Show traits + standard PNG (default)
- `png` - Standard PNG (512x512)
- `hires` - Hi-res PNG (1024x1024)
- `svg` - SVG only (no PNG conversion)
- `all` - All formats at once

### Examples

**Preview first (conversational flow):**
```bash
# Show gotchi info + preview image
bash scripts/find-gotchi.sh 9638

# Then user picks format
bash scripts/find-gotchi.sh 9638 --format hires
```

**Direct download (skip preview):**
```bash
# Get hi-res immediately
bash scripts/find-gotchi.sh 9638 --format hires

# Get all formats at once
bash scripts/find-gotc...

# Gotchi Finder Skill 👻

Find any Aavegotchi by ID and display with full traits and image.

## Quick Start

```bash
# Install dependencies
npm install

# Show a gotchi (PNG image + stats caption)
bash scripts/show-gotchi.sh 9638
```

**Output:** Single message with gotchi image and complete stats below!

## Features

✅ **Instant ID lookup** - Fetch any gotchi by ID number
✅ Fetch any gotchi from Base mainnet  
✅ Display complete traits (BRS, Kinship, Level, XP, etc.)  
✅ Show all 6 numeric traits (Energy, Aggression, Spookiness, etc.)  
✅ Generate PNG images (standard 512x512 or hi-res 1024x1024)  
✅ Export as SVG (scalable vector graphics)  
✅ Save JSON metadata  
✅ Support portals and all gotchi states  
✅ Flexible format options (PNG, hi-res, SVG, or all)  

## Output

For each gotchi, you can get:

1. **JSON file** - Complete metadata
2. **SVG file** - Original on-chain vector image (always generated)
3. **PNG file** - Standard 512x512 pixel image
4. **PNG file (hi-res)** - High resolution 1024x1024 pixel image

## Usage Examples

### 🎯 Default: Show Gotchi (Recommended)

```bash
bash scripts/show-gotchi.sh 9638
```

**Output:**
- 🖼️ PNG image (512×512) - shown as photo/media
- 📊 Complete stats - displayed as caption below image
- 👻 Single message format (perfect for Telegram/Discord)

**What you get:**
```
[Gotchi PNG Image]

👻 **Gotchi #9638 - aaigotchi**

**📊 Stats:**
⭐ BRS: **534** (MYTHICAL tier)
💜 Kinship: **2,795**
🎮 Level: **11** (XP: 5,890)
👻 Haunt: **1**
💎 Collateral: **WETH**

**🎭 Traits:**
⚡ Energy: **2**
👊 Aggression: **66**
👻 Spookiness: **99**
🧠 Brain Size: **77**

**👔 Wearables:** None equipped

LFGOTCHi! 🦞🚀
```

### Advanced: Custom Formats

If you need different formats, use `find-gotchi.sh`:

**Step 2: User chooses which format to download**
```bash
# If user wants hi-res
bash scripts/find-gotchi.sh 9638 --format hires

# If user wants SVG
bash scripts/find-gotchi.sh 9638 --format svg

# If user wants everything
bas...