Metadata-Version: 2.5
Name: nonebot-plugin-dnddicer
Version: 0.1.0
Summary: 专精 DND5e/5r 跑团的 NoneBot2 骰娘插件（屠龙骰）：掷骰表达式、角色卡与检定、属性生成、HP 管理、先攻列表、战斗轮等，命令手感对齐 nonebot-dicepp
Project-URL: Homepage, https://github.com/H-Elden/nonebot-plugin-dnddicer
Project-URL: Issues, https://github.com/H-Elden/nonebot-plugin-dnddicer/issues
Project-URL: Repository, https://github.com/H-Elden/nonebot-plugin-dnddicer.git
Author: Elden
License-Expression: MIT
License-File: LICENSE
Keywords: dice,dnd,dnd5e,nonebot,nonebot2,trpg,跑团,骰娘
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Games/Entertainment :: Role-Playing
Requires-Python: >=3.11
Requires-Dist: lark<2.0.0,>=1.1.0
Requires-Dist: nonebot-adapter-onebot<3.0.0,>=2.4.6
Requires-Dist: nonebot-plugin-localstore<1.0.0,>=0.7.4
Requires-Dist: nonebot2<3.0.0,>=2.5.0
Provides-Extra: dev
Requires-Dist: nonebot2[fastapi]<3.0.0,>=2.5.0; extra == 'dev'
Requires-Dist: nonebug<1.0.0,>=0.4.4; extra == 'dev'
Requires-Dist: pytest-asyncio<1.0.0,>=0.25.0; extra == 'dev'
Requires-Dist: pytest<9.0.0,>=8.3.0; extra == 'dev'
Description-Content-Type: text/markdown

# 屠龙骰（DNDDicer / nonebot-plugin-dnddicer）

