# trpg-game

**Repository Path**: kang_weibing/trpg-game

## Basic Information

- **Project Name**: trpg-game
- **Description**: 使用 Java 8 构建完整高度优化的回合制战斗游戏
- **Primary Language**: Java
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-08-15
- **Last Updated**: 2025-08-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 使用 Java 8 构建完整高度优化的回合制战斗游戏

# 🎮 游戏战斗系统设计规范（V1.0）

高内聚 · 低耦合 · 可扩展的回合制战斗架构

最后更新：2025年8月14日 | 版本：V1.0

## 设计愿景

构建一个灵活、可配置、易于扩展的回合制战斗核心，支持角色成长、技能策略、装备搭配与沉浸式交互体验，为后续系统演进（文本GUI界面、AI自动战斗升级）奠定坚实基础。

## 一、项目初始化与系统架构设计

### 目标

建立**模块化、高内聚、低耦合**的系统架构，实现关注点分离（SoC），确保系统具备良好的可维护性、可扩展性与表现力。

### 架构设计原则

| 维度 | 目标说明 |
| --- | --- |
| ✅ 可维护性 | 模块职责单一，接口清晰，便于团队协作与后期重构 |
| 🔁 可扩展性 | 新增技能、状态、装备类型无需修改核心逻辑，支持热插拔 |
| ⚙️ 可配置性 | 属性成长曲线、克制系数、AI策略等通过外部配置文件（JSON/YAML）驱动 |
| 🎨 表现力 | 支持文本动画、状态特效、节奏控制，提升玩家沉浸感 |

### 包结构设计（Java 风格）

cn.boxtools.core

├── entity        → 核心实体：角色、技能、状态、装备

├── component     → 可复用组件：属性、状态管理器、AI行为树节点

├── service       → 业务逻辑：战斗计算、伤害判定、AI决策

├── manager       → 系统级管理器：战斗流程、状态池、事件总线

├── factory       → 工厂类：技能工厂、状态工厂、装备生成器

├── util          → 工具类：随机数生成、序列化、动画渲染、日志

├── ui            → 用户界面与文本动画渲染

└── config        → 配置加载模块：JSON/YAML 解析器、全局参数管理

### 架构核心理念

- **组合优于继承**：使用 `Component` 模式构建角色能力，避免“角色类爆炸”问题。
- **接口通信，松耦合**：所有模块通过接口交互。
- **工厂模式统一创建**：`SkillFactory` 负责实例化技能与状态。
- **观察者模式**：监听属性变更、状态生效等事件，实现事件驱动。
- **状态机驱动流程**：战斗流程由 FSM 控制，状态切换清晰。
- **命令模式封装动作**：将玩家/敌人操作封装为 `CombatCommand`，支持撤销、回放与网络同步。

### 设计模式应用表

| 模式 | 应用场景 | 优势 |
| --- | --- | --- |
| 组合模式 | `Character` 由 `AttributeComponent`, `StatusManager` 等组成 | 灵活扩展，避免继承层级过深 |
| 策略模式 | `DamageCalculator` 实现多种伤害公式 | 易于替换或新增计算方式 |
| 工厂模式 | `SkillFactory.create("Fireball")` | 解耦创建逻辑，支持配置化 |
| 观察者模式 | 属性变更通知 UI、动画系统 | 实现事件驱动，提升响应性 |
| 状态模式 | `CharacterState`：战斗中、眩晕、死亡等 | 避免 `if-else` 堆叠，状态切换清晰 |
| 命令模式 | 封装玩家/敌人动作为 `CombatCommand` | 支持撤销、回放、网络同步扩展 |

## 二、核心角色系统与属性管理

### 基础角色设计

创建 `CharacterBase` 抽象基类，封装以下基础属性：

| 属性       | 说明 |
|------------|------|
| `HP` / `MaxHP` | 当前生命值 / 最大生命值 |
| `MP` / `MaxMP` | 魔法值 / 最大魔法值 |
| `ATK`      | 攻击力（影响伤害输出） |
| `DEF`      | 防御力（物理减伤） |
| `MDEF`     | 魔法防御（魔法减伤） |
| `SPD`      | 速度（决定行动顺序） |
| `Level`    | 当前等级 |
| `EXP`      | 当前经验值 |

### 高级属性系统

| 类别 | 属性名 | 说明 |
| --- | --- | --- |
| 基础属性 | ATK, DEF, SPD, HP, MP | 角色成长核心 |
| 战斗属性 | CritRate, DodgeRate, CritDamage | 影响战斗表现 |
| 元素属性 | FireResist, WaterResist | 用于克制计算 |
| 状态抵抗 | PoisonResist, StunResist | 减少负面状态命中率 |

### 属性组合加成机制

| 类型 | 示例 | 计算方式 |
| --- | --- | --- |
| 加法叠加 | 装备+10 ATK | 累加：base + mod1 + mod2 |
| 乘法叠加 | 狂暴”Buff +50% ATK | 乘算：base × (1 + rate) |
| 取最大值 | 多个护盾效果 | 保留最高值 |
| 层数叠加 | 毒伤可叠加3层 | 每层独立计时 |

