Close Menu
Home About Download Viewing Projects Future Steps Editing Projects Shortcut Versions

Hopscotch JSON Siri Shortcut Help Guide

About

The Awesome_E Hopscotch JSON Siri Shortcut is the ultimate shortcut for viewing and editing your Hopscotch JSON files. It contains over 1500 actions and can mod just about any aspect of your project. It's already come quite a long way, and it will continue to evolve. It all started when I looked into the get file, save file, and Set Dictionary Value blocks. I realized the potential for the Hopscotch Shortcuts combo. Now, I've even come as far as transferring code. It's quite amazing and I really suggest you try it if you have not already!

I looked into the sub-elements of nearly every trait of the "Hopscotch JSON" and realized, "Hey, I could read and write data to this". The shortcut began to advance. From one ability to several, one scene to many, things picked up quickly. And here we are now, with presets, filter checking, and secret blocks! It's all here. To learn more about what this shortcut can do, see the features dropdown in the navigation. The possibilities are endless. You can edit the player version, any object, any piece of code, and even transfer your favorite actions to another project through a preset file.

If you have any questions about this or have a bug to report, just ask me here. I'm always happy to help.

Download

This shortcut is open-sourced, which means that you are free to use it, tinker with it, and remix it! This shortcut is compatible with iOS 11 Workflow, iOS 12-13 Shortcuts, and iPadOS 13 Shortcuts. iOS 14 is NOT officially supported, though it may still work for some users. If you want to try it on iOS 14, however, the download instructions are the same as iOS 13.

iOS Version10.x-11.x
CompatibilityNoneFull
12.x13.x14.x+
FullLimitedUnstable

iOS 13, iPadOS 13 Download Instructions

Compatibility: Limited

    The Shortcuts app is installed by default on iOS 13 and iPadOS 13

  1. If you have not used shortcuts at all before, create a shortcut and add a random action. Save the shortcut, then delete it. This will allow the necessary setting below to show up.
  2. Go to Settings and scroll down to "Shortcuts". Tap "Shortcuts" and turn on "Allow Untrusted Shortcuts". This will allow you to run my shortcut.
  3. Now that you have the app and its proper settings, head back here and find the download links.
  4. Tap the Download Links in order from left to right, and they should all open the Shortcuts App. Order Matters! Tap "Add Untrusted Shortcut" for each one. Congrats, you now have the Hopscotch JSON Shortcut!
  5. Give the main shortcut a run! You can now mod any Hopscotch project.
Download Links Generate UUID View Dictionary Hopscotch JSON Stand-Alone
Note: Download links are different for iOS 13 and iPadOS 13.

iOS 12 Download Instructions

Compatibility: Full, Recommended

    Skip numbers 1 through 3 if you already have the Shortcuts app

  1. Go to the App Store, and search for "Shortcuts". Tap on "Shortcuts" by Apple. This is the app you need to install if not installed already.
  2. Tap on "GET", then tap "INSTALL". Enter your AppleID password or ask a parent. Then, allow the app to download.
  3. Great! Now you have the Shortcuts App. Head back here and find the download section again, as that is where the link can be found.
  4. Tap the Download Links in order from left to right, and they should all open the Shortcuts App. Order Matters! Tap "Get Shortcut" for each one. Congrats, you now have the Hopscotch JSON Shortcut!
  5. Give the main shortcut a run! You can now mod any Hopscotch project.
Download Links Generate UUID View Dictionary Hopscotch JSON Stand-Alone

iOS 11 Download Instructions

Compatibility: Full Support

    Skip numbers 1 through 4 if you already have the Workflow App

  1. You will need a second device on iOS 12+ for this, but it does not have to be yours. Login to your parent's or your Apple ID on the second device, and go to the App Store.
  2. Download the Shortcuts app on that device. You do this to put it in the cloud, which is how you can download an older version for iOS 11. You can delete it after if necessary.
  3. Go back to your iOS 11 device and make sure you are using the same Apple ID. Open the App Store there, and go to your purchases. To do this, tap your profile icon, then tap purchases.
  4. Find "Shortcuts", and tap the cloud. Apple will give you a dialog box to download an older version. Click "OK". The download should finish and the app should magically morph into Workflow.
  5. Come back to this page and find the download links. Tap them in order from left to right, and you should be redirected to the Workflow App. Congrats, you now have the Hopscotch JSON Shortcut!
  6. Give the stand-alone shortcut a run! You can now mod any Hopscotch project.
