table-roller v0.1.0
Table Roller
A framework to create RPG like tables, where each row has a random probability to be selected in a pré-configured range.
Installation
$ npm install table-roller
Example
Note: Look on test folder test/examples.test
for a small random treasure generator.
Imagine classic Dungeons and Dragons:
1 -> Critical miss
2-19 -> Hit
20 -> Critical Hit
This table above can be write on table roller format as:
import TableRoller from 'table-roller';
const hitRollerTable = {
name: 'HitRoller',
roll: '1d20',
rows: [
{ roll: 1, result: { resultType: 'roll', name: 'Critical Miss' } },
{ start: 2, end: 19, result: { resultType: 'roll', name: 'Hit' } },
{ roll: 20, result: { resultType: 'roll', name: 'Critical Hit' } }
]
}
const table = new TableRoller();
table.register(hitRollerTable);
return table
.roll({
type: 'HitRoller',
})
.then(response => {
console.log(response.toJSON());
});
With this sample configuration, each time roll() is called, a new result will be randomly returned from table above, with respective probabilities.
Features
- Each table row may have one or more results.
- Result may be everything you want, categorized by its resultType.
- Result may take the state to another table, to bge rolled by N more.
- To each added table, the system status is updates with current situation.
- Inconsistent status cant be roller.
- Internationalization support.
- Custom input parameters.
- Default Rolls: Table may have default rolls, that are rolled with 100% of probability.
API
Tables
Tables are configured on JSON format. You can register one or multiple tables at a time.
Some tables can be requested on demand (see bellow). Because of this, register
and registerAll
return a promise, that when it resolves, an object with current status.
register
Register a single table.
More information about table structure bellow.
registerAll
Register an array of tables.
More information about table structure bellow.
status
Status is an object returned in each register
or registerAll
. It contains following structure.
{
arguments: [],
ranges: {},
warnings: [],
errors: [],
missingReferences: {},
}
- arguments: List of configured arguments.
- ranges: Range of each argument. If it is possible to compute, it will be listed here.
- warnings: Show problems in your table that do not block rolling process.
- errors: Errors that block your rolling process.
missingReferences: When configuring tables that result in another table roll, missing references will be shwon here.
addLanguages
It is possible to add a internationalization option with addLanguages
.
A language is set in the format of a table, like other tables.
Look on Language tables bellow.
roll & rollAll
Roll one or more tables by its names and custom arguments.
Each roll has a type, that is the name of a table that will be rolled.
Other thing that can be specified on roll moment is custom arguments, like this:
const hitRollerTable = {
name: 'HitRoller',
roll: '$target',
rows: [
{ roll: 1, result: { resultType: 'roll', name: 'Critical Miss' } },
{ start: 2, end: 19, result: { resultType: 'roll', name: 'Hit' } },
{ roll: 20, result: { resultType: 'roll', name: 'Critical Hit' } }
]
}
...
return table
.roll({
type: 'HitRoller',
args: {target: 20},
})
.then(response => {
console.log(response.toJSON());
});
RollResult
When a roll or a group of rolls is finished, it return a promise that resolves into a RollResult.
RollResult is created with a list of results grouped in a 'General' category.
As a result has always a resultType, there is a group of operation to create new groups of results.
groupTypeBy(resultType{String}, newCategoryNAme{String})
Create a new category called 'newCategoryNAme' and add all resultType inside.
toJSON
Print all items as JSON.
listNames
List all names by category.
listFull
List all data about each item by category.
Table structure
const sampleTable = {
name: 'SampleTable',
roll: '1d100x80',
rows: [{
roll: 1,
result: [],
}, {
start: 2,
end: 99,
result: [{
type: 'roll_reference',
rule: '2d6',
name: 'Gem-10',
}]
}, {
roll: 100,
result: [{
type: 'reference',
name: 'SampleB',
}]
}],
defaultResults: [{
type: 'roll',
rule: '6d6x100',
item: { resultType: 'item', name: 'Some Awesome Item' },
}],
}
name
Every table must have a name.
roll
Roll define how a table is rolled, it can be done in 2 ways:
Custom argument
You can specify a roll with $variable_name
. Later, you can set variable_name
on rolls and this table will be rolled with this value.
Dice Roll
You can specify a roll like a Dice Roll, from RPG games.
With 2d10x2, two dices of 10 faces will be rolled, on the end, multiplied by 2.
First number represent the number of times that a dice will be rolled. Second number it the number of faces in a dice (or the random number limit, 10 menas a number between 1-10) and the last number is a multiplier applied on final result.
defaultResults
Default roll represent a row that has 100% of probability to be hit when rolling a table. Multiple results can be specified. Look for Results bellow.
rows
An array of rows. Each row has a hit range and an array of results.
row: [{
roll: 1, // Single value range.
results: { // Single result.
resultType: 'sampleType',
name: 'Sample Name',
}
}, {
start: 2,
end: 10,
results: [{
...
}]
}]
Results
Results are specified on table rows or on defaultResults
. A result may be:
- End Result: Results configures to be the final result on a tables system.
- roll: roll of an End Result.
- reference: Reference to another table.
- roll_reference: Roll of a reference to another table.
End Result
Money example.
{
resultType: 'money',
name: 'PO'
}
roll
Roll of money example. Will roll 3d6x10 of final item
.
{
type: 'roll',
rule: '3d6x10',
item: { resultType: 'money', name: 'PE' },
}
reference
Roll another table.
{
type: 'reference',
name: 'MagicItemTable',
}
roll_reference
Roll n times another table.
{
type: 'roll_reference',
rule: '2d6',
name: 'MagicItemTable'
}
Language Table structure
A language table structures is defined by a JSON, with results categories and names.
{
type: {
PC: { name: 'PC', description: 'Peças de Cobre' },
PP: { name: 'PP', description: 'Peças de Prata' },
PE: { name: 'PE', description: 'Peças de Electro' },
PO: { name: 'PO', description: 'Peças de Ouro' },
PL: { name: 'PL', description: 'Peças de Platina' },
},
gem: {
'Azurita': { name: 'Azurita', description: 'azul escuro mosqueado opaco' },
}
}
Internal system will look on tables like this for first key element, who must have the same name of resultType on items. Later it will look inside for item name.
In the end, the final block with name and description is attached to roll result.
License
Copyright (c) 2017 Diego Laucsen and other contributors; Licensed under MIT.
7 years ago