Puzzlescript Game Bar

About the Puzzlescript Game Bar

This is the "game bar" found in all Pedro PSI's games. It features for instance undo/reset buttons, a beautiful level selector, a hint manager, a fullscreen mode, auto-rotation, plus optional music, credits and how-to-play buttons. Sounds useful? Well you too can use it, for free!

This is how the Puzzlescript Game Bar looks like:

Puzzlescript Game Bar

The game bar's colours adapt to the foreground and background colours of your game.

Current version

Here is the latest release version of the Puzzlescript Game Bar .

Please note the game-bar bookmarklet and code updates in real time to the most recent version. You can as well use any of the archived older versions instead.

How to test the Puzzlescript Game Bar in your own game

Follow the instructions in the Game Console.

How to add the Puzzlescript Game Bar to your own game

Just include the javascript source code!

Include the javascript source GameBar.js in a regular Puzzlescript export or in a custom page.

To ensure the Puzzlescript Game Bar overwrites all needed functions, please load it after the game has loaded fully, i.e. by placing at the end of the <body> the snippet <script type="text/javascript" src="GameBar.js"></script>.

Hints

A hints button will appear whenever a hint file is detected.

Create a folder named hints, where you'll drop a hints file containing all hints. The hints file should be named exactly like the matching game .html page file, but with the .txt extension.

If you have several game pages, you can drop one hints file per game into the common hints folder.

hints file text standard

The hints file textual format follows 7 rules:

  1. Each hint ocupies exactly one line;
  2. hints belonging to the same level (hint groups) are placed in successive contiguous lines;
  3. hint groups are separated by one or more empty lines;
  4. if the first line in a hint group starts with the word level, the hint group will ignore this line.
    • Thus a group consisting of the single line level ... will be interpreted as containing zero hints;
  5. digits at the start of any hint line will be ignored;
  6. hint lines consisting solely of a reference to an image (see section below) will display that image.
  7. Important:hint groups are assigned to each level by the order in which they appear;

Example

As an example, see the hints file located at hints/platformer-template.txt, belonging to the Platformer Template game page.

Hint images

To add hint images to one game:

  1. Inside the hints/ folder, make a new subfolder named like your hints file without the .txt extension.
  2. Drop all hint images into this new subfolder.
  3. Reference each image, amidst the hints, by its relative path inside this subfolder.

For multiple games, each game must have its own subfolder inside the the hints/ folder.

Example

See hints/platformer-template.txt as well.

Animated hint images

Animated GIFs are supported, similarly to static images. They will show up as paused, but clicking on them or pressing spacebar will toggle animation.

Example

Skilleblokker uses one animated gif hint, specified in file hints/skilleblokker.txt.

Multi-line hints

Within one hint line, include as many HTML paragraph tags as required: <p>Line 1</p> <p>Line 2</p> etc.... This will cause an hint to display as multiple paragraphs.

Level titles

Level names Experimental may be included in the hints file, as long as the following convention is respected:

  1. Each level name requires exactly one line;
  2. every level line is separated by at least one empty line, plus an optional group of hint lines inbetween;
  3. every level line starts with the word level;
  4. the following parts are discarded, in order:
    1. the word level , at the start of the line;
    2. .
    3. digits 1 2 3 4 5 6 7 8 9 0, optionally separated by dots ., at the start of the line;
    4. text following two dashes --;
    5. trailing whitespace;
  5. after discarding the above, remaining text becomes the level title.

Examples

For a simple example, see the level names specified in the hints file located at hints/blockworks.txt, belonging to the Blockworks game page (no hints, only level titles). An example combining level titles with hints, is hints/skilleblokker.txt, from game Skilleblokker.

Level sections

Level sectionsExperimental may be appended to the level title by means of the section sign (§). For example, to assign the first level to a section named "Tutorial", within the hints file, write level 1 optional level name § Tutorial

As soon as a section is assigned, all following levels will be assumed to belong to that section, until a new section is opened. So each section name is written only once.

Section names instruct a better level selector layout. In the future, section names will also be useful when defining custom level progressions.

Custom level progressions

This set of features is still in development, subject to change. For now, you can add the following javascript code lines to your game page, either as an external script or inline.

Linear progression: n unsolved levels

To unlock just up to n unsolved levels, insert the line function ObtainLevelLookahead(){return n;}; where n is a natural number. The default value for n is 0, meaning instead that all unsolved levels are unlocked.