Download Links Generate UUID View Dictionary Hopscotch JSON Stand-Alone

The stand-alone shortcut is used to run it from the share sheet or on iOS 11. It is used to remove the need for Shortcuts to render all 1400+ actions.

Viewing Projects

This shortcut allows you to view the JSON file of a Hopscotch in several ways. It can be a published project, a draft, or someone else's project.

Future Steps

As many of you know, I have been phasing out the shortcut for a few months now. This shortcut certainly holds a strong legacy, but its functionality is limited by the one-run script-like nature of Siri Shortcuts. Performing complex actions is much more tedious to create and use, and there is no user control in order, or whether one wants to cancel an action wihout discarding all changes. For simple tasks, the shortcut will still be available for anyone to use or discuss about.

Apps like the Project Builder are completely open-ended and have far less issues with performance, reliability, etc. Web development is the future of technology, and I will follow that with my Hopscotch project editors. There are ways to easily reuse code without clutter, and create functions when there is no native function, whereas shortcuts has already been pushed to the limit with complex dicationary and text actions. Features like a semi-visual code editor, project statistic graphs, search, and images with prompts just cannot work well in Shortcuts; these are all features that are included in or will be a part of the Project Builder at some point in time, and it saves so much time to develop for the web as opposed to a shortcut to implement such features.

End of Support Statement

After the shortcut being the primary method of in-depth Hopscotch project JSON editing for over an entire year, its legacy certainly is strong.

The shortcut has been struggling to keep its existing features working properly, especially with text matching, and it’s starting to peak. That being said, new boundaries have been broken, and there is a full WEB editor that you can use across devices! It already has everything that was supported in the Siri Shortcut at any given time, and is still growing with MANY more possibilities that were just not possible with a one-run script like Siri Shortcuts.

As of June 28th 2020, I have stopped providing support and bug fixes for this Shortcut. The biggest existing issues have been fixed, you can still use it like you have been for the past year, and resources like the filter checker and secret blocks will still be kept up to date every time you run it. It’s not all over, but instead a stepping stone, a new chapter in the story. I will continue to support anyone by answering their questions and walking them through the JSON project structure, but will be transitioning my time to further developing the Web Editor. You can still use the shortcut, ask questions here, and talk about other modding or Shortcuts/script related stuff on this topic.

And to the whole community, thanks for the continued support. Now Let’s Go Mod A Project!

Editing Projects

Editing projects is the core focus of this shortcut. There are endless possibilities when it comes to the potential of a JSON editor like this, even if it is a little confusing to use at first. It is more guided than editing a raw JSON file, but it lets you have the same amount of control at a small cost of speed. Each section of the shortcut has more info on what it does, but some basic terms will be referred to a lot in the more advanced sections.

Stage Size

Stage Size was my first step in JSON editing, and it might be yours too, who knows? To edit this using my shortcut, simply change the values on the right-side column (shown in example popup). All tables follow this rule: The trait name on the left side should not be changed, and the value on the right is free to mess with.


⁣

Stage Size has some interesting traits. It can be negative (thanks MISSION_IMPOSSIBLE), and it also has a upwards limit where trail drawing stops working. Besides its quirks, stage size is actually really useful sometimes. If you want to make your game feel like it has more room or you just want to give it a different aspect ratio (width:height), stage size does that perfectly.

Editor Version


Table Showing Version Modifier
⁣

This is one of the two version traits you can modify. Once again, only change the value in the right side column of the table. Version 26 and up gives you the latest editor, 25 gives you the webplayer with the old editor, and 24 gives you old the editor mechanics (object variables and alphabetized variables, not the old UI), and projects are not played using the webplayer.

