Sections of a PuzzleScript file

A puzzlescript file is divided into the following sections. Each section is optional, and sections can appear in any order and any number of times.

Prelude

Before any of the "official" sections are declared, you can give details about your project in this section, and also set some useful options, which can make for some very different games.

title My Very First Game
author My Games Handle
homepage www.myhomepage.com

require_player_movement
key_repeat_interval 0.12

Here are the possible settings.

// comment

Comments in this form start with a double slash and extend to the end of the line. Once you've used one of these comments in the preamble, you can use them throughout your game. You can then also use semicolon as end of line, such as this object declaration.

// some temporary objects
temp1;transparent;
temp2;blue;

again_interval 0.1

The amount of time (in seconds) it takes an 'again' input event to trigger.

allow_undo_level

Allow undo to return to a previous level. Most useful when used together with level branching (see this page for more information).

author Games Wizard

Your name goes here. This will appear in the title screen of the game.

author_color darkred

Controls the font color of the author name in the title screen.

background_color blue

the objects pageControls the background color of title/message screens, as well as the background color of the website.

case_sensitive

the objects pageWill force the compiler to be case sensitive, to see "a" and "A" or "moved" and "moveD" as different objects. The main aim of this was to allow a larger range of characters to be used in levels. Since the entire range of Unicode characters is available for this purpose, this option is deprecated.

color_palette mastersystem

By default, when you use colour names, they are pulled from a variation of Arne's 16-Colour palette. However, there are other palettes to choose from:

1 - mastersystem
2 - gameboycolour
3 - amiga
4 - arnecolors
5 - famicom
6 - atari
7 - pastel
8 - ega
9 - amstrad
10 - proteus_mellow
11 - proteus_rich
12 - proteus_night
13 - c64
14 - whitingjp

(you can also refer to them by their numerical index)

continue_is_level_select

Don't show an extra option for the Level Select on the main menu. Instead, the "continue" button will open it, instead of continuing the game.

custom_font data:font/otf;base64,font data

Allows you to load in a custom font file via a data stream. It looks something like this.

