# Suikamon - AI/LLM Documentation

> Last Updated: 2026-04-02 | Network: Sui Testnet | Website: https://suikamon.com

## What is Suikamon?

Suikamon is a living NFT pet game on the Sui blockchain. Players adopt, care for, evolve, and battle digital pets that exist as tradeable NFTs. Each pet changes and grows through daily player interaction.

## Core Concepts

- **Living NFT**: Each pet is a Sui blockchain NFT that visually evolves through gameplay
- **Evolution**: Pets evolve through up to 7 stages (0-6) by earning XP from daily care
- **Discovery**: High-level pets can discover new rare eggs (play-to-earn mechanic)
- **PVP Combat**: Turn-based strategic battles between players' Suikamons
- **Scarcity**: Hard-capped supply per species that can never be increased
- **Suika**: In-game currency for actions and time (1000 Suika starting balance)

## How It Works

1. **Adopt** - Choose from limited egg supplies. Each species has a fixed cap
2. **Care** - Feed, clean, and train your pet daily. Build a bond and earn XP
3. **Evolve** - Reach level milestones to trigger permanent on-chain visual evolutions
4. **Discover** - High-level pets can find new rare eggs through gameplay
5. **Battle** - Challenge trainers in strategic PvP combat with skills and elemental advantages

## Species Catalog

### Common (2.99 SUI each, 500 supply cap per species)

| Species | Element | Base HP | Attack Dmg | Magic | Special |
|---------|---------|---------|------------|-------|---------|
| Bireon | Nature | 65 | 11 | Sky Talons (22 dmg) | - |
| Kobu | Nature | 52 | 12 | Savage Bite (19 dmg) | 80% bleed (16 DoT) |
| Pefareon | Nature | 43 | 8 | Blood Drain (20 dmg) | Drainlife (heals 16), Precise Attack |
| Talion | Fire | 65 | 16 | Immolate (15 dmg) | Execute (+20 dmg if target <50% HP), Precise Attack |

### Rare (9.50 SUI each, 100 supply cap per species)

| Species | Element | Base HP | Attack Dmg | Magic | Special |
|---------|---------|---------|------------|-------|---------|
| Aqua | Water | 52 | 14 | Water Lash (15 dmg) | 80% stun |
| Zaricat | Thunder | 60 | 9 | Static Lock (22 dmg) | 100% wound, Precise Attack |
| Hotpaw | Fire | 60 | 13 | Flame Burst (17 dmg) | 100% bleed (8 DoT) |

### Epic (29.99 SUI each, 50 supply cap per species)

| Species | Element | Base HP | Attack Dmg | Magic | Special |
|---------|---------|---------|------------|-------|---------|
| Yeti | Water | 75 | 10 | Snowball (16 dmg) | 70% stun |
| Pinky | Water | 65 | 12 | Healing Touch (21 dmg + 8 heal) | 40% block attack |
| Suimon | Water | 70 | 11 | Suiwave (20 dmg) | Drainlife (heals 17) |

### Legendary

| Species | Element | Price | Base HP | Attack Dmg | Magic | Special |
|---------|---------|-------|---------|------------|-------|---------|
| Voltaryx | Thunder | 99 SUI | 75 | 10 | Thunder Strike (16 dmg) | 70% stun, Precise Attack |
| Toro | Thunder | 199 SUI | 72 | 11 | Wild Charge (17 dmg) | 50% stun |

Supply cap: 10 per Legendary species.

## Game Mechanics

### Stats (0-100 scale)

| Stat | Description | Decay Rate (Adult) | Decay Rate (Baby) |
|------|-------------|--------------------|--------------------|
| Hunger | Food level | -2/tick | -4/tick |
| Happiness | Mood | -0.26/tick | -0.26/tick |
| Energy | Required for training | -2/tick | -4/tick |
| Health | Overall condition | Conditional (neglect) | Conditional (neglect) |
| Cleanliness | Hygiene level | -2/tick | -4/tick |
| Discipline | Training level | -2/tick | -4/tick |

- 1 tick = 5 minutes real time
- Resting reduces decay significantly (20-50% of normal rate)

### Condition Thresholds

| Condition | Trigger | Priority |
|-----------|---------|----------|
| Sick | Health < 25 | Highest |
| Hungry | Hunger < 25 | High |
| Dirty | Cleanliness < 25 | Medium |
| Tired | Energy < 25 | Medium |
| Sad | Happiness < 50 | Low |
| Thriving | All stats >= 25 | Normal |

### Actions & Costs

