Scripting help

Triggers

The "when" lines that start a rule, like when I get hit or every 3 seconds, and triggers of your own that set off a "when" in every script at once.

A trigger says when a rule happens. It is the when line at the top of a rule, and the lines under it run each time the trigger happens. Most triggers are built in, and the game sets them off by itself: when I start, when I get hit, when I reach an edge and after 3 seconds are all triggers.

​
​
​

This character patrols from the start, chases the hero when it sees them, and runs away when it gets hit. Every 4 seconds it calls out. Press the play button to try it.

In a character's script, only one rule runs at a time. When a trigger starts a new rule, that rule takes over from the one that was going (see One rule at a time).

Built-in triggers

These are the triggers a character's script can use. Find them all in the Trigger drawer of Words you can use.

TriggerWhen it happens
when I startWhen the level starts, and when the character comes back after being beaten.
when I see the {Hero}When the hero comes into view. Add within 5 blocks to say how near.
when I lose the {Hero}When the hero gets out of view.
when the {Hero} comes nearWhen the hero walks up close: 3 blocks, unless you say how near.
when the {Hero} walks awayWhen the hero goes more than 3 blocks away again.
when the {Hero} swings at meJust before the hero's swing would hit. Good for dodge.
when I get hitWhen the hero hurts the character, and it isn't beaten yet.
when the {Hero} touches meWhen the character bumps into the hero and hurts them.
when the {Hero} talks to meWhen the hero talks to the character.
when the {Hero} makes an offerIn an Adventure, when the hero offers things to trade (see Trading with the hero).
when I reach an edgeIn a Platformer, when the next step would walk off the floor.
when I bump into a wallIn a Platformer, when the character walks into a wall, or the side of the level.
when I landIn a Platformer, when the character comes down on a floor after a jump or a fall.
every 3 secondsAgain and again (see Time).
after 3 secondsOnce, this long after the script starts (see Time).
when the countdown endsWhen a countdown gets to 0.
when @apples is at least 3Once each time the check comes true. Most checks an if can make work here, but not a chance or a function.
when "alarm"When any script sends the trigger "alarm" (see Your own triggers).

Game and level scripts have triggers of their own, like when the game starts and when any {Heroes} enters. See Game and level scripts. The hero script has its own too, in The hero script.

Time

every 3 seconds happens again and again, and after 3 seconds happens once. Both count from when the script starts.

A keep-doing word goes on until another rule changes it. Add for 2 seconds to do it for just that long, as in chase the {Hero} for 2 seconds. Any time can be in minutes too, like start a countdown of 2 minutes. You can write wait 1 second or wait for 1 second.

A short time can be written in words. wait a second is 1 second. For less than a second, write wait half a second or wait a quarter of a second. This works anywhere a time goes, like every half a second.

​
for
​

This character patrols, and every 4 seconds it calls out, waits a moment, then chases the hero for 2 seconds. After 10 seconds it gets sleepy and stops. Press the play button to try it, then change the numbers and try again.

A step that takes time finishes before the next one starts. After run away 3 blocks, the next line waits until the character gets there. A move like that can also say how long it takes, with move left 4 blocks over 2 seconds or move left 4 blocks slowly. Advanced: timing has more.

A time picked at random

Write two times with to between them, and the character picks a time between them each time: every 2 to 4 seconds, wait 1 to 3 seconds, patrol for 1 to 2 seconds or my opacity is 0 over 0.5 to 1 seconds. Each character picks its own, so a level full of the same enemy doesn't move in step. Online, every player sees the same picks.

every 2 to 4 seconds
  jump
when I see the {Hero}
  wait 1 to 3 seconds
  chase the {Hero}

The first character jumps every 2 to 4 seconds, never quite in a beat. The second stops for a moment when it sees the hero, never for the same time twice, before it gives chase.

Your own triggers

You can make triggers of your own too. One is a signal any script can send. Write trigger and a name in quotes, like trigger "alarm". Every script that has a when "alarm" hears it and runs that rule. That can be one character, a whole horde, the level script and the game script, all at once.

The script that sent it waits until every one of them is done, then carries on with its next line.

trigger "cheer" with @times is 2, @words is "Hooray!"
​
repeat trigger @times times
end

This character hears its own trigger. It cheers twice, and only then says "That was fun".

Sending a trigger

The name goes in quotes. Big and small letters don't matter, so trigger "Alarm" sets off when "alarm" too.

Written likeWhat it does
trigger "alarm"Sets off every when "alarm", and waits for them all.
trigger "alarm" with @count is 5The same, with a value named @count.
trigger "alarm" with @count is 5 and goCarries on straight away, without waiting.

A trigger with nobody listening is done at once, and the script carries on.

Hearing a trigger

