# AI塔防游戏

**Repository Path**: io123/battle-bat

## Basic Information

- **Project Name**: AI塔防游戏
- **Description**: 一款基于unity3d 完全由AI完成的塔防游戏
《战蝠防线》是一款创新的塔防游戏，玩家需要在怪物进攻的同时控制英雄进行战术支援，通过建造和升级防御塔来守护基地。游戏拥有深度的成长系统和装备系统，为玩家提供长期的养成体验。
- **Primary Language**: C#
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-05
- **Last Updated**: 2026-07-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 战蝠防线 (BattleBat)

一款以「英雄微操 + 防御塔自主防守 + 局外养成」为核心的混合塔防手游，面向 **抖音小游戏** 平台，使用 **团结引擎 (Tuanjie)** 开发。

> 玩家在怪物进攻的同时操控英雄进行战术支援，通过建造 / 升级防御塔守护基地；关卡结算后进入局外养成（装备、皮肤、指挥官、战令等），形成「局内爽快 + 局外长线」的循环。

---

## 技术栈

| 项 | 说明 |
|----|------|
| 引擎 | 团结引擎 Tuanjie **1.9.1**（基于 Unity **2022.3.62t9**） |
| 语言 | C#（**7.3 兼容**，见下文离线编译校验） |
| 渲染 | Built-in 管线（程序化天空盒 + 线性雾 + 三色环境光，未使用 URP） |
| UI | **全部 UI Toolkit**（UXML + USS + PanelSettings），旧 uGUI HUD 已移除 |
| 目标平台 | 抖音小游戏（WebGL/MiniGame 导出，含抖音广告与触感桥接） |
| 美术 | Kenney / Quaternius 等 CC0 低模 + 少量 AI 生成的 UI 整图 |

---

## 项目结构

```
battle-bat/
├── Assets/
│   ├── _Project/
│   │   ├── Scripts/
│   │   │   ├── Core/          # 事件总线、对象池、资源清单、相机缓存、单例基类
│   │   │   ├── Controllers/   # 战斗流程、波次、敌人、塔、英雄、投射物、路径等运行时逻辑
│   │   │   ├── Models/        # 数据/配置（BattleConfig / EnemyConfig / TowerConfig / 枚举 …）
│   │   │   ├── Services/      # 广告(AdService / 抖音)、触感 Haptics
│   │   │   ├── Dev/           # 可玩沙盒、UI Toolkit 界面、局外存档、美术/手感工具
│   │   │   └── Editor/        # 一键出包、出包体检、启动场景、资源同步等编辑器工具
│   │   ├── Art/               # 模型 / 贴图 / UI 图（Kenney、Quaternius、AI 横幅）
│   │   ├── Audio/             # 音频
│   │   ├── Configs/           # ScriptableObject 配置资产
│   │   ├── Plugins/           # 抖音广告 / 触感 jslib
│   │   └── UI/                # UI 图标、字体、Kenney UI 素材
│   └── Resources/_Project/UI/ # 运行时加载的 UXML/USS/PanelSettings（打包同步目标）
├── Tools/TypeCheck/           # 离线编译校验脚本 + UnityEngine/UnityEditor 打桩
├── doc/                       # 设计文档（GDD、技术架构、需求、免费素材指南等）
└── asset_downloader.py …      # 外部 CC0 素材下载 / 整理脚本 + asset_manifest.json
```

> 说明：不存在 `Views/` 目录；界面代码集中在 `Dev/`（`HomeUI.cs` 首页、`BattleHudUI.cs` 战斗 HUD），配套 UXML/USS 在 `Assets/Resources/_Project/UI/`。

---

## 核心系统

### 事件驱动
模块间通过 `EventBus` 解耦，战斗只管发事件，表现层（`BattleJuice`、HUD）订阅响应：

```csharp
EventBus.Publish(new TowerUpgradedEvent { Position = pos, Level = lv });
EventBus.Subscribe<EnemyKilledEvent>(OnEnemyKilled);
```

已定义事件包括：敌人击杀 / 抵达终点、波次开始 / 清除、基地血量、塔开火 / 命中 / 升级 / 落成、英雄技能、Boss 召唤、结算发奖等（见 `Core/GameEvents.cs`）。

### 对象池
高频生成物（投射物、敌人、打击特效的球/方块/圆柱）统一走 `ObjectPool` / 内建池，避免每帧 `new`/`Destroy` 的 GC 峰值。

### 配置管理
使用 ScriptableObject（`Assets/_Project/Configs/`）：`BattleConfig`、`EnemyConfig`、`TowerConfig`、`TowerTalentConfig`、`WaveConfig` 等；敌人 / 塔 / 关卡数值均可在编辑器内调整。