(Monogram by Datagoblin: https://datagoblin.itch.io/monogram)
custom_font data:font/otf;base64,AAEAAAAOAIAAAwBgRkZUTWd... (long string of characters being the font data)

This works best with monospace fonts & font files with very small sizes (under 20KB). If you have a font file and you want to convert it into base64, use a tool like File to Base64 with the "Data URI" output format, then paste it into the editor.

The custom font setting can be a link to a font file on the Web, preferably of type `woff2`. You can find font files that are freely accessible in various places, including Google Fonts.

Search for VT323 and you will find it here.
Then search a bit more and find this link.
On this page there is (finally) this link to the downloadable font file.
Use it like this.

custom_font https://fonts.gstatic.com/s/vt323/v17/pxiKyp0ihIEF2isfFJU.woff2     
custom_font https://fonts.gstatic.com/s/inconsolata/v31/QldgNThLqRwH-OJ1UHjlKENVzkWGVkL3GZQmAwLYxYWI2qfdm7Lpp4U8WR32lw.woff2

Note that text pages like the title screen and message text are displayed as full lines of text. This means that there will be a variation in character widths, and even in a Monospace font wide characters like `大 ⚐` will display at full width.

debug

This outputs the compiled instructions whenever you build your file. For instance, the line


         Edit[ > Player | Crate ] -> [ > Player | > Crate ]

is compiled into four instructions, as the output from debug shows when you hit 'RUN':

===========
Rule Assembly : (4 rules)
===========
  (83) DOWN [ crate | up player ] -> [ up crate | up player ]
+ (83) DOWN [ down player | crate ] -> [ down player | down crate ]
+ (83) RIGHT [ crate | left player ] -> [ left crate | left player ]
+ (83) RIGHT [ right player | crate ] -> [ right player | right crate ]
===========

Going from left to right:

The number near the left is the line-number the rule came from in the original source code. You can click on the number to jump to that line in the file.
A plus-sign on the left of the line indicates that the rule is grouped with the previous one as part of a rule-group and the engine will loop through the group as a whole trying to apply the rules until no more rules in the group can be applied (See the rules page for more info).

The compiler does a lot of stuff to the rules you give to it to 'simplify' them in various ways. One thing it does for instance is replace all relative directions ( ^, v, <, and >), with UP, DOWN, LEFT, and RIGHT, which often involves splitting a single rule into many more rules (as above). And other thing you'll notice is that the core engine has rules only going DOWN and RIGHT - rules in other directions are flipped. For more information about directions in puzzlescript, see this page.

You can also get this output in the editor by clicking on the button.

flickscreen WxH

Setting flickscreen divides each level into WxH grids, and zooms the camera in so that the player can only see one at a time - the camera does not follow the player around on a move-to-move basis, but if the player moves from one part of this grid to another, the camera flicks to the new position. See Legend of Zokoban for a cute example.

font_size 1.5

Font size is in em, meaning 1 is the default and is treated as a percentage (e.g. 0.5 is half font size & 2 is double the normal font size). Can only be used with custom_font.

homepage www.myhomepage.com

The homepage of the author. This doesn't appear directly in the game itself, but is included in the shared game and exported HTML build.

keyhint_color blue

Controls the font color of lines giving hints about the keys to use, at the bottom of the title screen, pause menu, and message screens.

key_repeat_interval 0.1

the objects page When you hold down a key, how long is the delay between repeated presses getting sent to the game (in seconds)? The default value is 0.15.

level_select

Adding this will add a level select to your game. By default, this will allow the player to play all levels in any order. In order to add entries to the level select, add a section in-between your levels.

level_select_lock

Will lock any levels that haven't been solved yet or are next to be solved.

level_select_solve_symbol

Which symbol to display for levels that have been solved in the level select. It's "X" by default, but you can change it to any Unicode character such as a checkmark. If you're using a custom_font, make sure it does have a checkmark glyph.

level_select_unlocked_ahead

How many levels to unlock ahead after the last solved level when level_select_lock is on, 1 by default.
If you set it to 3, then section 1, 2, and 3 will be available. If you solve section 2, then you'll unlock 4 and 5. (So there will always be three levels unlocked AFTER the last solved level at max.)

level_select_unlocked_rollover

Alternative to LEVEL_SELECT_UNLOCKED_AHEAD that more strictly limits the number of unsolved levels at any time.
If you set this to 3, then section 1, 2, and 3 will be available at the start. If you solve section 2, then only section 4 will unlock. (So there will only ever be three "unsolved" levels at most.)

local_radius radius

If you set the local_radius flag to a whole number, then the game will only check rules that are in that amount of tiles (a square radius) around the player (or one of the players if you have multiple players in the level). If you still want to have rules to be checked anywhere on the level, preface them with the global keyword like this:

(Rows of global crates can push each other, even outside of the player radius)
  global [> GCrate | GCrate] -> [> GCrate | > GCrate ]

You generally don't need to use this unless you have a really big level, a ton of rules, and your game would otherwise run slowly.

message_text_align right

How to align text for messages: left, center (default), or right. If you need more control over the text layout, you can also use \n to add a newline.

Note:

The following few options deal with using the mouse. You can find more information about mouse input here.

mouse_left lmb

If the player clicks on a specific tile of the screen, then this object will be created there before any other rules are done. If you don't specify an object name, it will look for an object called lmb. Once you add this flag, various things (like the title screen) will change to reflect that the game is mainly mouse-controlled.

mouse_drag drag

If the player has clicked and is moving their mouse, it will place this object & start a turn when the cursor moves into a different cell. If you don't specify an object name, it will look for an object called drag

mouse_up lmb

If the player has clicked and is releasing their mouse button, it will place this object then do a turn.

mouse_right, mouse_rdrag, mouse_rup

Similar to the above three, but for the right mouse button and the defaults are rmb and rdrag. Note that you can also ⌘/Ctrl+Left Click to get the right mouse button behaviour in-game.

noaction

Removes the action key (X) instruction from the title screen, and does not respond when the player presses it (outside of menus and the like).

norepeat_action

For many games, you don't want holding the action key down to retrigger it - games where you're toggling a switch, say. For these games, set this option and the action button will only respond to individual presses.

nokeyboard

Allows the game to run without a Player object and movement. This is intended for mouse-only games, so things don't move when you didn't intend them to.

norestart

Disables the restart key (R). Not sure why you would want to do this, but it's there.

noundo

Disables the undo key (Z). I would generally advise against disabling undo, but it may be needed in games that depend on randomness.

realtime_interval 0.5

The number indicates how long each realtime frame should be. In the above case, twice a second the game engine will tick, but with no input. Player input is processed as regular. See this documentation for more info on making realtime games.

require_player_movement

This is a common requirement in games - if the player doesn't move, cancel the whole move. This is equivalent, where there's only one player character, to the following:

[ Player ]->[ Player Temp ]
late [ Player Temp ] -> CANCEL
late [ Temp ] -> [ ]

run_rules_on_level_start

For some games you will want, before the player sees the level, for the rules to be applied once. Games that have rules that generate level graphics on the fly, for instance, may want this. Try out this game with and without the prelude option and compare results.

runtime_metadata_twiddling

Allows you to change some prelude properties while the game is running using commands. More info here.

runtime_metadata_twiddling_debug

Will log to the console whenever a prelude property is changed.

scanline

Applies a scanline visual effect - only draws every other line. Weird.

sitelock_origin_whitelist

Causes your game to only be able to run on websites with the listed origins, separated by whitespaces. An origin is for example https://polyomino.com.

sitelock_hostname_whitelist

Causes your game to only be able to run on websites with the listed hostnames, separated by whitespaces. A hostname is for example polyomino.com.

smoothscreen flick WxH IxJ S

Zooms the camera in to a WxH section of the map around the playerand smoothly scrolls to follow the player. The optional argument IxJ (default: 1x1) specifies a boundary in which the player can move without moving the camera. The optional S argument (default: 0.125) specifies how far the camera will move towards the player each frame as a fraction of the distance to the player. Additionally, the optional flick keyword makes the camera move like flickscreen, where the camera always moves the full boundary width/height. To get a smooth version of flick screen, provide the flick keyword and make WxH and IxJ the same dimensions.

smoothscreen_debug

Render debug information about the smoothscreen camera. The red circle and box represent the camera's position and the boundary around it. The blue circle and box are at the position the camera is moving towards. The green circle marks the location of the player that is being followed by the camera.

sprite_size 12

Sets the size of the sprite grid to 12x12. The default is 5x5 for compatibility, but this allows you to pick some other square resolution. Note that sprites larger or smaller than this size are allowed. See the objects page for more detail.

If you need help with upscaling your sprites, there's a helpful tool available here.

skip_title_screen

Will skip the title screen when the game initializes. Instead, it will act like the "continue" button has been pressed, opening either the level, message, or level select based on game progress and other prelude flags.

status_line

Reserves some space at the bottom of the screen for displaying a status line. Use it with the status command, see rules commands.

text_controls

Will overwrite the default keyboard/mouse control text in the title screen with the text you specify here! It can display up to three lines of text at once, and supports using \n to add a newline.

text_color #039

Controls the font color of title/message screens, as well as the font color in the website. Like all colors, it can accept a color name or a hex code. See the objects page for more detail.

text_message_continue

Override the text below MESSAGEs that normally says 'X to continue' or 'Click to continue'.

title My Amazing Puzzle Game

The name of your game. Appears on the title screen.

title_color #FF5555

Controls the font color of titles in the title screen and pause menu.

throttle_movement

the objects pageFor use in conjunction with realtime_interval - this stops you from moving crazy fast - repeated keypresses of the same movement direction will not increase your speed. This doesn't apply to the action button. If you can think of an example that requires action to be throttled, just let me know.

tween_length 0.05

Enables tween animation as an alternative to using again. Tweens are enabled for for LEFT, RIGHT, UP, and DOWN object movement, and for ACTION (will fade in that object), and will take the duration you specify in seconds. An object must execute its movement for this animation to play, currently there is no way to play an animation without moving.

Note that if the next turn starts before this tween is completed, the previous tween instantly completes. For this reason, you should set the tween_length very low, somewhere between 0.05 and 0.075 seconds, but at least lower than the AGAIN_INTERVAL and KEY_REPEAT_INTERVAL, and to avoid using it in games that use REALTIME_INTERVAL.

Note that it has a number of limitations, and while it works well for simple games, it might not be powerful enough for complex ones. Additionally, LATE rules can interfere with this system, so it's not recommended to use these rules in games that use them. And for now tween animation is a PS+ feature, incompatible with all but the most basic sprites. You can't use it with oversize sprites, transforms, animations, render groups or canvas.

tween_easing easeInQuad

When using tween_length, use these to indicate how the movement should lerp. The following options are valid. (To view these in action, see easings.net). You can use either the name or the number.

1: linear (default)
2: easeInQuad
3: easeOutQuad
4: easeInOutQuad
5: easeInCubic
6: easeOutCubic
7: easeInOutCubic
8: easeInQuart
9: easeOutQuart
10: easeInOutQuart
11: easeInQuint
12: easeOutQuint
13: easeInOutQuint

tween_snap 5

By default, the tween will snap to the SPRITE_SIZE to conform to the pixel grid. However, with this prelude you can overwrite this if you want the transition to happen more granually when the canvas is drawn on a large scale. You can even put it to a very high number (like 1000) to make the snapping essentially smoothless.

verbose_logging

As you play the game, spits out information about all rules applied as you play, and also allows visual inspection of what exactly the rules do with the visual debugger.

You can switch this on in the editor by clicking on the button.

zoomscreen 10x10

Zooms the camera in to a 10x10 (WxH) section of the map around the player, centered on the player. Silly example.