内容
# battlecast-engine
一款适用于D&D 5e（2024 SRD）的规则引擎和战斗状态引擎，内置[MCP](https://modelcontextprotocol.io)服务器。从[battlecast.gg](https://battlecast.gg)中提取，该浏览器端战术战斗模拟器在生产环境中运行此引擎 - 这里的每条规则都经过数千次模拟战斗的测试。
任何通过MCP连接的LLM代理都可以构建战斗场景、运行战术模拟战斗，并进行规则验证的状态编辑。任何TypeScript程序都可以直接使用同一个引擎作为库。战斗是确定性的，当使用相同的种子时，结果相同，字节对字节 - 这使其同样适用于DM助手、战斗场景平衡、回归测试和LLM基准测试。
**内部功能**
- 骰子、攻击、优势/劣势、暴击、豁免检定
- 完整的伤害流程：抵抗、免疫、脆弱性、临时生命值、不死族坚韧、死亡守卫、死亡豁免、濒死状态
- 具有持续时间和豁免检定计时器的状态，持续效果
- 网格上的 footprint-aware 移动和碰撞（从中型到庞大），地形阻挡，视线
- 范围效果几何形状（锥形、线形、球形），法术施放，专注，增益
- 完整的战斗AI（瞄准、多攻击、智能移动、传奇动作），具有四种团队战术
- 317个SRD怪物和12个英雄职业，等级1-20
- 种子化、可重现的战斗：相同的种子，相同的结果，字节对字节
**文档**
- [docs/rules-coverage.md](docs/rules-coverage.md) - 精确的5e规则实现情况，已针对源代码进行验证，包括诚实的空白
- [docs/api.md](docs/api.md) - 库API
- [docs/mcp-tools.md](docs/mcp-tools.md) - 每个MCP工具的参数和示例会话
## MCP 服务器
```bash
npx battlecast-engine mcp
```
克劳德代码：
```bash
claude mcp add battlecast -- npx battlecast-engine mcp
```
或在任何MCP客户端配置中：
```json
{
"mcpServers": {
"battlecast": { "command": "npx", "args": ["battlecast-engine", "mcp"] }
}
}
```
### 工具
| 分组 | 工具 |
|---|---|
| 库 | `search_monsters`, `get_monster`, `list_heroes` |
| 生命周期 | `create_encounter`, `add_creature`, `start_battle`, `get_state`, `get_creature`, `list_encounters`, `delete_encounter` |
| 模拟 | `run_round`, `run_battle`, `set_team_tactics` |
| DM 控制 | `apply_damage`, `apply_healing`, `add_condition`, `remove_condition`, `move_creature`, `remove_creature` |
| 持久化 | `export_encounter`, `import_encounter` |
| 骰子 | `roll_dice` |
一个典型的会话：`create_encounter`（可选种子），`add_creature`几次，`start_battle`，然后是`run_round`进行逐轮叙述玩法或`run_battle`获得即时结果。`get_state`返回一个紧凑的快照，设计供语言模型读取。逐轮叙述直接来自引擎的战斗日志：
```
第 1 轮：
[R1] 5 级战士向哥布林战士 2 移动 30 英尺。
[R1] 5 级战士用标枪（15 vs AC 15）击中哥布林战士 2，造成 10 点穿刺伤害！
[R1] 哥布林战士 2 已被击杀！
[R1] 5 级战士使用动作激增，获得额外的攻击动作！
```
## 库
```ts
import { Encounter } from 'battlecast-engine';
const enc = new Encounter({ gridSize: 20, seed: 42 });
enc.addCreature({ monster: 'Goblin Warrior', team: 'red', count: 4 });
enc.addCreature({ heroClass: 'Fighter', heroLevel: 5, team: 'blue' });
enc.start();
const round = enc.runRound(); // AI 扮演一整轮
console.log(round.logs.map(l => l.details).join('\n'));
enc.damage('goblin-warrior-red-1', 8, 'fire'); // 完整的规则流程
const result = enc.runToCompletion(50);
console.log(result.winner);
```
更低级别的引擎基元（`applyDamage`、`resolveAttack`、`moveToward`、`executeRound`，以及怪物和英雄数据）也被导出 - 请参见 [docs/api.md](docs/api.md) 和 `src/index.ts`。
## 使用 battlecast-engine 构建？
代码使用MIT许可证，因此您只需保留许可证文件即可。但如果该引擎让您避免重新实现机会攻击，链接回去意味着很多，并有助于项目：
- 在您的README或致谢中链接到 [battlecast.gg](https://battlecast.gg) 或此仓库
- 在您的应用程序的关于屏幕中添加一行“powered by battlecast-engine”
如果您使用它构建了某些东西，请打开一个问题并说声 hello - 酷项目会列在这里。
## 开发
```bash
npm install
npm run build # tsc
npm test # vitest - 引擎套件从 BattleCast + API 测试移植
```
阅读 `DESIGN.md` 以了解架构、与 BattleCast 的同步合约和路线图。
## 许可证和 SRD 归属
代码使用MIT许可证（参见LICENSE）。
怪物、法术和职业数据来自龙与地下城5.2系统参考文档，由Wizards of the Coast以CC-BY-4.0许可发布。
