Generate Value

Hypstory can generate special values for you. In some ways they are similar to stored values: Their labels start with a dollar sign $, you can use them in check and store lines, and you can print them to your text.

However, generated values are also different, because they can work with parameters you provide to them. They all follow a fixed pattern:

  1. dollar sign $
  2. reserved label name
  3. optionally, parameters in parentheses (...)

Remember not to put spaces anywhere inside that pattern.

Ranged random number

Hypstory can generate a random number in a certain range for you: $randomNumber(min,max).

:CARD: how many slices

"Francesca, I was wondering, when you make a pizza for yourself, how many slices of salami do you put on it?"

"I decide on a pie-by-pie basis."


"I use my favorite random number: $randomNumber(4,20)."

The label for a random number consists of three parts:

  1. The dollar sign $ in front marks it as a label like you know from store lines.
  2. Then follows a reserved label name: randomNumber. Alternatively, you can use the short form: rn.
  3. Then, between opening and closing parentheses, there are two numbers separated by a comma. They have to be whole numbers (positive or negative). These numbers mark the lower and the upper end of the range for the random number.

The example above will create any whole number between and including 4 and 20.

Practice tip: Hit update a few times and see which numbers come up. Then change the second number in parentheses to 6, hit update and see what happens.

There must not be spaces anywhere between the dollar sign $ and the closing parentheses ). Like any normal label, this special label including the parentheses must be a continuous string of characters.

Roll a die

Hypstory can roll a die of any size for you: $roll(dieSize).

:CARD: pizza gambling

"You roll a die and I roll a die, and if you win, you get a pie. For free, that is," Alfonso announces.
:APPEND: Pick up the die and roll | result

:CARD: result

:STORE: ($myRoll = $roll(6)) ($alfonsosRoll = $roll(6))

"Okay. I rolled a $myRoll," you say.

:CHECK: $myRoll > $alfonsosRoll
"Well, I only rolled a $alfonsosRoll. You win a free pie," Alfonso says.

:CHECK: $myRoll <= $alfonsosRoll
"And I rolled a $alfonsosRoll. Better luck next time," Alfonso chirps.

The $roll(dieSize) value is a simpler version of the ranged random number value. Like every value, it starts with a dollar sign $, then follows the reserved label name roll.

In parentheses you put a single number that stands for the size of the die you would like to roll. $roll will return a random whole number between 1 and the number you've given it.

If you are not entirely sure about the lines with the :CHECK: tag, the check article will give you all the answers.

Practice tip: Change the die sizes in the example above on line 5 to 13. Hit update and see how the results change.

Workflow tip: You can use $roll(dieSize) with negative numbers. The result will be between -1 and the size you put in parentheses. Also, $roll without a (dieSize) does the same as $roll(6).

0 is not a valid parameter, because a die with zero sides does not have a side on which a result could be printed. If you do write $roll(0) anywhere in Hypstory, the internet will be deleted permanently. Seriously.

Random item

Hypstory can randomly select one out of a number of items you give it: $randomItem(items).

:CARD: be a better supporter

$randomItem(Alfonso,Francesca,Hypstory) would appreciate $randomItem(2,4,6,8) extra visits from you next $randomItem(week,month,year).

$randomItem(items) accepts any number of words or figures as parameters. Please keep in mind that spaces and punctuation are not allowed.

Workflow tip: You can use the short reserved label name $ri(items).

Number of card visits

Hypstory automatically counts how often a card has been visited. You can access and use this number for any card: $visits(cardname).

:CARD: start

It's pizza marathon day. Shouldn't you be munching pizza?
(You've been at Francesca's $visits(francescasShop) times.)

:LINK: Stop by Francesca's | francescasShop

:CARD: francescasShop

:CHECK: $visits == 1
"Good morning. How nice of you to stop by," Francesca says.

:CHECK: $visits > 1
Francesca winks at you: "Ah there you are again. Must be your pizza berzerk day."

:LINK: Time for a walk | start

$visits(cardname) outputs how often the card with that particular cardname has been displayed. It accepts any cardname as a parameter. However, you must use a cardname without spaces.

There is also a shorthand for a special case: $visits. It will give you the number of visits of the card where it occurs. In the case of lines 6 and 8 above that's the francescasShop card.

Workflow tip: Cardnames can contain spaces. However, as spaces are not allowed inside label names, you can just leave them out. The cardname will still work. Be aware that it's good practice to use cardnames that have no spaces in the first place.

Practice tip: Just stop by Francesca's a few times and see how $visits increases by 1 each time.

Including a card with an include line will also increase the number of visits of that card.