# tank0013

**Repository Path**: mobilezht1/tank0013

## Basic Information

- **Project Name**: tank0013
- **Description**: 开发一款基于 AI 对战的坦克大战游戏，支持多辆 AI 控制的坦克在封闭地图中自动战斗，通过编程实现坦克的智能决策系统，使坦克能够自主移动、攻击、防御并适应战场环境。
- **Primary Language**: Rust
- **License**: BSD-3-Clause
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-08-28
- **Last Updated**: 2025-09-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 坦克大战（Tank Battle）游戏完整需求文档（Rust + ggez 纯AI对战版）


## 1. 项目概述
开发一款基于Rust语言和ggez游戏库的**纯AI对战坦克大战游戏**，全程无人工操作，所有坦克由AI系统自主控制。游戏核心是多辆AI坦克在封闭地图中自动完成移动、攻击、防御、资源争夺及团队协作，通过Rust的高性能特性保障流畅运行，借助ggez实现2D渲染、音频处理和资源管理，最终打造一个展示AI决策能力与战场适应能力的可视化对抗平台。


## 2. 核心功能需求

### 2.1 游戏场景
- **地图元素**：
    - 可摧毁障碍物（砖块，被炮弹击中后破碎并移除）；
    - 不可摧毁障碍物（钢铁、墙壁，阻挡移动和炮弹）；
    - 空白区域（无阻碍，支持坦克自由移动）；
    - 出生点（坦克初始位置，每局随机或固定分配）；
    - 资源点（定时刷新增强道具，如生命值恢复、攻击强化等）。

- **地图机制**：
    - 支持随机生成（基于预设规则，如障碍物密度、资源点分布）和自定义地图（通过文件导入）；
    - 采用网格坐标系，通过ggez的`graphics`模块渲染，不同地形使用差异化纹理/颜色标识（如砖块为棕色，钢铁为灰色）。


### 2.2 坦克属性
- **基础属性**（通过Rust结构体存储，支持`Clone`/`Copy`高效复制）：
    - 生命值（初始值100，被击中后减少，归零则坦克被摧毁）；
    - 移动速度（单位：像素/帧，默认3-5像素，受地形影响）；
    - 攻击范围（炮弹最大飞行距离，默认200-300像素）；
    - 攻击伤害（命中后造成的生命值减少量，默认20-40）；
    - 攻击冷却（两次开火的最小间隔，默认30-60帧）。

- **增强属性**（通过拾取道具获得，有持续时间）：
    - 临时无敌（5秒内不受伤害，伴随闪烁特效）；
    - 攻击范围扩大（提升50%，持续10秒）；
    - 移动速度提升（提升30%，持续8秒）；
    - 伤害值增加（提升40%，持续12秒）。


### 2.3 AI行为逻辑（完全自主，无人工干预）
#### 2.3.1 基本行为
- **自主移动**：基于A*算法规划路径，避开障碍物、友军及己方炮弹；
- **敌人检测**：通过360°视野（半径可配置）实时识别进入范围的敌方坦克，视野被不可摧毁障碍物完全阻挡，被可摧毁障碍物削弱（如穿透砖块后范围减半）；
- **自动攻击**：锁定敌方坦克后，在攻击范围内且无冷却时自动开火，优先攻击威胁最高目标（如正在瞄准自己的敌方）；
- **躲避行为**：检测到敌方炮弹来袭（通过轨迹预判）时，执行不规则移动（如左右折返）规避；被多辆敌方锁定时，优先向障碍物方向撤退。


#### 2.3.2 高级行为
- **团队协作**：
    - 目标分配：通过信息共享避免多辆友军攻击同一目标，采用"就近分配"原则；
    - 角色分工：高血量坦克（生命值>70%）担任先锋（吸引火力），低血量高伤害坦克（生命值<50%且伤害值>30）担任远程支援；
    - 包围战术：多辆友军从不同方向（如上下左右）包抄单个敌方，压缩其移动空间。

- **资源管理与争夺**：
    - 道具评估：动态优先级排序（低血量时优先加血道具，普通状态优先攻击强化道具）；
    - 风险权衡：计算获取道具的成本（距离、沿途敌方数量）与收益（道具价值），风险过高则放弃；
    - 资源控制：记忆道具刷新点和时间间隔，提前占据高频刷新区域，阻止敌方获取关键道具。

