Principles of Kodu Computation

Body color and glow color are independent, and either will satisfy a color filter. "WHEN see red DO move toward" will move toward the closest object that either has a red body or is glowing red. There is no way to distinguish between these two conditions.

The "glow" action with no color argument uses the object's current body color to set the glow color.

When a pursuing object bumps its target they will bounce off each other in a manner determined by their mass and relative speed. This can terminate the bump relation after as little as one rule cycle; the duration of contact is indeterminate. A lost contact might be re-established, either deliberately through continued pursuit or accidentally via rebounding off other objects. Inertia and the elasticity of collisions mean the persistence of a bump is not guaranteed even if the pursuer halts its motion the instant the bump occurs. Due to the transitory nature of "bump", rules employing this predicate do not offer the "once" modifier.

Since the parent is only considered if its own parent's condition is true, an indented rule depends on all its ancestors' conditions being simultaneously true.

On each rule cycle, all the predicates on the current page are evaluated before any actions are run. This matters when a rule's action changes some state that a later rule's condition refers to. Even if the later rule's condition will be made false by the earlier rule's action, the later rule will still run because its condition was true when all the conditions were being evaluated.

This convention is sometimes useful and other times a source of obscure bugs. An example of the latter is:

[1] WHEN DO set score 5 points once
[2] WHEN timer 1 second DO subtract 1 point
[3] WHEN scored 0 points DO win

One solution is to initialize the score on page 1 but put the loop on page 2 so that the exit test cannot run until after the score has been properly initialized. Another solution is to use a short time delay to prevent the exit test from running on the very first rule cycle:

[1] WHEN DO set score 5 points once
[2] WHEN timer 1 second DO subtract 1 point
[3] WHEN timer .25 seconds DO
       ↳ [4] WHEN scored 0 points DO win

[1] WHEN DO set score red 5 points once
[2] WHEN DO set score "F" 1 point once
[3] WHEN timer 1 second DO subtract red 1 point
[4] WHEN scored "F" 1 point DO
       ↳ [5] WHEN scored red 0 points DO win

Actions can build on the effects of earlier actions. This matters mainly for score operations, where the actions "set score 5" and "score 1 point" will leave the score at 6 points when the rules are ordered as stated. If the order is reversed, the score will first be incremented and then that value will be discarded as the score is set to 5.

This rule arbitration mechanism is the heart of the Default Value idiom. In order for two actions to conflict, the verb must be the same, and the parameter values must be incompatible. For example, "color me red" and "color me blue" conflict, so the earlier action will prevail. Similarly, "open me" and "close me" conflict, as do "move toward" and "move wander".

There are a few cases where actions combine rather than conflict. For example, "move avoid" can merge with other move actions such as "move toward". Also, if a "WHEN gamepad L-stick DO move" rule is ordered after a "move toward" action, the two motions will combine. But if the gamepad rule appears before the "move toward" action it will override it.

When a "switch to page" action is executed, the actions of any remaining (i.e., higher numbered) rules are skipped. The following actions can therefore act as the "else" part of a conditional.

The "win" and "end" primitives also prevent any following actions from executing, because they immediately end the game.

For example: in a world with multiple apples, "WHEN see apple DO eat it once" will run until the first apple is successfully eaten. It will not run again until no apples are visible for at least one rule cycle, or the page is re-entered via a "switch to page" action.

Upon switching into a page, all rules have their "once" flag cleared, making them eligible to run. This is true even when the page being entered is the one that was just left.

If a program's goals can't be approached simultaneously, such as traveling to different locations or performing actions on different objects, the most straightforward solution is to assign each goal to a separate page. For example, to fetch an apple from a tree that launches an apple when bumped, and to give that apple to an octopus, we must pursue multiple objects. Pursuing the apple takes priority over pursuing the tree, but both can go on the same page because the apple doesn't become visible until the tree has been bumped. Pursuing the octopus should go on a separate page because the octopus is visible all the time; it will either override or be overridden by pursuit of the tree, neither of which is desirable.