### 局外存档
`MetaProgress` 统一管理局外数据（金币 / 钻石、指挥官、装备、皮肤、任务、战令、月卡、抽卡进度…），`MetaProgressFlusher` 负责落盘。

### 地貌与材质
- `BiomePalette`：按地貌（草原 / 沙漠 / 雪原 / 暮夜 / 蚀渊）集中管理地面、天空盒、装饰、敌人染色。
- `MaterialKit`：运行时把低模默认材质升级为哑光 / 金属 / 光滑 / 自发光，并生成地面斑驳、水面波纹等程序化纹理。自发光统一设 `GlobalIlluminationFlags.None`，避免 Built-in 管线频繁重算全局光。

---

## 核心玩法

### 战斗循环
```
选关 → 配装 → 局内准备 → 波次进攻 → 杀敌获金 → 建塔 / 升级 → 释放英雄技能与战术支援 → 波次强化三选一 → 关卡结算 → 局外养成
```

### 局内资源
- **战术金币**：局内建造 / 升级防御塔。
- **战蝠能量**：随时间恢复，用于英雄大招与战术支援（空投、路障等）。

### 四大防御塔
| 塔类型 | 特点 | 适用 |
|--------|------|------|
| 轻兵器塔 | 高攻速、单体 | 克制高速怪 |
| 重炮轰炸塔 | 低攻速、范围 AOE | 克制人海 |
| 电磁控制塔 | 减速 / 定身 / 削甲 | 控场辅助 |
| 能量共鸣塔 | 增伤 / 产金 | 输出辅助 |

塔升到分支点可二选一强化方向；每种塔有独立天赋树（`TowerTalentRuntime`）。

### 局内 Roguelite
每波结束（非最终波）弹出 **三选一强化**（进攻 / 经济 / 续航三类），仅作用于本局，构筑在顶部以 chip 常驻可见（`RunRoguelite` + HUD）。

---

## 成长与商业化

局外养成与变现体系集中在 `MetaProgress` + 首页各面板：

- **指挥官等级**：随进度解锁系统与装备槽。
- **装备系统**：品质分级、属性加成、直购 / 抽卡获取（属性加成生效，因免费素材无对应模型，装备不显示在角色身上）。
- **英雄皮肤**：换装改色（`SkinDef` + `MaterialKit.RecolorAll`）。
- **抽卡宝箱**：单抽 / 十连，出皮肤 / 装备 / 货币，开箱结果逐格弹入。
- **战令 Battle Pass**：30 级免费 + 尊享双轨。
- **每日任务 / 签到**、**7 日登录礼**、**月卡 / 首充双倍 / 成长基金 / 每日看广告领钻** 等变现点。

---

## 后端服务与战力排行榜

客户端通过 `IBackendService`（`Services/BackendService.cs`）抽象后端，与 `IAdService` 同套「接口 + 平台实现 + 全局入口」模式：

- **`LocalBackendService`**（默认，离线）：分数存本地最高分，排行榜用「自己 + 基线 NPC」拼出，**无服务器也能玩、能看榜**。
- **`HttpBackendService`**（配置 `BackendConfig.BaseUrl` 后启用）：用 `UnityWebRequest` 异步回调请求 REST + JSON 接口。
- **`PlayerIdentity`**：本地生成稳定 `PlayerId`（GUID）+ 可改昵称；抖音环境后续可用 `tt.login` 的 openid 覆盖。
- **战力分**：胜利结算时按「关卡深度 + 星级 + 击杀 + 剩余基地血 + 速通加成」计算并上报，服务端保留玩家历史最高分。
- 首页「排行」入口打开排行榜弹窗，拉取 TopN 并高亮自己所在行。

### 约定的服务端接口（需自建后端实现）

```
POST {BaseUrl}score          body: ScoreSubmission            → {"ok":true}
GET  {BaseUrl}leaderboard?top=N&playerId=xxx                   → LeaderboardResult
POST {BaseUrl}save           body: {"playerId":..,"data":..}   → {"ok":true}   （云存档，预留）
GET  {BaseUrl}save?playerId=xxx                                → {"ok":true,"data":".."}
```

排行榜弹窗内可**修改昵称**（TextField + 改名）与**手动刷新**；昵称本地即时生效，HTTP 后端在下次通关上报时同步。

### 本地起一个参考后端

仓库自带零依赖参考实现，可直接跑通「数据存服务器」链路：

```bash
node server/server.js   # 默认 http://localhost:3000/api/
```

然后把 `BackendConfig.BaseUrl` 改为该地址（详见 `server/README.md`）。留空则走本地离线假榜。

