Scripting help
Game and level scripts
Scripts for the whole game and for each level, winning and losing, examples with IDs, and a quest.
The game script runs the whole time someone plays, in every level and world. Each level can have a script of its own too. They're for quests and story moments, like a gate that opens when every enemy is beaten, a message when the hero finds the cave, or a countdown to beat.
| Script | When it runs | How to open it |
|---|---|---|
| Game script | The whole game, in every level and world. | Game script in the Scripts card of Game settings |
| Level script | While the hero is in that level. A level is an Adventure world or room, or a Platformer level or hidden level. | Level script at the bottom of the level's Map settings |
Both open in the same Character script window, with their own words. They can't use a character's words, like patrol. To show words, they use show for a banner, or say on a story scroll.
They point at the things around the hero by their IDs, like {North door} or {Slime King}. IDs says how to give a thing one.
Rules run side by side
In a game or level script, a rule starting doesn't stop the others. A story with waits carries on while an every 1 second rule ticks. Only the same rule starting again stops its earlier run.
Two rules can also listen for the same thing. With two when any {Heroes} picks up the {Gold key} rules for two quests, both happen.
Characters in a story moment
A game or level script can tell a character what to do. Each line waits for the character to finish, so they take turns:
Telling another character what to do has the rest.
A whole family at once
A family's name reaches every character in it. when any {Ghosts} is beaten runs for each one, and when all {Ghosts} are beaten runs when the last one in the hero's level goes. all {Ghosts} attack tells them all and waits until they're done, and if the remaining {Ghosts} is under 3 counts the ones still standing. Families in game and level scripts has every way to write them.
What they can hear
Game and level scripts have their own when lines, about the hero and the things around them.
| About | When lines |
|---|---|
| Starting and places | when the game starts (the game script only)when any {Heroes} enterswhen any {Heroes} leaves |
| Things in the level | when the {Slime King} is beatenwhen all {Enemies} are beatenwhen any {Heroes} picks up the {Gold key}when any {Heroes} opens the {North door} |
| Any hero | when any {Heroes} gets hurtwhen any {Heroes} is beatenwhen all {Heroes} are beatenwhen any {Heroes} comes backwhen any {Heroes} collects a coinwhen any {Heroes} attackswhen the countdown ends |
| Adventure only | when any {Heroes} talks to the {Baker}when any {Heroes} finds a shardwhen any {Heroes} gets a goal keywhen any {Heroes} gains a skill |
| Platformer only | when any {Heroes} reaches a checkpoint (or {Flag 2})when any {Heroes} reaches the goalwhen any {Heroes} hatches a power-upwhen any {Heroes} gets an extra lifewhen any {Heroes} jumpswhen any {Heroes} croucheswhen any {Heroes} bounces on a springwhen any {Heroes} loses a shieldwhen any {Heroes} opens a mystery box |
| Online | when any {Heroes} joinswhen any {Heroes} quits(the game script only) |
In the game script, when any {Heroes} enters and when any {Heroes} leaves name a place, as in when any {Heroes} enters {Frozen Cave}.
What happens to the hero themselves, like getting hurt or jumping, belongs in the hero script. Game and level scripts hear it from any hero with when any {Heroes} …. Inside that rule, {Hero} is the hero it happened to, so the {Hero} power up reaches them.
A when line can also use any check an if can make. The rule then happens each time the check comes true, as in when the {Hero} has at least 10 coins, when @apples is at least 3 or when the {Hero} is near the {Old well}.
Where things are
Game and level scripts aren't anywhere on the map, so they have no my row. They can read where the hero and other things are, and how far apart. See Where a character is for how rows and columns count.
| To get | Write |
|---|---|
| Where the hero is | the {Hero}'s rowthe {Hero}'s column |
| Where a thing is | the {Guard}'s rowthe {Old well}'s column |
| How far apart they are | the {Hero}'s distance to the {Old well}the {Goblin}'s distance to the {Old well} |
| Whether they're near | the {Hero} is near the {Old well}the {Goblin} is within 4 blocks of the {Old well} |
| Whether they're far apart | the {Hero} is far from the {Old well} |
A distance or a check always names both things, as these do. They can't move a character: only its own script can, with my row is ….
What they can do
Game and level scripts have their own steps too. if, repeat, wait and @variables work just as they do in a character's script.
| To do this | Write |
|---|---|
| Show words | show "The gate is open!" puts the words in a banner across the screen for 4 seconds. Add for 8 seconds to change how long.Banners show one after another, never on top of each other. |
| Work doors and locks | open the {North door}, lock {…} and unlock {…} work locked doors, gates, chests and lock blocks.In an Adventure, close {…} shuts a castle door again. |
| Hide a thing | hide the {Bridge} takes it out of play until bring back the {Bridge}. |
| Give and take | {Game} give 5 coins to the {Hero}{Game} take 5 coins from the {Hero}In an Adventure, items too, like {Game} give a "Health egg" to the {Hero} and {Game} take a "Health egg" from the {Hero}. |
| Fill a villager's bag | put "Health egg" in the {Baker}'s bag and take "Health egg" from the {Baker}'s bag.A shop keeper's bag is his shelves: put "Health egg" in the {Baker}'s bag for 10 coins sets the price.close the {Baker}'s shop and open the {Baker}'s shop choose whether talking to him opens his shop. |
| Count what's in a bag | @eggs is the number of "Health egg" in the {Baker}'s bag, or … in the {Hero}'s bag.A change to a bag counts from the next moment, so count after a wait. |
| Make a deal | @deal is offer "Health egg" to the {Hero} for 10 coins asks the hero, who picks Deal or No thanks. See Trading with the hero. |
| Move or hold the hero | move the {Hero} to the {Old well} puts the hero there.all {Heroes} freeze keeps every hero still for a story moment, until all {Heroes} unfreeze. |
| Run a countdown | start a countdown of 60 seconds shows a clock, and stop the countdown takes it away. |
| Play a sound | play the sound "Coin" plays one of your own sounds by its name in Media, or a built-in one. |
| Change the music | level music is "Midnight Dash"{Game} boss music is …{Game} win music is …Use your own songs, or ones from the Music list. |
| Ask the hero | @answer is the answer to "Ready?" with yes or no asks the hero wherever they are (see Asking the hero).@name is the typed answer to "What's your name?" lets them type the answer (see Typed answers).Two questions at once are asked in turn. |
They can change some settings as well. Number settings can change slowly, like level gravity is 60% over 2 seconds.
| Setting | Works in |
|---|---|
level darkness is 80% | Adventure and Platformer |
level darkness is off | Adventure and Platformer |
level weather is raining | Adventure and Platformer |
level gravity is 60% | Platformer |
level traction is 20% | Platformer |
level autoscroll is on | Platformer |
The hero's own health and lives are the hero script's to change. From here, tell the hero: the {Hero} health is 50% or the {Hero} lives is 5.
In a level script, my works the same as level: my weather is snowing, my darkness is 50%. Darkness 0 or off turns the dark off.
The weather takes its name from the settings, like snow, fog or wind and rain, or an everyday word:
| Word | Weather |
|---|---|
sunny | Clear |
raining, rainy, rain | Drizzle |
stormy, storm | Thunderstorm |
snowing, snowy | Snow |
foggy, misty, mist | Fog |
windy | Wind |
windy and snowy | Wind & Snow |
windy and rainy | Wind & Rain |
A level's changes last until the level starts again. The game script carries on from level to level, so its every and after rules keep their time.
Putting a setting back
restore puts a setting back to how the builder set it: the level's in its Map settings, and the game's music in Game settings.
| Write | What goes back |
|---|---|
restore level music | The level's own music. |
restore level darkness | Its darkness. Add over 2 seconds to fade back. |
restore level weather | Its weather. |
restore level gravity | Platformer only. Gravity, and traction too. They can glide back. |
restore level autoscroll | Platformer only. Autoscroll, and autoscroll speed too. |
restore {Game} boss music | The boss music in Game settings, and win music too. |
In a level script, my works the same as level: restore my darkness.
A story scroll
A scroll is an old sheet of paper that opens over the game for a story moment. While it's open, say writes its words on the scroll, and questions are asked on it too. The answers are written under each question, so the player can scroll back and read the story again. A scroll keeps its newest 60 lines, pictures and answers; older ones drop off the top.
How a scroll works
The script waits at each say line until the player reads it. They press A, Enter or Space, or click the scroll, and the next line comes. A ▶ at the end of a line shows it's waiting.
Old lines move up as new ones come. The ▲ and ▼ buttons at the side, the mouse wheel, and the d-pad on a said line scroll back through them.
While a scroll is open, the heroes stay still, as if they were frozen. Playing alone, the game waits too. hide the scroll puts it away, and the heroes can move again.
Ways to show a scroll
| Write | What happens |
|---|---|
show a scroll | Each line shows at once, and waits to be read. |
show a scroll with typing effect | Each line types out. Pressing A shows the rest of it at once. |
show a scroll with auto scroll | Each line moves on by itself after a pause, long enough to read it. |
show a scroll with typing effect and auto scroll | Both. |
hide the scroll | Puts the scroll away. |
Pictures on a scroll
A scroll can show pictures too. Each one goes in the middle of the scroll, under the line before it, and plays its pose. It doesn't wait, so the next line comes straight after it.
| Write | What it shows |
|---|---|
show addon "Game Logo" | One of your sprite addons by its name: a character, object, block, artillery piece or weapon. |
show picture "Boar" | A built-in sprite by the name the builder gives it, like "Cooper", "Boar" or "Villager 1". |
show the {Hero} | The hero the player plays, looking out at them. |
To choose a pose, add it after with, on its own or by its name: show picture "Boar" with @pose is "Walk left". "Walking left" works too. A built-in character has Stand and Walk down, Walk left, Walk right and Walk up, where its art has them. Without a pose, a character faces the player.
A weapon shows still, as you drew it. An object or block with one row of frames plays them all, and has no poses to choose. A name or pose the game doesn't have gets a red note that lists the ones it does have.
The player's answers are written on the right of the scroll, with the hero's face beside them.
A villager's scroll
In an Adventure, a villager can show a scroll too, to the hero who is talking to them. It works the same way, and reads like a chat: the villager's face is beside their lines on the left, and the hero's beside the player's answers on the right. A face shows on the first line of each turn, and again when the other one speaks.
show my picture shows the villager's own sprite, and takes a pose the same way: show my picture with @pose is "Walk left".
While the scroll is open, it takes the place of the villager's talk window. When it's put away, the talk window comes back. Like a villager's questions, their scroll goes in when the {Hero} talks to me; anywhere else it gets a red note. Only the hero talking to them sees it.
Good to know
The game and level scripts can only say things on a scroll. Without a show a scroll in the script, say gets a red note. To show words without a scroll, use show for a banner.
A script that opens a scroll and never hides it gets a tip, because the heroes can't move while it's open.
Online, the game script's scroll is the whole team's, and the first player to answer answers for everyone. To give each player their own scroll and their own answers, put the scroll in the hero script.
Playing with friends online
When friends play together online, the game script runs once for the whole team. Each level script runs once for everyone in that level.
A banner, a countdown or all {Heroes} freeze from the game script is for everyone. One from a level script is only for the players in that level.
{Heroes} is every hero in the game, wherever they are. {Hero} is the hero who set off the rule it's in, like the one who got hurt in when any {Heroes} gets hurt.
A rule no hero sets off, like when the game starts or every 5 seconds, has no {Hero} online. Alone, {Hero} there is the only hero. A tip says so. To reach every hero there, write all {Heroes}.
| Write | What it means |
|---|---|
if the game is onlineif the game is offline | Friends are playing together, or someone is playing alone. |
if the number of {Heroes} is at least 3 | How many heroes are in the game, beaten or not. Alone, it's 1. |
if the remaining {Heroes} is 1 | How many heroes are still in play. |
@team is the number of {Heroes} | Remember how many heroes there are. @left is the remaining {Heroes} counts those still in play. |
when all {Heroes} are near the {Gate} | Every hero in play is near the thing. Also within 5 blocks of the {Gate}. |
when any {Heroes} joins | A player joins, and everyone at the start. {Hero} is the one who joined. |
when any {Heroes} quits | A player leaves the game. {Hero} is the one who left. |
Any player can answer a question, and the first answer counts. {Game} is won wins for the whole team, and {Game} is lost ends the game for everyone.
Winning and losing
Any script can end the game, whatever the game's goal is.
| Line | What happens |
|---|---|
{Game} is won | The hero wins there and then, and the ending plays. To show words with it, write {Game} is won with "You saved the village!". |
{Game} is lost | Game over. Try again keeps the @variables. |
level is won | Platformer only. Finishes the level, as the goal flag does. |
level is lost | Platformer only. Costs a life and goes back to the last checkpoint, as falling into a pit does. |
A game script with {Game} is won counts as the game's goal, so the builder doesn't say the game has none.
In a Platformer, the game script can also set the lives the hero starts with. Write {Game} starting lives is 6 at the very top, before any when line.
Examples with IDs
These examples point at things by their IDs. IDs says how to give a thing one.
A gate that opens when the boss is beaten
Give the boss the ID Slime King, and lock the castle gate with any key and name it Castle gate. Then put this in the level's script.
A key that appears
Give an enemy the ID Big Slime, and name a key Gold key with its Key name. The key is hidden until the hero beats the slime.
A locked well
Give the well the ID Old well, and name its door Well door. When the hero comes close, the level script says whether they still need the key.
A baker who goes home
In an Adventure, give a villager the ID Baker. After the hero talks to them, the level script gives the hero a treat and sends the baker back to the shop.
A welcome for each place
The game script can name levels and worlds by their names. Here, two worlds called Frozen Cave and Lava Lake each get their own welcome.
Checkpoints and springs
In a Platformer, give the middle checkpoint flag the ID Flag 2, and a spring the ID Big spring. The level script cheers at the flag and counts the bounces.
Example: a quest
The wizard wants three star keys, hidden around the game. The game script counts the keys and opens the tower door. The tower's level script ends the game.
Before you write the scripts, name the keys Star 1, Star 2 and Star 3 with their Key name. Then lock the tower's door with any key, and name it Tower door.
# The game script
when the game starts
@stars is 0
show "Find the wizard's three star keys!"
when any {Heroes} picks up the {Star 1}
@stars goes up by 1
when any {Heroes} picks up the {Star 2}
@stars goes up by 1
when any {Heroes} picks up the {Star 3}
@stars goes up by 1
when @stars is 3
show "All three! The tower door is open."
play the sound "Fanfare"
unlock the {Tower door}# The tower's level script
when any {Heroes} enters
@ready is the answer to "Give the wizard the stars?" with yes or "not yet"
if @ready is yes
{Game} is won with "The wizard's tower shines again!"
end
