# The Regnus Scripting Tutorial

## Part 3: Ratios & Weights

Now you've got the hang of the basic idea of references, let's take a look at how to better control the probability of certain entries being selected by a reference...

### Ratios

When you set up a list of entries under a particular group in Regnus using the methods you have learned so far, you will no doubt have noticed that each entry is given an equal probability of being selected. This is, of course, correct for many applications.

However, there are also many times when you may want a particular entry to be more or less likely to be selected than others in the same group. A crude way to achieve this, which you may already have thought of, is to simply repeat entries to increase their probability, like so:

```
START <Weighting Example>##Probabilities;
```

GROUP Probabilities

ENTRY 25%

ENTRY 75%

ENTRY 75%

ENTRY 75%

Here, there is a 75% chance of generating the text "75%", and only a 25% chance of "25%". This works, of course, but is not a very good way of defining probability, especially if you have a lot of entries, as it can quickly become confusing to look at, makes your scripts unnecessarily large, and is increasingly difficult to edit if you need to change particular probabilities.

A far more sensible way to alter the probability (or "weight") of a particular entry being selected is to use the "RATIO" qualifier. This qualifier is used in exactly the same way as an "ENTRY" qualifier, but also allows you to define a probability for the text contained. The syntax for using the "RATIO" qualifier is as follows:

```
START <Weighting Example>##Probabilities;
```

GROUP Probabilities

RATIO 25:One quarter!

RATIO 75:Three quarters!

Here, we have used two ratio qualifiers to define percentage probabilities for the two entries. Actually, using percentages as in the above example is unnecessary; this example would work just as well written as:

```
START <Weighting Example>##Probabilities;
```

GROUP Probabilities

RATIO 1:One quarter!

RATIO 3:Three quarters!

This is because the maximum probability is always calculated as the combined total of all probabilities defined, in this case, 4. Thus, the first entry has a probability of being selected of one in four, just as in the previous example, the probability was twenty-five in one-hundred.

You can also mix and match "RATIO" qualifiers with "ENTRY" qualifiers. Standard entries are always given a probability of 1. So, the following example will have the exact same results as the previous one:

```
START <Weighting Example>##Probabilities;
```

GROUP Probabilities

ENTRY One quarter!

RATIO 3:Three quarters!

Ratios can also be fractional values, which is useful if you want a single entry in a group to be less commonly selected than the other entries in that group. For example:

```
START <Weighting Example>##Probabilities;
```

GROUP Probabilities

ENTRY Four fifths!

RATIO 0.25:One fifth!

The standard entry has a weight of 1, or four times the weight of the fractionally-weighted entry, so here, the under-weighted entry has a selection probability of one fifth.

**Note:** Fractional ratios are accurate to a precision of one thousandth (0.001) in the current standard. Values lower than this will not function correctly.

Having a quick play with using ratios should soon give you a firm idea of how they work, but although simple, they can be very useful, especially when writing scripts which need to use specific probabilities (for example in research projects or encounter charts and such for roleplaying games), so it's well worth being aware of how to use them!

### Counted Weights

Another way to weight entries is to use the "COUNT" qualifier. This allows you to assign a weight to an entry equal to the number of entries in another group. For example:

```
START <Weighting Example>##Probabilities;
```

GROUP Probabilities

ENTRY One quarter!

COUNT AnotherGroup:Three quarters!

GROUP AnotherGroup

ENTRY Something

ENTRY Something else

ENTRY Yet another thing

In this example, the second entry in the "Three quarters!" entry is assigned a weight of three as there are three entries in the referenced group "AnotherGroup".

This is primarily useful when the intention is to combine the contents of two groups for one purpose, while keeping them separate for other purposes, but wanting to ensure that each individual entry is treated with the same weight. For example, consider the following situation:

```
START <Weighting Example>##Animal;
```

GROUP Animal

ENTRY ##Cat;

ENTRY ##Dog;

GROUP Cat

ENTRY Lion

ENTRY Tiger

ENTRY Puma

ENTRY Cheetah

ENTRY Felis Silvestris Lybica

GROUP Dog

ENTRY Wolf

ENTRY Rottweiler

In this example, a Reference to the group "Animal" will return an entry from the group "Cat" fifty percent of the time, and an entry from the group "Dog" fifty percent of the time; but as there are five entries in the "Cat" group and only two in the "Dog" group, this means that such a Reference would only return the result "Puma" ten percent of the time, whereas "Rottweiler" would be returned twenty-five percent of the time.

Clearly, this is not the intention, and it can of course be fixed using a "RATIO" qualifier in the following way:

```
START <Weighting Example>##Animal;
```

GROUP Animal

RATIO 5:##Cat;

RATIO 2:##Dog;

GROUP Cat

ENTRY Lion

ENTRY Tiger

ENTRY Puma

ENTRY Cheetah

ENTRY Felis Silvestris Lybica

GROUP Dog

ENTRY Wolf

ENTRY Rottweiler

Now, there is an equal one-in-seven chance of any particular animal being returned. However, the problem with using "RATIO" qualifiers here is that the ratios would need to be updated each time a new entry is added to either group. The "COUNT" qualifier makes this much easier:

```
START <Weighting Example>##Animal;
```

GROUP Animal

COUNT Cat:##Cat;

COUNT Dog:##Dog;

GROUP Cat

ENTRY Lion

ENTRY Tiger

ENTRY Puma

ENTRY Cheetah

ENTRY Felis Silvestris Lybica

GROUP Dog

ENTRY Wolf

ENTRY Rottweiler

The "COUNT" qualifier takes into account all calculated weights for a named group, including any "COUNT" or "RATIO" qualifiers within that group, so the following would also provide an equal chance of any particular animal being returned:

```
START <Weighting Example>##Animal;
```

GROUP Animal

COUNT Cat:##Cat;

COUNT Dog:##Dog;

GROUP Cat

COUNT BigCat:##BigCat;

COUNT SmallCat:##SmallCat;

ENTRY Leopard

ENTRY Puma

GROUP BigCat

ENTRY Lion

ENTRY Tiger

ENTRY Cheetah

GROUP SmallCat

ENTRY Felis Silvestris Lybica

GROUP Dog

ENTRY Wolf

ENTRY Rottweiler

RATIO 1:Great Dane

**Note:** A "COUNT" qualifier should not be used to count the group in which it appears, as this will create an infinite logic loop and cause your Regnus parser to hang! The same is also true of "COUNT" qualifiers which attempt to count groups which themselves attempt to count the original group, for the same reasons, so be careful!

Finally, it is worth noting that both ratios and counted entries are also able to include labels, just as with "START" and "ENTRY" qualifiers:

```
START <Random Selection!>##StartPoints;
```

GROUP StartPoints

ENTRY <Example One>Today is sunny, so I will ##Action;!

RATIO 2:<Example Two>I would like to ##Action; today!

COUNT Action:<Example Three>I don't like to ##Action;!

GROUP Action

ENTRY go out and play

ENTRY stay indoors

ENTRY play with my friends

ENTRY play by myself

ENTRY go to sleep