# tank0012

**Repository Path**: mobilezht1/tank0012

## Basic Information

- **Project Name**: tank0012
- **Description**: 开发一款基于 Rust 语言和 ggez 游戏库的 AI 对战坦克大战游戏，支持多辆 AI 控制的坦克在封闭地图中自动战斗。通过 Rust 的高性能特性实现流畅的游戏体验，利用 ggez 提供的 2D 渲染、输入处理和资源管理功能，构建可视化的战斗沙盘，让 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版本）

## 1. 项目概述
开发一款基于Rust语言和ggez游戏库的AI对战坦克大战游戏，支持多辆AI控制的坦克在封闭地图中自动战斗。通过Rust的高性能特性实现流畅的游戏体验，利用ggez提供的2D渲染、输入处理和资源管理功能，构建可视化的战斗沙盘，让AI坦克能够自主移动、攻击、防御并适应战场环境。

## 2. 核心功能需求

### 2.1 游戏场景
- 随机生成或自定义地图，包含：
    - 可摧毁的障碍物（如砖块）
    - 不可摧毁的障碍物（如钢铁、墙壁）
    - 空白区域（可自由移动）
    - 出生点（坦克初始位置）
    - 资源点（增强道具，如生命值恢复、攻击强化等）
- 地图渲染：使用ggez的`graphics`模块实现2D网格地图绘制，不同类型的地形使用不同的纹理或颜色标识

### 2.2 坦克属性
- 基础属性：
    - 生命值（被攻击后减少，归零则坦克被摧毁）
    - 移动速度（单位时间内可移动的距离）
    - 攻击范围（炮弹可到达的最大距离）
    - 攻击伤害（命中目标后造成的伤害值）
    - 攻击冷却（两次攻击之间的最小间隔时间）
- 可选增强属性（通过道具获取）：
    - 临时无敌状态
    - 攻击范围扩大
    - 移动速度提升
    - 伤害值增加
- 属性实现：使用Rust结构体存储坦克属性，通过`#[derive(Clone, Copy)]`实现高效的状态复制

### 2.3 AI行为逻辑
- 基本行为：
    - 自主移动（避开障碍物和友军）
    - 敌人检测（发现进入视野范围内的敌方坦克）
    - 自动攻击（向敌方坦克发射炮弹）
    - 躲避行为（被攻击时或发现炮弹来袭时的规避动作）
- 高级行为：
    - 团队协作：
        - 自动分配攻击目标，避免火力浪费
        - "先锋-支援"角色分配：高血量坦克担任先锋吸引火力，低血量/高伤害坦克提供远程支援
        - 包围战术：多辆坦克从不同方向包抄敌方单个目标
        - 信息共享：发现敌方目标后自动共享位置信息给友军
    - 资源管理与争夺：
        - 道具评估系统：根据当前状态动态评估道具优先级
        - 风险收益比计算：距离、沿途危险程度与道具价值的权衡
        - 占据地图关键位置（如高地、道具刷新点）
    - 动态战术调整：
        - 局势评估：实时计算双方战力对比
        - 根据优势/劣势状态切换战术
        - 记录敌方AI行为模式并针对性调整策略
    - 地形战术利用：
        - 主动寻找掩体，仅暴露部分车身攻击
        - 利用拐角实现"peek"战术
        - 诱导敌方进入狭窄通道，限制其移动空间
    - 损伤控制与恢复：
        - 分级撤退机制：根据生命值情况采取不同撤退策略
        - 被锁定攻击时采取不规则移动模式
    - 战略欺骗：
        - 假装撤退引诱敌方进入伏击圈
        - 故意暴露位置吸引火力，为友军创造攻击机会

### 2.4 战斗机制
- 炮弹系统：
    - 炮弹沿直线飞行，碰到障碍物或敌方坦克后爆炸
    - 炮弹可摧毁可破坏的障碍物
    - 命中敌方坦克后造成伤害
    - 实现：使用ggez的`sprite`系统处理炮弹动画，通过Rust的`Vec`存储活跃炮弹，在游戏循环中更新状态
- 胜负判定：
    - 单局模式：最后存活的坦克（或坦克队伍）获胜
    - 积分模式：在规定时间内，击毁敌方坦克数量最多的一方获胜