There are advantages of all three versions! Versions 26-30 (30 is the newest) have access to all of the newer blocks (such as destroy), custom rules, and self variables. Version 25 allows you to run secret blocks, but self variables and custom rules do not exist. Version 24 is the legacy project version, and it has many different traits about it. For example, objects do not lose quality when scaled up, deprecated blocks such as "move with trail" and "set opacity" work only in versions 24 and below, and text rendering is far superior to the current engine (no 40-line limit, all unicode works properly, higher quality). Unfortunately, projects with player version 24 run the webplayer when played in Safari, which means text renders as it does now and deprecated blocks will only work in the app.

Player Version

Player Version, ah yes. This is the cause of so many current bugs in Hopscotch because of how new it is. It's recommended that you keep projects up to date, which you can do with easily with this [optimize] feature in my shortcut. That is mainly due to the fact that the web browsers currently use only the latest version, causing inconsistent gameplay.


⁣

Basically, each project has a specific version of the webplayer tied to it, and it uses the latest minor release of that version (1.0.0 uses 1.0.4, 1.1.0 uses 1.1.6, etc.). Newer webplayers usually have a major difference. For example, 1.2.0 and above makes it so variables no longer take a frame to execute. There are some bugs with it, but it is definitely something that everyone should get used to. The webplayer is versioned here so that existing projects do not break, but new projects will follow the new variable methods. If you are on version 1.0.x, update to 1.1.x. Otherwise, stay where you are.

Edited At Date

The Edited At Date won't really have an effect on your project. As you can probably tell, it changes the date the draft was edited on, which will also affect the order of your drafts. This trait is edited very easily, as you can type a date into several formats, and Shortcuts will also tell you the exact date and time that you are inputting (see the gray text). I haven't tested this yet, but with this method it may be possible to pin a draft that you are not using.

Base Object Scale

Finally, we have something that isn't the same when made on different devices. Base Object Scale is the scale factor used to determine the sizes of characters and only characters (shapes and text are not affected by this modification). Just like the other traits, change the value on the right and observe the effects. The iPhone generates a project with a default "BaseObjectScale" of 0.5, whilst the iPad's new project has a "BaseObjectScale" of 1.


⁣

There aren't that many use cases for this modification because you already have set size, but you may want to use it if you want the shape size to character size ratio to be different. Baseically, if you have a custom rule to initiate something 3D, but you want to use the same percent in set size for different-sized characters, you could use this to make sure that the characters always appear smaller. Not really an every-project thing, I know, but you might be able to find a use for it.

Font Size

This is useful because of Hopscotch's characters per line limit. Normally, each line has room for about 15 emojis in a 1024x768 editor, which ends up being about 600 pixels. In a smaller editor such as the 375x667 editor, text will max out at the width of the editor. When the font size is smaller, you can fit more characters onto one line. But ig it is bigger, text will lose less quality when upscaling (increasing the size of) it.

By changing this, you can make 16-bit emoji text-arts, something MagmaPOP always wished for. It's too bad that MagmaPOP wasn't here for my shortcut (and the removal of my game changer lol). You can also make larger labels that look nearly as clear as editor version 24's text, but at the cost of some line space.

Scenes

Most of us are familiar with the fact that Hopscotch has added an early version of a scenes editor for the beta channel. Given that it looks great and functions well, there are a few downsides and weaknesses to it. For example, you can't delete scenes once you create them. Also, you are unable to rearrange the scenes to rearrange the scenes to your liking. With my shortcut, you can add scenes to any editor (that does not mean that the normal editor gets the UI; they have to purely use modding in order to do anything with jumping between scenes), rename them, rearrange them, delete them, and transfer objects between them. In this first menu, you are asked to choose what you'd like to do with the scenes in your project.

Adding Scenes to the Project

This is the first step in working with scenes – you need to have more than one scene to work with more than one scene. Before the beta scenes editor, modding a normal project was the only way you could obtain more than one scene. If you are not a subscriber, this is still the only way to have more than one in a project. If you are, you can use the UI and tap "New Scene" in the project. To add a scene using my shortcut, you'll need to select "Add a Scene" when you are asked how you want to manage your project's scenes.

Next, the shortcut will prompt you to choose how many scenes you want to add. Input a number, then name each scene by editing the right side the following dialog boxes (they should be "dictionaries" where you edit the value of "name"). After you have done that, congrats, you have successfully added scenes to your project

Rearranging Your Scenes

