HSAPI: Planning

HSAPI: Coding Accelerated

This is a topic for planning HSAPI, a way to generate and modify Hopscotch project JSON with accessible JavaScript code. :hammer_and_wrench:

Let me rewind and explain what I mean by this. :rewind:

:gear: What is JavaScript?

JavaScript is a programming language, kind of like Hopscotch with way more to it! So instead of blocks, you write code like this:

// An array of fruits to choose from!
var fruits = ["apple", "mango", "watermelon", "orange"];

// Choose a fruit randomly!
// Math.random() generates a number between 0 and 1,
// so we do some math to make the number 0-3
const random = Math.floor(Math.random() * months.length);

// Write the fruit on screen!
console.log(random, fruits[random]);

It’s a little bit tricky to get used to, but it’s super cool and lets you write big programs for a computer or mobile device, like this forum, or Hopscotch itself!

:question: What is an API?

API stands for “Application Programming Interface”. It basically means “code that does stuff for other programs”.

:thinking: So then, what is HSAPI?

HSAPI will add JavaScript code (or code in a different language, perhaps) that lets you write crazy programs to, for example, swap out every Wait Milliseconds block in your project with regular Wait blocks:

(This is just a concept, it doesn’t actually work yet)

import HSAPI from "hsapi";

let project = HSAPI.importProjectFromUrl("https://c.gethopscotch.com/p/xu5kshy2a")
project.forEachBlock(block => {
    if (block.is(HSAPI.BlockTypes.waitMilliseconds)) {
        const divisionBlock = project.newBlock(HSAPI.BlockTypes.divide, [block.parameters[0], 1000])
        block.parameters[0] = divisionBlock

In this case, that means we’ll be writing the API which lets you write your own code to change the JSON in your project! You can then write all sorts of tools for making and editing Hopscotch projects. The possibilities are endless! :infinity:

:technologist: Wait, what about Hopscript?

Hopscript is a programming language. Basically, HSAPI will provide functions for Hopscript, and other projects, to be able to modify a project’s JSON with!

:slightly_smiling_face: Wow! How do I get involved?

This is a big project, so we’ll need all hands on deck to talk about this and come up with something great!

  • :brain: If you have any ideas and would like to help us brainstorm, feel free to discuss them in this topic!
  • :hammer_and_wrench: If you know your way around Hopscotch JSON and GitHub, you should make yourself a Hopscotch-exclusive GitHub (without any personal info) to contribute to HSAPI’s code with. (Please ask a forum Leader to verify that your GitHub account follows the Community Guidelines before contributing.)

Thanks, and please keep all posts on-topic! :D


Credits (Historical)

I just wanted to thank these people for being so awe-inspiring over the years. Without you guys, we might not be here now planning HSAPI:

@BuildASnowman for making the first big project with JSON hacking in 2016. This March marks the eighth anniversary of Chopin Etude “Torrent” - Full Piece, a project which blew everyone’s mind at the time of its release!

@MR.GAM3R for cracking open the JSON format after BuildASnowman, being the second person to hack on it way back in 2016!

@t1_hopscotch for making one of the first JSON readers ever in 2017!

@Awesome_E for making lots of different JSON hacking tools, pioneering the initiative to break free from the editor! First with Hopscotch Tools in 2019, and then officially with the web explorer!

Around 2021, I made the initial pitch for Hopscript, inciting a lot of interesting discussion.
^ @Awesome_E again for reviving this topic in 2023 with his own ideas.

@Petrichor for making Petrichorian Hopscript as a proof of concept, and making the project Connect the Pipes with it just today in 2024!

@Viridescence for providing leader approval and help with planning this very project!

(Additional shoutout to @Zachyswag for their interesting topic in 2019 about explaining the contents of the Hopscotch.app bundle!)

All of this has led up to this point, where we plan to make an accessible API for writing and manipulating real Hopscotch projects outside of the editor!


So to summarize what we were talking about in the Hopscript topic:

  • HSAPI was conceptualized out of a desire for more low-level control over what Hopscript should be able to do. However, for the sake of not limiting either of these projects, HSAPI and Hopscript are separate works entirely with different objectives
  • Split HSAPI into different modules, depending on the programmer’s needs:
    • HSAPI.Core will provide 100% coverage of Hopscotch’s editor features, as well as providing the ability to manipulate more than one project instance at a time
    • HSAPI.Extensions will provide new QoL language features, like while loops and code generation
      • This extra stuff will be user defined, so you only use what you need!
  • Does NOT necessarily need to be written in JavaScript - we can compile native code down to WebAssembly and it’ll run with native performance. The hopscotchification step might end up being a lot faster for really massive projects.

So what features did you have in mind @Petrichor @Viridescence? That’s where we left off last time.
Let the Hopscotchification commence :D


How does the HSAPI change a project?

1 Like

My thoughts exactly lol


However the user wants it to. It is basically just a library that you can use to modify the hopscotch project however you want – if you tell it to add a scene, or to change the type of a block, it will do just that. Essentially it is a tool you will use to write code to change a project for you – by itself it will do nothing. You need to write your own code that uses it in order to change a project


Thanks it sounds cool but how does it have the capability to do so and why would you rather use this than the normal editor?

1 Like

So basically, you’ll be able to make projects on your computer with just the project’s JSON data! You could download/import the project from a URL, then modify the block data with text code instead of the stock block editor. Then you could export the project file to your iPad using iTunes and upload it there.

The power that comes from HSAPI mostly resides with the ability to tinker with the project outside of the editor itself. I could make a level editor in JavaScript that generates a ton of blocks, for example.

It’s mostly a coding environment for text coders trying to make really big projects, or just mess around with the files and experiment closer to the raw code :D

So it just basically creates and edits projects without the need for the iPad editor, which others can make tools based on (kinda like the Siri Shortcut Petrichor mentioned). Hopefully that makes sense!

1 Like

It understands the json for you, so you don’t have to. You wouldn’t typically use this for making projects directly, but for generating hopscotch code to do something. For example, if you want to make a text-based language that transpiles to hopscotch or something to convert a midi file to a hopscotch project, you would use hsapi to make the actual project json, because the editor cannot be automated.

Think less like Awesome_e’s siri shortcut and more like a tool for creating something that does the same thing.


Wait does this mean you can create variables while playing a project with code or am I confused lol because that’s something that would personally be kinda useful as a pseudo list system haha


no, this is only for editing a project. Basically instead of editing the project yourself, this will help you write code to edit the project, which currently requires some more low-level knowledge of the format of the project jsons.


Oh alright then

So sorry you probably already answered this i’m just a little lost lol but what can this do that the editor can’t or is it just like a different way to edit code with no significant differences (which isn’t bad i’m just asking)

1 Like

It can put arbitrary blocks in arbitrary locations for example. Anything that can be done by editing the project json.

If you wanted to make something comparable to the regular editor, you would create a separate project that uses hsapi to deal with the json. The api itself isn’t an editor or editor-like thing.


Yo @rawrbear i really appreciate how you take time to make really in-depth posts with lots of detail :slight_smile:


By arbitrary blocks do you mean blocks you can’t access in the app?

((also what do you mean by arbitrary locations?))


Yes, basically you can do any block, even blocks that literally don’t exist, and put them anywhere, even places they don’t do anything.

i’m not sure why you would do that, but you could. Essentailly we’re making some code that you can use to make your own code that manipulates the project’s json.


Oh wow so literally making whatever blocks you want? Like unofficial blocks

Could there be any way for this to be viewable/accessible on the app through an extension or something? That would be amazing if people could make their own blocks and share it through the community maybe with spider hs or something


Sorry if the topic didn’t make sense! There’s just a lot of jargon to explain here without a lot of solid examples yet haha :upside_down_face:

It’s kind of like Hopscript, but instead of placing blocks like Hopscript does, it goes a little deeper and lets you modify any block within the project! Basically, it’s kind of like editing a JSON file, but it gives you the tools to read through it and edit it safely.

So that’s why it could do powerful things, like scanning through the JSON file for all the wait blocks - the API will read through the entire file and return all of them for you when you call that function.

It can do things that the editor just couldn’t do without a lot of manual labor, because JavaScript provides more powerful features.

Let’s say you’re making a pixel art. Instead of laboriously copying and pasting Draw a Trail loops in the editor, you could write a JS program to copy an image you saved and generate those blocks for you, without having to manually add all of those blocks in the editor, with the power of JSON editing.

HSAPI just provides the actual code tools to write a program like that, basically! You get all of JavaScript’s features, and then it’ll “hopscotchify” into an actual project by turning your JavaScript commands into Hopscotch project JSON.

These are just our ideas right now but it’ll be really powerful eventually. AE himself pitched something like this at one point too!

Thanks @Ezra!


No, thank you, rawrbear for taking the time to make really long and in-depth posts.


It’s my pleasure! I really enjoy it lol :)