Check

Check lines test switches and values: Is the lightswitch on? Is a character's budget greater than 10? Has the protagonist visited a certain place and gathered a number of clues?

The outcome of the check – true or false – decides whether the line after the check line will be processed. This affects all kinds of lines: paragraphs, links, shuffle lines etc.

To fully benefit from this article please read about switch lines and store lines first. There you will find some basic examples on how to use check lines as well.

Check a switch

The article about switch lines introduces how to check whether a switch is on: :CHECK: switchName. If you are not familiar with this check, read up on switch lines first.

However, there will be situations where you need to check the opposite: Is a switch off? For that, simply put a bang ! in front of the switch name you want to check.

There are two check lines in this example. The first one (line 4) checks whether the switch doneMakingPizza is on. If that is true (i.e. the switch is on), line 5 will be displayed. If not, it will be omitted.

In the second check line (line 6) the switch name is marked with a bang !. That means it checks whether doneMakingPizza is not on. If that is true (i.e. the switch is off), line 7 will be displayed. Otherwise it won't.

Each time you visit the going home card the doneMakingPizza switch changes its state, because it's a toogle. Depending on the state it is in, the first or the second check is true.

In this particular example the two check lines work as counterparts. Because both check the same switch, one resolves to true, the other to false. They can never be both true or both false.

Workflow tip: The :CHECK: tag has one synonym: :IF:. Everything you can do with the former can be accomplished with the latter in the same way. Choose the one that makes more sense to you.

Check a group of switches

A single check line can test several switches at once. The switch names have to be separated with a space. In order to improve legibility you can also use parentheses around switch names.

The check line in this example tests three switches simultaneously. It resolves to true only if lightsOn is not on and backDoorOpen is not on and alarmOn is on. If all three switches are in the right state, the last line will be displayed.

Technically, this way of checking switches is a shorthand for :CHECK: !lightsOn && !backDoorOpen && alarmOn. You can find details about that below.

Practice tip: Try setting the +alarmOn in the switch line to -alarmOn, hit update and see what happens.

Check a stored value

A switch is either on or off. So it easily translates to true or false, which is exactly what a check line needs. A stored value, however, has to be compared to some other value in order to be interpreted as true or false.

For that, Hypstory comes with a number of comparison operators:

• == checks whether the left side is equal to the right side. Please note that you need to write two equal signs instead of one.
• != checks whether the left side is not equal to the right side.
• >= checks whether the left side is greater than or equal to the right side.
• <= checks whether the left side is lower than or equal to the right side.
• > checks whether the left side is greater than the right side.
• < checks whether the left side is lower than the right side.

In most cases you will probably compare numbers. But text is possible as well. Equal to (==) and not equal to (!=) work as expected. But when you compare two words with >=, <=, >, or < Hypstory will compare their length in characters. Hence, Francesca >= Alfonso resolves to true.

Compare with a number or text

You can compare a stored value with a number or some text that you put directly into the check line:

Here, a word is stored under the label $myFavPizza. Two check lines compare it with a specific word.

The two comparisons != and == work as counterparts. Hence, one of the two check lines will always be true.

Practice tip: Try changing the text that is stored in line 2 to Piccante, hit update and see what happens.

Workflow tip: If the $myFavPizza in line 7 is new to you, read up on how to output stored values.

Compare with another stored value

You can also compare two stored values. Stored values are always numbers or text. So the comparison in this example works exactly like in the one above.

At the beginning two values are stored. Depending on which is bigger, a different text will be displayed.

Workflow tip: One number can be either greater than >, lower than <, or equal to == a second number. If you want to represent all three cases with two checks, one check has to include the equal to case. That's why the first check in this example uses the >= operator.

When you compare two pieces of text with a comparison operator, the number of their characters will be compared.

Use simple math in checks

When checking stored values you can also include simple math. The four basic arithmetic operations + - * / as well as parentheses () are allowed.

