Dice Roller & Parser / Парсер игральных костей

English Version | Русская версия

Парсер игральных костей

Этот парсер игральных костей возвращает объект, содержащий компоненты броска. Он поддерживает полную спецификацию Roll20 Dice Specification (с некоторыми изменениями) и русские операторы.

Быстрый старт

Установка

Установите библиотеку с помощью pnpm:

pnpm add @ttg-club/dice-roller-parser

Использование

Импортируйте библиотеку в ваш проект:

ES Modules

import { DiceRoller } from '@ttg-club/dice-roller-parser';

CommonJS

const { DiceRoller } = require('@ttg-club/dice-roller-parser');

Создайте экземпляр класса DiceRoller и используйте его для выполнения бросков:

const diceRoller = new DiceRoller();

// Возвращает итоговое значение броска
// Пример: бросить 2 кубика d20 и оставить лучший результат
const roll = diceRoller.rollValue('2d20kh1');
// Или на русском:
// const roll = diceRoller.rollValue('2к20вл1');

console.log(roll);

// Возвращает объект, представляющий детали броска
const rollObject = diceRoller.roll('2d20kh1');

console.log(rollObject.value);

Операторы

Библиотека поддерживает операторы на английском и русском языках.

Список операторов

Использование

Библиотека предоставляет два класса: DiceRoller и DiscordRollRenderer.

DiceRoller

Класс DiceRoller управляет парсингом строки с кубиками и выполнением бросков.

// Создает новый экземпляр класса DiceRoller
const roller = new DiceRoller();

Опции конструктора

Вы можете указать свой генератор случайных чисел или ограничить количество бросков.

// Кастомный генератор (всегда возвращает 0.5)
const customRoller = new DiceRoller(() => 0.5);

// Лимит 100 бросков на кость
const limitedRoller = new DiceRoller(null, 100);

Методы класса

• rollValue(input): Возвращает числовое значение.
• roll(input): Возвращает полный объект броска.
• parse(input): Возвращает структуру парсинга без броска.

DiscordRollRenderer

Класс DiscordRollRenderer принимает результат броска и преобразует его в строку markdown для Discord.

const renderer = new DiscordRollRenderer();
const roll = roller.rollValue('2d20kh1');
const render = renderer.render(roll);
console.log(render);

Типы возвращаемых данных

Библиотека возвращает типизированные объекты. Полные детали см. в TypeScript интерфейсах в исходном коде или в сгенерированных типах.

Разработка

Склонируйте репозиторий и установите зависимости:

pnpm install

Сборка проекта:

pnpm build

Запуск тестов:

pnpm test

Авторы

Это форк проекта dice_roller от Ben Morton. Ранее поддерживался Frank Ali, а теперь TTG Club.

Основано на 3d-dice/dice-roller-parser.

Dice Roller & Parser

This dice roller is a string parser that returns an object containing the component parts of the dice roll. It supports the full Roll20 Dice Specification (with some modifications) and Russian operators.

Quickstart

Installation

Install the library using pnpm:

pnpm add @ttg-club/dice-roller-parser

Usage

Import the library into your project:

ES Modules

import { DiceRoller } from '@ttg-club/dice-roller-parser';

CommonJS

const { DiceRoller } = require('@ttg-club/dice-roller-parser');

Then create a new instance of the DiceRoller class, and use it to perform some dice rolls:

const diceRoller = new DiceRoller();

// Returns the total rolled value
// Example: roll 2 d20 dice and keep the highest
const roll = diceRoller.rollValue('2d20kh1');

console.log(roll);

// Returns an object representing the dice roll
const rollObject = diceRoller.roll('2d20kh1');

console.log(rollObject.value);

Operators

This library supports both English and Russian operators.

List of Operators

Usage

This library exposes two classes, a DiceRoller and a DiscordRollRenderer.

DiceRoller

The DiceRoller class manages parsing of a dice string and performing rolls based upon the result.

// Creates a new instance of the DiceRoller class
const roller = new DiceRoller();

Constructor options

You can specify a custom random generator or limit the number of rolls.

// Custom random generator (always returns 0.5)
const customRoller = new DiceRoller(() => 0.5);

// Limit to 100 rolls per die
const limitedRoller = new DiceRoller(null, 100);

Class Usage

• rollValue(input): Returns the calculated number value.
• roll(input): Returns a full object representing the roll.
• parse(input): Returns the parsed structure without rolling.

DiscordRollRenderer

The DiscordRollRenderer class takes a rolled input and renders it to a markdown string compatible with Discord.

const renderer = new DiscordRollRenderer();
const roll = roller.rollValue('2d20kh1');
const render = renderer.render(roll);
console.log(render);

Output Types

The library returns strongly typed objects. See TypeScript interfaces in the source code for full details.

Development

Clone the repository and install dependencies:

pnpm install

Build the project:

pnpm build

Run tests:

pnpm test

Credits

This is a fork of Ben Morton's dice_roller project. It was previously maintained by Frank Ali and now by TTG Club.

Based on 3d-dice/dice-roller-parser.