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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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: