Generators

Reference Manual

Written by SoulLink

This feature is available to Grandmaster and Sage guild members.

WORK IN PROGRESS

The generator is the basic building block of the Random Generators feature. A generator takes a list of things and then each time it is rolled returns one of them at random. There are a total of six different types of generators.
In this article, you'll find all the information on generators and how they work. If you wish to learn how to create and use them check out the tutorial.

Generator Fields

Each generator has six fields that can be filled.

• Title (Mandatory): The title of the generator. This field is important as it is used to create the key of the generator. The key is used to reference this generator from templates and routers.
• Description (Optional): A small description that is displayed with the generator in the list. Use this to explain what this generator does, what kind of data it is based on and what it is used for.
• Type (Mandatory): You have to select one of the types. Check out the section below to get the details. This is the only field that cannot be changed after the generator has been created!
• State (Mandatory): The generator can be private or public.
• Tags (Optional): Use tags to organize your generators. You can use the search bar to filter the list based on these tags. Make sure that the generators which belong to the same project have the same tag.
• JSON Payload: This field is used to define the data set the generator will pick from. This payload is different for each type so check below for general examples.

Generator Types

The generator has six different types. Each of them has a specific purpose. Make sure you select the correct one for what you whish to achieve. Once created you cannot change the type of the generator and will have to re-make it.

Text (String) Generator

The basic generator chooses from a list of text and returns one of them. Each text has the same chance to be selected. The JSON Payload of this generator defined by one object named values. This object contains key-value pairs which make up the list of items. The key is used by the router for comparison and is not shown anywhere. The value is the output which is visible in the result when a pair is selected.

{
  "values": {
    "male": "male",
    "female": "female"
  }
}

Weighted Values

This is the only generator currently which supports weights. The weights affect the probability by which each result is selected. You can set a weight for each value by expanding the value to an object with the fields value and weight. The generator sums up all the weights and chooses a random number between 1 and the total weight. This means that each weight is treated as a range. The random number is used to decide which item is selected.
The easiest way to calculate the probability for each item is to make sure all the weights sum up to 100. Then an item with a weight of 1 has a 1% chance to be selected and an item with a weight of 20 has a 20% chance to be selected. The weight has to be a full number and does not accept fractions. This means that to create an item with a probability of 0.5% set the weight to 5 and then the sum of all weights needs to be 1000.
Weighted Example JSON Payload - Click to Expand

{
  "values": {
    "male": {
      "value": "male",
      "weight": 49
    },
    "female": {
      "value": "female",
      "weight": 51
    }
  }
}

Parameters

The parameters of the text generator can be used to manipulate the output in a specific way.

• print: The print parameter fixes the output of the generator to this value. When using an empty value nothing is printed.
• capitalize: A setting to capitalize the value of the generator.

The example below always outputs an Output capitalized.

[generator:example-text-generator-username|{"print":"output","capitalize": "true"}|variable]

Number Generator

This generator accepts a range of numbers and returns a random number from it.

• Use a from and to field to define a range.
• The range is inclusive. A range from 1 to 2 will either return 1 or 2 with a 50% probability each.
• The range can begin and end in negative numbers.
• With a faulty JSON payload the number generator always returns 0.
• The numbers can be defined both as numbers or as strings.

Example JSON Payload - Click to Expand

{
  "from": 167,
  "to": 205
}

Article Generator

This generator picks a random article from the currently active world. It returns the mentioned code to the article so anywhere where it is printed it will be linked to the article. The list of articles chosen is either by tag or by template type. The result is an empty text if no article with the tag or type can be found.

The article generator type requires any user to have an active world and an article with that type or tag within it. Otherwise it will simply output none_found.

By Tag

Select the article type generator and then add the payload below into it. Keep in mind that this can match parts of a template as well. This means that the tag color will match articles with the following tags: color, colors, eyecolor, hair-color etc. It will not match colour.
By Tag - Example JSON Payload - Click to Expand

{
		"tag": "#your-tag"
}

By Template Type

It is possible to select a random article based on its template. Custom templates are treated as their parent template and cannot be selected separately.
By Template Type (Settlement) - Example JSON Payload - Click to Expand

{
	"type": "settlement"
}

List of Template Names - Click to Expand

• Generic Article: generic
• Buildings & Landmark: landmark
• Character: person
• Condition: condition
• Conflict: militaryConflict
• Document: document
• Ethnicity: ethnicity
• Geography: location
• Item: item
• Language: language
• Natural Law: law
• Material: material
• Military Formation / Unit: formation
• Myths & Legends: myth
• Organization: organization
• Plot: plot
• Profession: profession
• Prose: prose
• Session Report: report
• Settlement: settlement
• Species: species
• Spell: spell
• Technology: technology
• Title & Rank: rank
• Tradition & Ritual: ritual
• Vehicle: vehicle

Parameters

The article generator has one parameter: title. It is used to change the text of the display link.

• title: Changes the display title of the article link to this.

[generator:example-article-generator-username|{"title":"Test"}|article]

Image Generator

This generator returns the BBCode for an image. The image will be rendered on the public page of the template it is added to. The images are selected by tag and can be scoped.
Example JSON Payload - Click to Expand

{
		"tag": "#your-tag",
		"scope":"user"
}

Image by Gallery

A generator can pick a random image from a full gallery of images. This generator does NOT accept scope, the scope is always the active world.
Example JSON Payload - Click to Expand

{
  "gallery": 43755
}

Parameters

An image can be configured with the parameters width and alignment. Width is a number in pixels. The alignment is one of left, right or centre. These parameters are added as configuration to the image BBCode.

• width: A number in pixels.
• align: The alignment of the image: left, center, right.

The parameters are set on the generator as shown below.

[generator:example-image-generator-username|{"width":"250","align": "left"}|example-image]

Block Generator

This generator returns the BBCode for a block. The block will be rendered on the public page of the template it is added to. The blocks are selected by tag and can be scoped.
Example JSON Payload - Click to Expand

{
		"tag": "#your-tag",
		"scope":"user"
}

Simple Template Generator

This generator returns the BBCode for the simple template. The simple template will be resolved in the next resolution pass of the template this generator is added to. The simple templates are selected by tag and can be scoped.
Example JSON Payload - Click to Expand

{
		"tag": "#your-tag",
		"scope":"author"
}

Scope

WORK IN PROGESS / NOT FINALIZED

The scope of a generator determines where the items are retrieved from. Scope is only relevant for the image, block and simple template generator.

• author: The scope is set to the author of the generator. This means that the tags are searched in the images, statblocks
• user: The scope is the user who clicks the template or the generator.
• active-world: A scope where the generator only uses resources from the currently active world. This scope is used for the article generator and the image by gallery generator.
• global: The scope uses a global database of things to pull from. NOT YET IMPLEMENTED

Navigation

JSON Wrapper/Convertor

provided by Gabrielle Decker