## 三、战斗流程与行动顺序控制

### 战斗状态机（State Machine）

\[战斗开始\]

↓

\[行动排序\] → \[AI决策\] → \[玩家输入\]

↓           ↓           ↓

\[执行动作\] ← ← ← ← ← ← ← ← ←

↓

\[状态更新\] → 检查中毒/灼烧等持续伤害

↓

\[状态检查\] → 是否死亡？是否结束？

↓

\[下一回合\] → 返回行动排序

↓

\[战斗结束\]

### 行动顺序机制

基于角色 **速度（SPD）属性** 排序，生成每回合行动队列。每回合重新计算顺序，支持“先制”、“延后”类技能影响。

### 状态生命周期管理

构建 `StatusManager` 统一管理角色状态：

- 中毒（每回合扣血）、眩晕（跳过回合）
- 增益（攻击力提升）、减益（防御下降）

每回合自动递减持续时间，到期自动清除。

## 四、伤害计算与战斗机制

### 基础伤害公式

`基础伤害 = max(1, 攻击方ATK - 防御方DEF)`

### 防御体系

区分 **物理防御（P-DEF）** 与 **魔法防御（M-DEF）**，技能类型对应不同防御计算路径。

### 元素克制关系

**克制链**：火 → 金 → 木 → 土 → 水 → 火

| 攻击方 | 防御方 | 效果 |
|--------|--------|------|
| 火     | 金     | ×1.5 倍伤害 |
| 金     | 木     | ×1.5 倍伤害 |
| 木     | 土     | ×1.5 倍伤害 |
| 土     | 水     | ×1.5 倍伤害 |
| 水     | 火     | ×1.5 倍伤害 |
| 反向克制 | | ×0.7 倍伤害（减伤） |

> ✅ 克制系数可配置，支持未来扩展新元素。

### 公式详解

| 步骤 | 公式 | 说明 |
| --- | --- | --- |
| 1. 命中判定 | 命中率 = 攻击方命中 - 防御方闪避 | 低于0%则必定闪避，高于100%则必定命中 |
| 2. 暴击判定 | 暴击率 = 攻击方暴击 - 防御方抗暴 | 成功则伤害 ×1.5 |
| 3. 基础伤害 | max(1, ATK - DEF) | 防御抵消 |
| 4. 克制系数 | 火→金: ×1.5，金→火: ×0.7 | 双向影响 |
| 5. 随机波动 | ±20% | 增加战斗不确定性 |
| 6. 最终伤害 | 基础 × 克制 × 暴击 × 波动 | 取整 |

### 示例：火球术攻击金系敌人

| 参数 | 值 |
|------|----|
| ATK | 100 |
| DEF | 60 |
| 基础伤害 | 40 |
| 元素克制（火→金） | ×1.5 → 60 |
| 暴击（×1.5） | 90 |
| 随机波动（+10%） | 99 |
| **最终伤害** | **99** |

## 五、技能系统与AI策略

### 技能类型扩展

| 类型 | 示例 | 特性 |
| --- | --- | --- |
| 物理 | 连斩、横扫 | 消耗MP，可暴击 |
| 元素魔法 | 火球术、雷击 | 属于特定元素，触发克制 |
| 治疗 | 治愈术、群体恢复 | 恢复HP，部分消耗MP |
| 控制 | 毒雾、眩晕术 | 附加状态，有触发概率 |
| 增益/减益 | 力量祝福、虚弱 | 影响己方或敌方属性 |

### 技能机制

- 消耗MP，设置冷却时间（CD）
- 支持概率触发特殊效果（如：30%中毒）
- 引入 **技能优先级系统**，决定AI释放顺序

### AI智能决策

- **目标选择策略**：<p></p><p></p><ul><p></p><p></p><li>优先治疗 HP &lt; 50% 的队友</li><p></p><p></p><li>优先攻击高威胁目标（高输出或低防御）</li><p></p><p></p></ul><p></p><p></p>
- **逃跑机制**：<p></p><p></p><p>成功率基于等级差动态计算：<code>逃跑率 = (我方等级 / 敌方等级) × 70%</code></p><p></p><p></p><p>受速度属性加成</p><p></p><p></p>

## 六、装备与物品系统

### 装备体系

| 类型 | 武器、衣服、帽子、腰带、鞋子             |
|------|----------------------------|
| 稀有度 | 普通 → 优良 → 精良 → 传说 → 史诗（5级） |
| 属性加成 | 每件提供1~4项属性（支持叠加）           |
| 等级要求 | 设置穿戴等级门槛                   |

### 装备机制

- 设置等级穿戴要求
- 提供 <code>equip()</code> 与 <code>unequip()</code> 方法，自动刷新角色属性
- 支持强化、镶嵌等扩展接口