> 专精 **DND5e / DND5r** 跑团的 [NoneBot2](https://nonebot.dev/) 骰娘插件（OneBot V11 适配器），
> 命令手感对齐 [nonebot-dicepp](https://github.com/pear-studio/nonebot-dicepp)（梨骰）。
>
> 当前版本：**v0.1.0**（第一期功能完整可用）· 完整使用手册见 **📖 [使用文档](./docs/index.md)**

## ✨ 简介

DNDDicer 的目标是填补「NoneBot 商店中缺少 **DND5e/5r 专业 + 现代维护 + 插件形态** 骰娘」的空位：
以 DicePP 掷骰引擎与命令手感为基准，做独立的、零配置可加载的 NoneBot 插件，供任何已有
机器人从商店安装即用。

- **掷骰引擎**：移植 nonebot-dicepp 的 AST 表达式引擎（Lark 文法），支持 `2d20kh1`、
  优势/劣势、爆炸骰、连掷、暗骰等 DicePP 完整语法面；
- **跑团全流程**：掷骰 → `.dnd` 属性生成 → 角色卡与检定/豁免/攻击点命令 → HP 管理
  （伤害掷骰、抗性/易伤、AOE 多目标结算、长休）→ 先攻列表与战斗轮；
- **规则范围**：仅 DND5e/5r——专精 DND 定位，不做 COC/d100 体系与 `.mode` 模式切换；
- **商店合规**：零配置可加载、本地存储走 `nonebot-plugin-localstore`、元数据完整、全程异步。

## 📖 使用文档

详细用法、输入/输出示例与常见问题见仓库 `docs/` 使用文档：

- [命令总表与快速开始](./docs/index.md) · [群管理与 FAQ](./docs/guide/faq.md)
- [掷骰语法](./docs/guide/roll-syntax.md) · [角色卡与检定](./docs/guide/character-card.md)
- [属性生成](./docs/guide/attributes.md) · [HP 管理](./docs/guide/hp-rest.md)
- [先攻列表](./docs/guide/initiative.md) · [战斗轮](./docs/guide/battle.md)

## 📦 安装

通过 NB-CLI（推荐，与商店安装方式一致）：

```bash
nb plugin install nonebot-plugin-dnddicer
```

或通过包管理器安装后，在 `pyproject.toml` 的 `[tool.nonebot]` 中声明加载：

```bash
pip install nonebot-plugin-dnddicer
```

```toml
[tool.nonebot]
plugins = ["nonebot_plugin_dnddicer"]
```

> 依赖：Python ≥ 3.11，NoneBot2 ≥ 2.5.0，OneBot V11 适配器（`nb plugin install` 会自动安装依赖）。

## ⚙️ 配置

插件**零配置即可加载运行**，以下配置项全部可选（在 `.env` / 环境变量中设置）：

| 配置项 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `dnddicer_command_priority` | `int` | `10` | 命令事件响应器基础优先级（越小越优先），与其他插件冲突时按需调整 |
| `dnddicer_default_face` | `int` | `20` | 全局默认骰面（DND 惯例 d20；已配置 `.dset` 的群以群配置为准，此项作兜底） |
| `dnddicer_enabled` | `bool` | `true` | 功能总开关，`false` 时只加载骨架、不注册命令 |
| `dnddicer_use_host_command_starts` | `bool` | `false` | 是否兼容宿主 `COMMAND_START` 起始符（NoneBot 默认 `/`，开启后 `/.help` 等亦可触发）。默认只匹配 `.` / `。`，避免 `/help`、`/bot` 等常见单词命令与其他插件同时命中（冲突） |

## 🎲 用法

> 命令以 `.`（或全角 `。`）开头，中英文别名对齐 DicePP；命令起始符默认仅 `.` / `。`，
> 如需用宿主斜杠 `/` 等起始符触发（如 `/.help`），请设置配置项 `dnddicer_use_host_command_starts=true`。
> **群聊服务默认关闭（白名单）**：需群主/管理员发送 `.bot on` 开启本群服务；`.bot off`
> 关闭后本群不再响应命令（`.bot` 本身不受影响）。群聊中使用 `.bot` 需先 @ 本机器人；
> 私聊不受服务开关限制，可直接使用全部功能。

### 🎲 掷骰（群聊 / 私聊）

| 命令 | 说明 |
| --- | --- |
| `.r [N#][hs][表达式] [原因]` | 掷骰表达式（`#` 连掷 1~10、`h` 暗骰、`s` 只显数值；仅 d20 有大成功/大失败播报） |
| `.rh [表达式] [原因]` | 暗骰（群内提示、结果私聊） |

### 📋 角色卡与检定（群聊）

| 命令 | 说明 |
| --- | --- |
| `.角色卡模板` / `.角色卡记录 <模板>` | 查看示例卡 / 记录或覆盖角色卡（`$…$` 分段模板） |
| `.角色卡` / `.角色卡清除` / `.状态` | 查看 / 删除角色卡 / 查看 HP 与生命骰摘要 |
| `.力量检定` / `.察觉检定+1` 等 | 属性/技能/先攻检定点命令，自动代入调整值/熟练/加值（`2#` 连掷、`+d4` 等可追加） |
| `.体质豁免` / `.敏捷攻击优势` 等 | 豁免/攻击点命令（原名直配，优势/劣势后缀） |
| `.先攻检定` | 掷先攻并自动写入本群先攻列表 |

### 🎯 属性生成（群聊 / 私聊）

| 命令 | 说明 |
| --- | --- |
| `.dnd [次数] [原因]` | 4D6K3 掷点生成六项属性（附合计与降序，自行分配给六属性） |

### ❤️ HP 与长休（群聊）

| 命令 | 说明 |
| --- | --- |
| `.hp [对象] 20/30 (5)` | 设置自己/队友 HP（含临时 HP） |
| `.hp [对象] -2d6+3` 等 | 伤害/治疗（支持掷骰表达式；目标后加 `抗性`/`易伤` 后缀可减半/加倍，分号分隔多目标同发结算） |
| `.hp` / `.hp list` / `.hp del` | 查看自己 / 本群列表 / 删除 |
| `.长休` | 长休结算（回满 HP、清临时 HP、回复一半生命骰） |

### ⚔️ 先攻与战斗轮（群聊）

| 命令 | 说明 |
| --- | --- |
| `.ri[修正] [名称/…]` | 掷先攻入表（`.ri20 地精` 固定值、`3#` 批量、`.先攻` 别名） |
| `.init` | 查看先攻列表（`del`/`clr`/`first`/`swap` 子指令） |
| `.br` | 新建战斗轮（清空先攻表） |
| `.回合` / `.轮次` | 查看/跳转当前回合与轮次（`.回合+2` 连续推进，轮到玩家自动 @ 提醒） |
| `.ed` | 结束当前回合并自动推进（`.结束` 别名） |

### ⚙️ 群管理（群聊）

| 命令 | 说明 |
| --- | --- |
| `.dset [表达式]` | 设置/查看群默认骰面（群主/管理员） |
| `.bot [on/off]` | 插件信息查询 / 本群服务开关（群主/管理员，需 @） |
| `.帮助` / `.help [命令]` | 命令总览 / 指定命令详细用法（如 `.help r`） |

> 一期范围外功能会**显式提示而非静默**：`.r exp` 期望值采样、`.r a/n` 特殊判定；
> 牌堆/随机表与规则查询（T2）、法术位/死亡豁免/BUFF 表（T3 候选）见下方路线。

## 📄 版本与路线

1. ✅ **v0.1.0**（第一期 = T0 + T1 + 战斗轮简化版 + `.bot` 服务开关）：掷骰引擎移植、`.r/.rh`、
   帮助、群配置（`.dset`）、角色卡与检定/豁免/攻击、`.dnd` 属性生成、HP 管理与长休
   （含抗性/易伤与 AOE 伤害掷骰）、先攻列表、战斗轮——全部落地，全量测试通过；
2. ⏳ **第二期 T2**：牌堆/随机表、规则查询；
3. ⏳（可选）**T3 增强期**：法术位管理（`.ss/.cast`）、死亡豁免闭环（`.ds`）、BUFF/临时加值表（`.buff`）等。

## 📦 本地开发

```bash
# uv 方式（推荐；或使用 pip 安装 .[dev]）
uv sync --group dev
uv run pytest
```

测试基于 [nonebug](https://github.com/nonebot/nonebug) 做 NoneBot 加载冒烟与全命令行为回归（与 NoneFlow 商店自动加载检查同思路）。

## 🤝 许可与致谢

- 本项目（业务层与工程骨架）以 **MIT License** 发布，见 [LICENSE](./LICENSE)。
- **掷骰引擎与命令语法移植自 [nonebot-dicepp](https://github.com/pear-studio/nonebot-dicepp)**
  （Copyright (c) 2022 pear-studio，MIT License）：相关文件头保留上游版权声明与 MIT 许可全文，来源按 MIT 要求在 LICENSE 中注明。
- 规则查询类资料内容**不随插件分发**（版权归原权利方/译者），需要时由使用者自行提供。
- 本项目与 nonebot-dicepp 无隶属关系，为独立命名的衍生/移植作品。
