Scripting help

Functions

Give some steps a name of your own, give them values, and use them in any script.

A script can make its own functions. A function is a name for some steps. Once it's made, you use its name as a step, and all its steps run.

To make one, write learn to, then the function's name, then its steps, then end. If it needs values, name them after with, with commas between them.

learn to greet with @times, @words
repeat @times times
say @words
wait 1 second
end
end
​
greet with 2, "Hello there!"

A shorter way to write it

The to after learn can be left out, so learn greet with @times, @words means the same. The examples in this help all write learn to.

A function's values are always parted by commas, never and. That way an and in an if always joins two checks.

Giving a function values

After with, list the values the function needs, as @values. A step that uses the function gives its values in the same order, so greet with 2, "Hi!" puts 2 in @times and "Hi!" in @words.

Inside the function, its @values are its own. A game @variable with the same name is left alone. It's clearest to give them names of their own, like @times and @words.

Values by name

A step can also give each value with its name, using is. Then the order doesn't matter, and the step says what each value is for. This reads better than a list of numbers, so it's the best way when a function takes more than one value.

learn to greet with @times, @words
repeat @times times
say @words
wait 1 second
end
end
​
greet with @words is "Hello there!", @times is 2
Written likeWhat it gives
greet with 2, "Hi!"In order: 2, then "Hi!"
greet with @times is 2, @words is "Hi!"By name
greet with @words is "Hi!", @times is 2By name, the same as above
the {Baker} greet with @times is 1, @words is "Hi!"By name, to another character

Give every value its name, or none of them. A name the function doesn't have, a name given twice, or one left out gets a red note that says which.

Just one value

When a function takes only one value, the step that uses it can leave with out. Both ways mean the same thing. The learn to line still needs its with.

learn to cheer with @words
say @words
wait 1 second
end
​
cheer "Well done!"
With withWithout it
cheer with "Well done!"cheer "Well done!"
@total is double with 4@total is double 4
the {Baker} cheer with "Hi!"the {Baker} cheer "Hi!"

A function with two or more values always needs with.

Functions without values

A function doesn't have to take values. Leave out with and it is just a name for some steps. Here an enemy has one move, the pounce, and uses it in two rules. To change the pounce, you change it once.

learn to pounce
wait half a second
move toward the {Hero} 3 blocks
wait a quarter of a second
go home
end
​
pounce
​
pounce

Functions with numbers

A @value can stand in for a number in a step, like how many blocks to move or how many seconds to wait. This lets one function do a small move and a big one.

learn to dash with @far, @rest
move toward the {Hero} @far blocks
wait @rest seconds
go home
end
​
dash with 2, 1
dash with 4, 0.5

The first dash goes 2 blocks and rests for 1 second. The second goes 4 blocks and rests for half a second.

A function value can also choose how long a setting changes. This starts the change and then waits for the same duration, so a caller knows the motion is complete.

learn to lean with @angle, @seconds
my angle is @angle over @seconds seconds with ease-in-out
wait @seconds seconds
end
Where a @value can goWrite it like
How farmove toward the {Hero} @far blocks
How longwait @rest seconds
How many timesrepeat @times times
Words to saysay @words
Inside other wordssay "You owe me @price coins!"

Functions that choose

A function can have an if in it, so it does different things at different times. This enemy speaks every time it is hit, and what it says depends on its health.

learn to react with @words
if my health is under 50
say "You won't beat me!"
run away 3 blocks
else
say @words
end
end
​
react "Ouch!"
​
react "Who goes there?"

Functions that remember

A function's own @values are gone when it ends. Any other @variable it changes is kept, so a function can count. This villager's greeting changes the more often the hero visits.

learn to greet with @words
@visits goes up by 1
if @visits is at least 3
say "You again! That's @visits visits."
else
say @words
end
end
​
greet "Nice to meet you!"

Functions that give back

A function can work something out and hand it back. Write give back, then the value. The line that used the function gets it.

learn to sum with @a, @b
give back @a + @b
end
​

give back also ends the function. Steps under it don't run, so it can sit inside an if to leave early.

learn to price with @coins
  if @coins is over 10
    give back "cheap"
  end
  give back "too much"
end
What you wantWrite it like
Remember what it gives back@total is sum with 2, 3
Check what it gives backif sum with 2, 3 is 5
Use it in some math@total is 1 + (sum with 2, 3)
Give it to another functiondash with (sum with 1, 2), 1
Give back another function'sgive back (sum with @a, 1) * 2

When it needs brackets

Brackets show where a function starts and ends. They can be left off when the function is the whole value, as in @total is sum with 2, 3. They are needed when the function is part of some math, or is a value for another function.

Every function on a line runs first, from left to right, and one inside another's brackets runs before it. Then the line itself runs. If a function takes time, with a wait, the line waits for it. A say on a scroll waits too, until the player reads it, but a speech bubble doesn't: put a wait after it to give the player time to read.

Good to know

WhenWhat happens
The function ends with no give backIt gives back nothing. That counts as "", or 0 in math.
It is used as a step on its ownIt still runs. What it gives back is dropped.
It never has a give backA yellow note says so where its value is used.
Another script tells a character to use itIt runs, and what it gives back is dropped.
It is used in a when lineIt can't be. Use it in an if under the when.
It is used at the top of a scriptIt can't be, in my @range is … or @x starts at ….

Making your own filters

A filter changes a value, like then upper case (see Filters). You can make your own. Write learn the filter, its name, and with one @value: the value before then. Give back the changed value.