### 2.5 音效与音乐系统
#### 2.5.1 核心音效分类与触发场景
基于游戏核心交互场景，设计以下必选音效，所有音效需支持**音量独立调节**，并通过ggez的`audio`模块实现加载与播放：

| 音效类型 | 具体场景 | 音效特性要求 |
|----------|----------|--------------|
| **坦克操作音效** | 1. 坦克移动（不同地形：平地/砖块边缘）<br>2. 坦克转向（快速转向/缓慢转向）<br>3. 坦克开火（普通攻击/强化攻击）<br>4. 坦克被击中（轻度损伤/重度损伤）<br>5. 坦克摧毁（爆炸+残骸落地） | 1. 移动音效需匹配坦克速度，速度越快音效频率越高<br>2. 开火音效需有「发射」和「炮弹飞行」两层音轨<br>3. 摧毁音效需有0.5-1秒的衰减过程，增强沉浸感 |
| **障碍物交互音效** | 1. 炮弹击中可摧毁障碍物（砖块破碎）<br>2. 炮弹击中不可摧毁障碍物（钢铁反弹）<br>3. 坦克撞击障碍物（轻微碰撞/强力撞击） | 1. 可摧毁障碍物破碎需有「碎裂」分层音效（先裂纹再破碎）<br>2. 钢铁反弹需加入「金属撞击+弹开」音效，突出硬度感 |
| **道具交互音效** | 1. 道具生成（从地图中刷新）<br>2. 坦克拾取道具（成功获取）<br>3. 道具生效（如无敌状态激活/攻击强化启动）<br>4. 道具过期（效果消失提示） | 1. 生成音效需带有「闪烁感」，引导玩家/AI关注<br>2. 生效音效需与道具类型匹配（如加血道具用「治愈感」音效，攻击强化用「能量提升」音效） |
| **UI与系统音效** | 1. 游戏开始（倒计时结束）<br>2. 游戏结束（胜利/失败）<br>3. 切换菜单选项（调试模式/难度选择）<br>4. 开启/关闭AI调试日志 | 1. 游戏开始/结束音效需有「仪式感」，如胜利用激昂短旋律，失败用低沉音效<br>2. UI交互音效需轻量化（时长<0.3秒），避免干扰战斗音效 |


#### 2.5.2 背景音乐（BGM）设计
采用**动态BGM系统**，根据战场局势自动切换音乐风格，通过ggez的`Source::loop`实现循环播放，支持「暂停/继续」和「音量调节」：

1. **初始阶段BGM（游戏前30秒）**
    - 风格：轻快、节奏平缓的电子音乐
    - 用途：营造战前准备氛围，适应玩家/观察者熟悉场景
    - 音量：默认50%（低于战斗音效音量）

2. **战斗阶段BGM（双方开始交火后）**
    - 风格：激昂、鼓点强烈的摇滚/电子混合乐
    - 触发条件：检测到首次坦克开火或坦克被击中
    - 动态调整：战斗激烈程度（每分钟击毁数≥2）时，自动提升BGM节奏（如加速10%）和音量（60%）

3. **优势/劣势BGM（局势倾斜时）**
    - 优势BGM：当己方存活数≥敌方2倍时，切换为「胜利倾向」音乐（加入铜管乐器，增强自信感）
    - 劣势BGM：当己方存活数≤敌方1/2时，切换为「紧张感」音乐（加入低频贝斯和急促鼓点，提示危机）
    - 切换逻辑：局势变化后3秒延迟切换，避免频繁跳动

4. **结算阶段BGM（游戏结束时）**
    - 胜利BGM：欢快、高昂的旋律，时长8-10秒（配合结算动画）
    - 失败BGM：低沉、舒缓的旋律，时长5-7秒（避免负面情绪强化）
    - 自动停止：结算界面关闭或重新开始游戏时，BGM淡出（1秒衰减）

    
## 3. 技术需求

### 3.1 开发环境
- 编程语言：Rust 1.60+（利用其内存安全和高性能特性）
- 游戏库：ggez 0.8+（提供2D图形渲染、输入处理、音频和资源管理）
- 构建工具：Cargo（Rust包管理器和构建系统）
- 依赖项：
    - `ggez`：核心游戏框架
    - `rand`：用于地图随机生成
    - `nalgebra`（可选）：用于向量计算，辅助实现坦克移动和碰撞检测