A rule that starts when and a name in quotes runs each time that trigger is sent. Characters, the hero script, the game script and level scripts can all have one.

A trigger never stops a rule. A character in the middle of a rule puts it on hold, runs its when "alarm", then picks the rule up again where it was. Its own when lines still work as always, so when I get hit stops everything it was doing, the trigger's rule too.

Every script with the when hears it, the one that sent it too. Characters hear it first, in the level's order, then the hero script, the game script and the level script. Each one runs until it gets to a step that takes time, like wait or chase the {Hero} for 2 seconds, and then the next one starts. So a whole horde moves together.

What a trigger brings

Inside a when "alarm", the word trigger stands for the trigger it heard. It has the values it was sent with, and a few things it always knows.

Written likeWhat it gives
trigger @countThe value sent as @count.
trigger 1st valueThe first value sent. 2nd, 3rd, 4th and 5th work too.
trigger 7 valueThe seventh value. Past the fifth there's no short way to say it.

A value it wasn't sent with is nothing. Named values are easier to read than numbered ones, so give values names when a trigger has more than one.

What a trigger brings can be read but not changed. To change it, keep it in a @variable of your own first, like @count is trigger @count.

Who sent it

A trigger also knows who sent it. The game fills these in by itself.

Written likeWhat it gives
trigger nameThe sender's name: its brush's name, like "Bubble, green", or the one its script gave it with my name is.
trigger idThe sender's ID as words, like "Guard". A thing with no ID gets one made up, like "enemy-slime3".
{trigger id}The sender itself, in braces, wherever an ID goes: hide {trigger id}, {trigger id} attack.
trigger rowThe row the sender was on, when it has a place.
trigger columnThe column the sender was on, when it has a place.

trigger id and {trigger id} are different. Without braces it's words you can show or check, like if trigger id is "Guard". With braces it points at the sender, even one with no ID of its own.

Names

A character's name starts as the name of the brush it was placed with, as the builder's drawer writes it. A script can give it another with my name is "Goblin". The game script is called "game", a level script by the level's name, and the hero script "hero".

A name is words, not an ID. Other scripts still point at the character with its ID, like {Goblin}.

Checking who sent it

These checks go in an if, inside a when "…". Put not in front to check the other way, like if not trigger is from me.

Written likeTrue when it was sent by
trigger is from meThis script. A sender hears its own trigger.
trigger is from the {Hero}The hero script.
trigger is from a friendA villager.
trigger is from an enemyAn enemy, a boss, or a boss's part.
trigger is from a bossA boss, or one of its parts.
trigger is from a shop keeperA villager with a shop.
trigger is making dealsA villager whose item is a deal.
trigger is from the gameThe game script.
trigger is from a levelA level script.

What built-in triggers bring

Some built-in triggers bring something too, the way a trigger of your own brings its values. Inside the rule, trigger stands for it, and what it brings is named after what it is.

when I hatch a power-up
  if trigger power-up is speed boost
    say "I got speeeeeed boost!"
  end
TriggerWhat it bringsWhat it can be
when I hatch a power-up and when any {Heroes} hatches a power-up (Platformer)trigger power-upspeed boost, super jump, jetpack, invincible, shield or extra life
when I gain a skill and when any {Heroes} gains a skill (Adventure)trigger skilldash, smash or swim

Check it without quotes, like if trigger power-up is speed boost, or is a speed boost. To show it, put it in words in quotes: say "I got a trigger power-up!". Like everything a trigger brings, it can be read but not changed.

These rules don't have the other trigger words. trigger @count, trigger name, {trigger id} and trigger is from … only work in a when "…" with a name. Inside a when any {Heroes} … rule, the {Hero} is still the hero it happened to.

Controlling a horde

A boss can send one trigger, and every minion with a when for it reacts. The boss doesn't need to know their IDs, or how many there are.

The boss's script:

when I see the {Hero}
  trigger "charge" with @times is 2
  say "Get them!"

Each minion's script, or one family script for them all:

when "charge"
  repeat trigger @times times
    charge at the {Hero} for 2 seconds
  end

Each minion charges as many times as the boss says. The boss says "Get them!" once every minion has finished charging.

Stopping the rest

stop triggering inside a when "alarm" means the scripts after this one don't hear it. Put it before any step that takes time, because the scripts after it start as soon as this one gets to one.

when "alarm"
  if trigger @count is over 3
    stop triggering
  end
  say "I heard it"

Good to know

WhenWhat happens
A when "alarm" sends "alarm" againTriggers sent inside each other stop after 8 deep, so it can't go on for ever.
A listener never finishesThe sender waits up to a minute, then carries on.
A character is far away and asleepIt hears the trigger when it wakes up, and the sender waits for it. Add and go to not wait.
You want just one character to do somethingTell it by its ID instead: see Telling another character what to do.