In the first check line the number 2 is added directly to $yourPizzaCount, because that's how many pizzas Alfonso can eat. Now the result can be compared with the standing record.

The second check line might not make much sense, but it shows how you can use simple math when comparing stored values.

There is a specific order of operations: First, the arithmetic operators are calculated, i.e. + - * / and the parentheses (). After the calculation has yielded its results, the comparison starts. In other words: arithmetic comes before comparison.

Chain checks together

There will be situations where you need to chain several checks together in order to make a decision: Maybe you need to compare more than one stored value with some numbers. Or you want to check switches and values at the same time.

For that, Hypstory has two logical operators: AND && and OR ||.

Chain with AND

A check line with the AND-operator && will resolve to true if the checks on both sides of the operator are true.

In line 4 there are two different checks: a switch check, and a comparison check with a stored value. The line below is displayed because both checks resolve to true. If one of the checks were false, the line would not be displayed.

There is a specific order of operations at work here: First, comparisons are resolved. Then, based on the comparisons' results, the logical operations are resolved.

Practice tip: Try changing the + in the switch line to a -, hit update and see what happens.

Chain with OR

A check line with the OR-operator || will resolve to true if at least one of the checks on either side of the operator is true.

In line 4 there are two different checks: a comparison check with a stored value, and a switch check. The line below is displayed because at least one of the two checks is true, namely the switch.

Line 5 would also be displayed if both checks were true. Only if both checks were false, line 5 would not be displayed.

Note the order of operations here: First, comparisons are resolved, then the logical operations. (If arithmetic operations were involved as well, they would be calculated before the comparisons.)

Combine AND and OR

You can use the two logical operators together in the same check line.

When you combine AND && and OR || operators the AND operator will be resolved first. That makes the OR operator 'stronger' in a way, but can be confusing at times.

In order to make the check's structure very clear and more readable it is good practice to use parentheses (). Whatever is in parentheses gets resolved first.

The first check line does have parentheses but behaves exactly like it would without them:

1. (broke && hungry) gets resolved first. AND resolves to true if both sides are true. But here one side is false, so it resolves to (false).
2. Then (false) || $couponStamps >= 10 gets resolved. OR resolves to true if at least one side is true. This is the case here, so the entire check line is true and line 5 gets displayed.

The second check line is grouped differently by the parentheses. As a result, its behavior changes:

1. (hungry || $couponStamps >= 10) gets resolved first. It resolves to (true), because at least one side is true.
2. Then broke && (true) gets resolved. Because one side of the AND operator is false the entire check line is false. As a result, line 7 does not get displayed.

Practice tip: These concepts might be a little hard to grasp at first. Just fiddle around with the source text above: Use the not-operator ! on some of the switches inside the check lines and see what happens. Once you are on top of this it will be your new superpower for writing Hypstories.

Workflow tip: The not-operator !, which was introduced in the section about checking switches, also works before opening parentheses: !(broke && hungry). Why don't you give it a try and see what happens?

Manipulate groups of lines

Check lines can affect more than one line. Just add a pipe | and the number of lines after the check.

There are two check lines in this example. The first affects the two lines below. If it resolves to false, both lines will be omitted. The second check line affects three lines.

The pipe with the number of lines must be the last part of the check line.

Practice tip: Did you realize that the second check line also affects a switch line?

Ambiguous cases

Check lines, comparison, logical operators – they are all made for stored values and switches. But what if you write a check that does not make sense in a conventional way? What happens when you compare a number and a word? Is the number 1 true or false if it occurs on one side of an && operator?

Using checks like these might not make much sense in a Hypstory. But being aware of how Hypstory handles them can help you find the error if your Hypstory does not work the way you wanted.

Practice tip: The code box in this section is an ideal place to really go crazy with weird checks. Just try some out that come to mind. If you happen to find contradictory behavior or a bug, please drop me a line: chris@hypstory.org.