Creating your own JZT Game World is easy with its built-in items, enemies, and terrains, but sometimes your game needs something special that can’t be done with the build-in things. Perhaps you’d like a shopkeeper that trades gems for items, for example, or a special button that unlocks a gate and lets loose a hoarde of snakes. There are a lot of creative concepts that you can include in your JZT Game Worlds, and JZTScript is what lets that happen.
JZTScript is simple programming language used to program Scriptable things in JZT. A lot of game interactions are scripted using JZTScript. For example, in The Village of JZT, everything from the Dancing Trees in the Marsh, to the pedestals on which you place the Gems of Illumination in the cave are created using JZTScript.
This manual will describe everything you need to know to get started with JZTScript and create your own special interactions in your game. So let’s get started!
Everything in JZT is a, well, Thing! A segment of a wall is a Thing, a gem is a Thing, a lion is a Thing… I suspect you’re getting the idea here. One type of Thing is a little more special than the others, though, and it’s known as a Scriptable Thing.
This section is incomplete. More details to come
To create a new script, click the Scripts tab in the JZT Game World Editor and click the New Script button. You’ll be prompted for a name to call the script. Choose a good name so that you’ll know exactly which behaviours you want to attach to your Scriptable Things.
You can create as many scripts on a board as you’d like, but your script will only be available on that board. If you want Scriptable Things to use a script that was created on another board, you’ll need to create a copy of that script on the new board.
Each script is made up of lines that are executed one-after-another until your script completes. Each line can either be a comment, label, or command, which I’ll explain briefly below:
Comments are just reminders for you, the programmer! They don’t make your Scriptable Things do anything, but they are good for leaving yourself notes about what a script does or to help others understand your scripts if you ever want to collaborate on a world with friends.
Comments start with two forward slashes and can contain any text you like. They can also occur at the end of a line, even if that line is a label or command. Neat! Here’s some examples of comments:
// This is a comment :touch // This is a comment after a label go north // And this is a label after a command
Normally, commands in your script are executed one-after-another. Sometimes you might want to jump back to the start of a script, though, or have parts of your script execute only when triggered by something else. (For example, when you touch or shoot a Scriptable Thing). To do this, you can use labels!
Labels are lines that start with a colon (:) followed by a name of that label. Once you create a label, your script can “jump” to it by its name. Your script can also jump to these labels in response to receiving a “message” from the game or from another Scriptable. You can name labels anything you’d like, but it can’t have any spaces. Here’s an example of a label:
In addition to whatever label names you come up with, JZT has some names that mean something special. These represent common messages that your script can receive. These messages are as follows:
Many commands make use of directions. Whenever a direction is required, you can specify it using any of the following:
Directions can also be modified by placing one or more Direction Modifiers in front of it:
cw northwould represent the same as
cw randnewould represent either east or
ccw northwould represent the same as
ccw randnewould represent either
opp seekwould represent a direction away from the player.
opp flowwould represent the opposite direction that a Scriptable Thing is moving in.
ccw opp seekwould represent a direction counterclockwise to the direction away from the player.
opp randnewould represent either
rndp northwould represent either
rndp flowwould represent either a 90 or 270 degree turn from the direction that a Scriptable Thing is moving in.
Colors can be specified using the following words. Note that colors can be in either upper or lowercase, but shouldn’t contain any spaces. (So “BrightBlue” must always be specified without a space.)
The following “things” can be identified in JZTScript:
Some JZTScript commands use expressions to determine whether or not to take a certain action. Expressions will evaluate to either
false. The following expression types can be used:
trueif the provided expression evalues to
not adjacent: Evaluates to true if the player is not immediately adjacent to the current Scriptable Thing, otherwise evalues to
trueif the player is immediately adjacent to the current Scriptable Thing, otherwise evalues to
trueif the current Scriptable Thing is blocked in a provided direction, otherwise it evalues to
blocked nEvalues to true if the Scriptable Thing has an obstacle blocking its way to the north.
blocked opp seekEvaluates to true if the Scriptable Thing is blocked in the direction away from the player.
trueif the player is aligned with the current Scriptable Thing in a provided direction, otherwise it evalues to
aligned north: Evalues to true if the player is vertically aligned with the current Scriptable Thing in the northerly direction.
trueif there is a line of sight between the player and the current Scriptable Thing. (That is to say, no walls or objects appear within a straight line between the two.) An optional distance can be provided, which signifies that the player must be at most that many spaces away from the Scriptable Thing for this to evaluate to
peep 5evalues to true if the player can be seen within five spaces of the current Scriptable Thing.
exists [count] <thing>
trueif the current board contains any of the specified thing, otherwise evalues to
false. An optional number can be specified, in which case this expression only evalues to
trueif there are at least that many of the specified thing on the board.
exists 5 lion: Evalues to
trueif there are at least five lions on the current board.
exists red gem: Evalues to
trueif there are any red gems on the current board.
<counter> [<, >, <=, >=, =] <number>
trueif a game counter is tested according to the provided mathematical test operators.
health >= 10evalues to
trueif the player’s health is 10 or higher.
gems = 5evalues to
trueonly if the player’s gem count is exactly 5.
ammo < 20evalues to
trueonly if the player has less than 20 ammo shots left.
trueif the current Scriptable Thing is either on a light board, or within the radius of a torch.
JZT can play sound effects and music using a simple format. Musical instructions are provided within double quotes. Each character in the notation has the following purpose. Spaces are ignored.
"c e g + c e g# x 0" Plays the notes c, e, then g in succession, increases the octave by one, then plays the notes c, e, and g-sharp, followed by a rest and a percussive tick.
The following commands can be used in your JZTScript to enact various behaviours. Most commands start with a word and are followed by a sequence of parameters. In this guide, optional parameters are specified by
[square brackets] and required parameters are specified by
This guide also contains examples of each command.
Become [color] <thing>
become yellow gemwould cause a Scriptable Thing running this command to turn into a yellow gem.
becomessomething else, the Scriptable will be removed from the board and its script will no longer continue.
Change [color] <thing> [color] <thing>
change ammo red gemwould turn all ammo on the board into red gems.
change yellow gem blue gemwould turn all yellow gems into blue gems.
change blue wall emptywould turn all blue walls into empty spaces.
Char <character index>
char 2would change this Scriptable Thing to look like a solid happy face
char 14would change this Scriptable Thing to look like a musical note
color brightredwould change this Scriptable Thing to a bright red color
color bluewould change this Scriptable Thing to a dark blue color
Go (<direction> [count])
gocommand multiple directions by specifying each direction with commas.
go north 5would go north five spaces, one space at a time at the Scriptable Thing’s current speed.
go n, s, e 2, wwould go north one space, south one space, east two spaces, and west one space (each move will happen one space at a time).
go opp seek 3would go three spaces away from the player
Give <number> <counter>
give 5 ammowill increment the player’s ammo by 5 shots.
give 10 healthwill increase the player’s health by 10 units.
give 1 superstarwould increase a game counter called “superstar” by 1.
If <expression> <label>
if exists 5 red gem dosomethingwould jump to a label called “dosomething” if there are at least 5 red gems on the current board.
if superstar >= 1 congratulatewould jump to a label called “congratulate” if there is a game counter called “superstar” whose value is one or higher.
play "cdefgab+c"would play an octave of notes.
Put <direction> [color] <thing>
emptyThing will erase any Thing that’s already there.
put s blue gemwould put a blue gem south of the current Scriptable Thing’s position.
put n emptywould erase whatever Thing is north of the current Scriptable Thing’s position.
Scroll [bold] "message" [label]
scrollcommands will be added to the same scroll on the screen. (That is, if you have two scroll commands, both messages will appear in a single scroll presented to the user.)
scroll bold "The troll speaks..."will pop up a scroll on the screen with some white, centered text.
scroll "Buy some gems" buygemsWill pop up a scroll on the screen with an option to buy some gems. If the player selects this message, the active ScriptableThing will jump to a label called “buygems.”
Send [scriptable name] <message>
send loopJumps to a label called “loop” for the current Scriptable Thing’s script.
send troll dieSends a “die” message to all Scriptable Things called “troll,” causing these Scriptable Things to jump to their “die” label at the next execution cycle.
Set [number] <counter>
set 10 healthThe player’s health will be set to exactly 10.
set 0 starsReduces the custom “stars” counter to zero.
speed 5The Scriptable Thing’s execution speed with be set to 5.
Take <number> <counter> [label]
take 5 healthReduces the player’s health by 5 (ending the game if the user has less than 5 health to begin with).
take 10 gems toopoorAttempts to reduce the player’s “gems” counter by 10; if the player doesn’t have enough gems, the counter will stay at its initial value, but the script will jump to a label called “toopoor.”
throwstar opp seekLaunches a throwing star in the opposite direction of the player.
torch 5Creates an illuminated circle with a radius of 5 vertical (and 10 horizontal, since tiles are double-height in JZT) spaces around the current Scriptable Thing.
Try (<direction> [count])
Gocommand, except if the Scriptable Thing is blocked from movement, it will ignore that movement and continue. (To illustrate the difference, let’s say you have a Scriptable Thing with a wall placed directly north of it. If the Scriptable Thing is instructed to
try n, e, it will try to move north, fail to do so because of the wall, and then will move east one space at the next execution cycle. If that same Scriptable Thing were given a
go n, ecommand, it would try to move north, fail to do so because of the wall, and then continue to try to move north until the wall is removed and it’s able to move north.)
try n 5Tries to move north five times.
try s 3, e, n 5Tries to move south three times, then east once, then north five times.
restore touchTurns the most recently “zapped” touch label active again.
say "Hello, there!"displays the words “Hello, there!” at the bottom of the screen for a few seconds.
shoot northShoots northward
shoot seekShoots toward the player.
wait 5Stops executing commands for 5 cycles
walk seekWalk in the direction toward the player. (Note, if the player moves, this Scriptable Thing will continue to walk in the direction it was walking; it won’t change course to follow the player unless explicitly told to walk in a new direction.)
restorecommand. If there are multiple labels with the same name, only the first unzapped label will be zapped.
zap touchFinds the first occurrence of a label named “touch” in the script, and renders it ineffective. This means that the second “touch” label will then be jumped to the next time that Scriptable Thing receives a touch message.