This one is a little menu-heavy, but easy to learn. First, select how many times you would like to move a scene to the front/top. I suggest inputting the number of scenes that are in your project. This will simplify things for the next step. If you did that, then just tap all of your scenes in reverse order as you get prompted. This should nicely rearrange your scenes into your preferred order.

See the demo video below.

User selection menu asking which scene should be the first one

Deleting Scenes

This is as simple as it gets. You choose which scenes to delete, and they get deleted. The only important things to note are:
  1. Objects not rearranged will be deleted after entering and exiting the project in Hopscotch.
  2. If all scenes are deleted, all objects will merge into one new scene created by Hopscotch, regardless of where they come from

Choosing Objects

Obviously, each scene has its own set of objects. However, you may want to move an object from one scene to another, and that is not possible in Hopscotch (you can use custom rules and all that stuff, but that's too tedious). Using my shortcut, you can transfer multiple objects (you choose how many) between scenes. They will keep all of their traits, and their code will not be changed. After selecting the option "Choose Objects", choose the objects you'd like to move and choose the scene(s) they appear in. (If you choose more than one, the object's JSON code gets duplicated but the object does stay persistent between the two scenes).

Objects

Objects are a key component to any project in Hopscotch. They run the actions, hold certain properties, etc. However, some traits can be hard or impossible to adjust to your liking, and you can do just that with the shortcut. Choose your objects, and you will be greeted with a table. The left side tells you what trait it is, and the right side allows you to change those values. Just tap "Done" after each trait is good and you've successfully modified an object.





Variables

Variables keep track of most changing (and constant) numbers in your project. They are those yellow bubbles that you can choose a name for, but their options in the editor are very minimal. You can rename them, or leave them the way they are. However, the shortcut allows you to also change their type and delete them, although doing either of these will probably remove any trace of that variable in the project's code. This editor is old and is in chunk format, similar to abilities. You can either input raw JSON or keep the structure it is in. When you choose to modify variables, you get one popup with any and all variables. Hit done and those are your new variables.

Custom Rules

Custom rules are a great addition to Hopscotch, and they allow you to make a set of rules that you can apply to multiple objects. There really isn't much to say about them or change about them. Renaming and deleting them are easily done in the menu, so the only thing left to do is change the rules contained within them. This is actually surprisingly useful because you can do a true duplicate of the rule, meaning it will mirror any other instances of that same rule. To begin, choose to modify custom rules, then select all of the custom rules that you would like to change the rule sets of.

Next, you will be greeted with an input box showing the UUIDs of rules that are contained in each custom rule. Before going into this, you should preview the project and already have a pretty good idea of what exact rules you want to modify. Delete, move, add, or copy any rules that you wish, and tap ok. Bam you're done editing custom rules. Do this for every custom rule that you choose to modify. Also, note that custom rule UUIDs also appear as rules, as expected. You can use this to put the a custom rule inside of itself as well as to do other things that Hopscotch wasn't meant for. However, that does crash the game upon playing it.

Rules

Rules are those pink blocks inside every object that tell it “when” to do something. Each object's rules are considered blocks, and those describe the event that causes the actions inside to run. Examples include “When Game Starts”, “When iPad is tapped”, and “When equals”. These can be modded only to a limited extent, but having access to these blocks also provides information on their ability (the blocks inside that rule – you can use this UUID to edit that in the abilities part of the shortcut).

Upon selecting to modify rules in the shortcut, you will be asked how many sets of rules you would like to modify. The term “rule set” refers to the entire object or custom rule that you are referencing. For example, if you wanted to edit 3 rules under “Bounce” and 1 rule under the object “Chillanna”, you would need to modify 2 rule sets, one being the custom rule, “Bounce,” and the other one being the object, “Chillanna”. Basically, the “rule set” is the container of the rules, which is always going to be the custom rules or objects that you want to modify. After that, you will need to choose (for each rule set) whether it is an object or custom rule, and which object or custom rule you are looking for.

After you have chosen your object or custom rule, you will need to choose which rules you'd like to view or edit inside of that. When choosing the rules, they will show up like the pink rule block does in Hopscotch, along with its UUID. In the images below, the rules listed include the name of the pink block (e.g. Game Starts, equals, etc.) as well as the UUID of the rule (this is what is used to identify it elsewhere). You can select multiple rules to modify, and for each one, another text box will pop up. This text box contains pure JSON code, meaning that any syntax errors may result in project corruption. From this point, you have information on the following pieces of information: the rule block type (the actual pink bubble that tells what type of rule it is), the ID (the same UUID is shown on the “choose rules” list), the ability ID (this is the UUID to the ability, which contains the code run inside the rule), and any other info on the rule block itself (conditional parameters, event parameters such as “self”, etc.).

Abilities

This is where the real fun starts :)

Before we begin discussing each one, let's summarize what abilities are and the functions of each one so that you know which one you need to choose. Abilities are Hopscotch's way of storing every single block of code (whens/rules don't count) run by an object. Hopscotch stores each set of blocks under a collapsible within one “ability”, and these all have a UUID that they are identified by. My shortcut currently has 3 ways of modifying abilities (soon to be 4 with Create Dictionary Ability), and those are the ae_json_edit custom block, the MIDI hack, and find by UUID. The pre-named custom block is useful for quick access to code, the MIDI hack adds songs to your project, and find by UUID is how you modify bits of code that are pointed to by other abilities or rules. When choosing to modify abilities, choose the ones you need (can be more than one).

The Prenamed Ability: “ae_json_edit”

This is one of the easiest concepts to understand when it comes to JSON editing, and it is where I recommend starting. The ae_json_edit ability is just an ordinary custom block/ability that you create in the project by tapping “New Block” (the shortcut can also create it if it does not exist). Selecting ae_json_edit when modifying abilities simply shows you the JSON code for that ability, in what I like to call “chunks”. Basically, a chunk is one cluster of the JSON code, representing one item in a list. You can use this format, or you can directly input a JSON list of blocks (without the brackets) you want to transfer. This option is great for transferring code from outside tools as well as getting started with the JSON structure of a Hopscotch block. The pre-named ability is also super useful when testing just a couple of blocks and how they react to different parameters, which is my main use for it.

When you select this ability, the existing code of the ability is shown if that ability exists and is not empty. Otherwise, it creates the ability (rainbow block), and defaults you to insert secret blocks. When editing this for the first time, pay attention to the “key-value pair” of JSON code (example – “description”: “move forward”). Since the keys are predetermined by Hopscotch, there is no point in modifying them. Instead, modify the values of them, such as the block's type, parameter values, etc. – stuff that you would notice a difference in when you reopen the project in Hopscotch. This is a simple but powerful tool, as it allows you to mess around with just a couple of bloks or paste in code from other generators such as Petrichor's pixel art tool. That choice is up to you. After you are done changing that code, tap done. You will also be given a screen to change other info about the ability if that's what you wish, but once you tap done on that, you have successfully edited the pre-named ability, ae_json_edit.

The Hopscotch MIDI Hack

First, of all, credit goes where credit is due. The Hopscotch MIDI Hack was originally created by MR.GAM3R, and it can be found here. BuildASnowman created a MIDI Hack outside of Hopscotch, and MR.GAM3R, inspired by it, created a similar tool in the form of a web page with some help from MIDIConvert (more info and how to use the web page can be found here). Due to the fact that it is written in HTML and JavaScript, it is extremely easy to integrate into shortcuts, as shortcuts allows me to take variable data and get the contents of HTML code, which I modified very slightly.

Now, let's go into the very simple process of using it in my shortcut. When you get to the MIDI Hack, my shortcut will just prompt you to choose a MIDI file from your file browser (supported file extensions are .mid and .midi). Once you select your MIDI file, the shortcut creates an ability with the same name as the MIDI file, and just like that the song is in your project. When using this, just remember that only the MIDI audio format is supported. MP3, M4A, WAV, and other common formats will not work.

Personally, I added this to my shortcut to experiment and give others the chance to use it for adding songs to projects. I would not rely on the consistency, accuracy, or performance of it, but it is a great tool for demonstrating the possibilities of modding Hopscotch. Keep in mind that I did not make the MIDI Hack and I am not sure entirely how it works (besides reading the notes and converting it to JSON), so if you need help with that specifically, ask MR.GAM3R.

Find by UUID

Finding an ability by its UUID is the only way you can access every last bit of code in your project, and this is used for more advanced JSON editing. The main process of this goes through a process like this: think of the final ability, backtrack it to a rule, object, or custom rule, then locate its UUID by searching through the rules and other IDs. It's no easy feat and is extremely hard to do without a note-taking app of some sort opened in multitasking. This method of JSON editing is not for the faint of heart, as it is heavily based on text and short-term memory. But once you understand where to find the UUID of an ability you are looking for, this is the option that you use to modify the code inside of that. This is where you paste an ability ID from a rule, a control script ID from another block, etc. These are the blocks of code that are being pointed to by other abilities. If that was too much of a mouthful of word soup, I recommend gaining some more modding experience first. I am open for questions on the shortcut topic at any time.

Presets



Presets are a way of copying code between projects, which can be super helpful in many situations, such as copying a template, adding custom block abilities (secret blocks and set image blocks, for example), and more! Code being saved to a preset can include abilities and custom rules. To save and/or load a preset, select “Presets” when choosing traits to modify in your project, then select whether you want to save a preset, load a preset, or do both simultaneously.

Saving a preset requires selecting which abilities and custom rules to save, and that's it. A file is generated, and can be saved it to wherever you want! No work is required except for being patient, since the Shortcuts is extremely slow with matching ability IDs. It also has a limit of 64 nested abilities since Shortcuts does not have a repeat until. You can edit this iteration count in the shortcut, but the shortcut will run a repeat action for the max iteration count every time. Reliability is not guaranteed on iOS 13.



Loading a preset is even simpler than saving a preset. Choose load preset, and choose the file(s) that you want to load. The shortcut will merge the two projects automatically. Reliability on iOS 13 should be better with loading presets when compared to saving presets due to the lack of match text actions. However, both loading and saving presets are extremely slow and limited in functionality when compared to the Hopscotch Project Builder preset functionality.

Optimization

Optimization, simply but, makes a project better without any work needed. To perform any of these actions, select “Optimize” when choosing traits to modify, and select the action to perform. At this point in time, the only useful optimization is Color Slot Optimization, since the purpose of the other two features is outdated. Color slot optimization, as stated, will turn all RGB and HSB operators into HSB values that take up significantly less storage in the project (over 90% reduction in file size).

There isn't much else about optimization. Unfortunately, I never got the time to add separate features to this main shortcut, such as the Ability Dictionary shortcut, but the color optimization works pretty well.

Change Logs

What Was in v0.1

Changes in Version 0.2

Changes in Version 0.3

Changes in Version 0.4

Changes in Version 0.5

Changes in Version 0.6

Regex Video KONZ Video

Changes in Version 1.0

Huge update coming your way! This version includes several new features and improves old features drastically.

Changes in Version 1.1

View Dictionary Free ePoints

Make sure to get the view dictionary update as well as the shortcut itself. As per usual, enjoy the shortcut update!

Changes in Version 1.2

Generate UUID ePoints Info

Get the View Dictionary Update if you have not updated it since v1.1 (if you got that when downloading v1.1 of my JSON shortcut, you are good). Also, make sure to grab the UUID update, as I fixed a small issue there that would cause presets to not work. As per usual, enjoy the shortcut update! ePoints Info has a secret message, and it is not a rick roll (or is it). This monster of a shortcut now has 958 actions in it!

Changes in Version 1.3

Minor Update

Changes in Version 1.3.1

Bug Fix, thanks @M_W_K

Changes in Version 1.4

Back to the Big Changelogs

Changes in Version 1.4.1

Stand-Alone

Bug Fix we Shall

Changes in Version 1.5

ok fine here is an update

Changes in Version 1.6

Should have really done this earlier. Even though you had a Shortcut disclaimer and my warnings, huge apologies to everyone on iOS 13 losing drafts.

Changes in Version 1.6.1

Important bug fix. Sorry for the wait (@MISSION_IMPOSSIBLE)

What's New in Version 1.6.2

This is an iOS 13 exclusive release to fix shortcut bugs specific to this version of iOS and can only be manually downloaded as of now.