# PlayGame

**Repository Path**: daili12/play-game

## Basic Information

- **Project Name**: PlayGame
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

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

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# PlayGame - 基于Python和Pygame的地图探索游戏

## 项目概述

PlayGame是一个使用Python和Pygame开发的地图探索游戏，具有角色移动、自动寻路、NPC巡逻、城市系统、载具系统等功能。游戏采用网格化地图设计，支持缩放和拖动查看。

## 项目结构

```
playgame/
├── map/                    # 地图数据文件
│   ├── world_map.json      # 主地图配置
│   └── world_position.json # 城市位置数据
├── resources/             # 资源文件
│   ├── person/            # 角色图片
│   │   ├── hero.png       # 主角图片
│   │   └── soldier.png    # 士兵NPC图片
│   ├── position/          # 地点图标
│   │   ├── none.png       # 默认图标
│   │   ├── village.png    # 村庄图标
│   │   └── town.png       # 城镇图标
│   └── terrain/           # 地形图片
│       ├── desert.png     # 沙漠
│       ├── grass.png      # 草地
│       ├── mountain1.png  # 山脉
│       ├── wall1.png      # 围墙1
│       └── wall2.png      # 围墙2
├── test/                  # 测试文件目录
│   ├── __init__.py
│   ├── test_role.py       # 角色系统测试
│   ├── test_map.py        # 地图系统测试
│   ├── test_vehicle.py    # 载具系统测试
│   ├── test_pathfinding.py # 寻路系统测试
│   └── test_integration.py # 集成测试
├── AI.py                  # AI系统定义
├── common.py              # 通用设置和状态类
├── map.py                 # 地图系统和网格管理
├── playgame.py            # 游戏主循环和入口
├── position.py            # 城市和地点系统
├── pyUI.py                # 用户界面和交互处理
├── role.py                # 角色系统（主角、NPC、载具）
├── world.py               # 游戏世界初始化
├── README.md              # 项目说明文档
├── class_diagram.md        # 类图文档
└── REFACTORING_REPORT.md  # 重构分析报告
```

## 核心功能模块

### 1. 游戏设置 (common.py)
- **Setting类**：管理游戏窗口大小、起始年份、阻力系数等全局设置
- **State类**：处理游戏时间系统和视图状态

### 2. 地图系统 (map.py)
- 支持多种地形类型：草地(1)、沙漠(10)、山脉(11)、围墙(31/32)、村庄(221)、水域(100)
- 网格化地图管理，每个格子有独立的移动阻力权重
- 地图缩放和拖动功能
- 自动寻路算法（基于Dijkstra算法）

### 3. 角色系统 (role.py)
- **Role类**：角色基类，提供基本移动和寻路功能
  - 统一的寻路算法实现
  - 移动类型判断辅助方法
- **Human类**：人类角色基类
- **Main_role类**：玩家控制角色，具有相遇检测功能
- **NPC类**：支持巡逻AI行为
- **Vehicle类**：载具基类，支持乘客管理
- **Boat类**：船只，只能在水中移动
- **Carriage类**：马车，只能在陆地上移动
- **Boat_NPC类**：船只NPC，具有AI行为

### 4. 载具系统 (role.py)
- **乘客管理**：支持乘客上下载具
- **驾驶系统**：驾驶者控制载具移动
- **交互系统**：支持与载具交互
- **地形限制**：船只只能在水中移动，马车只能在陆地上移动

### 5. 城市系统 (position.py)
- 城市属性：人口、军队、经济指标等
- 城市类型和规模区分
- 城市所有权系统

### 6. AI系统 (AI.py)
- **巡逻AI**：NPC在指定点之间巡逻
- **跟随AI**：NPC跟随目标（待实现）

### 7. 用户界面 (pyUI.py)
- 地图渲染和地形显示
- 鼠标和键盘交互处理
- 视角移动和缩放控制
- 帧率显示和调试信息

## 游戏特性

### 地图特性
- **地图尺寸**: 100x50 网格
- **地形类型**: 多种地形具有不同的移动阻力
  - 草地：正常移动
  - 沙漠：较慢移动
  - 山脉：无法通行
  - 围墙：无法通行
  - 水域：船只可通行，人类不可通行
