Chartopia User Guide

We've been inspired by communities of roleplayers around the world into creating a web based service that is the perfect companion tool for any Dungeon Master/Game Master/Player. It provides easy access and quick rolling on a vast collection of tables without having to sift through piles of books to find that perfect chart for your gaming needs. This site is available is mobile friendly although there is a native Android app available with a subset of the functionality.

Chartopia is part chart discovery tool (i.e. search) part creation tool (editor), part game preparation tool for random tables. Think of it as like the Pinterest or Deviant Art of random tables.

Important note: please ensure all tables you create have an offline backup. Whilst we have no intentions of wiping the database we do not want your hard work to be lost in these early days.


The front page of Chartopia is a search engine. Simple typing in search terms will reveal random tables that match the criteria. If you log in, you have access to some filters that can restrict the search to your own tables.

After seeing the results of a search, tag recommendations are available to help refine your search.

Quick rolling

All tables that are either your own or those that have been shared by the community are able to be rolled on using the "Roll" button. Doing so will generate a random result from the respective table and display it to you. If you're curious to see more detail on the chart, it's possible to view it.

Saving a quick roll

All rolls can be saved for future reference. Often there are situations where a rolled result is useful to keep for later, such as an NPC's name or perhaps an exotic artifact that has been discovered. Rolled results can be saved from the quick roll dialog and accessed from the "Roll history" where extra information can be added to provide some contextual information about the roll (if required).

Viewing a chart

The quick roll feature allows one to avoid having to closely examine a table, but sometimes one like to know exactly what the table is composed of. Charts can be viewed in their entirety including all the syntax highlighting for features such as equations, rollable lists, and linked charts (to be explained later).

Creating a simple chart

To create a simple chart, click on Create > Create Chart.

You should now see the following screen.

Of note are the following

  • The title is set at the top of the main area
  • The side bar to the left has minor meta data settings such as visibility settings and image.
  • Under the title there is meas of revealing more meta data settings such as a more detailed description.
  • The chart occupies the rest of the main edit area.

Inferred rows

By default, a new chart is a d12 random table with a single column called Result and a row 1 value of empty. Notice how rows 2-12 are all inferred. Inferred values are automatic/implied copies of the previous row.

Inferred rows have serve two purposes:

  • It avoids copy paste by auto filling data to either the end of the table or to the next occupied table row (whichever is first).
  • When the chart is viewed outside of the editor, the dice value column will collapse inferred rows together to form dice ranges. e.g. 1-4 = copper, 5-8 = silver, 9-11 = gold, 12 = platinum.

Inserting result data

To add/edit data to the table, click a table cell. This will allow in-place rich text formatting. By highlighting text, a popup can be used to apply basic formatting. Note that it's impossible to have a table cell that is just whitespace (empty or with just spaces) and empty will be used as a placeholder.

