Skip to main content

Index

One App. Every Game. Infinite Setups.

OmniRoll is a Web-based autonomous generic application to generate random setup for (close to) any boardgame:

web-based
Accessible from Web browser. From most Web browser (either desktop, or mobile), you can add it as "native" application.
autonomous
No server, no registration, no login. All data are stored locally on the device.
generic
It is not dedicated to a limited set of boardgames. Just add data (module) to support new games.

Features​

Application is split into several sections:

  • Referential: List of data sources which define supported games and contents.
  • Collection: Games and contents owned by the user.
  • Randomizer: Setup generation.

Referential​

Referential consists in a ordered list of data sources each providing games. Each game has a unique identifier and declare:

  • components (organized in hierarchical sets)
  • randomizers (random setup configuration)

Each source defines location of a module YAML file. Currently, only source URL is supported.

warning

A game might be defined from many sources. However, only the one with highest priority (the first) will be taken into account.

Source actions​

  • : Move source up for higher priority.
  • : Move source down for lower priority.
  • : Fetch for updated module and check content. In case of error, previously loaded content is kept.
  • : Open source edit form.
  • : Remove any data stored for this source. It must be fetched to be accessible again.
  • : Disable source. Don't remove data but they are not taken into account for collection.
  • : Enable source. Make content accessible from collection.
  • : Remove the source and all associated data.

Game metadata​

Once a module has been fetched and content checked, the list of available games are shown directly under each source:

  • : Total available sets.
  • : Total available components.

Collection​

Collection consists of games, sets and components owned by the user. It is used to filter available components when generating random setup.

Game list​

By default, no game are accessible. However, collection page shows all game available from modules.

  • : Game doesn't belong to collection. By clicking, it will be added. However, on first time no content (no set) is selected.
  • : Game belong to collection. By clicking, it will be removed. However, selected content is kept.

Game page​

Once a game is added to the collection, it is accessible from left menu. But randomizers are not accessible until content (set) is selected.

When editing, a tree of content set is displayed. The search bar let filter out matching nodes.

  • : Set doesn't belong to collection. By clicking, add it (and implicitly all sub-sets).
  • : Set explicitly belong to collection. By clicking, remove it (and implicitly all sub-sets).
  • : Set implicitly belong to collection. By clicking, add it explicitly.

Randomizer page​

Randomizer page is divided in three parts:

  • (Optional) Variables: Only displayed if there's. Expand to a form when clicking the area, and collapse on Close.
  • Roll: A Roll button to fill/replace all slots regarding randomizer constraints and collection.
  • Slots: May be arranged by group.

Module​

This section helps you authoring a module to support new games. The first part (Writing a module) is about data model, the next one (Designing a module) are advices for module design, and finally (Hosting a module) provides some recommendation for publishing modules.

Writing a module​

This part aims to explain data model of module. A module consists in at least one YAML file.

Basically, it follows this hierarchical structure:

Module​

At the root, a source defines a module:

# Module
key: "" # (Required)
name: "" # (Required) Display name
description: "" # (Optional)
updated-at: "" # (Optional)
games: [] # (Optional) List of games. See below.
tip

It is adviced to split module into several files:

# Module
key: "my-module"
name: "My module"
games:
- include: "game-1.yaml"
- include: "game-2.yaml"

Game​

A game might be defined by many modules (but only first one is taken into account):

# Game
key: "" # (Required) Unique game identifier
name: "" # (Required) Display name
description: "" # (Optional)
updated-at: "" # (Optional)
sets: [] # (Optional) Hierarchical organisation of content
randomizers: [] # (Optional) List of randomiers
tip

For large sets, it is recommended to split into several files:

# Game
key: "my-game"
name: "My game"
sets:
- include: "set-1.yaml"
- include: "set-2.yaml"

Set​

Sets represents hierarchy of content (e.g. boxes, seasons, extensions).

# Set
key: "" # (Required) Unique identifier for the game
name: "" # (Required) Display name
description: "" # (Optional)
updated-at: "" # (Optional)
sets: [] # (Optional) Sub-sets
components: # (Optional) Dictionary of components by kind
Kind1: [] # List of components of given kind
Kind2: [] # List of components of given kind

Component​

# Component
key: "" # (Required) Unique identifier for the game
name: "" # (Required) Display name
description: "" # (Optional)
properties: {} # (Optional) Custom properties whose values are: boolean, number, string or array of string
# They are directly accessible when referenced in expressions

Randomizer​

Define how to generate random setup.

# Randomizer
key: "" # (Required) Unique identifier for the game
name: "" # (Required) Display name
description: "" # (Optional)