PAGE 1:
[1] WHEN see apple DO move toward
[2] WHEN bump apple DO grab it
       ↳ [3] WHEN DO switch to page 2
[4] WHEN see tree DO move toward

PAGE 2:
[1] WHEN see octopus DO move toward
[2] WHEN bump octopus DO give

[1] WHEN got apple DO
       ↳ [2] WHEN see octopus DO move toward
       ↳ [3] WHEN bump octopus DO give
[4] WHEN see apple DO move toward
[5] WHEN bump apple DO grab it
[6] WHEN see tree DO move toward

The earlier two-page solution uses a single indented rule with an empty WHEN part: an instance of the Do Two Things idiom. The one-page solution uses two indented rules with non-empty WHEN parts, so these rules implement more complex conjunctive conditions: the If This And Also That idiom.

Even more complex state machines can be implemented on a single page by using scores, but the result is more baroque and less transparent than using separate pages.

A rule such as "WHEN timer 1 second DO ..." will run for one just rule cycle every time the timer expires. Thus, their actions should be of the type that take effect instantaneously, such as updating a score, creating or destroying an object, playing a sound, or switching pages. Move actions would be ineffective in this context because they require multiple rule cycles for the character to accelerate.

To use a timer to trigger an extended duration action, the timer must either set a flag or cause a page switch.

Because timer predicates are only true for an instant, any dependent (indented) rule can only run for an instant. Thus, if the indented rule contains its own timer, the nested timer will start but will be cancelled on the very next rule cycle when the parent rule is no longer active. Thus, nested timers conditions can never be satisfied.

Score expressions can occur in "WHEN scored score-color" conditions or in "DO score score-color", "DO set score score-color", or "DO subtract score-color" actions. A score expression consists of one or more tiles, in any order, that are either point tiles or score color tiles. The values of all the tiles that make up a score expression are added together.

A "WHEN scored score-color" condition or a "DO score score-color", "DO set score score-color", or "DO subtract score-color" action can also take a random expression as an argument. This consists of a "random" tile optionally preceded and/or followed by a score expression.

The condition will be true if the score changed during the preceding rule cycle.

Even inanimate objects like trees and rocks can grab, give, or receive objects. For clarity in the points that follow, we will use the term "character" for the holder and "object" for the thing being held, but any object can play either role.

If a character is holding an object when it grabs another object, the first object is dropped. Similarly, if a character is holding an object when another character gives it something, the first object is dropped.

If a character is grabbed while holding an object, the held object is dropped. If a held character attempts to grab an object, it fails: the action has no effect.

The holder can detect the held object with "got", but not with "see".

A character can see and bump a held object, but cannot steal it from the holder. However, the holder can use "give" to transfer the object.

For example: held objects can perceive the world, speak, create or launch other objects, and even boom the object holding them. But they cannot move or, as mentioned above, grab anything.

A character can only say one thing at a time. (But characters can play multiple sounds at once.) The minimum duration for a speech action is somewhere between 1.25 and 1.5 seconds.

If a character is already saying something when a new speech action is attempted, the new speech is discarded.

When a spoken text is heard is controlled by an option of the "said" tile in "WHEN hear said". By default, a character will not "hear" (hence, react to) an utterance until the speaker has finished. This allows for natural pacing of a conversation between characters. However, if a character should react immediately to an utterance, the setting can be changed to respond to the onset rather than the offset of speech.

With the default setting of "WHEN hear said", a character will never hear an utterance that is being repeated continuously because there is no speech offset event. The "once" modifier or some transient WHEN condition can be used to ensure that speech is uttered only once.

Dying, which can result from being eaten or shot, is detected by "WHEN health 0 points". The condition is true for exactly one rule cycle, so actions that require more time (such as motion) will not execute successfully. Switching to a new page can be used for short-circuit effect, but any rules on the new page will never run because this is the character's last rule cycle. However, many other actions can be performed in the dying state, such as manipulating scores, creating objects, even launching a missile.

A dying character that wishes to check its body color or glow color cannot do so, because it is no longer perceptible in the world.

During its last rule cycle, a dying character has already dropped whatever it was holding.