Quick Start

# Run instantly without installation
npx pixel-pets-cli

# Summon a pet immediately
npx pixel-pets-cli pull

# Summon 10 pets
npx pixel-pets-cli pull -n 10

# Summon 50 pets with a repeatable seed sequence
npx pixel-pets-cli pull gallery-seed -n 50

# Summon 100 pets with full per-pet reveals
npx pixel-pets-cli pull -n 100

Installation (Optional)

# Global install for faster access
npm install -g pixel-pets-cli

# Then use directly
pixel-pets-cli pull
pixel-pets pull      # Alias
ppets pull           # Short alias

Commands

| Command | Description | |---------|-------------| | pull [seed] | Summon a new pet | | pull -n <count> | Summon multiple pets with full animated reveals | | pull <seed> -n <count> | Run a repeatable multi-summon sequence | | list | Show your pet collection | | show <name> | Display detailed pet card | | animate <name> | Watch pet animation | | stats | Show collection statistics | | rates | Display summon rates | | clear --confirm | Clear all pets | | help | Show help information |

Summon System

Tier Distribution

| Tier | Probability | Base Stats | Sparkle Chance | |------|-------------|------------|----------------| | [B] Bronze | 45% | 10 | 0.5% | | [S] Silver | 30% | 20 | 0.8% | | [G] Gold | 15% | 35 | 1.2% | | [P] Platinum | 7% | 50 | 2.0% | | [D] Diamond | 2.5% | 65 | 3.5% | | [M] Mythic | 0.5% | 80 | 5.0% |

Multi-Summon Flow

  Summoning 10 pets...

  Gallery ready: 10 reveals

  Reveal 01/10
  +----------------------------------------------+
  | Brave Thunder                                |
  | [P] PLATINUM (7.0%)                          |
  +----------------------------------------------+
  |  Species: stormfeather Face: (oo)            |
  |  Expression: o  Accessory: feather           |
  +----------------------------------------------+

  ...

  Summon Summary (10 pets)
  -----------------------------------------------
  [B] bronze     x4
  [S] silver     x3
  [G] gold       x2
  [P] platinum   x1
  -----------------------------------------------

Features

• 16 Original Creatures - Slimeling, Fluffox, Sparkfin, Mossbear, Cloudpup, Crystalwing, Emberclaw, Frostwhisk, Thornback, Glowmoth, Sandscale, Stormfeather, Dewdrop, Ironpaw, Vineheart, Nightshade
• 6 Tier System - Bronze, Silver, Gold, Platinum, Diamond, Mythic
• 3-Frame Animation - Idle, action, and secondary poses with blink support
• Sparkle Variants - Tier-based sparkle chances with animated effects
• 6 Attributes - Vitality, Agility, Spirit, Luck, Charm, Focus
• Probability-First Summons - No tier targeting, every pull stays true to the published odds
• Gallery-Style Multi Pulls - Each pet is revealed with its own staged transition
• TTY-Aware Rendering - Rich animation in terminals and readable fallback output in non-interactive environments
• Local Storage - Your collection persists between sessions

Sprite System (v2.1)

Dimensions

• Height: 5 lines
• Width: 12 characters (rendered, after eye placeholder replacement)
• Frames: 3 per species (idle, action, secondary)
• Eye Placeholder: {E} replaced at render time

Animation Sequence

[Rest] → [Rest] → [Rest] → [Rest] → [Action] → [Rest] → [Rest] → [Rest] → [Blink] → [Rest] → [Rest] → [Secondary] → [Rest] → [Rest] → [Rest]

Expression System

| Glyph | Emotion | |-------|---------| | ^ | Happy | | o | Neutral | | = | Sleepy | | * | Excited | | ~ | Playful | | u | Sad | | w | Cute |

Technical Details

Data Storage

Pets are stored locally at ~/.pixel-pets/collection.json

Algorithms Used

• xorshift128+ - PRNG (public domain)
• djb2 - Hash function (public domain)

Architecture

See docs/SPEC.md for detailed technical specification.

Language

| Language | Link | |----------|------| | English | README.md | | Traditional Chinese | README_zh-TW.md | | Simplified Chinese | README_zh-CN.md | | Japanese | README_ja.md | | Korean | README_ko.md |

License

MIT License - see LICENSE.

Original Work Notice

This is an original, independent project. All code, creature designs, and game mechanics are original creations. See DISCLAIMER.md for details.