How Hopscotch works

How Hopscotch works right now

This post is in response to some folks on the forum who wanted more details about how Hopscotch works. The following is somewhat technical but should be understandable by a determined 14-year-old who is interested in coding.

Note: we reserve the right to update this in later versions of the player for various reasons. As of today, November 25, 2019, it is accurate to the best of my knowleddge

The code

The Hopscotch player is written in javascript, a language for the web. That’s why it can run on your browser and inside the Hopscotch app.

We also use several libraries and frameworks to help us code more productively:

WebGL is a graphics API that lets us write code to run on your computer or iPad’s graphics card. Almost all games are written using WebGL or its cousin, OpenGL, because using the graphics card is the best way to get fast performance for something that has a lot of visual components (like a game!).

PixiJS is a WebGL renderer. Pixi takes care of the details of using WebGL properly and lets us focus on writing code. When a new version of WebGL comes out, Pixi will figure out the optimal way for Hopscotch to interact with it.

Typescript is a language that helps you write Javascript using a type system. A type system is useful for ensuring that your code runs correctly and does what you think it should do.

The project file

Your projects are saved as JSON files. Our code reads the JSON file to figure out what you’ve coded, so we know the characters to put on screen and what they should do. The easiest way to create one of these files is to use the visual code editor in Hopscotch.

However, there are other ways to edit your Hopscotch project! You could write an editor for the JSON files yourself as Awesome_E did here.

You could also write a JSON file out line-by-line into a text editor, either by copying the file of an existing project or writing it from scratch. The disadvantage of writing Hopscotch code by hand is that the JSON was not originally designed to be human-readable and editable. It can be quite confusing and tedious to write out all that you want to do. The advantage is that you can have more precise control over what exactly is in your file. You could even use features that aren’t built into the Hopscotch editor yet.

Editing a JSON file yourself is not for the faint of heart, but if you are looking to make your project perfect or want to learn something new, it can be a worthwhile endeavor.

Something on my to-do list is to write a detailed report on where everything in Hopscotch fits into the JSON file. That’s outside the scope of this post right now.

The run loop

The run loop is what makes your project play. Anything graphical, such as a game, usually has a run loop. We use a javascript function called requestAnimationFrame that calls each time the picture on your screen refreshes. For most computers and devices, this will be 60 times per second or about once every 16.67 milliseconds.

In Hopscotch, most action blocks will take one frame to execute–i.e., About 16.67 milliseconds. There are exceptions, though, and we’ve singled out some blocks to execute immediately. When you run those blocks, the block after them will execute in the same frame.

The blocks that run immediately right now are:

  • Set Trail Color
  • Set Trail Width
  • Set Variable
  • Change Variable
  • Repeat
  • Repeat Forever
  • Check Once If
  • Check If Else.

The Movement blocks

There are exceptions to the one block/one frame rule. The following red blocks are movement blocks:

  • move forward
  • turn
  • change x
  • change y

Movement blocks will execute over several frames. How many depends on a variable called speed which you can set with the set speed block. The default speed is 400, which translates to your character moving forward 10 points or turning 10 degrees (out of 360) for each screen refresh.

If you increase the speed to some huge number, you could execute the entirety of your move forward or turn in one frame. Setting the speed to 99999 can make your project faster, up to a point. But if your blocks are broken up into small chunks, it won’t make a big difference. If you had the code move forward 1, setting the speed to a high number wouldn’t matter because the best it could do would be to move forward one point in one frame. Move Forward 1000 could teleport you 1000 points in a single frame if you set the speed high enough, but if you wanted to make a more exciting path, where Move Forward is interspersed with Turn we will need to use a frame for each of those actions, no matter the speed.

The Wait block

The Wait Seconds block works by setting a time in the future before which no code can execute. If you were to wait 3 seconds, you’d block the run loop for that script until 3 seconds in the future. Because we can only check the time once per frame, the accuracy of wait is based on the time to execute a frame. We know each frame takes a minimum of 17 milliseconds, so that is the highest precision you could expect from the wait block. If you were to wait one millisecond, you would have to wait at least 17 milliseconds to get to the next frame and let your next block of code execute.

In Hopscotch, we added the wait seconds block and removed the wait milliseconds block. Using seconds makes things more clear for new users since people usually think and talk in seconds. It also gives a more realistic portrait of how precise wait will be.

What is lag?

Your code taking longer than 17 milliseconds to run is what usually causes lag today. If you have a project with many characters, generally, through cloning, they will all execute their actions on the same frame. If 1,000 characters are trying to do something in one frame, that might take more than 17 milliseconds and cause your project to lag behind the screen refresh.


I hope this overview was helpful to some of you. Any errors are my own! Please post any questions in the comments, and I will try to answer them. We also always welcome suggestions about how to make Hopscotch better.



Very detailed


Very detailed explanation


This is all very understandable.


Interesting and detailed explanation

Thanks for taking the time to type this up


Very informative! Thanks for this



Hey thanks for the mention, but also great job explaining to inner workings of the app. This really reminds me of the Frame Rule tutorial I wrote on this topic some time ago.



Wow, what an amazing explanation! Some of the details here are interesting to know about, and it cool to learn how it works. Thanks AwesomeOnion!




This was really cool! the only other thing I would want this to include is web API docs, even if it literally just said the URLs.


Wow, this is very interesting and detailed! Thank you for making this, I think it will help everyone that is trying to push the boundaries of Hopscotch, and also just generally interested people (like me)!


a resounding thank you, and nice new profile pic!

I agree with all that’s been said about helping people push the boundaries of Hopscotch, and I also find this very helpful to kids like me who have noticed phenomena and now have an explanation for it. this info will make it so much easier to code with an educated background instead of making guesses with things such as wait time, sound blocks, and character speed. thank you so much for taking your time to write this guide!


Here are some public APIs, enjoy!





Wow that’s really useful, thanks!

Since you also seem really open to sharing this stuff and making it open for us to use, do you think you could allow CORS requests? Currently, the only way to access this through a web page is through a CORS proxy, and those aren’t super reliable, though they do get the job done.


Thank you sooo much! Honestly I wasn’t expecting a reply, but this is better than I expected. @ Awesome_E: I would assume you could do it by using a GET request and then removing the redirect as long as it is a client sided redirect. After doing that you could generate a HTML output and return it with MimeType.Text or MimeType.Text/HTML. If you have a google account, you should be able to make a web api for it.


I specified how I do it currently


This is absolutely incredible
Thank you so much for taking the trouble of typing this up it’s incredibly useful :clap:


@awesomeonion is there a place where I can find the avatars at and when a user joined the app?

to better word that to make my request more clear, is there a way i can find this:

    "id": 4842647,
    "avatar_type": 25,
    "created_at": "December 2018",
    "iphone_user": false,
    "nickname": "koletsgo",
    "remote_avatar_url": ""

without using search?


You can get pfp from replace the numbers with their User ID
Edit: realized you meant the image not the picture.


yup, I meant input type output image