diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 301 |
1 files changed, 301 insertions, 0 deletions
diff --git a/README.md b/README.md new file mode 100644 index 0000000..2011ca9 --- /dev/null +++ b/README.md @@ -0,0 +1,301 @@ +# OneRoll - 高性能骰子表达式解析器 + +一个用 Rust 实现并通过 PyO3 绑定到 Python 的骰子表达式解析器。支持复杂的骰子表达式解析、各种修饰符和数学运算。 + +## 特性 + +- 🚀 **高性能**: 使用 Rust 实现核心逻辑，性能优异 +- 🎲 **功能丰富**: 支持各种骰子表达式和修饰符 +- 🐍 **Python 友好**: 提供清晰的 Python 接口 +- 🎨 **美观界面**: 支持 Rich 和 Textual 的交互式界面 +- 📊 **统计功能**: 内置统计和分析功能 +- 🛠️ **易于使用**: 支持命令行、交互式和 TUI 模式 + +## 安装 + +### 从源码构建 + +```bash +# 克隆仓库 +git clone https://github.com/HydroRoll-Team/oneroll.git +cd oneroll + +# 安装 maturin +pip install maturin + +# 构建并安装 +maturin develop +``` + +### 安装 Python 依赖 (可选) + +```bash +pip install rich textual +``` + +## 快速开始 + +### 作为 Python SDK 使用 + +```python +import oneroll + +# 基本使用 +result = oneroll.roll("3d6 + 2") +print(f"总点数: {result['total']}") + +# 使用 OneRoll 类 +roller = oneroll.OneRoll() +result = roller.roll("4d6kh3") +print(f"4d6kh3 = {result['total']}") + +# 简单投掷 +total = oneroll.roll_simple(3, 6) +print(f"3d6 = {total}") +``` + +### 命令行使用 + +```bash +# 单次投掷 +python -m oneroll "3d6 + 2" + +# 统计模式 +python -m oneroll --stats "3d6" --times 100 + +# 交互式模式 +python -m oneroll + +# 终端用户界面 (TUI) +python -m oneroll --tui +``` + +## 支持的表达式 + +### 基本骰子 +- `3d6` - 投掷3个6面骰子 +- `1d20` - 投掷1个20面骰子 +- `2d10` - 投掷2个10面骰子 + +### 数学运算 +- `3d6 + 2` - 骰子结果加常数 +- `2d6 * 3` - 骰子结果乘以常数 +- `(2d6 + 3) * 2` - 括号和复合运算 + +### 修饰符 +- `!` - 爆炸骰子: `2d6!` +- `kh` - 取高: `4d6kh3` (取最高的3个) +- `kl` - 取低: `4d6kl2` (取最低的2个) +- `dh` - 丢弃高: `5d6dh1` (丢弃最高的1个) +- `dl` - 丢弃低: `5d6dl1` (丢弃最低的1个) +- `r` - 重投: `3d6r1` (重投小于等于1的结果) +- `ro` - 条件重投: `4d6ro1` (条件重投一次) + - `u` - 去重: `4d6u` (相同点数只计一次) + +### 复合表达式 +- `6d6dl2kh3` - 丢弃最低2个，然后取最高3个 +- `4d6!kh3` - 爆炸骰子，取最高3个 +- `3d6r1 + 2d8ro2` - 重投组合 + +## API 参考 + +### 便捷函数 + +```python +# 解析并计算骰子表达式 +result = oneroll.roll(expression: str) -> Dict[str, Any] + +# 简单骰子投掷 +total = oneroll.roll_simple(dice_count: int, dice_sides: int) -> int + +# 多次投掷 +results = oneroll.roll_multiple(expression: str, times: int) -> List[Dict[str, Any]] + +# 统计投掷 +stats = oneroll.roll_statistics(expression: str, times: int) -> Dict[str, Any] +``` + +### OneRoll 类 + +```python +roller = oneroll.OneRoll() + +# 解析并计算骰子表达式 +result = roller.roll(expression: str) -> Dict[str, Any] + +# 简单骰子投掷 +total = roller.roll_simple(dice_count: int, dice_sides: int) -> int + +# 带修饰符的投掷 +result = roller.roll_with_modifiers( + dice_count: int, + dice_sides: int, + modifiers: List[str] +) -> Dict[str, Any] +``` + +### 常用表达式常量 + +```python +# D&D 常用投掷 +oneroll.CommonRolls.D20 # "1d20" +oneroll.CommonRolls.D20_ADVANTAGE # "2d20kh1" +oneroll.CommonRolls.D20_DISADVANTAGE # "2d20kl1" +oneroll.CommonRolls.ATTRIBUTE_ROLL # "4d6kh3" +``` + +## 使用模式 + +### 1. 命令行模式 + +```bash +# 直接投掷 +python -m oneroll "3d6 + 2" + +# 统计模式 +python -m oneroll --stats "3d6" --times 100 + +# 显示版本 +python -m oneroll --version +``` + +### 2. 交互式模式 + +```bash +python -m oneroll +``` + +支持的命令： +- `help` - 显示帮助 +- `history` - 显示投掷历史 +- `stats <表达式> <次数>` - 统计投掷 +- `clear` - 清空历史 +- `quit/exit` - 退出程序 + +### 3. 终端用户界面 (TUI) + +```bash +python -m oneroll --tui +``` + +特性： +- 美观的终端界面 +- 快速投掷按钮 +- 投掷历史记录 +- 统计功能 +- 键盘快捷键支持 + +### 4. Python SDK 模式 + +```python +import oneroll + +# 基本使用 +result = oneroll.roll("3d6 + 2") + +# 统计功能 +stats = oneroll.roll_statistics("3d6", 100) +print(f"平均值: {stats['mean']:.2f}") + +# 多次投掷 +results = oneroll.roll_multiple("2d6", 10) +totals = [r['total'] for r in results] +``` + +## 示例 + +### D&D 游戏示例 + +```python +import oneroll + +roller = oneroll.OneRoll() + +# 属性投掷 +attr_result = roller.roll(oneroll.CommonRolls.ATTRIBUTE_ROLL) +print(f"属性投掷: {attr_result['total']}") + +# 攻击投掷 +attack_roll = roller.roll("1d20 + 5") +print(f"攻击投掷: {attack_roll['total']}") + +# 伤害投掷 +damage_roll = roller.roll("2d6 + 3") +print(f"伤害投掷: {damage_roll['total']}") +``` + +### 统计示例 + +```python +import oneroll + +# 统计 3d6 投掷 100 次 +stats = oneroll.roll_statistics("3d6", 100) + +print(f"最小值: {stats['min']}") +print(f"最大值: {stats['max']}") +print(f"平均值: {stats['mean']:.2f}") +print(f"总和: {stats['total']}") +``` + +## 项目结构 + +``` +OneRoll/ +├── src/ # Rust 源码 +│ ├── lib.rs # 主入口文件 +│ ├── errors.rs # 错误类型 +│ ├── types.rs # 数据类型 +│ ├── calculator.rs # 计算逻辑 +│ ├── parser.rs # 解析逻辑 +│ ├── python_bindings.rs # Python 绑定 +│ └── oneroll/ +│ ├── __init__.py # Python 包入口 +│ ├── __main__.py # 命令行入口 +│ ├── _core.pyi # 类型注解 +│ └── grammar.pest # 语法定义 +├── examples/ # 示例代码 +├── tests/ # 测试代码 +└── docs/ # 文档 +``` + +## 开发 + +### 构建 + +```bash +# 开发构建 +maturin develop + +# 发布构建 +maturin build +``` + +### 测试 + +```bash +# 运行测试 +python -m pytest tests/ + +# 运行示例 +python examples/sdk_example.py +``` + +## 许可证 + +MIT License + +## 贡献 + +欢迎提交 Issue 和 Pull Request！ + +## 更新日志 + +### v0.0.1 +- 初始版本 +- 支持基本骰子表达式 +- 支持数学运算和修饰符 +- 提供 Python SDK 接口 +- 支持命令行和交互式模式 +- 支持 TUI 界面 +- 内置统计功能 |