- **动态战术调整**：
    - 局势评估：实时计算双方战力（存活数量×平均生命值×平均伤害），优势（己方战力≥敌方1.5倍）时主动进攻，劣势（己方战力≤敌方0.7倍）时防御周旋；
    - 行为学习：记录敌方AI的攻击模式（如偏好正面冲突或伏击），针对性调整策略（如对伏击型敌方采用集群推进）；
    - 时间策略：游戏结束前30秒（或剩余时间10%），若平局则切换为激进攻击，若领先则保守防御。

- **地形利用**：
    - 掩体防御：主动停靠在障碍物旁，仅暴露部分车身攻击（减少被击中面积）；
    - 拐角战术：在拐角处快速探出攻击后立即缩回掩体（"peek"战术）；
    - 通道限制：诱导敌方进入狭窄通道（如两排障碍物之间），限制其移动方向后集火。

- **损伤控制**：
    - 分级撤退：轻度损伤（生命值50%-70%）边打边退；中度损伤（30%-50%）优先撤退至安全区；重度损伤（<30%）全力绕障碍物周旋，等待友军支援；
    - 自我保护：被锁定时采用无规律移动（如随机转向+变速），降低被命中概率；生命值<20%时视野范围缩小30%（模拟"受损"状态）。

- **战略欺骗**：
    - 诱饵战术：假装向道具点移动，引诱敌方跟随，实际转向伏击点（与友军配合）；
    - 火力吸引：故意暴露位置吸引敌方火力，为友军创造侧击机会；
    - 假动作：绕障碍物做往返移动，误导敌方预判行进方向。


### 2.4 战斗机制
- **炮弹系统**：
    - 物理特性：沿直线飞行（速度8-10像素/帧），碰到障碍物或敌方坦克后爆炸；
    - 交互规则：可摧毁可破坏障碍物（如砖块），对不可摧毁障碍物（钢铁）仅触发碰撞音效；
    - 渲染与更新：通过ggez的`sprite`系统实现炮弹动画，在游戏循环中实时更新位置，超出攻击范围后自动销毁。

- **胜负判定**：
    - 单局模式：最后存活的坦克（或队伍）获胜；
    - 积分模式：规定时间（如3分钟）内，击毁敌方坦克数量最多的一方获胜；
    - 自动流程：单局结束后5秒自动重置（地图刷新、坦克重生），支持连续对战（可配置局数，如10局决胜）。


### 2.5 音效与音乐系统
#### 2.5.1 核心音效
所有音效通过ggez的`audio`模块实现，支持独立音量调节，按场景分类如下：

| 类型         | 具体场景                          | 特性要求                                  |  
|--------------|-----------------------------------|-------------------------------------------|  
| 坦克操作     | 移动（平地/障碍物边缘）、开火、被击中、摧毁 | 移动音效频率随速度变化；摧毁音效含1秒衰减  |  
| 障碍物交互   | 炮弹击中砖块（破碎）、击中钢铁（反弹）    | 砖块破碎分"裂纹→破碎"两层音效；钢铁带金属撞击音 |  
| 道具交互     | 生成、拾取、生效、过期              | 生成音效带"闪烁感"；生效音效与道具类型匹配（如加血用治愈音） |  
| 系统提示     | 游戏开始、结束（胜利/失败）        | 开始/结束音效带仪式感（胜利激昂，失败低沉）；时长<10秒 |  


#### 2.5.2 背景音乐（BGM）
采用动态BGM系统，通过ggez的`Source::loop`循环播放，支持根据战场局势切换：

- **初始阶段**（前30秒）：轻快电子乐，音量50%（营造准备氛围）；
- **战斗阶段**（首次交火后）：激昂摇滚/电子混合乐，战斗激烈时（每分钟击毁≥2）加速10%、音量提升至60%；
- **局势倾斜阶段**：优势时切换胜利倾向音乐（含铜管乐器），劣势时切换紧张感音乐（含低频贝斯）；
- **结算阶段**：胜利BGM（8-10秒欢快旋律），失败BGM（5-7秒低沉旋律），结束时1秒淡出。


