GitHub repository
On this page

8bitskull/dicebag/dicebag.dicebag

Dicebag is a Defold extension containing probability functions designed specifically for games.

  • GitHub: 8bitskull/dicebag — pinned to 2fe3aed
    1. Pick a release from 8bitskull/dicebag releases and add its Source code (zip) URL (or a packaged .zip asset, if the library ships one) to game.project under [project] dependencies, then Fetch Libraries in the Defold editor.
    2. Run bunx @defold-typescript/cli resolve to materialize its types.
    3. Import it under a namespace alias of your choice:
      import * as dicebag from "dicebag.dicebag"

Functions

set_up_rng(seed?: number): number

Sets up the randomseed and clears the first number of random rolls.

Parameters

  • seed?: number — optional seed, if not specified a seed will be generated using socket.gettime().

Returns

  • number — the number used to seed the random function.

flip_coin(): boolean

Flip a coin.

Returns

  • boolean — true or false (50% chance).

roll_dice(num_dice: number, num_sides: number, modifier: number): number

Roll a number of dice, D&D-style. An example would be rolling 3d6+2. Returns the sum of the resulting roll.

Parameters

  • num_dice: number — Number of dice to roll.
  • num_sides: number — Number of sides on the dice.
  • modifier: number — Number to add to the result.

Returns

  • number — Sum of rolled dice plus modifier.

roll_special_dice(num_sides: number, advantage: number, num_dice: number, num_results: number): number

Roll a number of dice and choose one (or more) of the highest (advantage) or lowest (disadvantage) results. Returns the sum of the relevant dice rolls.

Parameters

  • num_sides: number — Number of sides on the dice.
  • advantage: number — If true, the highest rolls will be selected, otherwise the lowest values will be selected.
  • num_dice: number — Number of dice to roll.
  • num_results: number — How many of the highest (advantage) or lowest (disadvantage) dice to sum up.

Returns

  • number — Sum of the highest (advantage) or lowest (disadvantage) dice rolls

roll_custom_dice(num_dice: number, sides: Array<[ number, number ]>): number

Roll custom dice. The dice can have sides with different weights and different values.

Parameters

  • num_dice: number — How many dice to roll.
  • sides: Array<[ number, number ]> — A table describing the sides of the die in the format [[weight1, value1], [weight2, value2], ...].

Returns

  • number — The sum of the values as specified in the table sides.

bag_create(id: string | number | Hash, num_success: number, num_fails: number, reset_on_success: boolean)

Create a marble bag of green (success) and red (fails) 'marbles'. This allows you to, for example, make an unlikely event more and more likely the more fails are accumulated.

Parameters

  • id: string | number | Hash — A unique identifier for the marble bag.
  • num_success: number — The number of success marbles in the bag.
  • num_fails: number — The number of fails marbles in the bag.
  • reset_on_success: boolean — Whether or not the bag should reset when a successful result is drawn. If false or nil the bag will reset when all marbles have been drawn.

bag_draw(id: string | number | Hash): boolean

Draw a marble from a previously created bag.

Parameters

  • id: string | number | Hash — A unique identifier for the marble bag.

Returns

  • boolean — True or false

bag_reset(id: string | number | Hash)

Manually reset a marble bag. Will also be called when a marble bag is empty, or a success is drawn in a bag where reset_on_success is true.

Parameters

  • id: string | number | Hash — A unique identifier for the marble bag.

table_create(id: string | number | Hash, rollable_table: Array<[ number, any, boolean? ]>)

Create a rollable table. This is similar to a marble bag, except each entry can have a different weight, and can return any value (not just a boolean).

Parameters

  • id: string | number | Hash — A unique identifier for the rollable table.
  • rollable_table: Array<[ number, any, boolean? ]> — A table of weights, values and reset flags.

table_roll(id: string | number | Hash): any

Draw a random value from the rollable table created in table_create. The value will be removed from the table. If reset_on_roll is true, the table will reset. Otherwise, the table will reset when all values are drawn.

Parameters

  • id: string | number | Hash — A unique identifier for the rollable table.

Returns

  • any — The value specified in table_create.

table_reset(id: string | number | Hash)

Manually reset a rollable table. Will also be called when the rollable table is empty, or a drawn value where reset_on_roll is true.

Parameters

  • id: string | number | Hash — A unique identifier for the rollable table.