How Rules Work

It may help, when building complex experiences, to note the following properties about Rules in GMetri.

Order Matters

• Rules are executed in order of definition. So on the rules page if you have these rules in the following order, then Video1 would end up in a paused state, as that executes last:

  • First Rule: "When Video1 is clicked, Then Video1 should play"

  • Second Rule: "When Video1 is clicked, Then Video1 should pause"

• Within a single rule, the "When Events" are checked in order

• Within a single rule, the "Then Actions" are executed in order. So if you have a rule like the following, the image would end up hidden.

  • "When something is clicked, Then Image1 should show AND Image1 should hide"

The Mental Model for Rules

It is helpful to think of the "When" side of rules as a series of pipes, that are either green or red in color. If any of the When events get triggered, the system decides if its a hit or a miss, and paints the pipe either red (No go) or green (Good to go).

The reason the paint analogy works, is because the when event states persist.

"is clicked" is a special rule that paints the pipe green for exactly one Rules check, and then paints it red again.

"has been clicked", in contrast to "is clicked", paints the pipe green, forever. However, these events do trigger and check if the rule should be executed everytime.

Example:

Let's say we have the following rule, based on a "count" integer variable:

When (count is = 2 AND Image1 is clicked) Then (you_have_passed_text should appear)

• Let's say count becomes 1. Then the "count is = 2" when event is checked - it's obviously not true, so the system paints "count is = 2" pipe red. Whenever the image is clicked, its counter part is red, so this rule wont trigger.

• When count becomes 2, the first pipe is painted green, and clicking on Image1 will trigger the rule.

• Again, once count become 3, the first pipe is painted back red.

Implications of the Rules Mental Model

This mental model also makes clear a few important points:

• If a pipe is already green, painting it green again will have no impact.

  • Example, for the rule "When a > 2, then ...", when a goes above 2 and becomes 3, this rule gets triggered once. But after that, a becoming 4, 5, 6 etc will have no impact (as the pipe is already green).

• Variable When Events trigger when they change: "When variable_a changes" when event is triggered ONLY if the value stored in variable_a changes. Lets say its value is "hello", and we set it to "hello" once again, this rule isn't triggered again. Because truly, the variable_a did not change.

• Click based When Events trigger every time.

• If you have a rule that says "When Image1 is clicked AND Image2 is clicked", it would very likely never trigger. This is because "is clicked" makes the pipe green for excely one Rules check and then paints it red again. For this rule to trigger, the user would have to click both the images at the same instant. What you more likely want in a scenario like this is "When Image1 has been clicked AND Image2 has been clicked"

When do Rules Run?

• Rules require a trigger to run. Any of the "When Events" can provide the trigger. A trigger needs either a single green pipe (in case of OR) or all green pipes (in case of AND) to flow through successfully and fire the rule.

• In case of "AND" linked when events, all "pipes" (When Events") need to be green for the trigger to actually run (fire) the rule.

• In case of "OR" linked when events, any single pipe being green, and the generation of a trigger (in that pipe) is enough to actually run (fire) the rule.

Common Rule Triggers

• An "on click" when event always generates a trigger. However for "on click" the pipe becomes red immediately after the trigger. If there's any other pipe (i.e. when event) linked to it using an "AND" condition, and the pipe is red at that instant, the rule won't fire.

• A "has been clicked" when event also generates a trigger. But there's no negation happening here - once the pipe is green, it stays green, until the scene changes.

• A "variable_a changes" when event is similar to "has been clicked". Once the variable changes because of any rule, the pipe stays green. You may want to use this event as a trigger generator on every value change of a variable.

• A "variable_a > 5" (or any other variable comparison) based when event generates a trigger at the instant the condition becomes true. If the condition is already true and the variable changes again in a way that keeps the condition true, no new trigger is generated. Note: A variable pipe that is already green, won't trigger again unless it goes red (i.e. condition becomes false) and then becomes green again (only a color change qualifies as a trigger for variable comparison when events).

Recreated per Scene

Rules are defined per scene at a time.

When a viewer enters a GMetri experience, the Rules are initialized for the scene that the viewer is in. On every scene change, the older engine is dismantled and a new one is created for that scene. So when you go from Scene1 to Scene2 and back to Scene1, all the "is clicked" when events get reset back to the initial state (of not being clicked yet).

Initialization of a Scene

Whenever a viewer enters a new scene, the following things happen, in order:

• The scene's preload event is fired. You can use this event to show/hide videos or audios that you want to autoplay on scene start. Any rules defined with the when event "When scene preloads" get triggered here.

• Any elements that are set to "autostart" (like any audios), autostart at this time.

• All variables based rules are checked with their current values. So if you have any when events like "When variable_a is = 2 then ...", they are triggered at this point.

• The scene's load event is fired. Any rules defined with the when event "When scene loads" get triggered here.

Checking if a Variable is Equal to Another

You can use variable substitution to check if a variable is equal to another. Example:

When variable_a is = {{variable_b}}

However, this check will be triggered only whenever variable_a changes, and not when variable_b changes. So to check for variable equality, we need to use the following rule:

When variable_a is = {{variable_b}} OR variable_b is = {{variable_a}}

Checking for variable equality