variables: # (Optional) Supported types: `integer`
- key: "" # (Required) Unique identifier for the randomizer
name: "" # (Optional) Display name (default to `key`)
type: "integer" # (Required)
min: 0 # (Optional) Minimum value
max: 999 # (Optional) Maximum value
default: 10 # (Required) Default value

pools: # (Required) List of component pool to pick from
- key: "" # (Required) Unique identifier for the Randomizer
criteria: "" # (Optional) Expression to select component (default to all owned)
# Context: component, variables

groups: # (Optional) List of groups to gather slots
- key: "" # (Required) Unique identifier for the Randomizer
name: "" # (Optional) Display name (default to `key`)

slots: # (Required)
- key: "" # (Required) Unique identifier for the Randomizer
name: "" # (Optional) Display name (default to `key`)
count: 1 # (Optional) Number or expression
# Context: component, variables
pool: "" # (Required) Pool key to pick from
group: "" # (Required if there are groups) Group key
pick: "remove" # (Optional) One of: remove (default), keep
criteria: "" # (Optional) Expression to filter pool components
# Context: component, variables

Expression​

Syntax​

Several fields support expression. It relies on JavaScript syntax, but with some limitations and custom behaviors.

An expression consists in:

  • Literals:
    • Boolean: true or false
    • Number: 0, 1, ...
    • String: 'with single quote', "with double quote", ...
    • Set/collection of strings: [], ['a', 'b'], ...
  • A reference to the Context:
    • component, component.name
  • Unary operations:
    • ! <expression>
  • Binary operations (from lowest to highest priority):
    • <left> || <right>
    • <left> && <right>
    • <left> == <right>
    • <left> != <right>
    • <left> in <right>
    • <left> > <right>
    • <left> >= <right>
    • <left> < <right>
    • <left> <= <right>
    • <left> + <right>
    • <left> - <right>
    • <left> % <right>
    • <left> * <right>
    • <left> / <right>
  • Ternary expression: <condition> ? <if-true> : <if-false>
  • Grouping: (<expression>)

However some syntax is not supported:

  • Literals: null, undefined, NaN, Infinity
  • Unary operations: +, -, ~
  • Binary operations: ??, ===, !==, <<, >>, >>>, &, |, ^
Evaluation​

For detail on how operations are evaluated:

  • "Truthy":
    • true boolean
    • a number different from zero
    • a non-empty string
    • a non-empty collection

The ! <expression> unary operation is used to reverse.

Scalar values (boolean, number, string) are compared by value and type. true is greater than false, and strings are compared in lexicographical order.

Collections are treated as sets of strings. A set is strictly greater if and only if it contains all elements of the other set and has more items. A string is considered equal or lesser than a collection if it is included in the collection.

Here are some specific behaviors:

ExpressionResult
Boolean
boolean + booleanLogical OR (||)
false - boolean
true - true
false
true - falsetrue
boolean * booleanLogical AND (&&)
String
string + scalar
scalar + string
Concatenation
string * number
number * string
Repetition of the string
Collection
collection + string
collection + collection
string + collection
Union of both
collection - string
collection - collection
Difference of both
string in collection
collection in collection
Check if included

Expression context​

Variables accessible in the expression depends where it is used. However, there are some general rules.

  • component (aliases: cmp, c):
    • key, name, description
    • kinds: a singleton set with kind
    • Any define properties
# component
Character:
- key: "johndoe"
name: "John Doe"
description: "A character named John Doe"
properties:
is_npc: true
// expressions
c.key // 'johndoe'
c.kinds // ['Character']
c.is_npc // true
  • variables (aliases: var, v): Dictionnary of variables by their keys.
# randomizer
key: "setup"
variables:
- key: "counter"
type: "integer"
// expressions
v.counter // 0

Designing a module​

Writing a good module isn't just about content completeness, but also about organization, nomenclature, ... Here are some tips to help you design your modules effectively.

Split by game​

If you consider to provide content for multiple games, it is preferred to split them into separate modules.

# module-1.yaml
key: "module-1"
games:
- key: "game-1"
name: "Game #1"

# module-2.yaml
key: "module-2"
games:
- key: "game-2"
name: "Game #2"

Otherwise, consider using separate files for each game.

# module.yaml
key: "module"
games:
- include: "game-1/index.yaml"
- include: "game-2/index.yaml"

# game-1/index.yaml
key: "game-1"
name: "Game #1"

# game-2/index.yaml
key: "game-2"
name: "Game #2"

Split by language​

If you provide game content covering many languages, consider using separate files for each language. At least, use dedicated sets.

