PawPaths

一个基于 React + Gemini AI + PeerJS 的治愈系联机宠物放置小游戏。

项目亮点

• AI 驱动事件：利用 Google Gemini API 生成个性化的宠物互动和随机事件
• 去中心化联机：基于 PeerJS 实现 P2P 联机，支持公共广场（多重宇宙分片）和私密房间
• 强制睡眠机制：深度的放置玩法，宠物需要合理的作息管理
• 多端适配：响应式设计，完美适配移动端和桌面浏览器
• 动态环境：支持昼夜变化和天气系统

技术栈

• 前端: React 19, TypeScript, Tailwind CSS
• 构建: Vite 5
• AI: Google Generative AI (Gemini 3 Flash Preview)
• 网络: PeerJS (WebRTC), BroadcastChannel API
• 测试: Vitest, Testing Library
• 图标: Lucide React

快速开始

# 1. 克隆项目
git clone https://github.com/your-username/pawpaths.git
cd pawpaths

# 2. 安装依赖
npm install

# 3. 配置环境变量
# 前往 https://aistudio.google.com/ 获取免费的 Gemini API Key
# 创建 .env 文件并添加：
echo "API_KEY=your_gemini_api_key" > .env

# 4. 启动开发服务器
npm run dev

项目结构

pawpaths/
├── components/          # React 组件
│   ├── GameControls.tsx    # 游戏控制面板
│   ├── GameHeader.tsx      # 顶部状态栏
│   ├── PeerLayer.tsx       # P2P 联机层
│   ├── PetAvatar.tsx       # 宠物头像
│   ├── ShopModal.tsx       # 商店弹窗
│   └── WorldBackground.tsx # 世界背景
├── config/              # 配置文件
│   └── settings.ts         # 游戏设置常量
├── hooks/               # 自定义 Hooks
│   └── useEnvironment.ts   # 环境状态管理
├── services/            # 服务层
│   ├── geminiService.ts    # AI 服务
│   └── storageService.ts   # 本地存储
├── tests/               # 测试文件
├── config_pets_*.js     # 宠物配置数据
├── petData.tsx          # 宠物数据聚合
├── types.ts             # TypeScript 类型定义
└── index.tsx            # 应用入口

可用脚本

npm run dev        # 启动开发服务器
npm run build      # 构建生产版本
npm run preview    # 预览生产构建
npm run test       # 运行测试 (watch 模式)
npm run test:run   # 运行测试 (单次)
npm run test:coverage  # 运行测试并生成覆盖率报告

如何贡献

添加新宠物

1. 在 config_pets_standard.js 或 config_pets_exotic.js 中定义宠物属性
2. 在 petData.tsx 的 ICON_MAP 中关联 Lucide 图标
3. 如需添加新的 PetType，同时更新 types.ts
4. 提交 Pull Request

开发指南

• 遵循现有的代码风格和目录结构
• 新功能请添加对应的测试用例
• 提交前确保 npm run test:run 通过

许可协议

本项目采用 MIT License 协议开源。