Scripting help

Recipes & Tips

Scripts to copy and change, like a character that rolls at the hero and a ghost that fades away, and tips for keeping a script easy to read.

A recipe is a script that does one thing, ready for you to copy and change. A tip is a way of writing a script that makes it easier to read and to fix.

Every script on this page can be tried. Press the play button beside it, then change a number and try it again.

The recipes build on each other, so it helps to read them from the top.

Recipe: seeing what a script does with log

log writes a line in the script's log, so you can see what a script is doing while the game plays. It's the quickest way to find out why a character isn't doing what you expected.

On this page, the log is the box under each script. While the game plays, it takes the place of the problems box. Press Stop and the problems come back.

Writing a line in the log

Write log, then some words in quotes. When the script gets to that line, the words show in the log. Press Play and watch the box under the script.

No problems detected

Each line in the log starts with the game's time and who wrote it, like 0:02 Enemy: I saw the hero. A line written many times in a row shows once, with a count.

In the builder, the log has a drawer of its own. Turn on Script log in Game settings, and the Script log drawer shows under Find a brush. It fills up while you try your game.

The Script log drawer under Find a build tool: Copy and Clear in its header, and under it the lines an enemy's script wrote, each with the game's time and who wrote it.

Logging a line of the script

Put log in front of a line of the script, with no quotes. The line still does just what it did before, and the log says what happened.

No problems detected

You logIt writesLike
A when or every lineEach time the rule starts, and what set it offwhen I see the {Hero}: the hero is 4 blocks away, to my left
A step that happens at onceThat it was doneface the {Hero}: done
A step that takes timeHow long it took, once it's donewait 1 second: done after 1 second

log works in front of other lines too, like an if or a repeat. The recipes below use it there.

Seeing what a @variable holds

Write log and a @variable on its own, like log @count. The log says what it holds now, like @count is 3.

For a thing, the log says more, so you can find out what the variable points at. It says what kind of thing it is, its map id, and where it is now. A list shows each thing in it.

The variable holdsThe log says
A number, words, yes or no@count is 3
A thing in this level@boss is {Slime King}: a character, map id enemy_2, at column 12, row 3
A thing that's beaten or hidden… not out now (beaten or hidden)
A thing in another level… in another level (frozen cave)
A thing taken off the map… taken off the map
A list@ghosts is a list of 2: and then each thing, as above

Finding out what went wrong

This character should wait 3 seconds and then speak, but it never says a word. The log shows why.

No problems detected

The log says the wait was cut short after 2 seconds, because every 2 seconds took over. A character runs one rule at a time, so when the rule comes round again, it stops its own earlier run. Change wait 3 seconds to wait 1 second, and the character speaks.

Good to know

A log line is safe to leave in a script.

AboutWhat happens
The gameA log line takes no time, and never changes what the character does.
PlayersThey never see the log.
In the builderTurn on Script log in Game settings, and the Script log drawer shows what your scripts write.

More about the log is in Seeing what a script does.

Recipe: choosing what to do with if

if lets a character choose. It checks something, and the steps under it happen only when the check is true. Use it when a character should do one thing some of the time and another thing the rest of the time.

One choice

This character tells the hero to back off, but only when the hero is close. every 2 seconds makes it check again and again. While the hero is further away, the check isn't true, so the line under the if is skipped.

No problems detected

near means within 3 blocks. Walk up to the character and it speaks. Walk away and it goes quiet.

The log in front of the if writes its answer each time, yes or no, and what it checked. Watch the log as you walk up and away.

The lines between if and end are the ones that depend on the check. They are written further in, so you can see where the if starts and stops.

This or that

Add else, and the character does one thing when the check is true and another when it isn't. This one turns to face the hero, and says which side the hero is on. Columns are counted from the left, so a hero with a smaller column is on the left.

No problems detected

Each choice can have as many steps as you like. Here each one has two: turn to face the hero, then speak. Jump over the character to the other side, and at its next check it turns round and says the other line.

More than two choices

else if adds another check. The checks are tried from the top, and the first one that's true wins. The steps under else happen when none of them were true.

This character says something different for a hero who is very close, quite close, or far away.

No problems detected

