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

专精 DND5e / DND5r 跑团的 NoneBot2 骰娘插件（OneBot V11 适配器），致力于做功能最全面、体验最好的 DND 骰娘。

当前版本：v0.4.0 · 完整使用手册见 📖 使用文档

✨ 简介

DNDDicer 的目标是填补「NoneBot 商店中缺少 DND5e/5r 专业 + 现代维护 + 插件形态 骰娘」的空位：围绕 DND 跑团全流程持续做深做全，致力于提供功能最全面、体验最好的 DND 骰娘，零配置可加载，供任何已有机器人从商店安装即用。

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

📖 使用文档

详细用法、输入/输出示例与常见问题见使用文档（手册式分章，含跑团示例；在线版：https://h-elden.github.io/nonebot-plugin-dnddicer/，源文件在仓库 docs/）：

• 开始：快速开始 · 示例团与人物
• 第一章 · 基础操作：掷骰基础 · 掷骰进阶 · 生命值管理 · 先攻列表 · 战斗轮 · 规则查询
• 第二章 · 玩家进阶：角色卡与属性 · 检定与豁免 · 武器与攻击 · HP 进阶与长休
• 第三章 · DM 进阶：代掷与代操作 · 血量与伤害结算 · 查询范围
• 第四章 · 最佳实践：最佳实践
• 参考：命令总览 · 群管理与 FAQ · 自建查询服务

📦 安装

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

nb plugin install nonebot-plugin-dnddicer

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

pip install nonebot-plugin-dnddicer

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

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

⚙️ 配置

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

🎲 用法

命令以 .（或全角 。）开头；命令起始符默认仅 . / 。，如需用宿主斜杠 / 等起始符触发（如 /.help），请设置配置项 dnddicer_use_host_command_starts=true。群聊服务默认关闭（白名单）：需群主/管理员发送 .bot on 开启本群服务；.bot off 关闭后本群不再响应命令（.bot 本身不受影响）。群聊中使用 .bot 需先 @ 本机器人；私聊不受服务开关限制，但可用命令更少：角色卡、检定、HP、先攻等仅限群聊（差异见快速开始）。

DM 代操作（@ 提及目标）：多数带目标的命令支持用 @群成员 指定目标：直连该成员在本群的角色卡，不受同名 NPC/改名影响，且可与名称混写（.hp @玩家 -4d6、.hp @玩家;地精 -d4、.ri+3 @玩家、.init del @玩家、.回合 @玩家、.角色卡 @玩家、.力量豁免 @玩家、.先攻检定 @玩家 等）。完整机制见代掷与代操作，命令清单见命令总览 - @ 提及目标。

🎲 掷骰（群聊 / 私聊）

📋 角色卡与检定（群聊）

🗡️ 武器与攻击（群聊）

角色卡通过 $武器$ 段自定义武器/法术项：名称+命中加值,伤害表达式+类型，如 长剑+8,1d8+5挥砍；名称尾加 x 表示不可攻击检定，如 火球术x,8d6火焰。

骰娘只忠实执行、不判 AC、不自动补属性：

详见 武器与攻击。

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

❤️ 生命值管理（群聊）

基础用法见生命值管理，武器伤害写法与长休进阶见 HP 进阶与长休，DM 的结算打法见血量与伤害结算。

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

🔍 规则查询（群聊 / 私聊，需骰主开启）

规则查询默认关闭（dnddicer_query_enabled）：开启后群聊仍受本群服务开关管辖，私聊可用；查询内容来自《5e不全书》，只用于当次回复与短时内存缓存、不落盘、不随插件分发。详见规则查询。

⚙️ 群管理（群聊）

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

📄 版本与路线

1. ✅ v0.1.0（第一期 = T0 + T1 + 战斗轮简化版 + .bot 服务开关）：掷骰引擎移植、.r/.rh、帮助、群配置（.dset）、角色卡与检定/豁免/攻击、.dnd 属性生成、HP 管理与长休（含抗性/易伤与 AOE 伤害掷骰）、先攻列表、战斗轮，全部落地、全量测试通过；
2. ✅ v0.2.0：HP 抗性/易伤与 AOE 掷骰完善、.dnd 原因 兼容修复、NPC/怪物血量（三层目标搜索、先攻列表与 .hp list 联动、.ri 入表自动回满、.npc 持久/临时 跨战斗保持）、.dndx 属性名绑定掷点；
3. ✅ v0.2.1：@ 提及目标（DM 可代玩家操作 .hp/.npc/.ri/.回合 等、查看角色卡）、玩家名称显示统一回退链、.hp del/clr 语义修订（仅作用 NPC 血量）、优势/劣势别名粘连等真机反馈修复；
4. ✅ v0.2.2：掷骰说明文字按四则运算还原（常量复合子表达式与一元负号）、私聊下的群聊限定命令不再静默与 .bot 私聊文案修正；使用文档站上线（手册式 15 页，随发版自动部署）；
5. ✅ v0.3.0：自定义武器与攻击系统（$武器$ 段、.武器名攻击 / .武器名伤害、.设置武器 / .删除武器）、.hp 伤害位置武器写法（含来源括号代发）；属性攻击命令退役（破坏性变更，旧卡需重录）、文档站新增《武器与攻击》页与全站同步；
6. ✅ v0.4.0：规则查询（.查询 / .搜索 两种检索、候选选择与翻页、.查询图片 图片模式、.查询范围 书目限定与 .规则书）；文档站按前置条件重排为四章（基础操作 / 玩家进阶 / DM 进阶 / 最佳实践）；大成功/大失败播报另起一行、修饰符回显加括号；
7. ⏳ 第二期余下：牌堆/随机表；
8. ⏳（可选）T3 增强期：法术位管理（.ss/.cast）、死亡豁免闭环（.ds）、BUFF/临时加值表（.buff）等。

每版完整变更（新增 / 变更 / 修复 / 文档）见 CHANGELOG.md。

📦 本地开发

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

测试基于 nonebug 做 NoneBot 加载冒烟与全命令行为回归（与 NoneFlow 商店自动加载检查同思路）。

🤝 许可与致谢

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