Scripting help
Making characters act
Change how a character looks, give the hero things, and time a character's moves, with examples.
my lines change the character itself while the game plays: how it looks, and its Object settings.
How it looks
Seven lines change its look:
| Line | What it changes | What it can be |
|---|---|---|
my opacity | How solid it looks | 0 to 100. At 0 it's invisible, though it can still touch the hero. |
my hue | Its colors, turned round the rainbow | -180 to 180. 0 is its own colors. |
my look | Light or dark | light, dark or normal. normal is the look you set in Colors. |
my effect | The effect around it | Any effect, like sparkles or fire, or none. |
my direction | Which way it faces | left, right, up or down. |
my angle | How far it's tilted, clockwise | -180 to 180. 0 is upright. See Spinning, tilting and growing. |
my size | How big it is, grown from its feet | 10% to 400%, or normal, which is its own size. |
These changes last until the level starts again. They don't change the settings you made in the builder.
This ghost waits facing left, faint and sparkling. When it sees the hero, it turns solid and dark, and gives chase. A hit turns it a new color and sets it on fire for 2 seconds, then it goes back to its own colors. Press the play button to try it, then change the numbers and try again.
Its Object settings
An enemy's script can set the same things as its Object settings. Each line is named after the setting, and takes the setting's own choices, written as plain words.
| Line | Setting | What it can be |
|---|---|---|
my weapon is lightningmy weapon is "Ninja star" | Weapon | A weapon the game has, like crossbow, lobbed shot or ball-and-chain, or none; or one of your own from the Addon Lab, by its name in quotes. |
my shot speed is slow | Weapon's Speed | slow, normal or fast, for a weapon that shoots or throws (built-in ones too). |
my shot size is big | Weapon's Size | small, normal or big. |
my shot spin is onmy shot spin is off | Weapon's Spins | Whether its shots turn round and round as they fly. |
my attack time is 2 seconds | Attacks every | 0.25 to 10 seconds, or a range like 1 to 3 seconds. |
my defeat effect is splat | Defeat effect | normal, poof, fireballs, pop, splat, leaves or zap. |
my speed is fast | Speed | slow, normal, fast or extra fast. Friends can use this line too. |
my walk left is 4 blocksmy walk right is 4 blocks | Walking: Left, Right | Platformer: how far each way it walks from its start. |
my notice left is 8 blocksmy notice right is 8 blocks | Notice: Left, Right | Platformer: how near on each side the hero must come. |
my walk distance is 4 blocks | Walk distance | Adventure: how far from its start it walks. |
my notice distance is 8 blocks | Notice distance | Adventure: how near the hero must come. |
my walk down stairs is onmy walk down stairs is off | Walk down stairs | Platformer, for an enemy that can. |
my grip is slippery | Grip | Platformer: sticky, normal or slippery. How well it keeps its footing on a tipped seesaw platform and on slippery ground. |
my weight is heavy | Weight | Platformer: normal or heavy. A heavy one tips a seesaw platform where it stands and lands. |
my body motion is bobbing | Body motion | Platformer: none, bobbing or pecking. How far and how fast stay as set. |
While the game plays, the script wins: the settings panel still shows what you set in the builder, and that's what the script starts from. Like the look lines, these last until the level starts again, and they're never saved to the map.
Poses
my pose is shows one of the character's poses and keeps showing it until the script picks another. my pose is normal goes back to walking and standing.
An enemy or boss you drew in the Addon Lab has the poses on its sprite. A pose you named goes in quotes; capitals don't matter.
| Line | What it shows |
|---|---|
my pose is "Anger" | A pose you added and named in the Addon Lab |
my pose is dying | One of the starting poses, played without being beaten |
my pose is walk left | A walk pose, whichever way the character is going |
my pose is normal | Back to the usual walking and standing art |
A pose plays from its first frame and loops. Dying plays once and stays on its last frame.
when I get hit
my pose is "Anger"
wait 1 second
my pose is normalSome built-in bosses have poses of their own, like windup; see boss parts.
Spinning, tilting and growing
These lines turn a character's picture round, and make it bigger or smaller. They change how it looks, not where it is, so a character can spin anywhere, even in the air. A spin goes on while the script carries on to its next lines.
| Line | What it does |
|---|---|
I am spinning | Spins it clockwise, 1 turn a second, until it's stopped. |
I am spinning left | Spins it the other way, anticlockwise. |
I am spinning 2 turns a secondI am spinning slowly | Spins it faster or slower. With slowly, one turn takes 2 seconds. |
I am not spinning | Stops it at once, at the angle it's at. |
I stop spinning slowlyI stop spinning over 1 second | Slows it down until it's upright, on its feet. |
my angle is 45 | Tilts it clockwise. -45 tilts it the other way, and 0 stands it up. It stops a spin. |
my size is 150% | Makes it bigger or smaller, from 10% to 400%. normal is its own size. |
my size goes up by 20%my size goes down by 25% | Grows or shrinks it by a part of its own size. From 100%, goes up by 20% makes 120%, and goes down by 20% takes it back to 100%. |
Like my opacity, my angle and my size can change gradually with slowly or over 2 seconds.
A spin and a move together make a roll. Add a pose of your own, like a ball, and it looks like it curls up first. This slime rolls at Cooper when it sees the hero:
This one gets smaller each time it's hit, and falls over once it's small:
| Good to know | What happens |
|---|---|
| Its body | Spinning and tilting only turn its picture. Where it can hit and be hit stays the same. |
| A bigger size | A bigger character hits and can be hit from further away, and a smaller one from nearer. Against the ground and walls it stays its own size, so it never gets stuck. |
| What stays upright | Its effect grows with it but stays upright, and so do its health bar and say bubble. |
| Checking | if I am spinning, if my angle is over 45 and if my size is over 150 check them. See Reading a setting. |
| How long it lasts | Until the level starts again, like the other my lines. |
| Who can use it | Enemies, bosses, villagers and the hero, in Adventures and Platformers. |
One step up or down
my speed goes up and my speed goes down move a setting one step from where it is now. They work on the five settings whose choices go in order. At the top or bottom step the line does nothing, so it is safe to run every time something happens.
| Line | Steps, low to high |
|---|---|
my speed goes up | slow, normal, fast, extra fast |
my shot speed goes up | slow, normal, fast |
my shot size goes up | small, normal, big |
my grip goes up | slippery, normal, sticky |
my weight goes up | normal, heavy |
This boss gets faster each time it is hit:
How it moves has no line, because it is the script: patrol, chase the {Hero}, fight smart and the other keep-doing words are what it picks.
An if can check the weapon and speed too: if my weapon is lightning, if my weapon is "Ninja star", if my speed is extra fast.
Harmless enemies
I am harmless makes an enemy that can't hurt the hero. Touching it does nothing, and it stops using its weapon. I am harmful turns that off again, and the enemy has the same weapon it had before.
| Line | What happens |
|---|---|
I am harmless | The enemy can't hurt the hero. |
I am harmfulI am not harmless | The enemy can hurt the hero again. |
This sleepy guard is safe to walk past until the hero hits it:
I am harmless
when I get hit
I am harmful
chase the {Hero}| Good to know | What happens |
|---|---|
| Shots in the air | A shot the enemy already fired still hurts. |
| Beating it | The hero can still hit a harmless enemy, and stomp it in a Platformer. |
| How long it lasts | Until the level starts again, like the other settings lines. |
| Who can use it | Enemies, in Adventures and Platformers. |
Weapons from the Addon Lab
A weapon you drew in the Addon Lab goes by its name, in quotes, as My Addons shows it; capitals don't matter. You don't have to add it to the game first: any weapon you've made can be named. If no weapon of yours has that name, the line does nothing and the enemy keeps the weapon it had. The game keeps a copy of every weapon its scripts name, so it still works when the game is played elsewhere or copied. See Weapons for drawing one.
One weapon comes built in, so you can try it right here: a Ninja star that spins as it flies. Press Play and the ghost throws it at Cooper.
Several settings on one line
A my line can set several things at once, with commas between them. The parts are one change, and they all happen at the same moment.
Each part after the first borrows the start of the line. So my shot speed is fast, size is small, spin is on is the same as my shot speed is fast, my shot size is small and my shot spin is on. A part can start with my again, as in my look is dark, my size is 50%.
To keep a long set-up tidy, end the line with a comma and carry it on underneath, indented:
Inside a rule, the carried-on lines go one indent deeper than the my line.
A timing at the end is for the whole line. Every part that can change slowly, and has no timing of its own, takes it:
| Line | What happens |
|---|---|
my opacity is 0, hue is 50 over 2 seconds | Both change together, over 2 seconds. |
my opacity is 0 quickly, hue is 50 slowly | Each part keeps its own timing. |
Setting a character up
Put my lines at the top of the script, before any when line, to set the character up. They happen when the level starts, and again when a beaten enemy comes back.
Changing during the game
my lines work inside a rule too. There, my opacity, my hue, my angle and my size can change gradually. End the line with over 2 seconds, very quickly, quickly, slowly or very slowly.
A gradual change doesn't hold up the next line. Add a wait if you want the script to wait for it:
Putting a setting back
restore my puts one of my settings back to how the builder set it, in Object settings. Whatever scripts changed goes, even a my line at the top of my own script.
Most settings a my … is line sets can be put back, like my size, opacity, hue, angle, look, effect, pose, weapon, speed, walk distance or notice distance. A script can only put back what it can set, so the hero script can't restore my weapon. My direction can't be put back.
A size, opacity, hue or angle can change back slowly, with over 2 seconds or slowly at the end. Anything else goes back at once, and a time after it gets a yellow note.
Health, lives, coins and @variables aren't settings, so restore my health gets a red note. Another script can put back one of my settings by telling me: the {Guard} restore my size.
Reading a setting
A setting is a value too. Use it wherever a value goes: in an if or a when line, in math, in a @variable, or in another setting's line.
| To do this | Write |
|---|---|
| Check it | if my size is over 150if my weapon is lightning |
| Check it against another value | if my health is under @dangerif @limit is under my size |
| Remember it | @old is my weapon |
| Put it back later | my weapon is @old |
| Change it from where it is | my opacity is my opacity - 10 |
| Read another character's | the {Guard}'s sizethe {Guard}'s weapon |
The settings that are numbers are my health, my opacity, my hue, my angle and my size, and in a Platformer, my tilt. The ones that hold words are my look, my effect, my weapon, my speed and my direction.
| Good to know | What happens |
|---|---|
| Numbers | They're whole, so my size is 150, not 150.4, while it grows. |
my look | It's normal until the script changes it. |
| A weapon from the Addon Lab | my weapon is its name, like Ninja star. |
| Words that don't fit | my weapon is @old does nothing when @old isn't a weapon. The script log says so. |
| Another character's | the {Guard}'s size is nothing when there's no Guard here. |
Where a character is
Every block on the map has a column and a row. Columns count from the left, and rows count up from the bottom, so the bottom-left block is column 1, row 1. The builder's rulers count the same way. Point at a block on the map, and the rulers show its column and row.
Reading where things are
| To get | Write | What it gives |
|---|---|---|
| My row or column | my rowmy column | The block this character is on. |
| The hero's | the {Hero}'s rowthe {Hero}'s column | The block the hero is on. |
| A thing's, by its ID | the {Guard}'s rowthe {Door} column | The block of the first thing with that ID. The 's is up to you. |
| How far apart two things are | my distance to the {Door}the {Goblin}'s distance to the {Hero} | Blocks in a straight line, like 2.2. from works too, as in the {Door} distance from me. |
Use them wherever a number goes: in an if or a when line, in math, or in a @variable. To show one in a say, put it in a @variable first.
when the {Hero} talks to me
@far is my distance to the {Door}
if my row is over 5
say "I'm up high. The door is @far blocks away."
endJumping to a block
my row is 2 and my column is 4 make a character jump straight to that block. It doesn't walk there, it's just there.
when I see the {Hero}
say "Catch me if you can!"
wait 1 second
my column is 4
my row is 2A row line and a column line with no wait between them make one move, so this ghost goes straight to column 4, row 2. The number can be math or a @variable, like my column is my column + 1. my column goes up by 1 works too.
Good to know
| When | What happens |
|---|---|
| It can't stand on the block | A wall, water, something in the way, someone else on the block, or off the map: it stays put. With the Script log on, the log says why. |
| The block is higher or lower ground | In an Adventure, it stays put. It can only jump to a block on the ground it's on now. |
| The block is in the air | In a Platformer, it falls from there. |
| Who can be moved | Only the script's own character. A boss can't jump to a block, and game and level scripts can't move anyone. |
| Its home | Doesn't change. go home still goes back to where you put it in the builder. |
| Which block it's on | The one its feet are in. In a Platformer, an enemy standing on the bottom row's ground is in row 2. |
| A thing that isn't here | A beaten or hidden character, or one in another level, has no row, column or distance. In math, that counts as 0. |
| A thing on several blocks | Its row and column are its first block's. A distance is to its nearest block. |
Giving the hero things
A villager gives from their own bag. Their bag starts with the item set in Gives the hero in their Object settings. Write give, then the item's name in quotes, just as the bag shows it: give a "Sack of apples" to the {Hero}. If the villager doesn't have it, nothing happens. If the hero's bag is full, the villager says so.
You can leave out a or an before an item.
Things from nothing
Only the game can make something from nothing. Write {Game} in front, and the game gives it, whoever's script the line is in. The villager's bag doesn't change.
| Write | What the hero gets |
|---|---|
give a "Sack of apples" to the {Hero} | The villager's own sack of apples, if they have one. |
{Game} give a "Sack of apples" to the {Hero} | A new sack of apples, made by the game. |
{Game} give 5 coins to the {Hero} | 5 coins, made by the game. |
Trading with the hero
A villager can't take things from the hero's bag. Instead, they offer a deal, and the hero chooses. A deal box shows what the hero gives and what they get, with Deal and No thanks. Both sides happen together, or neither does.
Making an offer
Write offer, then what the hero gets, then to the {Hero}, then "for" and what they give. Each side is an item in quotes, with how many in front, or some coins. To keep the hero's answer, put it in a @variable: it is yes when the deal was made, and no when it wasn't.
| Offer | What it is |
|---|---|
offer "Health egg" to the {Hero} for 10 coins | The villager sells an egg. |
offer 10 coins to the {Hero} for 3 "Sack of apples" | The villager buys apples. |
offer 2 "Health egg" to the {Hero} for "Speed egg" | A swap, item for item. |
Where things go
What the villager gives comes out of their bag, and what the hero gives goes into it. A shop keeper's bag is his shelves, so apples he buys go on sale. If the deal can't happen, the box says why and has only OK. That's when the hero is short of something, either bag would be too full, or the villager doesn't have what they offered.
Counting what's in a bag
A script can count what the hero carries, or what a villager holds in their own bag. Then it can check the number, like if @apples is at least 3.
| Count | Gives |
|---|---|
@apples is the number of "Sack of apples" in the {Hero}'s bag | How many apples the hero carries. |
@eggs is the number of "Health egg" in my bag | How many eggs the villager holds. |
@coins is the number of the {Hero}'s coins | The hero's coins. Shards and goal keys work the same way. |
A villager can also check the hero's bag with if the {Hero} has at least 3 "Sack of apples".
When the hero makes an offer
Talking to a villager opens a talk box with what they say. A shop keeper whose shop is open goes straight to their market stall instead, and a closed shop's keeper has a talk box with Shop left out.
Make offer shows in the talk box or the stall only when the villager can take an offer: their script has a when the {Hero} makes an offer rule, or their settings give their item as a deal. With Make offer, the hero picks things from their bag and some coins to give. The villager's when the {Hero} makes an offer rule decides what happens.
A shop keeper's when the {Hero} talks to me rule still runs. A question it asks comes before the stall, and the stall opens once it's answered. What it says shows in the stall's speech bubble.
| Word | What it does |
|---|---|
… in the offer | Counts an item the hero offers, like @apples is the number of "Sack of apples" in the offer, or … coins in the offer. |
accept the offer | Takes everything offered, and gives the hero the villager's Gives the hero item, if they still have it. |
accept the offer for "Health egg" | Takes everything offered, and gives this item from the villager's bag. |
turn down the offer | Says no. The hero keeps everything. |
An offer the rule doesn't answer is turned down when the rule ends. A villager with no offer rule takes an offer that covers what their Wants setting asks for, and turns down any other.
A shop keeper who trades
A shop keeper's talk box has a Shop button. Put close my shop first in his talk rule to take it away, so he talks or makes deals instead. open my shop brings it back.
Example: a slime that only fights back
Start from Walks around. That script says attack at the start, so the slime fights from the beginning. Move attack into a new rule, and the slime only fights once the hero hits it:
Example: a villager who waves you over
Start from Stays put and add a rule. Now the villager calls out every few seconds until the hero comes over, and hands over the item in Gives the hero when the hero talks to them:
Example: a ghost that fades in and out
Like the Spooky weapon, but the ghost keeps walking its patrol while it's gone. Every 3 seconds it fades out in a quarter of a second, patrols unseen for 2 seconds, then fades back in. It works the same in a Platformer and an Adventure.
patrol for 2 seconds is the waiting part. A wait would hold the script too, but it also stands the ghost still; a mode with for holds the script while the ghost keeps doing it, then goes back to what it was doing before. The ghost still hurts by touch and can still be hit while it's invisible, so make the patrol for time shorter if that feels unfair. The ghost recipe makes it harmless while it's gone.
With a few ghosts on one level, that script makes them all vanish together. Give each its own rhythm with a range of times: a time between the two is picked each time, and each ghost picks its own.
Advanced: timing
Some steps can say how long they take, and how they speed up and slow down along the way.
This works for moves that go somewhere, which are run away 3 blocks, move toward the {Hero} 2 blocks, move left 4 blocks and go home. It also works for the gradual my opacity and my hue changes. Jumps and keep-doing words, like chase the {Hero} and patrol, don't take a timing.
How long it takes
End the line with one of these. Without one, a move takes as long as walking it would.
| Words | How long |
|---|---|
over 2 seconds | The time you write |
over 1 to 3 seconds | A time between them, each time |
very quickly | A quarter of a second |
quickly | Half a second |
slowly | 2 seconds |
very slowly | 4 seconds |
Speeding up and slowing down
with adds a timing. It's written exactly as CSS writes it, so one copied from any generator on the web works. These all work: ease, ease-in, ease-out, ease-in-out, linear, cubic-bezier(x1, y1, x2, y2), linear(0, 0.3 20%, 1) and steps(4).
A timing changes how fast the character covers its way, never the way itself. Walls and ledges still stop it. It also never goes faster than about three times its walking speed, so a steep curve just takes a little longer.
A curve that goes past 1, like linear(0, 1.1, 1), overshoots a little and comes back.
Coming out of the ground
Enemies and boss bodies in Platformer and Adventure can use I burrow and I emerge. Without a time, the change happens instantly. Add over 0.5 seconds to show the movement. A timed action finishes before the next line runs.
when I start
# Begin safely underground.
stand still
I burrow
when I see the {Hero}
# Rise, stay out for three seconds, then go back under.
I emerge over 0.5 seconds
wait 3 seconds
I burrow over 0.5 secondsAdd and go to keep running the script during a transition: I emerge over 0.5 seconds and go. Asking to burrow while emerging reverses smoothly from the current position. Repeating the same request does not restart it.
Use if I am underground, if I am above ground, if I am emerging, or if I am burrowing to choose what happens next. “Above ground” means the character has reached the exposed height chosen in Object settings. The Groundhog's own art already shows it halfway out.
Fully underground characters cannot touch, hurt, or be hurt, but their scripts keep running and can still notice the hero. During a transition only the exposed body can touch or be hit. I am harmless and I am invulnerable still work independently: use them if you want rising or retreating to be safe.
An attached boss part asks its boss to run a burrowing function. Individual parts, heroes, villagers, and blocks cannot burrow. Maze uses the Groundhog's built-in behavior and does not offer these scripting words.