分数上报带**轻量签名**（`BackendSign` FNV-1a 64，客户端/服务端逐位一致）；参考后端用 `REQUIRE_SIGN=1` 开启校验，可挡住裸 POST 刷分与重放（已端到端验证）。排行榜弹窗支持改名、**随机取名**（真机输入法唤不起时的兜底）与手动刷新。

### 建议逐步迁移到服务端的逻辑（防作弊 / 跨端）

排行榜与云存档已接入抽象层；后续可把这些从纯客户端迁到服务端校验：
分数上报签名校验、抽卡概率与结果下发、内购凭证与广告 SSV 校验、每日任务 / 签到 / 战令进度结算、关卡数值热更。（当前均为客户端本地实现，接口已留好扩展位。）

## 画面与手感优化

在免费低模 + Built-in 管线的前提下，做了一轮可玩性与观感打磨：

- **场景**：程序化渐变天空盒（按地貌调色）、阴影质量（软阴影 + 高分辨率 + 合理阴影距离）、地面程序化斑驳 / 瓦片纹理、河流 UV 流动、装饰随机朝向 / 倾斜、树木风吹摇摆、氛围粒子（萤火 / 雪 / 灰烬 / 孢子）。
- **战斗打击感**：炮口闪光、命中火花、击杀多层爆炸 + 碎片、敌人受击闪白与低血泛红、塔升级金色上升光环、建塔落地尘土环、基地掉血震屏 + 触感、波次来袭横幅（最终波警示）。
- **UI 手感**：全弹窗缩放淡入、首页 Tab 切换淡入、货币数字滚动跳动、任务进度条平滑填充、签到点呼吸、Toast / 状态提示淡入、运行时安全区适配（刘海 / 挖孔）。

> 诚实说明：这些属于「让原型更干净、更有反馈」的范畴，达不到商业级美术精度；进一步提升需 URP + 烘焙光照 + 后处理 + 付费美术包。

---

## 开发工作流

### 离线编译校验（重要）
本仓库没有在本机常驻团结编辑器，改完代码用 Mono 的 `mcs` + 打桩做**离线编译校验**：

```bash
sh Tools/TypeCheck/check.sh   # 期望输出 OK（exit 0）
```

- `Tools/TypeCheck/` 下的打桩（`UnityEngineStubs.cs` / `UnityEditorStubs.cs`）让游戏脚本能脱离 Unity 编译。
- 用到打桩里没有的 Unity API 时，**先补打桩再用**。
- 代码需 **C# 7.3 兼容**（`mcs` 限制，避免 C# 8+ 语法）。
- **编译通过 ≠ 画面 / 运行正确**：渲染、布局、点击等仍需在团结编辑器内实测。

### 编辑器工具（菜单 `Battle Bat/`）
- **① 一键准备出包（同步资源 + 补 Shader）**：把运行时 UI/资源同步进 `Resources`，补齐 Always Included Shaders。
- **② 出包前体检**：导出前检查常见问题。
- **创建启动场景并加入 Build**：生成启动场景并写入 Build 列表。
- **Sync Runtime Resources → Resources** / **Create Test Sandbox** 等辅助项。

### 外部素材
`asset_downloader.py` / `asset_organizer.py` 配合 `asset_manifest.json` 下载并整理 CC0 素材到工程；付费 / 需登录的素材（Synty、Asset Store、Mixamo）无法脚本化下载，需手动导入后再接线。

---

## 构建与发布（抖音小游戏）

1. 用团结引擎 (Tuanjie 2022.3.62t9 / 1.9.1) 打开工程。
2. 运行菜单 **Battle Bat → ① 一键准备出包**，再运行 **② 出包前体检**。
3. 通过团结的抖音小游戏 (MiniGame) 导出流程生成小游戏包。
4. 抖音广告 / 触感通过 `Assets/_Project/Plugins/` 下的 `.jslib` 桥接。

---

## 文档

`doc/` 目录：

- `GDD_Core_Gameplay.md` — 核心玩法
- `GDD_Growth_System.md` — 成长系统
- `GDD_Monetization_Gear.md` — 装备与内购
- `GDD_Task_System.md` — 任务系统
- `Tech_Architecture.md` — 技术架构
- `Free_Assets_Guide.md` — 免费素材指南
- `抖音小游戏上架改造checklist.md` — 上架改造清单
- `需求/游戏设计1.0.md`、`需求/游戏需求设计1.0.md` — 需求与资源清单

---

## 安全提示

- `doc/图像生成.md` 含明文 API 密钥，请勿提交到公共仓库，并及时轮换。
- 提交前留意 `.env`、凭证等敏感文件不要入库。

---

**战蝠防线** — 守护最后防线，成为真正的战蝠指挥官。