| Action | Effect | Suika Cost | Notes |
|--------|--------|------------|-------|
| Feed Meal | +30 hunger, +5 happiness, +3 health | 1 | Balanced nutrition |
| Feed Snack | +15 hunger, +10 happiness, -10 health, -10 cleanliness | 1 | Quick boost |
| Clean | Sets cleanliness to 100, +10 happiness, +3 health | 1 | Full bath |
| Train | +30 discipline, +5 happiness, +10 health, XP wheel spin | 2 | Costs 25 energy |
| Medicine | +30 health, -10 happiness | 5 | For sick pets |
| Rest | Reduces decay, +25 energy/tick | 1 | Up to 10 hours |
| Energy Refill | Sets energy to 100 | 5 | 24h cooldown |

### XP & Leveling

- XP per level: 1000 XP (flat rate for all levels)
- XP from feeding (hunger < 50): 30 XP
- XP from feeding (hunger 50-90): 20 XP
- XP from cleaning: 20 XP
- Training XP: Random wheel spin (5-100 XP)
- PVP Trial win: 10 XP
- PVP Ranked win: 20 XP
- Daily streak bonus: +1 XP per streak day on eligible actions
- Low discipline penalty: 50% XP when discipline < 10

### Evolution Stages

Evolution levels depend on species (maxStage 4, 5, or 6):

**4-stage species** (Bireon, Zaricat, Yeti): Evolve at levels 3, 10, 20
**5-stage species** (Hotpaw, Toro, Suimon): Evolve at levels 3, 8, 14, 20
**6-stage species** (Aqua, Kobu, Pinky, Pefareon, Talion, Voltaryx): Evolve at levels 2, 5, 10, 15, 20

Stage 0 = Egg (hatch at any level). Evolution updates the NFT image on-chain permanently.

### Suika Currency System

- Starting balance: 1000 Suika per pet
- Time cost: 0.15 Suika per tick (passive consumption)
- At 0 Suika: Hibernation (stats freeze at 50)
- Replenishment: Buy more Suika with SUI (1 SUI = 1000 Suika base rate)
- Egg donation reward: 100 Suika

### Discovery System

- Unlocks at levels 10, 20, 30, 40...
- Uses Sui blockchain checkpoint hashes for verifiable randomness
- Offspring rarity influenced by parent rarity:
  - Common parent: 90% common, 9% rare, 1% epic
  - Rare parent: 68% common, 20% rare, 10% epic, 2% legendary
  - Epic parent: 60% common, 25% rare, 13% epic, 2% legendary
  - Legendary parent: 50% common, 25% rare, 20% epic, 5% legendary

## PVP Combat System

### Overview

Turn-based combat with a 50-turn limit. Each turn, both players choose an action simultaneously.

### Actions

| Action | Description | Notes |
|--------|-------------|-------|
| Attack | Physical damage | Fatigues if used twice in a row (50% damage) |
| Magic | Elemental damage + special effects | Builds charge (+5 damage next magic use) |
| Recover | Heal HP | Limited uses per battle (2-3 depending on stage) |
| Dodge | Evade attacks + counter (100% damage) | Cannot use twice in a row |

### Resolution (Rock-Paper-Scissors)

| Attacker \ Defender | Attack | Magic | Recover | Dodge |
|---------------------|--------|-------|---------|-------|
| **Attack** | Both take damage | Attacker hits | Attacker hits, defender heals | Attacker misses, gets countered |
| **Magic** | Magic hits | Both hit (higher wins) | Magic hits, defender heals | Half damage, 50% special |
| **Recover** | Takes damage, heals | Takes damage, heals | Both heal | Both recover |
| **Dodge** | Counter attack (100% dmg) | Half damage, 50% special | Dodge wastes, defender heals | Both miss |

### Special Mechanics

- **Precise Attack**: 50% chance to hit through dodge (Zaricat, Pefareon, Talion, Yeti, Voltaryx)
- **Stun**: Target skips next turn (Aqua 80%, Yeti 70%, Voltaryx 70%, Toro 50%)
- **Wound**: Next heal is halved (Zaricat 100%, Yeti via Recover vs Attack)
- **Bleed/DoT**: Damage over time next turn (Hotpaw 8 dmg, Kobu 16 dmg at 80%)
- **Execute**: Bonus damage when target below 50% HP (Talion +20 dmg)
- **Drainlife**: Heals self next turn (Pefareon 16 HP, Suimon 17 HP)
- **Block Attack**: Chance to nullify opponent's next attack (Pinky 40%)
- **Element Advantage**: +2 magic damage (Fire > Nature > Thunder > Water > Fire)
- **HP Scaling**: Base HP + ((Level - 1) x 2)

### Battle Modes

| Mode | Description | Reward | Cost |
|------|-------------|--------|------|
| Challenge | 4 preset stage-2 fighters | 75% adoption discount | Free |
| Trial | Train your pets vs AI | 10 XP per win | 1 Suika |
| Ranked | Competitive PVP | 20 XP per win, trophies | 2 Suika |