- **缩放功能**: 支持鼠标滚轮缩放地图
- **拖动查看**: 支持鼠标中键拖动地图

### 角色移动
- **方向移动**: WASD键控制角色移动
- **点击移动**: 鼠标左键点击目标位置自动寻路
- **速度系统**: 角色速度和地形阻力影响移动速度
- **时间系统**: 游戏内时间流逝与实际移动相关
- **载具系统**: 支持进入和退出载具

### 载具系统
- **船只**：
  - 只能在水域中移动
  - 支持乘客上下载具
  - 驾驶者控制船只移动
- **马车**：
  - 只能在陆地上移动
  - 支持乘客上下载具
  - 驾驶者控制马车移动
  - 移动速度比步行快

### NPC行为
- **巡逻AI**: NPC在指定巡逻点之间循环移动
- **相遇检测**: 主角与NPC或城市相遇时触发事件

### 城市系统
- 当前版本包含2个城市：穆阳(15,15) 和 宁浦(8,26)
- 城市具有经济属性和所有权系统

## 运行要求

- Python 3.x
- Pygame 库

## 安装说明

### 1. 克隆项目
```bash
git clone <repository-url>
cd playgame
```

### 2. 安装依赖
```bash
pip install pygame
```

### 3. 验证安装
```bash
python playgame.py
```

## 启动游戏

运行主程序文件：
```bash
python playgame.py
```

## 控制说明

### 键盘控制
- **W**: 向上移动
- **S**: 向下移动
- **A**: 向左移动
- **D**: 向右移动
- **E**: 进入载具
- **Q**: 离开载具
- **方向键**: 地图视角移动
- **ESC**: 退出游戏

### 鼠标控制
- **左键点击**: 移动到指定位置（自动寻路）
- **右键点击**: 与载具交互或下船
- **鼠标滚轮**: 缩放地图
  - 向上滚动：放大地图
  - 向下滚动：缩小地图
- **中键拖动**: 拖动地图视角

## 使用示例

### 示例1：角色移动
```python
from role import Human
from world import World
from common import Setting

# 初始化游戏世界
setting = Setting()
world = World(setting)

# 创建角色
hero = Human(1, 1, "英雄")
world.map.add(hero)

# 手动移动
hero.move(4, world)  # 向右移动

# 自动寻路
hero.find_way((1, 1), (5, 5), world.map)
```

### 示例2：载具使用
```python
from role import Carriage, Human
from world import World
from common import Setting

# 初始化游戏世界
setting = Setting()
world = World(setting)

# 创建角色和载具
hero = Human(1, 1, "英雄")
carriage = Carriage(3, 1, "马车")
world.map.add(hero)
world.map.add(carriage)

# 进入载具
if carriage.can_enter(hero):
    carriage.add_passenger(hero)
    print(f"{hero.name} 进入了{carriage.name}")

# 控制载具移动
carriage.find_way((3, 1), (10, 1), world.map)

# 离开载具
carriage.remove_passenger(hero)
print(f"{hero.name} 离开了{carriage.name}")
```

### 示例3：NPC巡逻
```python
from role import NPC
from AI import AI_type
from world import World
from common import Setting

# 初始化游戏世界
setting = Setting()
world = World(setting)

# 创建NPC
npc = NPC(15, 14, "巡逻士兵")
npc.set_attr(1, 500)
npc.set_AI(AI_type.PATROL, (8, 9), (8, 19))
world.map.add(npc)

# NPC会自动在(8,9)和(8,19)之间巡逻
```

## 测试

### 运行所有测试
```bash
# 运行角色系统测试
python -m pytest test/test_role.py -v

# 运行地图系统测试
python -m pytest test/test_map.py -v

# 运行载具系统测试
python -m pytest test/test_vehicle.py -v

# 运行寻路系统测试
python -m pytest test/test_pathfinding.py -v

# 运行集成测试
python -m pytest test/test_integration.py -v

# 运行所有测试
python -m pytest test/ -v
```