### 背包管理系统

- 容量限制，支持物品分类（消耗品、装备、材料）
- 实现物品使用逻辑：<p></p><p></p><ul><p></p><p></p><li>恢复类药品 → 增加HP/MP</li><p></p><p></p><li>敌人战败后随机掉落物品</li><p></p><p></p></ul><p></p><p></p>
- 提供增删查改接口

## 七、成长系统与用户体验

### 角色成长机制

- 战斗获得经验值，达到阈值升级
- 每级提升基础属性（成长系数可配置）
- 特定等级解锁新技能

技能学习表：`Level → Skill` 映射

### 数据持久化

使用 **Jackson** 序列化技术保存：

- 角色状态（等级、属性、技能）
- 背包内容、装备信息

支持 `save()` 与 `load()` 功能

### 用户交互设计

通过 `Scanner` 实现控制台交互：

- 战斗中选择：攻击 / 技能 / 使用物品 / 逃跑
- 菜单导航清晰，反馈及时

### 文本动画特效

集成简易动画系统，增强视觉表现力：

| 动画类型 | 实现效果示例 |
| --- | --- |
| 攻击动画 | 显示角色动作 → 伤害数字弹出 → 暴击时闪烁 💥 CRITICAL! |
| 技能特效 | 火球术：🔥→💥；治疗：✨+50HP；毒雾：🟩☁️ 中毒！ |
| 状态动画 | 中毒：绿色波纹 ~ ~ ~；眩晕：✱ ✱ ✱ 环绕；增益：↑ ATK+20 |
| 装备反馈 | 角色图标随装备变化（如持剑🗡️、戴盔🛡️） |
> 使用 `Thread.sleep()` 控制帧率，加入 `>>>` 进度条提升沉浸感

## 八、战斗动画特效系统

### 动画框架设计

构建基于文本的 **逐帧动画引擎**，支持：
- 延迟播放
- 进度条模拟
- 异步显示（未来支持多线程渲染

### 核心动画类型

| 动画类型 | 实现效果示例 |
| --- | --- |
| 攻击动画 | 显示角色动作 → 伤害数字弹出 → 暴击时闪烁 💥 CRITICAL! |
| 技能特效 | 火球术：🔥→💥；治疗：✨+50HP；毒雾：🟩☁️ 中毒！ |
| 状态动画 | 中毒：绿色波纹 ~ ~ ~；眩晕：✱ ✱ ✱ 环绕；增益：↑ ATK+20 |
| 装备反馈 | 角色图标随装备变化（如持剑🗡️、戴盔🛡️） |
| 节奏控制 | 使用 Thread.sleep() 控制帧率，加入 >>> 进度条提升沉浸感 |

### 视觉元素建议

使用 Unicode 符号增强表现力：

- 🗡️ 攻击 | 🔥 火系 | ⚡ 雷系 | ✨ 治疗 | 🛡️ 防御
- 💀 死亡 | 🩸 流血 | 🟩 中毒 | ✅ 增益 | ❌ 减益

## 九、高级系统扩展

### 组队系统 (Team System)
- **队伍管理**：创建、解散、成员管理、申请机制
- **权限控制**：队长权限、转让队长、踢出成员
- **状态管理**：组建中、准备就绪、战斗中、已解散
- **最大人数**：支持1-5人组队，自动状态切换

### 宠物系统 (Pet System)
- **宠物类型**：狗、猫、鸟、马、龙，各有特色属性
- **成长机制**：经验值、等级、技能学习、属性提升
- **互动系统**：喂食、休息、训练、忠诚度管理
- **战斗系统**：宠物对战、技能使用、状态管理

### 公会系统 (Guild System)
- **公会管理**：创建、解散、成员管理、职位系统
- **职位体系**：会长、长老、成员，不同权限
- **资源捐献**：金币、材料捐献，公会升级
- **公会技能**：经验加成、金币加成、装备强化等

### 交易系统 (Trading System)
- **市场管理**：物品上架、购买、下架、过期清理
- **价格机制**：自由定价、交易记录、市场统计
- **搜索功能**：关键词、类型、价格范围筛选
- **安全机制**：卖家验证、交易确认、自动过期

### 副本系统 (Dungeon System)
- **副本类型**：森林洞穴、山地要塞、水下神殿、龙巢、远古高塔
- **难度设计**：1-10星难度，等级要求，人数限制
- **冷却机制**：24小时冷却，防止刷副本
- **奖励系统**：经验、金币、装备、材料、任务物品


## ✅ 总结

本系统设计遵循 **高内聚、可扩展、易维护** 的原则，融合了现代游戏开发的核心机制，具备以下优势：

- ✅ 模块清晰，便于团队协作
- ✅ 支持未来扩展（如多人战斗、联机、GUI界面）
- ✅ 强调用户体验与沉浸感
- ✅ 代码结构规范，利于测试与维护
- ✅ 高级系统完整，支持社交互动和团队协作