## Supply Limits

Per-species supply caps (adoption + discovery combined):

| Species | Rarity | Total Cap | Adoption Price |
|---------|--------|-----------|----------------|
| Bireon | Common | 500 | 2.99 SUI |
| Kobu | Common | 500 | 2.99 SUI |
| Pefareon | Common | 500 | 1.50 SUI (50% off) |
| Talion | Common | 500 | 2.99 SUI |
| Aqua | Rare | 100 | 9.50 SUI |
| Zaricat | Rare | 100 | 9.50 SUI |
| Hotpaw | Rare | 100 | 9.50 SUI |
| Yeti | Epic | 50 | 29.99 SUI |
| Pinky | Epic | 50 | 27.00 SUI (10% off) |
| Suimon | Epic | 50 | 29.99 SUI |
| Voltaryx | Legendary | 10 | 99.00 SUI |
| Toro | Legendary | 10 | 199.00 SUI |

## Discount System

- **PVP Challenge Discount**: Win 4 Challenge battles to earn 75% off (Common/Rare only, 24h validity)
- **Referral Discount**: 10% off first adoption via partner referral link (?ref=0x...)
- **Species Discounts**: Some species have promotional pricing (shown on Adopt page)
- High discounts (>=75%) limited to Common rarity
- Discounts cannot be combined

## Architecture

### On-Chain (Sui Blockchain)

- Pet NFT ownership (tradeable on marketplaces)
- Visual evolution (stage, level, image_url stored in NFT)
- Evolution tokens (one-time use authorization for upgrades)
- Mint numbers and rarity tracking
- Smart Contract: `suikamon_nft::pet`

### Off-Chain (Supabase PostgreSQL)

- All game stats (hunger, happiness, energy, health, cleanliness, discipline)
- Game mechanics (tick decay, action effects, XP calculations)
- Gameplay state (resting, timestamps, cooldowns, Suika balance)
- PVP battle history and rankings

### Tech Stack

- Frontend: React 18, TypeScript, Vite, Radix UI
- Backend: Node.js, TypeScript, Express
- Database: PostgreSQL (Supabase)
- Blockchain: Sui (Move language)
- Wallet: @mysten/dapp-kit

## URLs & Routes

| Route | Description |
|-------|-------------|
| `/` | Homepage |
| `/adopt` | Adopt new pets (also `/mint` redirects here) |
| `/play` | My Pets dashboard (requires wallet) |
| `/rankings` | Suikamon leaderboard |
| `/trainers` | Trainer leaderboard |
| `/battle` | PVP battle arena |
| `/pvp-lab` | Challenge mode |
| `/pvp-trial` | Trial mode |
| `/pvp-ranked` | Ranked mode |
| `/whitepaper` | Full documentation |
| `/help` | Human-readable help page |
| `/llms.txt` | This page (machine-readable docs) |
| `/{species-name}` | Species detail page (e.g., `/aqua`, `/bireon`) |

## API Endpoints

| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/api/pets/adopt` | Mint new pet |
| POST | `/api/pets/:petId/feed` | Feed action |
| POST | `/api/pets/:petId/clean` | Clean action |
| POST | `/api/pets/:petId/train` | Train action |
| POST | `/api/pets/:petId/medicine` | Medicine action |
| POST | `/api/pets/:petId/rest` | Start rest |
| POST | `/api/pets/:petId/wake` | Stop rest |
| POST | `/api/pets/:petId/refill-energy` | Energy refill |
| POST | `/api/evolution/request-token` | Request evolution token |
| GET | `/api/pets/user/:walletAddress` | Get user's pets |
| GET | `/api/pets/:petId` | Get pet details |
| GET | `/api/species/supply` | Get supply status |

## Social Links

- Twitter: https://x.com/suikamongame
- Discord: https://discord.gg/W9ZBTpue7t
- Telegram: https://t.me/suikamongame
- Marketplace: https://www.tradeport.xyz/sui/collection/suikamon

## Training Wheel Outcomes

When training, a wheel spin determines XP reward:

| Outcome | XP | Segments | Chance |
|---------|-----|----------|--------|
| Small | 5 | 3 | 25% |
| Medium | 10 | 2 | 16.7% |
| Large | 15 | 2 | 16.7% |
| Great | 25 | 1 | 8.3% |
| Jackpot | 50 | 1 | 8.3% |
| Prize | 100 + stats boost | 1 | 8.3% |
| Sick | -60 health/happiness | 1 | 8.3% |
| Nothing | 0 | 1 | 8.3% |

---

For human-readable help: https://suikamon.com/help