# module.yaml
key: "module"
games:
- key: "game-1"
name: "Game #1"
sets:
- include: "en.yaml"
- include: "fr.yaml"

# en.yaml
key: "en"
name: "English"

# fr.yaml
key: "fr"
name: "French"

Grouping sets​

Avoid sets providing both content and sub-sets simultaneously. As when user select a set, all subsets are included automatically.

For example, some editions (e.g. crowdfunding, deluxe, anniversary) might include some expansions. Then, prefer to create a super set that groups all related sets together.

Designing keys​

Keys are unique identifiers used to reference items within different scopes:

  • Game: strictly unique inside a module and only one is taking into account by the application
  • Set: unique inside a game (doesn't conflict with component or randomizer ones).
  • Component: unique inside a game (doesn't conflict with set or randomizer ones).
  • Randomizer: unique inside a game (doesn't conflict with set or component ones).
  • Variable: unique inside a randomizer (doesn't conflict with pool, group or slot ones).
  • Pool: unique inside a randomizer (doesn't conflict with variable, group or slot ones).
  • Group: unique inside a randomizer (doesn't conflict with variable, pool or slot ones).
  • Slot: unique inside a randomizer (doesn't conflict with variable, pool or group ones).

Right key design is a complex task that requires good knowledge of current content organization as well as future evolution. Whatever how it is composed, the suggested form is slug.

Here are some concepts to consider:

  • Prefix set and component keys with language ISO code (e.g. en-, fr-)
  • Use season, wave, edition, etc. identifier as infix (e.g. 2026-, group-0, wave-1-)
  • Similar components might exists for different usage (e.g. a "character" which might be used as a hero or a villain)
  • (by the way) the name

Multiusage components​

Some components might be used in multiple way. Depending if it can simultaneously serve different purposes, consider duplicating the component with different keys for each usage (and specify the purpose in each key).

# game-1.yaml
key: "game-1"
name: "Game #1"
sets:
- key: "set-1"
name: "Set #1"
components:
Hero:
- key: "hero-johndoe"
name: "John Doe"
Villain:
- key: "villain-johndoe"
name: "John Doe"
randomizers:
- key: "default"
name: "Default"
pools:
- key: "content"
slots:
- key: "hero"
pool: "content"
criteria: "c.kinds == 'Hero'"
- key: "villain"
pool: "content"
criteria: "c.kinds == 'Villain'"

Otherwise, randomizer support remove or keep picking which might help managing reusable components. Another solution is to use distinct pools to separate reusable components.

# game-1.yaml
key: "game-1"
name: "Game #1"
sets:
- key: "set-1"
name: "Set #1"
components:
Character:
- key: "character-johndoe"
name: "John Doe"
properties:
tags:
- "Hero"
- "Villain"
randomizers:
- key: "exclusive"
name: "Exclusive"
pools:
- key: "all"
slots:
- key: "hero"
pool: "all"
criteria: "c.tags == 'Hero'"
- key: "villain"
pool: "all"
criteria: "c.tags == 'Villain'"
- key: "reuse-by-picking"
name: "Reuse by picking"
pools:
- key: "all"
slots:
- key: "hero"
pool: "all"
criteria: "c.tags == 'Hero'"
pick: "keep"
- key: "villain"
pool: "all"
criteria: "c.tags == 'Villain'"
pick: "keep"
- key: "reuse-by-pools"
name: "Reuse by pools"
pools:
- key: "hero"
criteria: "c.tags == 'Hero'"
- key: "villain"
criteria: "c.tags == 'Villain'"
slots:
- key: "hero"
pool: "hero"
- key: "villain"
pool: "villain"

Hosting a module​

As only HTTP URLs are supported, module files must be hosted on publicly accessible HTTP server. For example:

tip

Gist is a simple service to host and edit files.

  • (If not already done) Create a GitHub account from GitHub Gist
  • Once logged in, click on + button on top right
  • You may enter a Gist description to give some context and explanation
  • Enter a filename for your module (e.g. module.yaml, root.yaml) and the associated content.
  • You may add more files by clicking on Add file button ; as recommended, it is better to split module into several files per game (e.g. game1.yaml, game2.yaml, ...) and sets (e.g. game1-set1.yaml, game1-set2.yaml, ...)
  • Once done, click on arrow from the green button and select Create public gist, and click on the button to publish your Gist.
  • Click on the Raw button of the module file, and copy the URL from the browser address bar. It should look like https://gist.githubusercontent.com/<username>/<hash>/raw/<hash>/<filename>.yaml
  • Use this URL as source URL in OmniRoll to load your module.