The order matters here. A hero 1 block away is within 2 blocks and within 5 blocks too, but only the first check counts, so the character says "Too close!" and nothing else. The log shows this: once a check answers yes, the checks under it aren't tried.

Handy checks

These are some of the things an if can check.

CheckWhen it's true
my health is under 50The enemy's health is below 50. over, at least and at most work too.
the {Hero} is nearthe {Hero} is within 5 blocksThe hero is within 3 blocks, or within the number you write.
the {Hero} is farThe hero is more than 3 blocks away.
I see the {Hero}The hero is in the enemy's view.
the {Hero}'s column is under my columnThe hero is to the left.
a 1 in 3 chanceOne time in three, picked by luck.

Every check, and how to join two of them, is in Choosing with if and end.

Recipe: doing steps again with repeat

repeat does the same steps again and again. Use it when you find yourself writing the same lines over and over. The script gets shorter, and it's easier to see what the character does.

Before

This character paces left and right three times when it sees the hero, then gives chase. The same two lines are written three times, so you have to count them to know how many times it paces.

No problems detected

After

Here the two lines are written once, inside a repeat. The script does just the same thing. Now the number says how many times it paces, and changing 3 to 5 is all it takes to pace more.

No problems detected

The lines between repeat and end are the ones that repeat. They are written further in, so you can see where the repeat starts and stops. The line after end happens once, when the repeat is done.

The log in front of the repeat writes a line each time round, like time 2 of 3.

Ways to repeat

A repeat can run a set number of times, or keep going until the script stops it.

WriteWhat it does
repeat 3 timesDoes the steps 3 times. The most is 20.
repeat @count timesDoes them as many times as the number in a @variable.
repeatrepeat foreverKeeps going until a stop repeating line, or until another rule takes over.
stop repeatingLeaves the repeat early, and carries on with the line after end.

Repeating until something happens

Put stop repeating under an if, and the repeat goes on until the check is true. This character creeps up one block at a time. When the hero is near, it stops creeping and shouts.

No problems detected

Repeating until another rule takes over

A repeat with no number never runs out by itself. In a character's script only one rule runs at a time, so a new rule that starts takes over, and that ends the repeat. This guard paces until it sees the hero.

No problems detected

The next recipe uses a repeat like this one to make a character roll at again and again.

Recipe: rolling at the hero

A spin and a move together make a roll. The spin turns the character's picture round, and the move carries it over the ground, so it looks like a ball rolling at the hero.

The basic roll

This is the smallest roll that works. It has three steps: start spinning, move, stop spinning.

No problems detected

LineWhat it's for
I am spinning 2 turns a secondStarts the spin. The script goes straight on to the next line while it spins.
move toward the {Hero} 4 blocks over 1 secondThe roll itself. The character keeps spinning all the way.
I stop spinning quicklySlows the spin down until the character is upright, on its feet.

This character rolls only once. when I see the {Hero} happens at the moment the hero comes into view. While the hero stays in view, it doesn't happen again, even if the hero jumps over to the other side. The log shows it: the when line is written there once, and never again.

Rolling again and again

To keep rolling for as long as it sees the hero, the roll needs to happen again and again. Two things make that easy to write.

PartWhat it does
A functionlearn to roll at gives the three roll steps a name. After that, roll at is a step you can use, and it does all three.
A repeatDoes the roll and a rest, over and over, while the hero is in view.

A second rule, when I lose the {Hero}, takes over when the hero gets away. That ends the repeat and sends the character home.

No problems detected

The wait 1 second is a rest between rolls. It gives the hero time to hit back or get away.

With the roll in a function, the rule under it stays short however much the roll grows. The next two steps only change the function. Functions has more about them.

If itLook at
Never stops rolling, and the log never shows when I lose the {Hero}Its Notice distances in Object settings. A character with a wide notice hardly ever loses the hero.
Should only roll at a hero close byWrite when I see the {Hero} within 5 blocks in place of that rule's first line.

Rolling the right way

A ball that rolls to the right turns clockwise, and one that rolls to the left turns the other way. I am spinning turns clockwise, and I am spinning left turns the other way.

Here the function uses an if to check which side the hero is on before each roll, and picks the spin to match. Jump over this character, and its next roll comes back at you, turning the other way.

No problems detected

A warning before each roll

