# ts 挨饿

**Repository Path**: byref/aie

## Basic Information

- **Project Name**: ts 挨饿
- **Description**: ts aie
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-03
- **Last Updated**: 2026-03-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AIE - TypeScript生存冒险游戏引擎

<div align="center">

![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-3178C6?style=for-the-badge&logo=typescript&logoColor=white)
![Node.js](https://img.shields.io/badge/Node.js-18+-339933?style=for-the-badge&logo=nodedotjs&logoColor=white)
![Jest](https://img.shields.io/badge/Jest-30.2-C21325?style=for-the-badge&logo=jest&logoColor=white)
![License](https://img.shields.io/badge/License-ISC-blue?style=for-the-badge)

一个轻量级、模块化的TypeScript生存冒险游戏引擎，采用面向对象设计，包含完整的角色、属性、背包和物品系统。

</div>

## 📖 项目概述

**AIE**（Adventure in TypeScript Engine）是一个纯TypeScript实现的生存冒险游戏引擎原型。项目采用现代化的TypeScript特性，遵循面向对象设计原则，实现了完整的游戏核心系统，包括角色移动、属性管理、背包系统和物品数据库。

### 🎯 核心设计理念
- **类型安全**：充分利用TypeScript静态类型检查，提供编译时错误检测
- **模块化架构**：每个功能模块独立封装，职责单一，易于扩展和维护
- **面向对象设计**：使用类和接口定义游戏实体，遵循SOLID原则
- **事件驱动**：内置自定义事件系统，支持游戏状态变更通知
- **测试驱动**：完整的Jest测试套件，确保代码质量和稳定性

## ✨ 功能特性

### 🎮 游戏系统
- **8方向移动系统**：支持上、下、左、右及四个对角线方向移动
- **属性管理系统**：体力、健康、饥饿、口渴四个核心生存属性
- **背包容量管理**：可配置的物品存储容量，支持添加、移除、查询操作
- **物品数据库**：预定义的游戏物品系统，支持食物、陷阱等分类
- **事件监听系统**：自定义事件机制，支持移动、属性变化等游戏事件

### 🛠 技术特性
- **纯TypeScript实现**：无需构建系统，可直接使用`ts-node`运行
- **完整类型定义**：所有API都有明确的类型注解和JSDoc文档
- **自动化测试**：配置Jest测试框架，支持测试监控和覆盖率报告
- **代码规范**：统一的中英文混合注释风格，遵循项目开发指南
- **模块化设计**：每个文件专注单一职责，易于理解和维护

## 🏗️ 技术栈

| 技术 | 版本 | 用途 |
|------|------|------|
| **TypeScript** | 5.0+ | 核心编程语言 |
| **Node.js** | 18+ | 运行环境 |
| **Jest** | 30.2 | 单元测试框架 |
| **ts-jest** | 29.4 | TypeScript测试支持 |
| **npm** | - | 包管理 |

## 📁 项目结构

```
aie/
├── 📄 user.ts                     # 用户核心类（主角）
├── 📄 user_property.ts            # 用户属性系统
├── 📄 backpack.ts                 # 背包管理系统
├── 📄 item.ts                     # 物品定义和数据库
├── 📄 weapon.ts                   # 武器接口定义
├── 📄 user.test.ts                # Jest单元测试文件
├── 📄 user_test.ts                # 手动测试文件
├── 📄 AGENTS.md                   # 项目开发指南和代码规范
├── 📄 package.json                # npm依赖配置
├── 📄 jest.config.js              # Jest测试配置
├── 📄 .gitignore                  # Git忽略配置
└── 📄 README.md                   # 项目说明文档
```

### 核心模块说明

| 模块 | 文件 | 职责 |
|------|------|------|
| **用户系统** | `user.ts` | 游戏主角，负责移动、物品操作、事件管理 |
| **属性系统** | `user_property.ts` | 管理体力、健康、饥饿、口渴等生存属性 |
| **背包系统** | `backpack.ts` | 物品存储容器，提供添加、移除、查询功能 |
| **物品系统** | `item.ts` | 物品定义、分类和数据库管理 |
| **武器系统** | `weapon.ts` | 武器接口定义（待实现） |

## 🚀 安装与运行

### 环境要求
- **Node.js**: 18.x 或更高版本
- **npm**: 9.x 或更高版本
- **TypeScript**: 5.0+（通过`ts-node`运行，无需全局安装）

### 安装步骤
```bash
# 克隆项目
git clone <repository-url>
cd aie

# 安装依赖
npm install
```

### 运行项目
```bash
# 运行所有测试
npm test

# 监控模式运行测试（文件变更时自动重新测试）
npm run test:watch

# 生成测试覆盖率报告
npm run test:coverage

# 直接运行TypeScript文件（示例）
npx ts-node user_test.ts

# 编译TypeScript（如果配置了tsconfig.json）
tsc
```

## 🎮 快速开始

### 1. 创建游戏角色
```typescript
import { User, createUser } from './user'
import { Power, Health, Thirsty, Hungry } from './user_property'

// 创建属性实例
const properties = {
    power: new Power(100),
    health: new Health(100),
    thirsty: new Thirsty(100),
    hungry: new Hungry(100)
}

// 创建用户实例
const player = createUser(
    'player_001',
    'adventurer',
    '勇敢的冒险者',
    properties
)

// 或者直接使用构造函数
const player2 = new User(
    'player_002',
    'explorer',
    '探索者',
    properties
)
```

### 2. 移动和事件监听
```typescript
import { Direction } from './user'

// 添加移动事件监听
player.addEventListener('move', (position: [number, number]) => {
    console.log(`角色移动到位置: [${position[0]}, ${position[1]}]`)
})

// 添加体力不足事件监听
player.addEventListener('no_power', (power: any) => {
    console.log(`体力不足! 当前体力值: ${power.value}`)
})

// 移动角色（向上移动2个单位）
const newPosition = player.move(Direction.Up, 2)
console.log(`新位置: [${newPosition[0]}, ${newPosition[1]}]`)
```

### 3. 物品操作
```typescript
import { createItem } from './item'

// 抓取物品
const success = player.grab('apple', 3)  // 抓取3个苹果
if (success) {
    console.log('成功抓取苹果')
}

// 丢弃物品
const dropped = player.drop('apple', 1)  // 丢弃1个苹果
if (dropped) {
    console.log('成功丢弃苹果')
}

// 创建物品实例
const apple = createItem('apple')
if (apple) {
    console.log(`物品: ${apple.name}, 类别: ${apple.category}`)
}
```

### 4. 背包管理
```typescript
const backpack = player.backpack

// 检查背包状态
console.log(`背包总物品数: ${backpack.totalCount}`)
console.log(`剩余槽位: ${backpack.remainingSlots}`)
console.log(`背包是否已满: ${backpack.isFull}`)

// 获取物品数量
const appleCount = backpack.getItemCount('apple')
console.log(`苹果数量: ${appleCount}`)

// 获取所有物品
const allItems = backpack.getAllItems()
allItems.forEach(({ item, count }) => {
    console.log(`${item.name}: ${count}个`)
})
```

## 📚 API文档

### 用户类 (User)

#### 构造函数
```typescript
constructor(
    id: string,
    username: string,
    nickname: string,
    properties: UserProperties,
    _backpack?: Backpack,
    _position?: [number, number]
)
```

#### 主要方法
| 方法 | 参数 | 返回值 | 说明 |
|------|------|--------|------|
| `move(dir, distance)` | `dir: Direction`, `distance: number` | `[number, number]` | 向指定方向移动指定距离 |
| `grab(itemId, count)` | `itemId: string`, `count?: number` | `boolean` | 抓取指定数量的物品 |
| `drop(itemId, count)` | `itemId: string`, `count?: number` | `boolean` | 丢弃指定数量的物品 |
| `addEventListener(eventName, callback)` | `eventName: string`, `callback: Function` | `void` | 添加事件监听器 |
| `get position()` | - | `[number, number]` | 获取当前位置（getter） |
| `set position(pos)` | `pos: [number, number]` | `void` | 设置位置（setter） |
| `get backpack()` | - | `Backpack` | 获取背包实例（getter） |

#### 方向枚举 (Direction)
```typescript
enum Direction {
    Up = 1,        // 上
    Down = 2,      // 下
    Left = 3,      // 左
    Right = 4,     // 右
    Up_Left = 5,   // 左上
    Up_Right = 6,  // 右上
    Down_Left = 7, // 左下
    Down_Right = 8 // 右下
}
```

### 属性系统 (UserProperty)

#### 基础接口
```typescript
interface UserProperty {
    name: string
    value: number
    consume(amount: number): void  // 消耗属性值
    restore(amount: number): void  // 恢复属性值
}
```

#### 具体属性类
- `Power`: 体力属性
- `Health`: 健康属性
- `Thirsty`: 口渴属性
- `Hungry`: 饥饿属性

### 背包系统 (Backpack)

#### 主要方法
| 方法 | 参数 | 返回值 | 说明 |
|------|------|--------|------|
| `addItem(itemId, count)` | `itemId: string`, `count?: number` | `boolean` | 添加物品到背包 |
| `removeItem(itemId, count)` | `itemId: string`, `count?: number` | `boolean` | 从背包移除物品 |
| `getItemCount(itemId)` | `itemId: string` | `number` | 获取指定物品数量 |
| `hasItem(itemId)` | `itemId: string` | `boolean` | 检查是否拥有指定物品 |
| `getAllItems()` | - | `Array<{item: Item, count: number}>` | 获取所有物品 |
| `clear()` | - | `void` | 清空背包 |
| `get totalCount()` | - | `number` | 获取总物品数（getter） |
| `get remainingSlots()` | - | `number` | 获取剩余槽位（getter） |
| `get isFull()` | - | `boolean` | 检查背包是否已满（getter） |

### 物品系统 (Item)

#### 物品类别
```typescript
enum ItemCategory {
    Food = 'food',    // 食物
    Trap = 'trap',    // 陷阱
    Other = 'other'   // 其他
}
```

#### 预定义物品
| ID | 名称 | 类别 | 说明 |
|----|------|------|------|
| `wood` | 小木棍 | Other | 基础材料 |
| `stone` | 石头 | Other | 基础材料 |
| `apple` | 苹果 | Food | 恢复类食物 |
| `meat` | 肉 | Food | 恢复类食物 |
| `trap_basic` | 基础陷阱 | Trap | 捕捉工具 |

## 🧪 测试

### 测试配置
项目使用Jest作为测试框架，配置支持TypeScript：

```javascript
// jest.config.js
const { createDefaultPreset } = require("ts-jest")
const tsJestTransformCfg = createDefaultPreset().transform

module.exports = {
    testEnvironment: "node",
    transform: {
        ...tsJestTransformCfg,
    },
}
```

### 运行测试
```bash
# 运行所有测试
npm test

# 运行特定测试文件
npx jest user.test.ts

# 运行特定测试用例
npm test -- --testNamePattern="用户移动测试"

# 监控模式运行测试
npm run test:watch

# 生成覆盖率报告
npm run test:coverage
```

### 测试覆盖率
测试覆盖以下核心功能：
- ✅ 用户创建和属性初始化
- ✅ 位置管理和移动系统
- ✅ 物品抓取和丢弃
- ✅ 背包容量管理
- ✅ 事件监听系统
- ✅ 属性消耗和恢复
- ✅ 边界条件和错误处理

## 📝 开发指南

详细开发规范请参考 [AGENTS.md](./AGENTS.md)，以下为简要指南：

### 代码风格
- **文件命名**: 使用kebab-case（如`user-property.ts`）
- **类名**: PascalCase（如`User`, `Backpack`）
- **方法/变量**: camelCase（如`move()`, `totalCount`）
- **私有字段**: 下划线前缀（如`_backpack`, `_position`）
- **常量**: UPPER_SNAKE_CASE（如`MAX_SLOTS`）

### 类型注解
- 所有函数参数和返回值都需要显式类型注解
- 使用接口定义对象形状
- 避免使用`any`，优先使用`unknown`
- 使用`type`关键字进行类型别名定义

### 注释规范
- 公共API使用JSDoc注释
- 支持中英文混合注释（保持一致性）
- 复杂逻辑需要行内注释说明

```typescript
/**
 * 移动用户
 * @param {Direction} dir - 移动方向
 * @param {number} distance - 移动距离
 * @returns {[number, number]} 移动后的位置坐标
 */
move(dir: Direction, distance: number): [number, number] {
    // 实现代码...
}
```

### 添加新功能流程
1. **创建新文件**：在根目录创建描述性文件名的`.ts`文件
2. **遵循命名规范**：按照上述命名约定命名类、接口、方法
3. **添加JSDoc注释**：为所有公共API添加完整的JSDoc文档
4. **编写测试**：在`*_test.ts`或`*.test.ts`中添加测试用例
5. **更新文档**：如有需要，更新AGENTS.md和README.md

### 设计模式应用
- **组合模式**：User类组合Backpack和UserProperties
- **工厂模式**：`createUser()`和`createItem()`工厂函数
- **观察者模式**：自定义事件监听系统
- **策略模式**：UserProperty接口的不同实现类
- **数据访问对象**：ITEM_DATABASE物品数据库

## 🔄 项目状态与发展

### 当前状态
- ✅ 核心游戏系统完成（用户、属性、背包、物品）
- ✅ 完整的测试套件
- ✅ 开发文档和代码规范
- ⚠️ 武器系统接口定义（待实现）
- ⚠️ 图形界面（待开发）
- ⚠️ 多人网络功能（待开发）

### 未来发展计划
1. **图形界面**：添加基于Canvas或WebGL的图形渲染
2. **网络功能**：实现多人游戏和实时同步
3. **扩展系统**：添加技能、任务、成就系统
4. **性能优化**：添加游戏循环和帧率控制
5. **部署工具**：构建打包工具和部署脚本

## 📄 许可证

本项目采用 **ISC许可证**。详细信息请查看 [LICENSE](LICENSE) 文件。

## 🤝 贡献指南

欢迎提交Issue和Pull Request！贡献前请确保：
1. 阅读并理解 [AGENTS.md](./AGENTS.md) 中的开发规范
2. 为新功能添加完整的测试用例
3. 保持代码风格一致
4. 更新相关文档

## 📧 联系方式

如有问题或建议，请通过以下方式联系：
- **项目仓库**: [https://gitee.com/byref/aie.git](https://gitee.com/byref/aie.git)
- **问题跟踪**: 请在仓库中提交Issue

---

<div align="center">
<strong>🎮 开始你的TypeScript游戏开发之旅吧！</strong>
</div>