### 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>,
  }
  ```
- 行为输出结构：
  ```rust
  enum TankAction {
      Move(Direction),
      Attack(Point),
      Stay,
      Retreat,
  }
  ```

### 3.3 游戏架构
- 采用ECS（实体-组件-系统）模式或简单的状态机模式
- 主循环结构（基于ggez的`EventHandler`）：
    - `update()`：处理游戏逻辑、AI决策、物理碰撞
    - `draw()`：渲染游戏场景、坦克、炮弹和UI元素
    - `input()`：处理调试模式下的用户输入

### 3.4 性能要求
- 支持至少8辆AI坦克同时对战，保持60 FPS稳定帧率
- 每辆坦克的AI决策计算时间不超过50ms
- 内存占用控制在100MB以内

### 3.5 音效与音乐技术规范
#### 3.5.1 资源格式与加载
- 支持格式：优先使用**OGG**（压缩率高、音质损失小），备用**WAV**（无压缩，适合短音效）
- 加载方式：
    - 预加载：游戏启动时加载所有核心音效（坦克操作、障碍物交互）到内存，避免播放延迟
    - 懒加载：道具音效、UI音效等非高频音效，首次触发时加载，后续缓存复用
- 资源管理：通过`ggez::audio::Source`封装音效资源，使用`HashMap`存储音效映射（如`HashMap<SoundType, Source>`）

#### 3.5.2 播放控制与优化
- 多音效并发：支持至少10个音效同时播放（如多辆坦克同时开火+爆炸），通过ggez的`AudioContext`管理音频通道
- 空间音效（可选）：对坦克移动、开火音效添加「方位感」，根据坦克在屏幕中的位置（左/中/右）调整左右声道音量比例（如左侧坦克音效左声道音量提升20%）
- 距离衰减：炮弹飞行音效随距离增加而降低音量（距离每增加100像素，音量衰减10%），模拟真实听觉体验
- 性能优化：短音效（<0.5秒）使用「内存缓存」，长音效（如BGM）使用「流式加载」，避免内存占用过高

#### 3.5.3 配置接口
- 提供音效配置结构体，支持代码层面或配置文件（如`config.toml`）调整：
  ```rust
  #[derive(Debug, Serialize, Deserialize)]
  struct AudioConfig {
      master_volume: f32,    // 主音量（0.0-1.0）
      sfx_volume: f32,       // 音效音量（0.0-1.0）
      bgm_volume: f32,       // 音乐音量（0.0-1.0）
      spatial_audio: bool,   // 是否启用空间音效
      bgm_dynamic: bool,     // 是否启用动态BGM
  }
  ```
- 调试模式支持：可通过快捷键（如`F8`）快速开关BGM，`F9`快速静音所有音效，便于AI调试时排除音频干扰

## 4. 扩展需求（可选）
- 地图编辑器：支持用户通过GUI界面创建自定义地图
- 观战模式：实时显示战斗过程和各项数据统计（击毁数、存活时间等）
- AI调试模式：
    - 可视化展示AI的视野范围和决策路径
    - 输出AI决策过程的日志信息
- 多难度等级：不同难度对应不同的AI智能水平和反应速度
- 网络对战：支持多玩家通过网络连接，控制自己的坦克与AI或其他玩家对战

## 4. 扩展需求（补充：4.5 音效相关扩展）
- **自定义音效库**：支持玩家导入自定义音效文件（需符合格式规范），并在游戏内选择使用
- **音效可视化**：观战模式中添加「音效波形图」，随战斗音效实时显示声波变化，增强观赛体验
- **AI音效交互**：高级AI可通过「音效识别」辅助决策（如听到敌方坦克开火音效后，判断敌方位置并规避）
- **多语言/风格音效包**：提供不同风格的音效包（如复古8位机风格、现代写实风格），支持一键切换

## 5. 交付成果
- 可运行的游戏二进制文件（通过`cargo build --release`生成）
- 完整的Rust源代码（包含注释）
- 游戏资源文件（纹理、音效等）
- Cargo配置文件（`Cargo.toml`）
- 游戏操作说明文档
- AI接口说明文档（供扩展不同AI算法使用）
- 构建和运行指南