A roll is fairer, and more fun to dodge, when the hero can see it coming. Here the function turns the character to the hero and waits a moment before each roll.

No problems detected

with ease-in makes the roll start slowly and speed up, like a real ball. See Advanced: timing.

Making it your own

Change these parts of the roll to make it fit your character.

To changeChange thisTry
How far it rollsThe blocks in the move line6 blocks for a long roll
How fast it rollsThe time in the move lineover 2 seconds for a slow, heavy roll
How fast it spinsThe turns in the I am spinning line3 turns a second, or slowly
How it stopsThe end of the I stop spinning lineslowly, or over 1 second
How big it isA my size line before the spinmy size is 150%, then my size is normal after the roll

A character you drew in the Addon Lab can curl up too. Give its sprite a pose of a ball. Then show that pose before the spin, and write my pose is normal after it. See Poses.

Spinning only turns the character's picture. Where it can hit and be hit stays the same. All the spin words are in Spinning, tilting and growing.

Recipe: a ghost that fades in and out

This ghost patrols, fades away, and fades back in. While it's gone it can't hurt the hero, so the hero can walk right through it. It works the same in an Adventure and a Platformer.

The basic fade

my opacity says how solid a character looks. 100 is solid, 50 is half see-through, and 0 can't be seen at all. This ghost starts at 50. Every 3 seconds it fades to nothing, patrols unseen for 2 seconds, then fades back.

No problems detected

LineWhat it's for
my opacity is 50, at the topSets the ghost up before the level starts.
my opacity is 0 over 0.5 secondsFades it out. A fade doesn't hold up the next line.
patrol for 2 secondsThe time it stays gone. The ghost keeps walking, and the script waits here.
my opacity is 50 over 0.5 secondsFades it back in.

Harmless while it's gone

A ghost nobody can see still hurts the hero who bumps into it, and that feels unfair. I am harmless stops it hurting, and I am not harmless lets it hurt again.

No problems detected

The fade doesn't hold up the next line, so the ghost is harmless from the moment it starts to fade out. It can hurt again from the moment it starts to fade in.

Not every time

A ghost that vanishes on a beat is easy to learn. Put the fade inside an if with a chance, and the hero can't tell when it will go. Here it vanishes about half the time. The log shows how each try came out.

No problems detected

One number to change

The number 50 is written twice. To make the ghost more solid, you'd have to change both, and it's easy to miss one. A @variable of the ghost's own keeps the number in one place, at the top.

No problems detected

Change 50 to 80 in the first line, and the ghost starts at 80 and fades back to 80. This is handy for a ghost you use in more than one game. See A character's own @variables.

Fading as functions

Fading out is two steps that belong together, and so is fading in. Give each pair a name with learn to. Now the rule at the bottom reads like a plan: fade out, patrol, fade in.

No problems detected

A flicker before it goes

A warning makes the ghost fairer. Here it stops and flickers three times before it vanishes. The flicker is a function with a repeat inside it.

No problems detected

The rule now says every 5 seconds, not 3. The flicker takes a second and a half, and with the 2 seconds gone, the whole thing takes longer than 3 seconds.

Making it your own

Change these parts to make the ghost fit your game.

To changeChange thisTry
How solid it looksThe number in the first line80 for a ghost that's easy to see
How long it's goneThe time in the patrol for linepatrol for 1 to 2 seconds, for a time picked by luck
How often it goesThe chance in the if linea 1 in 4 chance for a ghost that rarely goes
Ghosts that don't go togetherThe time in the every lineevery 5 to 8 seconds, so each ghost picks its own time
How many flickersThe number in the repeat linerepeat 5 times, with a longer every
Good to knowWhat happens
Keep it shorter than the everyWhen the every rule comes round again, it stops its own earlier run. A ghost stopped while it's gone stays gone, and harmless, until the next time.
Hitting itThe hero can still hit a harmless ghost, even one that can't be seen.
Who can use itEnemies. Villagers can fade, but I am harmless is for enemies.

Recipe: a villager who trades

An Adventure villager can't take things from the hero's bag. They offer a deal, and the hero picks Deal or No thanks. This farmer swaps an egg for 2 apples.

The trade

The farmer counts the hero's apples first, so the hero only sees a deal they can take.