Example (★ = solved level, • = locked level)

With linear progression set to 3, here are some possible states:

  • 1, 2 , 3 , 4•, 5•, 6•, 7• (starting state)
  • 1★, 2 , 3 , 4, 5•, 6•, 7• (level 4 unlocked upon solving level 1)
  • 1★, 2 , 3 , 4★, 5 , 6•, 7• (player skipped levels 2 and 3, solved level 4 and thus unlocked level 5)
  • 1★, 2★, 3 , 4★, 5 , 6, 7• (player returned to solve level 2, thus unlocking level 6)
  • Gate levels (♛)

    Any level may be marked as a "gate level" (♛), meaning that it 1) must be solved before reaching higher levels and 2) can only be accessed when all previous levels are solved.

    To mark a group of levels as "gate levels", insert the line function ObtainGateLevels(){return [a,b,c];}; where a,b,c, etc... are natural (level) numbers separated by commas. The default value is the empty array [ ] meaning no "gate levels".

    Example

    With linear progression set to 3, but level 4 now being a gate level, here are some possible states:

    • 1, 2 , 3 , 4♛•, 5•, 6•, 7• (starting state)
    • 1★, 2 , 3 , 4♛•, 5•, 6•, 7• (gate level 4 remains locked after solving level 1)
    • 1★, 2★, 3★, 4♛, 5•, 6•, 7• (solving levels 2 and 3 unlocks gate level 4, but subsequent levels 5 and 6 remain locked)
    • 1★, 2★, 3★, 4♛★, 5 , 6, 7 (solving gate level 4 unlocks three further levels)
    • Music

      Just add the music files!

      To control a music playlist via the game bar, each music track should be added to the page inside <audio class="music"> tags, placed anywhere in the page. If these tags are detected, a music button will be revealed automatically.

      Other buttons

      "Credits" button

      To display a "Credits" button, provide an HTML element with id="Credits", the button will then be revealed automatically.

      "How to play" button

      To display a "How to play" button, provide an HTML element with id="How-to-play", the button will then be revealed automatically.

      Advanced customisation

      For advanced customisation, you'll need to add extra javascript code lines to your game page, either as an external script or inline.

      The Puzzlescript Game Bar javascript code was written in a way that allows very easy customisation of key aspects: functions named Obtain... expect to be overwritten! Below is a non-exhaustive list:

      Disable screen rotation (don't enforce landscape mode)

      Add function ObtainXYRotateCondition(x,y){return false};

      Disable scrolling to game on page load

      Add ObtainInitialScroll=false;. This is useful in itch.io game pages at high screen resolutions (e.g. 1080p).

      Disable console messages that appear on game load

      Add ObtainInitialMessages=false;

      Change the Puzzlescript Game Bar colours

      To change the background colour, add function ObtainBGColor(){return NEW_HEXCOLOUR_AS_STRING;};

      To change the foreground colour, add function ObtainFGColor(){return NEW_HEXCOLOUR_AS_STRING;};

      Intermediate colours are deduced from these extremes.

      Troubleshoting

      You are hosting your game at the itch.io platform and...

      ... nothing shows.

      Please ensure that the Puzzlescript Game Bar javascript source is loaded from within the <iframe> containing the game, rather than from the main itch page.

      ... save progress is wiped when a new game version is uploaded.

      Please add the line ObtainStorageURL(){return state.metadata.title;} to your page javascript code. This will associate the save files with your game title, probably a stabler value than the default page URL (which may change when uploading new game versions).

      You use a modified version of Puzzlescript, now broken...

      The Puzzlescript Game Bar overwrites exactly 4 puzzlescript functions:

      • function doWin()
      • function nextLevel()
      • function doSetupTitleScreenLevelContinue()
      • function level4Serialization()

      If your Puzzlescript version relies on changes to any of these functions, it's likely those particular changes be erased. You're welcome to file an issue, so it can be taken a look at.

      After publishing a game with the game bar, you changed the level order and now worry the player's save files might have become jumbled

      Adding or reordering levels may indeed change the way a save file is interpreted. For example, suppose the following save file: 1★, 2★, 3★, 4, 5★, 6 (star denotes a beaten level) will be interpreted after the following changes:

      • Adding several final levels (levels 7,8,9): 1★, 2★, 3★, 4, 5★, 6, 7, 8, 9 Ok;
      • Adding an intermediate level (level 2.5): 1★, 2★, 2.5★, 3, 4★, 5, 6 Problem;
      • Reordering levels (worst case) (switching levels 3 and 4): 1★, 2★, 4★, 3, 5★, 6 Problem;
      • Reordering levels (best case) (switching levels 1 and 2): the save file becomes 2★, 1★, 3★, 4, 5★, 6 Ok.

      With a jumbled save file, players can still play normally, while noticing that their progress changed for no apparent reason.

      After publishing a game with the game bar, you added/removed messages between the levels and now worry the player's save files might have become corrupt

      Since v.5, adding level messages won't affect the saved files. Prior to v.4, players would probably have lost their progress as a result.

      You found a different problem.

      Please file an issue so it can be fixed sooner.

      Examples

      Here are some games that use the Puzzlescript Game Bar:

      Check also the game bar testing links available for some games in the Puzzlescript games database!

      Would you like to add your game to the list? Please let Pedro PSI know!

      Bookmarklet

      The Puzzlescript Game Bar can also be added in real time to any online puzzlescript game with this handy Game Bar bookmarklet!

      Simply add the bookmarklet above to your bookmarks, then on a game page of your choice run (click on) the new bookmarklet to add the Puzzlescript Game Bar to that particular game.

      In Chrome

      Drag the above bookmarklet link to your bookmarks toolbar.

      In Firefox

      Right click on the above bookmarklet link, then select "bookmark this link".

      If nothing else works

      Replace the content of an old bookmark with the above link content. Or you could run the bookmarklet js code directly in a game page (it'd still be quicker than manual alternatives).

      Contributions

      Special thanks

      To minotalen for very active ongoing collaboration!

      To Noa Hoffmann (Noa Cube Studio) for very insightful UX advice and other important suggestions.

      To Tim Knauf for using the bar, which resulted in diverse customisation improvements.

      To Builder17 for a useful suggestion.

      Would you like to contribute?

      Head to the official Game Bar Repository, submit a pull request or file an issue.

      FAQ

      How is Puzzlescript Game Bar's different from available alternatives?

      Puzzlescript Game Bar was designed to be a 1-step install, beautiful, intuitive and customisable.

      Also, the Puzzlescript Game Bar now supports hints and has a fullscreen mode! How cool is that?

      Full list of features:

      • A level selector;
      • Fullscreen mode;
      • Auto-landscape mode (screen rotation);
      • Hints system, including text and image hints;
      • Mute/unmute control for a BGM playlist (optional);
      • Non-linear level navigation:
        • All levels must be completed (no matter the order) before the game finishes;
        • Level unlocking:
          • N-level lookahead: players can access up the following N unsolved levels, further levels are "locked";
          • Multiple Gate levels (♛): gate levels only show up after all previous levels were beaten and lock further levels;
      • Keyboard shortcuts:
        • L: toggle the level selector;
        • H: toggle Hints;
        • in level selector:
          • 0 1 2 3 4 5 6 7 8 9: pick a level;
        • in current menu:
          • Left/Right: next/previous option;
          • Enter: select current option;
          • Esc: close current window;
          • Tab/Shift+Tab: next/previous menu item.
        • F: Toggle Fullscreen
        • M: Pause/Resume BGM playlist

      Notable alternatives to the Puzzlescript Game Bar are listed under Game Tools.

      Can you use Puzzlescript Game Bar for free?

      Yes, it's under a MIT license.

      What are the differences between the shared Puzzlescript Game Bar and the one live at the Creative Archive?

      The live Puzzlescript Game Bar at the Creative Archive is the cutting-edge, sometimes experimental version. As soon as the changes are consolidated, they will be added to the official Puzzlescript Game Bar shared in this page. Any functions that depend on the Creative Archive's infrastructure to work or that lack general interest won't be included into the official Puzzlescript Game Bar.

      Does the Puzzlescript Game Bar level selector handle checkpoints?

      Only in case all checkpoints are concentrated in a single level (e.g. a open world map such as in Tiaradventur). Support for multiple levels with checkpoints is not planned, unless you file an issue.

      Does the Puzzlescript Game Bar hint system handle checkpoints?

      No, sorry! But if this would make a difference, please file an issue.

      Feedback

      Problems? Suggestions?

      Please let Pedro PSI know !

      Praise?

      Enjoyed Puzzlescript Game Bar? Add your message below to the Creative Archive's Guestbook!

      Leave your message!