🐾 Buddy Sprite

零依赖的虚拟宠物伙伴精灵系统，支持 终端、浏览器 和 Node.js 三端通用。

灵感来源于 Claude Code（Anthropic 的智能编程工具）中隐藏的伙伴（"buddy"）系统。原始实现与 React/Ink 和 Bun 运行时紧密耦合。buddy-sprite 将核心逻辑提取并重新实现为一个独立的、零运行时依赖的通用包。

English

    __
  <(· )___
   (  ._>
    `--´
  Quackers ★★★

✨ 特性

• 🎲 确定性生成 — 相同的 userId 永远生成相同的宠物
• 🐣 18 种物种 — 鸭子、猫、龙、幽灵、六角恐龙、机器人等
• 🎨 6 种眼睛样式、8 种帽子 — 皇冠、巫师帽、螺旋桨、光环……
• ⭐ 5 个稀有度等级 — 普通 → 罕见 → 稀有 → 史诗 → 传说
• 📊 5 项属性 — 调试力、耐心、混乱、智慧、毒舌
• ✨ 闪光变体 — 1% 概率获得闪光宠物
• 💬 对话气泡 — 带自动淡出动画
• 🤚 摸头 — 浮动爱心动画
• 😴 待机动画 — 眨眼、小动作、呼吸
• 🖥️ 终端适配器 — ANSI 颜色，基于光标的原地刷新
• 🌐 浏览器适配器 — 基于 DOM 的组件，CSS 过渡动画
• 📦 零运行时依赖 — 纯 TypeScript，打包后约 14KB
• 🔧 ESM + CJS + DTS — 全平台兼容

📦 安装

npm install buddy-sprite

🚀 快速开始

终端

import { roll, assembleCompanion } from 'buddy-sprite'
import { createTerminalBuddy } from 'buddy-sprite/terminal'

const { bones } = roll('user-123')
const companion = assembleCompanion('user-123', {
  name: 'Quackers',
  personality: '一个热爱调试的快乐小伙伴',
  hatchedAt: Date.now(),
})

const buddy = createTerminalBuddy(companion)
buddy.start()
buddy.speak('嘎嘎！你好呀！')
buddy.pet()

// 调用 buddy.destroy() 停止

浏览器

<div id="buddy-container"></div>
<script type="module">
  import { assembleCompanion } from 'buddy-sprite'
  import { createBrowserBuddy } from 'buddy-sprite/browser'

  const companion = assembleCompanion('user-123', {
    name: 'Quackers',
    personality: '快乐',
    hatchedAt: Date.now(),
  })

  const buddy = createBrowserBuddy(
    document.getElementById('buddy-container'),
    companion,
  )
  buddy.start()
  buddy.speak('来自浏览器的问候！')
</script>

自定义渲染器（Node.js / 任意平台）

import { BuddyEngine, assembleCompanion } from 'buddy-sprite'

const companion = assembleCompanion('user-123', {
  name: 'Quackers',
  personality: '快乐',
  hatchedAt: Date.now(),
})

const engine = new BuddyEngine(companion, (frame) => {
  // frame.spriteLines — ASCII 精灵行
  // frame.bubbleLines — 对话气泡文字（或 null）
  // frame.isPetting   — 是否正在显示爱心
  // frame.colorKey    — 稀有度颜色键名，用于自定义颜色映射
  console.clear()
  console.log(frame.spriteLines.join('\n'))
})
engine.start()

🎮 体验演示

# 终端演示
npx tsx examples/terminal-demo.ts

# 浏览器演示（直接打开 HTML 文件）
open examples/browser-demo.html

📐 架构

buddy-sprite/
├── src/
│   ├── index.ts          # 统一导出
│   ├── types.ts          # 类型定义（稀有度、物种、眼睛、帽子、属性）
│   ├── sprites.ts        # 18 种物种的 ASCII 精灵帧数据 + 渲染函数
│   ├── companion.ts      # 宠物生成（PRNG、哈希、稀有度抽取、属性生成）
│   ├── engine.ts         # BuddyEngine — 动画状态机（核心）
│   └── adapters/
│       ├── terminal.ts   # 终端适配器（ANSI 转义码）
│       └── browser.ts    # 浏览器适配器（DOM 渲染）
└── examples/
    ├── terminal-demo.ts  # 终端演示脚本
    └── browser-demo.html # 浏览器演示页面（直接打开，无需构建）

引擎 ↔ 适配器协议

BuddyEngine 在每个 tick 发出 BuddyFrame 对象，适配器消费这些帧进行渲染：

interface BuddyFrame {
  spriteLines: string[]        // ASCII 精灵行
  name: string                 // 宠物名字
  face: string                 // 单行脸部表情（窄模式用）
  bubbleLines: string[] | null // 对话气泡文字
  isBubbleFading: boolean      // 气泡是否正在淡出
  isPetting: boolean           // 是否正在显示爱心
  colorKey: ColorKey           // 稀有度颜色键名
}

🎲 生成系统

宠物由 userId 字符串确定性生成：

1. userId + 盐值 → FNV-1a 哈希 → Mulberry32 PRNG 种子
2. PRNG → 稀有度（加权）、物种、眼睛样式、帽子、闪光、属性
3. 相同的 userId 永远生成相同的宠物

| 稀有度 | 权重 | 帽子 | 属性下限 | | ------ | ---- | ---- | -------- | | 普通 | 60 | ❌ | 5 | | 罕见 | 25 | ✅ | 15 | | 稀有 | 10 | ✅ | 25 | | 史诗 | 4 | ✅ | 35 | | 传说 | 1 | ✅ | 50 |

🙏 致谢

• 灵感来源：Claude Code（Anthropic 出品）中的伙伴（"buddy"）系统
• 原始实现位于 Claude Code 仓库的 src/buddy/ 目录，使用 React + Ink 进行终端渲染
• buddy-sprite 是一个全新的独立实现，零依赖，三端通用

📄 许可证

MIT