learn the filter shout with @words
give back "(@words then upper case)!"
end
​

No problems detected

Good to knowWhat happens
One valueA filter takes just one @value, the one before then.
Its nameAny words, but not one of Splat Script's own filters, like reverse.
With other filtersUse it with them in any order: "hi" then shout then reverse.
The whole gameMake it in the game script and every script can use it, as with functions.

Functions that use functions

A function can use another function as one of its steps. Build small moves first, then make bigger moves out of them. Here combo is made of two strike moves, and each strike ends with retreat.

learn to retreat
run away 2 blocks
wait half a second
end
​
learn to strike with @far
move toward the {Hero} @far blocks
retreat
end
​
learn to combo
strike 2
strike 4
say "Had enough?"
end
​
combo

Functions can be stacked four deep: a function, one it uses, one that one uses, and one more.

A function for a boss's heads

A long move like a bite is a good fit for a function. This script goes on one of the Sunflower's head tabs (see Bosses made of parts). One bite function makes a quick nip and a slow, long bite.

learn to bite with @far, @warning
  my pose is windup
  wait @warning seconds
  my pose is lunge
  move toward the {Hero} @far blocks very quickly
  my pose is normal
  go home quickly
end

every 3 to 4 seconds
  if I see the {Hero}
    bite with 3, 1
    bite with 6, 2
  end

when I get hit
  my pose is normal
  go home quickly

Sharing a function with the whole game

Put a function in the game script and every character can use it. This one is written once in the game script:

learn to taunt with @words
  say @words
  wait 1 second
  say "Ha ha ha!"
end

The game script can't talk, but a function in it can still have say, because the character that uses the function does the talking.

Whose scriptWhat it writes
An enemywhen I see the {Hero}taunt "You can't pass!"
A villagerwhen the {Hero} talks to metaunt "Got you!"

If a function has a step the character can't do, that one step does nothing for them, and a note in their script says which. A villager can't patrol, for example.

Sharing a function with a family

A function in a family's script is for the characters in that family. Other scripts can tell one of them to use it, like the {Ghost 3} roll, or tell them all with all {Ghosts} roll.

When the same name is used in more than one place, the nearest one wins.

A character's script uses a function that's inThe one that runs
Its own scriptIts own
Its family's script, and not its ownThe family's
Only the game scriptThe game script's

Telling another character what to do

A script can tell another character to do something. Write the character's ID in braces, then what it should do. The character needs an ID, which you type in its Object settings.

What you tell it can be one of its own functions, a function from the game script, or a single step like jump back.

This is the Baker's script. It teaches the Baker one function:

learn to wave hello
  say "Hello!"
  wait 1 second
end

And this is the level's script. It tells the Baker to use it:

when any {Heroes} talks to the {Baker}
  the {Baker} wave hello
  the {Guard} say "Move along!"

The character does it as if the line were in its own script. Inside the function, I and my mean the Baker.

It waits its turn

The script waits on the line until the character is done. So in the example above, the Guard only speaks after the Baker has finished. That makes story moments easy to write, one line after another.

To carry on straight away, end the line with and go. Here three enemies all attack at once:

when I see the {Hero}
  the {Minion 1} attack and go
  the {Minion 2} attack and go
  the {Minion 3} attack and go

What happens to the character

Being told to do something is like one of the character's own rules starting. Whatever it was doing stops. Its own rules still work, so when I get hit can cut the told thing short. The script that told it then carries on.

What you wantWrite it like
Use one of its functionsthe {Baker} wave hello
Give the function valuesthe {Baker} greet with 2, "Hi!"
Do one stepthe {Guard} jump back
Keep doing something a whilethe {Guard} chase the {Hero} for 2 seconds
Don't wait for itthe {Guard} attack and go

Good to know

WhenWhat happens
The line gives valuesThey are read by the script doing the telling, before the character starts.
The character is beaten or hiddenThe line is skipped.
The character is in another levelThe line is skipped.
More than one character has the IDOnly the first one is told. With the Script log on, it warns you once.
A Platformer enemy is far from the heroIt is asleep. It does what it was told once the hero comes near.
The character never gets to itThe script waits up to a minute, then carries on.
The ID is a boss's partIt can't be told. Tell the boss itself.

Secret functions

Write secret in front of learn to and the function is private. Only the script it is written in can use it. A character's own @variables can be secret too: see Secret @variables.

secret learn to count my coins
  say "One, two, three…"
end
Where it is writtenWho can use itWho can't
A character's scriptThat characterAny script telling it, like the {Baker} …
A level's scriptThat level's scriptEvery other script
The game scriptOnly the game scriptEvery character and level

Where a function works

A function made in the game script can be used in every script in the game, unless it is secret. One made in a character's own script is theirs, but another script can tell that character to use it.

The Learn drawer in Words you can use adds learn to … end. It also lists every function this script can use.

What a function can't do

A function can use other functions, up to four deep, but it can't use itself, not even by way of another function. It can't have a when line inside it, and it can't be made twice.

give back only goes inside a function, and it needs a value after it.

A function also can't have the same name as a Splat Script word. chase is taken, for example.

MistakeWhat the script tells you
Too few valuesWhich @values the function needs
A name Splat Script already hasThe word it is too like
A name ending in and goThat and go means "don't wait"
The same name twiceThe line where the first one is
A function that uses itselfThat it ends up calling itself
give back outside a functionThat it goes between learn to and end
A function in math, no bracketsTo put it in brackets
A when line insideThat the function needs an end