## 3. 技术需求

### 3.1 开发环境
- 编程语言：Rust 1.89（利用内存安全和高性能特性）；
- 游戏库：ggez 0.9.3（提供2D渲染、输入处理、音频管理）；
- 构建工具：Cargo（Rust包管理器）；
- 依赖项：
    - `ggez`：核心游戏框架；
    - `rand`：地图随机生成；
    - `nalgebra`：向量计算（辅助移动和碰撞检测）；
    - `serde`/`toml`：配置文件解析（如音效音量、AI参数）。


### 3.2 接口设计
- **AI核心接口（Trait）**：
  ```rust
  trait TankAI {
      /// 输入：环境感知信息；输出：坦克动作
      fn decide(&mut self, perception: &TankPerception) -> TankAction;
  }
  ```  

- **环境感知结构**：
  ```rust
  struct TankPerception {
      self_state: TankState,          // 自身状态（位置、生命值、冷却等）
      allies: Vec<TankState>,         // 友军状态列表
      enemies: Vec<EnemyState>,       // 敌军状态列表（含位置、威胁等级）
      obstacles: Vec<Obstacle>,       // 视野内障碍物
      powerups: Vec<Powerup>,         // 视野内道具（含位置、类型、剩余时间）
      bullets: Vec<Bullet>,           // 视野内炮弹（含轨迹预判）
  }
  ```  

- **行为输出结构**：
  ```rust
  enum TankAction {
      Move(Direction, Speed),         // 移动（方向+速度）
      Attack(TargetPoint),            // 攻击（目标坐标）
      Stay,                           // 静止
      Retreat(SafeDirection),         // 撤退（向安全方向）
  }
  ```  


### 3.3 游戏架构
- 基于ggez的`EventHandler`实现主循环：
    - `update()`：处理AI决策、物理碰撞（坦克-障碍物、炮弹-目标）、状态更新（生命值、冷却等）；
    - `draw()`：渲染地图、坦克、炮弹、特效（如爆炸动画）及UI信息（战力对比、剩余时间）；
    - 无用户输入处理逻辑（全程AI自主运行）。

- 性能要求：
    - 支持至少8辆AI坦克同时对战，稳定60 FPS；
    - 单辆坦克AI决策耗时≤50ms；
    - 内存占用≤100MB。


### 3.4 音效与音乐技术规范
- **资源格式**：优先OGG（压缩率高），短音效可用WAV（无延迟）；
- **加载策略**：核心音效（坦克操作、爆炸）预加载至内存；非高频音效（道具、UI）懒加载+缓存；
- **播放控制**：支持10+音效并发播放，通过`AudioContext`管理通道；可选空间音效（根据坦克位置调整左右声道音量）；
- **配置接口**：支持通过`config.toml`调整音量（主音量、音效、BGM）及动态BGM开关。


## 4. 扩展需求（可选）
- **地图编辑器**：可视化界面支持绘制/删除障碍物、设置出生点/资源点，导出地图配置文件；
- **观战模式**：实时显示AI决策目标（如"攻击敌方A"）、视野范围（半透明区域）、攻击轨迹预判（虚线）；
- **AI调试工具**：输出决策日志（如"因检测到敌方→决定攻击"），可视化战术调整过程；
- **多难度AI**：不同难度对应不同决策频率（简单：10次/秒，困难：20次/秒）和战术复杂度；
- **自定义音效库**：支持导入用户音效文件（符合格式规范），一键切换风格（如复古8位机、现代写实）；
- **网络观战**：支持远程连接观看AI对战，同步显示战场数据。


## 5. 交付成果
- 可运行二进制文件（通过`cargo build --release`生成）；
- 完整Rust源代码（含注释，遵循Rust代码规范）；
- 游戏资源（纹理、音效、音乐文件）；
- 配置文件（`Cargo.toml`、`config.toml`）；
- 文档：
    - 构建与运行指南（含环境依赖、启动参数）；
    - AI接口说明（供扩展新AI算法）；
    - 资源规范（纹理尺寸、音效格式要求）。