### 测试覆盖范围
- 角色移动和寻路功能
- 载具交互和乘客管理
- 地图渲染和交互
- NPC AI行为
- 城市系统功能

## 版本历史

### v2.0 (2026-03-01) - 重构版本
- **重构优化**：
  - 统一寻路算法实现，消除重复代码
  - 优化类继承关系，明确职责边界
  - 降低代码复杂度，提高可维护性
  - 清理冗余代码和无效注释
- **代码改进**：
  - 净减少代码约180行
  - 新增_can_move_to()辅助方法
  - find_way方法从约120行减少到约60行
  - find_way_rec方法从约80行减少到约30行
- **功能增强**：
  - 完善载具系统
  - 优化主角和载具的寻路一致性
  - 修复角色退出载具后无法移动的问题
- **文档更新**：
  - 更新class_diagram.md，反映新的类结构
  - 更新README.md，添加详细使用示例
  - 添加REFACTORING_REPORT.md，记录重构过程
- **测试完善**：
  - 创建test目录
  - 添加角色系统测试
  - 添加地图系统测试
  - 添加载具系统测试
  - 添加寻路系统测试
  - 添加集成测试

### v0.06
- 地点系统
- 相遇检测机制

### v0.05
- 速度体系
- 地形阻力影响

### v0.04
- NPC系统框架
- 巡逻AI
- 围墙和士兵

### v0.03
- 图片更新
- 文件读取地图
- 自动寻路

### v0.02
- 地图缩放和拖动功能

### v0.01
- 基础框架
- 大地图制作
- 按键响应

## 开发计划(TODO)

### 短期计划
1. 增加简单界面和更多交互操作
2. 完善AI行为类型（跟随AI等）
3. 优化寻路算法性能

### 中期计划
1. 扩展城市经济和管理系统
2. 添加任务和事件系统
3. 完善载具系统（更多载具类型）

### 长期计划
1. 添加战斗系统和技能系统
2. 支持多人在线游戏
3. 添加游戏存档和读取功能

## 技术特点

- 使用JSON文件存储地图数据，便于编辑和扩展
- 模块化设计，各功能系统分离清晰
- 自动寻路算法支持复杂地形路径规划
- 时间系统与游戏动作同步
- 面向对象设计，类职责明确
- 继承体系优化，避免代码重复

## 重构亮点

### 1. 代码复用优化
- 删除Vehicle类中重复的4个方法
- 统一寻路算法实现
- 净减少代码约180行

### 2. 类关系优化
- 明确职责边界
- 通过继承获取通用功能
- 符合单一职责原则

### 3. 代码复杂度降低
- 新增辅助方法封装复杂逻辑
- 大幅简化核心方法
- 提高代码可读性

### 4. 冗余代码清理
- 删除无效注释
- 删除未使用代码
- 提高代码质量

## 扩展建议

### 功能扩展
1. **战斗系统**: 添加角色战斗和技能系统
2. **任务系统**: 设计主线任务和支线任务
3. **经济系统**: 完善城市经济和贸易功能
4. **多人模式**: 支持多人在线游戏
5. **存档系统**: 添加游戏存档和读取功能

### 性能优化
1. **寻路算法优化**: 考虑使用A*算法
2. **渲染优化**: 优化地图渲染性能
3. **内存优化**: 优化大地图的内存占用

### 代码质量
1. **类型注解**: 添加类型提示（Type Hints）
2. **单元测试**: 完善单元测试覆盖
3. **文档完善**: 补充详细的API文档
4. **代码规范**: 统一命名风格和代码格式

## 贡献指南

欢迎贡献代码！请遵循以下步骤：

1. Fork本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启Pull Request

## 许可证

本项目采用MIT许可证 - 详见LICENSE文件

## 联系方式

如有问题或建议，请通过以下方式联系：
- 提交Issue
- 发送邮件

## 致谢

感谢所有为本项目做出贡献的开发者！

---

这个项目展示了如何使用Pygame构建一个完整的地图探索游戏框架，具有良好的扩展性和模块化设计。经过重构优化后，代码质量显著提升，维护性大幅改善。