diff --git a/LICENSE b/LICENSE index 622df20..052d743 100644 --- a/LICENSE +++ b/LICENSE @@ -1,6 +1,6 @@ The MIT License (MIT) -Copyright (c) 2013 Codex +Copyright (c) 2013 Timothy Torres Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in diff --git a/README.md b/README.md index 6654706..560614b 100644 --- a/README.md +++ b/README.md @@ -1,185 +1,16 @@ RL-Dice ======= -A module to be used with conventional Roguelike dice. +A robust module to roll and manipulate roguelike dice. -Dice Index ----------- +Consult the [online documentation](https://timothymtorres.github.io/RL-Dice) for the API and usage examples. -({x}d{y}+{s}{z}^+{s}{r})x{v} +The dice module provides the following: -x - Number of dice -y - Faces of the dice -z - Bonus value to be added to the last roll result (can be negative) -r - Rerolls, if + then remove lowest rolls, if - then remove highest rolls -s - If double sign (++ or --) adds {z} value to ALL dice rolls and/or {r} rerolls to all dice rolls -v - Sets of dice used - -Examples: - - 1d6 = Roll 1 six sided die - 3d4 = Roll 3 dice with four sides - 2d4+1 = Roll 2 dice with four sides, add +1 to last roll - 3d3++1 = Roll 3 dice with three sides, add +1 to all rolls - 3d3--1 = Roll 3 dice with three sides, add -1 to all rolls - 2d6^+2 = Roll 4 dice with six sides, remove the two lowest rolls - 2d4^++1 = Roll 4 dice with four sides, remove the two lowest rolls - 3d4-2^-1 = Roll 3 dice with four sides, remove the highest roll, add -1 to last roll - (1d6)x1 = Roll 1 six sided die (one set) - (1d6)x3 = Roll 1 six sided die (three sets) - - The difference between 3d6 and (1d6)x3 is {3d3} vs {1d6, 1d6, 1d6} - Sets return MULTIPLE results where number of dice only returns a SINGLE result or... - You could use both! - - (3d3)x3 = Roll 3 six sided die (three sets) {3d3, 3d3, 3d3} +* Dice notation strings - used to create or roll dice instances +* Dice number/faces - can be increased or decreased +* Dice bonus - can be increased or decreased +* Dice rerolls - can reroll and filter out via highest or lowest results +* Dice sets - can return multiple results +* Dice pluralism - enable bonus or rerolls to individual dice or to all dice -Usage ------ - -First load the module: - - local dice = require('rl-dice/dice') - -Then to use, it is really simple: - - print(dice.roll(8)) -- 2 (ie. math.random(1, num)) - print(dice.roll({sets=5,faces=3}) -- 3, 1, 1, 2, 3 - print(dice.roll('3d6')) -- 12 - print(dice.getString({num=3, faces=6})) -- '3d6' - print(dice.getDice('3d6')) -- {num=3, faces=6} - print(dice.roll(Dice.getDice(dice.getString({set=3, faces=6}))) -- 2,6,1 - print(dice.roll(Dice.getString(dice.getDice('(1d6)x3')))) -- 2,6,1 - print(dice.chance(.72)) -- true (math.random() rolled .27) - print(dice.chance(.13)) -- false (math.random() rolled .51) -There are also additional dice roll methods not normally seen in roguelikes, such as applying bonuses to all dice and the ability to reroll dice. - -Methods -------- - -dice.roll(num/string/dice_tbl) or dice:roll() - - returns set1, set2, set3, etc. - -dice.chance(decimal) - - returns decimal >= math.random() - -dice.getString(dice_tbl) or dice:getString() - - returns "formatted dice string" - -dice.getDice(str) - - returns {formatted dice table} - -dice.setMin(minimum) - - sets the lowest possible roll minimum for class default (if nil allows negative results to be rolled) - - -Dice Table ----------- - - dice = { - num = (+)number, - faces = (+)number, - sets = (+)number, -- optional - bonus = (+ or -)number, -- optional - double_b = binary, -- optional (requires bonus) - rerolls = (+ or -)number -- optional - double_r = binary, -- optional (requires rerolls) - minimum = number/nil -- optional (nil results in class default (if any) ) - } - -Classes & Metamethods ---------------------- - -dice:new(num/string/dice_tbl, minimum) [returns roll obj] - - weapon = dice:new('1d6') -- '1d6' - -dice.__add [modify bonus] - - weapon = weapon + 4 -- '1d6+4' - -dice.__sub [modify bonus] - - weapon = weapon - 2 -- '1d6+2' - -dice.__mul [modify number of dice] - - weapon = weapon * 2 -- '3d6+2' - -dice.__div [modify dice faces] - - weapon = weapon / -2 -- '3d4+2' - -dice.__pow [modify dice rerolls] - - weapon = weapon ^ 1 -- '3d4+2^+1' - -dice.__mod [modify dice sets] - - weapon = weapon % 2 -- '(3d4+1^+1)x3' - -dice.__concat [modify double sign (for bonus or rerolls)] - - weapon = weapon .. '++^^' -- '(3d4++2^++1)x3' - weapon = weapon .. '+^' -- '(3d4+2^+1)x3' - -- '++' or '--' to enable double sign for bonus, '^^' to enable double sign for rerolls - -- '+' or '-' to enable single sign for bonus, '^' to enable single sign for rerolls - -dice.__tostring [returns dice str] - - print(weapon) -- '(3d4+2^+1)x3' - -Minimums --------- - -You can set minimums for the dice result for either the entire class, a single dice instance, or nil. (nil allows negative roll results) - -To set the class minimum: - - dice.setMin(0) -- Dice minimum for ALL results is now 0 - -To set a dice instance minimum: (the second argument in dice:new(dice_str, minimum)) - - dice:new('1d5', 1) -- Dice minimum for ONLY this dice instance is 1 - -A dice instance minimum overrides a class minimum. Therefore, - - dice.setMin(0) -- dice class min is 0 - dice_INST = dice:new('1d3-10', 1) -- dice inst min is 1 - print(dice_INST:roll()) -- 1 - - dice.setMin(nil) -- dice class min is nil (can roll negative results) - dice_INST = dice:new('1d3-5') -- dice inst min is nil as well - print(dice_INST:roll()) -- -3 - -Dice Strings ------------- - -The dice must follow a certain string format when creating a new dice object or it will raise an error. - - dice_str = '1d5' -- valid - dice_str = '3d5' -- valid - dice_str = '(1d3)x1' -- valid - dice_str = '1d2+1' -- valid - dice_str = '1d10^+1' -- valid - dice_str = '1d5+1^-2' -- valid - dice_str = '(1d3+8^+3)x3' -- valid - dice_str = ' 1d5' -- not valid (space in front of string) - dice_str = '+10d5' -- not valid - dice_str = '5d+5' -- not valid - dice_str = '3d4+^1' -- not valid - dice_str = '(1d3)x1+5' -- not valid (bonuses and rerolls have to be inside the sets parenthesis!) - dice_str = '3d4^3' -- not valid (reroll needs a + or - sign in front of it) - -Remember! ---------- - -* Error message will result if dice are incorrectly formatted. -* You must put a pos or neg sign in front of the bonus or reroll! (if you are going to use them) -* Double sign, bonus value, sets, and rerolls are optional, but number of dice and dice faces are NOT! -* When using dice.roll(), if dice result is 0 or neg, it will default to 1. (unless dice.minimum is set to another value) diff --git a/dice.lua b/dice.lua index fa5c0ae..8cd5a79 100644 --- a/dice.lua +++ b/dice.lua @@ -4,7 +4,31 @@ -- @copyright 2013 -- @license MIT/X11 -local dice = {} +local dice = { + _AUTHOR = 'Timothy Torres', + _URL = 'https://github.com/timothymtorres/RL-Dice', + _DESCRIPTION = 'A robust module to roll and manipulate roguelike dice.', + _LICENSE = [[ + MIT LICENSE + Copyright (c) 2013 Timothy Torres + Permission is hereby granted, free of charge, to any person obtaining a + copy of this software and associated documentation files (the + "Software"), to deal in the Software without restriction, including + without limitation the rights to use, copy, modify, merge, publish, + distribute, sublicense, and/or sell copies of the Software, and to + permit persons to whom the Software is furnished to do so, subject to + the following conditions: + The above copyright notice and this permission notice shall be included + in all copies or substantial portions of the Software. + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS + OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF + MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. + IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY + CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, + TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE + SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + ]] +} dice.minimum = 1 -- class default lowest possible roll is 1 (can set to nil to allow negative rolls) local random, max, abs, sort, match, format = math.random, math.max, math.abs, table.sort, string.match, string.format