3 lines I can't understand. They're skipped when you play.

  • "when the {Hero} talks to me" is for villagers, not enemies.
  • Counting what's in a bag is for villagers, the game script and level scripts.
  • "offer" is for an Adventure's villagers, its game script and its level scripts.

Changing it

To make itChange
Sell for coinsoffer "Health egg" to the {Hero} for 10 coins, and count the {Hero}'s coins first.
Buy from the herooffer 15 coins to the {Hero} for 2 "Sack of apples". A villager's coins never run out.
Take what's offeredUse when the {Hero} makes an offer instead. See When the hero makes an offer.

The egg comes out of the farmer's own bag, and the apples go into it. Set the egg in Gives the hero in the farmer's Object settings, or the farmer has nothing to trade.

Tip: leave notes with comments

A line that starts with # is a comment. It's a note for you, or for anyone who reads your script, and the game skips it. A few good comments make a script much easier to come back to later.

Before

This is the ghost from the recipe above. It works, but you have to read every line to find out what it does, and nothing says why the numbers are what they are.

No problems detected

After

Here is the same script with comments. The game does just the same thing. Now the top line says what the character is, and each part says what it's for.

No problems detected

A comment sits on a line of its own. It can go anywhere in the script, and it can be written further in, like the lines around it.

What to write

A good comment tells the reader something the line under it doesn't.

WhereWhat to writeLike
The top of the scriptWho the character is and what it does.# A ghost that fades away now and then.
Above a numberWhat the number means, and what happens if it changes.# How solid the ghost looks.
Above a ruleWhy the rule is there, or something to watch out for.# Keep this longer than the time the ghost is gone.
Above a group of stepsWhat the steps do together.# Fade back in

A comment that only says the line again doesn't help. # Patrol above patrol is one of those, so leave it out.

Switching a line off

A comment is also a quick way to try a script without one of its lines. Put # in front of the line, and the game skips it. Take the # away to bring the line back.

Here the ghost never becomes harmless, because both of those lines are switched off. Try it, and see how much harder the ghost is to get past.

No problems detected

Tip: keep a script tidy with functions

A function is a name for some steps. The rolling recipe put its roll in one. When a script gets long, move its steps into functions with clear names. Then each rule is short, and it reads like a plan.

Before

This character rolls at the hero every 4 seconds while it can see them, and rolls twice when it's hit. It works, but the same five lines are written three times. To change the roll, you'd have to change it in three places.

No problems detected

After

Here the roll and the rest are functions. The script does just the same thing, and the two rules at the bottom now say what happens in plain words.

No problems detected

Why it helps

Functions help in three ways.

What you getWhy
Short rulesA rule shows what the character does. How it does it is inside the function.
One place to changeMake the roll longer inside the function, and every rule that uses it changes.
Fewer mistakesSteps written once can't be different by accident in one of the copies.

Ways to stay organized

These habits keep a script with functions easy to find your way around.

HabitHow
Name it for what it doesroll at says more than move 1. The name can be several words.
One job for each functionKeep the roll and the rest apart. Then a rule can roll twice and rest once.
Functions first, rules lastPut every function at the top of the script, with the when rules under them.
Give it a valueFor a short roll and a long one, make one function that takes how far to go, not two functions.
Say what it's forWrite a comment line that starts with # above a function, to say what it does.

Here the roll takes a value, so one function does a short roll and a long one:

No problems detected

Everything a function can do is in Functions. A function that many characters need can go in the game script or in a family; see Sharing a function with the whole game and Families.

A boss that keeps popping up

A loop lets the boss attack again even if the hero stays nearby. This example needs no special pose names. Use Object settings to choose its exposed height.

when I start
  stand still
  I burrow

  repeat forever
    repeat until the {Hero} is within 4 blocks
      wait 0.1 seconds
    end

    ambush

    # A short break gives the hero time to move.
    wait 2 seconds
  end

learn to ambush
  I am harmless
  I am invulnerable

  I emerge over 0.5 seconds

  I am harmful
  I am vulnerable

  wait 3 seconds

  I am harmless
  I am invulnerable

  I burrow over 0.5 seconds
end

The Groundhog's own script also waits after the hero leaves: one second of scratching, then one second looking at the camera. Its warning dirt is an in-game effect, so editing the script does not make that one-time effect repeat.