Tip: As a shortcut to edit the very next cell, press ctrl+enter (NB: currently only works when Chartopia domain language features aren't present in the cell).

Chartopia domain language

Chartopia syntax constructs are put inside curly brackets, e.g. {item}.

The following characters are treated specially by Chartopia: {, }, ?, |, [ and ]. They can be escaped by using a backslash, for example \{. If you want to use special characters inside Chartopia syntax constructs, i.e. inside constructs surrounded by curly brackets, they must be escaped. If you want the result to look like \{ inside the Chartopia syntax construct, it should be typed as \\{.

The following table contains examples with explanations.

Example Rendered Type Meaning
{item1|item2|item3} Resolve: item1|item2|item3 Rollable list Choose randomly between item1, item2 or item3
{item|} Resolve: item| Rollable list Choose randomly between item or nothing
{item1|item2 with \| pipe|item3} Resolve: item1|item2 with | pipe|item3 Rollable list with escaped characters Choose randomly between item1, item2 with | pipe or item3
{item1|{a|b|c}|item2} Resolve: item1|{a|b|c}|item2 Nested rollable lists Choose randomly between item1, result of rolling on list {a|b|c} or item2
{3+4-7.5 + (5-7)/2 + 6^2 + 4.1^0.5 + (-1)^4} Resolve: 3+4-7.5 + (5-7)/2 + 6^2 + 4.1^0.5 + (-1)^4 Equation Supported operators: + (sum), - (subtraction), / (devision), * (multiplication), ^ (exponentiation)
{d4} Resolve: d4 Equation Random roll of d4 dice
{3d12} Resolve: 3d12 Equation Sum of 3 random rolls of d12 dice
{-4+1.5*d3} Resolve: -4+1.5*d3 Equation One dice example
{1+2*3d12-d4^3} Resolve: 1+2*3d12-d4^3 Equation Example with multiple dice
{item1 {d2+10}|item {4d12}} Resolve: item1 {d2+10}|item {4d12} Equation in rollable list {d2+10} and {4d12} will be evaluated to random numbers. Curly brackets around equations are compulsory. {item1 d2+10} will be treated as plain text
{highest(2, 4d12)} Resolve: highest(2, 4d12) Equation Sum of two highest rolls out of 4 rolls of d12 dice
{lowest(2, 4d12)} Resolve: lowest(2, 4d12) Equation Sum of two lowest rolls out of 4 rolls of d12 dice
{75%?item1|25%?item2} Resolve: 75%?item1|25%?item2 Condition 75% chance of choosing item1 and 25% chance of choosing item2
{75%?item1|item2} Resolve: 75%?item1|item2 Condition 75% chance of choosing item1 and 25% chance of choosing item2
{75%?item|} Resolve: 75%?item1| Condition 75% chance of choosing item1 and 25% chance of choosing nothing
{a|50%?b|10%?c} Resolve: a|50%?b|10%?c Condition 40% chance of choosing a, 50% chance of choosing b and 10% chance of choosing c
{1-3?item1|4?item2} Resolve: 1-3?item1|4?item2 Condition If d4 dice value is 1,2 or 3, item1 is chosen. If d4 dice value is 4, item2 is chose. This is the same as 75% chance of choosing item1 and 25% chance of choosing item2. Dice values must be consecutive and cannot be automatically deducted
{a|50%?b|c} Error: a|50%?b|c Error Error in condition. Error message appears on mouse hover

Chartopia supports linked charts via the CHART and REROLL macro as shown in the following table.

Example Rendered Meaning
CHART(123) Roll on "Test" Roll on chart with id 123
CHART("My chart") Roll on "My chart" Roll on chart with title "My Chart". Chart title is case-sensitive
CHART(name="My chart", cols="1") Roll on "My chart" (columns: 1) Roll on the first column of chart with title "My Chart"
CHART(name="My chart", filter="test") Roll on "My chart" (filter="test") Roll on the rows that contain "test" from the chart called "My Chart". The filter is a regular expression and only rows that satisfy the regular expression will be rolled on. The filtered table becomes 1dx where x equals the number of rows that satisfy the filter.
CHART(name="My chart", filter="test", filter_cols="1, 3-5") Roll on "My chart" (filter="test", filter_cols="1, 3-5") Roll on the rows that contain "test" in the first, third, fourth or fifth column from the chart called "My Chart".
CHART(name="My chart", filter="test", filter_cols="1", cols="2") Roll on "My chart" (filter="test", filter_cols="1", cols="2") Roll on the rows that contain "test" in the first column from the chart called "My Chart" but return only the second column.
REROLL() Re-roll Reroll on the current chart
REROLL(cols="1") Re-roll (columns: 1) Reroll on the current chart and return only the first column

Chartopia can aggregate results of random rolls via the AGGR macro which accepts the number of rolls to perform (number or any valid equation) and an entity that may contain any combination of text and/or other macros. The result of the macro is a comma-separated list of generated items. The number of times an item was generated is shown adjacent. It is important to note that if the entity that the macro rolls on contains unmatched brackets, they must be escaped with a backslash, e.g. \(.

Example Rendered Meaning
AGGR(3, CHART("My chart")) Roll on "My chart" 3 times Roll on chart with title "My Chart" 3 times. If all 3 rolled results are different, all of them will be displayed. The rolled results that are identical will be aggregated
AGGR(3d12, CHART("My chart")) Roll on "My chart" 3d12 times Roll on chart with title "My Chart" random number of times determined by 3d12 roll
AGGR(2, CHART(name="My chart", cols="1")) Roll on "My chart" (columns: 1) 2 times Roll on the first column of chart with title "My Chart" 2 times
AGGR(3, REROLL()) Re-roll 3 times Reroll on the current chart 3 times
AGGR(d3, REROLL(cols="2")) Re-roll (columns: 2) d3 times Reroll on the current chart the number of times randomly generated by rolling d3 dice and return only the second column
AGGR(d3+12, {apple|pear|carrot} and CHART("Desserts")) Roll on {apple|pear|carrot} and Roll on "Desserts" d3+12 times Roll on the expression "{apple|pear|carrot} and CHART("Desserts")" the number of times determined by the equation d3+12
AGGR(12, {apple|pear (sweet)|carrot}) Roll on {apple|pear (sweet)|carrot} 12 times Roll on the list "{apple|pear (sweet)|carrot} 12 times. The brackets inside the rollable list are matching, so no need to escape them
AGGR(12, {apple|pear \(sweet|carrot}) Roll on {apple|pear (sweet|carrot} 12 times Roll on the list "{apple|pear (sweet|carrot} 12 times. The brackets inside the rollable list are NOT matching, so it is necessary to escape them

The UNQ macro returns a given number of unique results. It accepts the same parameters as the AGGR macro, and generated unique results are shown as a comma-separated list. Since this macro requires a given number of unique results to be generated, it may show an error if it fails to generate the requested number of unique results after 1000 attempts.

Example Rendered Meaning
UNQ(3, CHART("My chart")) Roll on "My chart" 3 times (unique results only) Roll on chart with title "My Chart" several times until 3 unique results are generated
UNQ(3d12, CHART("My chart")) Roll on "My chart" 3d12 times (unique results only) Roll on chart with title "My Chart" and select random number of unique results determined by 3d12 roll
UNQ(3, REROLL()) Re-roll 3 times (unique results only) Reroll on the current chart and select 3 unique results
UNQ(d3+12, {apple|pear|carrot} and CHART("Desserts")) Roll on {apple|pear|carrot} and Roll on "Desserts" d3+12 times (unique results only) Roll on the expression "{apple|pear|carrot} and CHART("Desserts")" and select the number of unique results determined by the equation d3+12
UNQ(12, {apple|pear (sweet)|carrot}) Roll on {apple|pear (sweet)|carrot} 12 times (unique results only) Roll on the list "{apple|pear (sweet)|carrot} and select 12 unique results. The brackets inside the rollable list are matching, so no need to escape them
UNQ(12, {apple|pear \(sweet|carrot}) Roll on {apple|pear (sweet|carrot} 12 times (unique results only) Roll on the list "{apple|pear (sweet|carrot} and select 12 unique results. The brackets inside the rollable list are NOT matching, so it is necessary to escape them

Letter case modifier macros are listed below.

Example Rendered Meaning
LOWER(CHART(123) or {APPLE|CARROT}) LOWER(Roll on "Test" {APPLE|CARROT}) Everything inside the LOWER macro will be converted to lower case
UPPER(CHART(123) {apple|carrot}) UPPER(Roll on "Test" {apple|carrot}) Everything inside the UPPER macro will be converted to upper case
SNTCE(CHART(123) {apple|carrot}) SNTCE(Roll on "Test" {apple|carrot}) Everything inside the SNTCE macro will be converted to sentence case, i.e. only the first letter will be capitalized

Other supported macros are presented below.

Example Rendered Meaning Superseded by
EQN(12) Roll 12 Returns 12 {12}
EQN(d12) Roll d12 Roll d12 dice {d12}
EQN(2d12) Roll 2d12 Roll d12 dice twice and sum up the result {2d12}
[apple;pear;apricot] Roll d3 on [apple;pear;apricot] Roll d3 dice on the rollable list of apple, pear and apricot {apple|pear|apricot}
[1:apple; 2-3:pear; 4-8:apricot] Roll d8 on [1:apple; 2-3:pear; 4-8:apricot] Roll d8 dice on the rollable list of apple, pear and apricot. Dice value 1 will return apple, dice value between 2 and 3 will return pear and dice value between 4 and 8 will return apricot {1?apple|2-3?pear|4-8?apricot}
AGGR(2d10,[apple;pear;apricot]) Roll d3 on [apple;pear;apricot] 2d10 times Roll d3 dice on the rollable list of apple, pear and apricot, then do this 2d10 times. Identical results will be aggregated AGGR(2d10,{apple|pear|apricot})

Linked charts

A Linked Chart is a nested/subsidiary chart that is called/rolled upon from another (parent) chart. For example, if one has a table of first names and a table of last names, both of these can be rolled on their own. However, one could then create a separate table called ‘Random Names’ that is able to roll on both the first name and last name table at the same time.

Advantages include:

  • Reuse of tables
  • Allow tables of different lengths to be used together. I.e. the first name table could have had 100 possibilities but the last name table may have had just 20.
  • Allow the linked charts to be edited separately to the other charts that use them.


Take two tables called "First Names" and "Last Names"

Both of these tables can be rolled independently, however, both can be utilised in a "Simple Name Generator" table that will combine both the first name and last names together in the event of a dice roll. You can link the charts together by searching for and adding a linked chart via the result editor.

Searching and adding for charts to link against can be achieved by adding the text chart( at which point a popup will reveal possible subcharts to link to, or means of opening a dialog that reveals your entire chart collection.

By pressing the "Select chart..." option, the following dialog will be shown, providing a means to linked to charts from your wider collection, and not just the subtables for this chart.

By inserting the table 'First Names', then adding a space before inserting the table 'Last Names', it will look like something like the following:


  • Result data was only required for values 1 and 12.
  • Value 1 is a First Name + Last Name.
  • Value 12 provides a 1 in 12 chance of getting a hyphenated last name.
NB: It is possible to link a table back to itself but there loop limit to prevent infinite loops.
NB: There is currently no formal (official) means of linking to other user’s charts.

Formatting a table roll result

As well as Markdown formatting, there is also the option to set how has results of a linked/nested chart displays after a dice roll.

For example, a table cell could have the following result that, in the middle rolls on another table. The result of the "Loot" table could be either display 'nested' or 'as a sentence', with or without column headers.

When editing the "Loot" table there is an option for how you would like it to display when used by other charts.

For example, here are two potential ways to display the result of rolling this chart row:

With Nested list

Or with As sentence, no column names

Adjusting row positions

All rows can be drag-dropped within its own table by using the dice-value table cell as the drag handle.

Additionally to drag-drop, there are basic functions for adjusting row positions and state. It is possible to shift a row up, down, or insert rows above or below a specific row. It's also possible to clear an entire row so that it infers results from the row above.

Dice values

Setting a new dice combination for the table will update the number of table rows automatically. There are preset dice combinations available i.e d4, d10, d12 etc but it's possible to create a custom combination in the format is either AdX or dX, where A is the number of dice to be rolled, and X is the number of sides on any dice. (for example d14 will roll a single 14 sided-die, 34d7 will roll 34 seven-sided dice, etc.)

One one addition operand can be include to extend the format to AdX + BdY. e.g. the following are possible:

  • 2d12
  • d12 + 4
  • 2d12 + d6
  • 2d12 + 3d6

Note the maximum number of rows a table can have in 1000 so any combination that could reach beyond this value is forbidden. e.g. 100d100 is not valid because it’s max rows is 10,000.

Note also that certain dice combinations will make certain rows unreachable. A 3d12 table has a range of 3-36 making rows 1 and 2 unreachable when rolling on the table. These rows can still be edited but will be grey to represent their unreachable status.

Visibility Settings

When a chart is published, it can have one of three visibility settings

Only you can search for, view and roll on this chart. It will not be inaccessible by any other users
All users can search for this chart, view it and roll on it.
An unlisted chart is public, but does not show up in search results. This is useful way to share the url with others, but preventing it showin up in wider searches.

Importing .csv data

Documentation coming soon...

Embedding to websites

It's possible to embed public and unlisted charts into your own website. Note that your website will need to support iframes (the same system used when embedding youtube videos).

To do so, view a chart, and press the </> button. It will show a dialog with the html that you can copy-paste into your website. Note that if you are embedding a chart that is not yours, the author can change the visibility settings at any time, resulting in an error in your website's iframe.

For convenience, the provided html includes a wrapping <div> element that has style inforation to make sure the chart is fully visible. You may edit this as you see fit in order to alter the size constraints.

Template editing mode

While your chart is either empty, or has only data in the first cell, its possible to change "Edit mode" (via the left side bar) to "Template". This activates a special editing mode that offers a variety of tools specifically for creating a 'generator'.

Chartopia has always been able to replicate the idea of a non-table type generator by setting the dice type to d1. Behind the scenes, a template edit mode works in the same way but the UI makes it easier to apply a richer variety of structured formatting.

Chartopia PHB Templates

The template editor provides useful 'players hand book -esque' templates to add to the editor. They may look familiar too you from your exisitng print literature.

The benefit of the editor is it's now much easier to create a random NPC, random spell or random class by using the structure of a players hand book template, but with the features of the Chartopia domain Language.

Unlike inline editing of tables which uses a rich-text editor, the template editor uses Markdown. The following screenshot shows a 'preview' of the 'monster stat block' template after bring selected from the "Insert PHB template" dropdown.

NB: Chartopia endeavours to use GFM style markdown (i.e. github markdown) for line break rules. In standard Markdown, a line line break is achieved by ending a line with space+space+enter. Enter+enter creates a new paragraph. GFM markdown on the other hand should do a line break with a simple enter press.

Refer to this cheat sheet for more info.

NB: Until recently, all editing in Chartopia was done via markdown, although editing was done via a popup and couldn't be done directly to the table. Markdown is our preferred format, so we will endeavour to created a markdown inline-editor for tables in the future.

Markdown doesn't have a syntax for scaling images. If you'd like to scale an image, the following syntax can be used.

<img src="" width="50%">


Why is there a d1 option?

This exists for when users want to create a random generator and use random tables merely to create random content for that generator. Note that we recommend using the template editing mode for creating a generator.

Why is the max number of table rows 1000?

At the moment this is purely for performance reasons; the website crawls to a stop when having to load that much data. Ideally there would be a 10,000 limit because that's the largest table I've sourced but for the time being, its possible to create to emulate 1000+ row charts by linking charts to each other.

This guide doesn't cover every last feature on the site.

This is designed to give people the tools they need to utilize the main features of Chartopia, with more information for secondary options coming soon. We hope that you'll find the additional features intuitive enough to make your own way around, but please send us feedback if you cannot.

Where do I send feedback?

You can send send a message via the contact form on our website Contact