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.
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
Rollbutton 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.
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
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:
trueorfalse - Number:
0,1, ... - String:
'with single quote',"with double quote", ... - Set/collection of strings:
[],['a', 'b'], ...
- Boolean:
- 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":
trueboolean- 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:
| Expression | Result |
|---|---|
| Boolean | |
boolean + boolean | Logical OR (||) |
false - booleantrue - true | false |
true - false | true |
boolean * boolean | Logical AND (&&) |
| String | |
string + scalarscalar + string | Concatenation |
string * numbernumber * string | Repetition of the string |
| Collection | |
collection + stringcollection + collectionstring + collection | Union of both |
collection - stringcollection - collection | Difference of both |
string in collectioncollection 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,descriptionkinds: 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:
- GitHub Gist (See example below)
- GitHub (including pages)
- GitLab (including pages)
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 filebutton ; 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
Rawbutton of the module file, and copy the URL from the browser address bar. It should look likehttps://gist.githubusercontent.com/<username>/<hash>/raw/<hash>/<filename>.yaml - Use this URL as source URL in OmniRoll to load your module.