surprise

A surprise block is used to randomly choose between multiple options. Only one of the options will be executed.

The simplest form of a surprise block is a list of options. All options are given equal chance of being selected.

surprise {
    ShieldPowerup,
    TriblastPowerup,
}

Weighted Random

It is possible to assign weights to each option to control the likelihood of each option being selected.

surprise {
    2 => TriblastPowerup,
    1 => ShieldPowerup,
}

In this example, the TriblastPowerup is twice as likely to be selected as the ShieldPowerup.

Multiple Statements

Each option can be a block of code instead of a single statement:

surprise {
    {
        Print { "You got a Triblast Powerup!" }
        TriblastPowerup
    },
    {
        Print { "You got a Shield Powerup!" }
        ShieldPowerup
    },
}

Returning Values

A surprise block can also be used as an expression, in which case the resulting value will be the value of the selected option. The last expression of the block determines the resulting value of the option.

let x = surprise {
    "apple",
    "banana",
}
// x is either "apple" or "banana", chosen randomly

To return multiple values from a surprise block, separate them with commas:

let name, points = surprise {
    {
        Print { "You got an apple!" }
        "apple", 100
    },
    {
        Print { "You got a banana!" }
        "banana", 200
    },
}
// Either name="apple" and points=100, or name="banana" and points=200, chosen randomly

If you only have a single line for each option, you will need to wrap the multiple values in parentheses, otherwise they would be interpreted as multiple options instead of a single option returning multiple values:

let name, points = surprise {
    ("apple", 100),
    ("banana", 200),
}
// Either name="apple" and points=100, or name="banana" and points=200, chosen randomly

Specifying the Random Number Stream

You can also provide an ID to the surprise block to choose its random number stream. See Random Number Generator Streams

surprise<apple> {
    Smitten,
    Poisoned,
}