An explanation of how Hopscotch json files look

An explanation about the general structure of the json

It is easiest to think of Hopscotch projects as containers containing containers. A great visualisation of this is the web editor at https://explore.gethopscotch.com.

Scenes contain a list of pointers to objects. Objects contain a list of pointers to either custom rules instances or rules. The player will check for custom rule instances first. They also contain a single pointer to an ability

Custom rule instances contain the same things as objects.

Rules contain a pointer to an abiltiy.

Abilities contain blocks, which can themselves contain abilities.

An explanation of the json’s properties

uuid: String containing the project’s UUID. UUIDs are short strings that uniquely identify each project. They are assigned to a project whenever it is uploaded to Hopscotch’s servers. They are placed at the end of links to projects. Project uuids, by default, are the unix timestamp of the uuid’s creation multiplied by 65536 (2^16) and converted to base 36.

playerVersion: String containing the player version. For example, "2.0.0", or "1.5.15". The Hopscotch webplayer is versioned using semantic versioning. This determines which version of the player is used.

traits: An array containing a list of traits.

What do traits look like?

Traits are the orange variables in the editor, such as x position and name. The contents of the traits array are not necessary.

An exact copy of each trait is in each datum where it is used, and not just referenced to like everything else. I am not sure how the traits list is used, only that the Hopscotch app editor always creates it, and will perfectly recreate it if deleted.

Traits are objects containing the following properties:

HSTraitTypeKey: A number for the trait type.

HSTraitObjectIDKey: A string for the ID of the object that the trait belongs to.

HSTraitObjectParameterTypeKey: A number. This is similar to HSTraitTypeKey. In the player, it is only used to check if it “uses original object”. It is considered to do so if either HSTraitTypeKey is HSBlockType.OriginalObject or if HSTraitObjectParameterKey is HSBlockType.OriginalObject

HSTraitIDKey: A string with a unique id for each trait. It being present causes the player to parse the trait.

description: A string with a description like for blocks.

customObjects: An array containing a list of custom objects.

What do custom objects look like?

Custom objects store information about the custom images in a project.

They are objects with the following properties:

size: an object containing the properties width and height, which are both numbers.

fileName: A string containing the filename of the image.

id: A string containing a unique id that is used to reference this custom image in objects.

updatedDate: A string containing the timestamp that the image was updated. The timestamps here include the timezone even in published projects.

name: A string containing the name of the image. Does not need to be unique. This is the default name of any objects added using this image.

createdDate: A string containing the timestamp that the image was created at.

baseObjectScale: This property seems to be unused in modern versions of Hopscotch. A number that scales every character, but not shapes or text. Defaults to 1 if not present, at least in the player. (Or at least it used to. I have tested it as of 8/11/22 and it seemed to have no effect, in the editor or the player.) As of player 1.5.16, though I have not checked any earlier versions, it is ignored, and instead a value of 0.5 is used for full size shapes (the shapes accesible from the app) and 1 for everything else.

version: A number representing the latest version of the Hopscotch app that this project was saved with. If the version is higher than the app version you are currently using, it will prevent you from entering it. For example, https://c.gethopscotch.com/p/12khixgvdq If the version is less than or equal to 24, when playing it in the app you will not use the webplayer, but instead the old player from before they switched to the webplayer. This obviously is not the case when playing outside the iOS app. Some versions have special behaviour in the player/editor. I will not list the actual behaviours here but version 26 adds object variables while 28 adds custom whens. As of August 2022, the current version is 34.

abilities: An array containing a list of abilities.

What do abilities look like?

Abilities are objects that contain blocks. They are referenced to by rules and some blocks, such as check once if, that contain other blocks.

blocks: An array containing a list of blocks.

abilityID: A string containing a unique id for the ability. It is used to refer to this ability in other places. This is referenced in rules and in blocks with controlScripts.

createdAt: A number that contains the time the ability was created. Used to order custom blocks on the keyboard. This number is the seconds since 1/1/01 at midnight utc with six decimal points.

name: A string containing the name of a custom block. This property is only present on abilities for custom blocks, and if it is here it will add the ability to the keyboard as a custom block. Duplicate names still work. If the value of this is an empty string, it will not show up in the keyboard.

What do blocks look like?

Blocks are objects that are in lists inside of abilities. They are also included in datums inside of parameters, with some slight differences.

block_class: A string representing what kind of block this is. Either "method" for normal blocks, like move forward, set variable, comment, etc., "control" for some blocks with inner blocks, like draw a trail, 'conditionalControl" for check once if and check if else, "conditionalOperator" for conditional operators like =, ≠, <, >, etc., or "operator" for math or string operators. The player does not use this.

type: A number representing the type of the block.

parameters: IF THE BLOCK IS INSIDE OF A DATUM IN A PARAMETER, THE KEY FOR THIS PROPERTY IS ACTUALLY params An array containing a list of parameter for the block.

description: A string containing the name of the block type. Not used to display it or in the player. This property is unnecessary.

controlScript: An object with a single property abilityID which is a string that is the abilityID of the ability that contains the inner blocks. This property is only present on container blocks that have other blocks inside of them.

controlFalseScript: Only present on check if else blocks. (It also exists on check once if blocks but does not do anything) Is identical to controlScript but points to the ability containing the blocks for the else container.

What do parameters look like?

Parameters are an object that are found in the parameters property of blocks.

defaultValue: A string containing the default value of the parameter. You can see it in the editor by pressing backspace on an operator, while value is empty.

value: A string containing the current value of the parameter.

key: A string containing the label for the parameter. This is the only part of blocks that can be customized in the json but not in the app. For this reason it is often used to label blocks which do not otherwise have labels, such as wait til timestamp.

type: A number representing the type of the parameter.

datum: An object. It contains either a trait, an operator block, or an image for set image parameters. It could also contain the property variable, which will be a variable id that it contains. The order the player checks for is: image for set image block, variable, trait/block, or it checks the variable property below.

variable: A string containing an id. The editor only seems to use it in rules to reference eventParameters, but in the player, if datum is falsy, and variable is not, the player will first search for a variable with this id. If it does not find one, it will then check for a trait. If there is no trait with this id either, then it will search for an eventParameter. Once it finds one, it will use it as the value of the bubble.

scenes: An array containing a list of scenes.

What do scenes look like?

Scenes are objects that represent scenes in the project.

objects: An array of strings. Each item is an objectID of an object in the objects array on the top level of the json. These are the objects that are in the scene. If the same object is in multiple scenes, they will each get their own sceneObject in the player, so it will split so that each scene will have an identical, but not the same, object.

name: A string containing the name of the scene.

filename: A string containing the filename of the scene’s preview thumbnail. It is not necessary.

fontSize: A number that scales text. Do note that if it is too big, the text line height will exceed the maximum the player can handle and the text will be cut off in the middle. The default is 80 for projects made on iPads, and 72 on phones.

customRules: An array containing custom rules.

What do custom rules look like?

Custom rules are objects that represent the reusable custom rules in Hopscotch.

id: A string containing a unique id for this custom rule. Also not reused for any regular rules. Referred to in custom rule instances.

abilityID: A string containing the ID of the ability that contains the blocks that are outside of the rules here. As of now, only set variable blocks are accesible to put there in the editor, though any block will work if it is in the ability, and it will run. It is run before any rules, so it is in a way a “before game starts” rule. It only runs the first frame’s worth of code, however.

name: A string containing the name of the custom rule.

parameters: An array containing the parameters of the custom rule. They are basically the same as parameters in blocks when they are called. Their type is 57.

rules: An array of strings, containing the unique ids of the rules or other custom rule instances that are inside the custom rule.

objects: An array containing objects.

What do objects look like?

Hopscotch objects are json objects that represent characters, shapes, text, etc.

width: A string containing the width of the object.

height: A string containing the height of the object.

name: A string containing the object’s name.

resizeScale: A string containing a multiplier to the scale. This is changed by pinching the object in the editor.

filename: Not sure what this does. It is usually “object name.png” (for example, “text-object.png”) and needs to be correct or the editor will not understand it and replace the object with a monkey. Custom images use “image.png”. To find the correct filename for any id, the easiest way is to create a set image block for it, open it in the Hopscotch editor, then check the block’s datum after saving it.

abilityID: A string containing the ID of the ability that contains the blocks that are outside of the rules here. As of now, only set variable blocks are accesible to put there in the editor, though any block will work if it is in the ability, and it will run. It is run before any rules, so it is in a way a “before game starts” rule. It only runs the first frame’s worth of code, however.

rules: An array of strings, with each string being the id of a custom rule instance or a rule that is part of the object’s code.

xPosition: A string containing the x position of the object.

yPosition: A string containing the y position of the object.

objectID: A string containing a unique id for this object that is used to refer to it. It is used in scenes and references to this in variables and eventParameters.

type: A number representing the object type.

text: A string containing the text content of the object. The editor puts it there for every object, even those that are not text objects. It is not necessary.

customObjectID: A string containing the id of the custom object. This is only present on images.

previous_project_uuid: In remixes, this is a string containing the uuid of the project this one was remixed from.

original_user: An object containing information about the user that this project was remixed from. In drafts, this is used for the remix bar. Published projects make it much harder to edit this.

variables: An array containing a list of variables. Does not include local variables.

What do variables look like?

Variables are objects that represent variables in the app.

type: A number containing the type of the variable.

name: A string containing the variable’s name. Duplicate names are fine, since these are not local variables.

objectIdString: A string containing the unique id of the variable used to refer to it.

eventParameters: An array containing a list of event parameters.

What do event parameters look like?

eventParameters are probably the most confusing part of the Hopscotch json format. They are used in events to refer to objects – for example when (self) is tapped, the self is an eventParameter. They have the following properties:

description: A string which describes the type of the eventParameter. It is not necessary.

id: A string that is a unique id for this eventParameter. It is used in rules to point to the specific eventParameter.

blockType: A number containing the type of this event parameter.

objectID: Only used for references to specific objects (blockType 8000), this is a string with the unique object id of the object.

stageSize: An object with two properties: width and height. They are both numbers and determine the dimensions of the stage.

edited_at: A string containing a timestamp of when the project was last edited. This does not include the time øne in published projects.

customRuleInstances: An array containing custom rule instances (Places that custom rules are used)

What do custom rule instances look like?

Custom rule instances are used in objects and other custom rules to actually run the custom rule. In older versions (pre-player 2.0.0) they would just include the custom rule id. They changed this to allow parameters on custom rules.

id: A string containing a unique id for this instance of the custom rule. It is referenced in the rules array in objects and custom rules.

customRuleID: A string containing the id of the custom rule that this is an instance of.

parameters: An array containing a list of parameters.

playerUpgrades: An array containing a list of all the times the player was upgraded. You can upgrade a project’s player version by tapping the … button on the draft and then selecting “uppdate to latest player”. This will update the playerVersion to the latest player version and add a property to this object with the key of the version upgraded from and the value of the version upgraded to. (for example, {"2.0.0":"2.1.1"} would be a playerUpgrades object with a single upgrade from 2.0.0 to 2.1.1)

requires_beta_editor: A boolean that is true if the project has been saved with advanced mode.

rules: An array containing a list of rules.

What do rules look like?

abilityID: A string containing the id of the ability that the rule contains.

id: A string containing a unique id for this rule. Must also be different from all custom rule instances. Is referenced in the rules list in objects and custom rules.

ruleBlockType: A number representing the type of the rule.

objectID: A string. Not sure what this does, if anything. It is often empty.

name: A string. Not used in the player. Often empty. Seems to have no effect in the editor. Unnecessary.

parameters: An array containing a list of parameters with the same format as with blocks.

9 Likes

In many places throughout the Hopscotch project json format, numeric IDs will be used to determine the type of blocks or parameters. Here is a list of these IDs that is up to date as of 8/26/22:

HSBlockType

Blocks, event parameter types, traits, rules

WaitTilTimestamp = 19,

WaitUntilInputIsDone = 20,

None = 22,

Move = 23,

Rotate = 24,

ChangeX = 27,

ChangeY = 28,

Scale = 29,

Clear = 30,

StrokeWidth = 31,

StrokeColor = 32,

ChangeCostume = 33,

ChangeSpeed = 34,

Wait = 35,

SetOpacity = 36,

PenDown = 37,

PenUp = 38,

SetHeading = 39,

SetText = 40,

SetPosition = 41,

SendToBack = 42,

BringToFront = 43,

ChangeVariable = 44,

SetVariable = 45,

MoveWithTrail = 46,

SetInvisibility = 47,

Grow = 48,

Shrink = 49,

Flip = 50,

SetSize = 51,

PlaySound = 52,

MakeAClone = 53,

SetColor = 54,

Destroy = 55,

SetImage = 56,

SetWidthAndHeight = 57,

SetZIndex = 58,

SetOriginXY = 59,

SetCenterXY = 60,

WaitSeconds = 61,

PlaySoundSeconds = 62,

SaveInput = 63,

SetTextToInput = 64,

PlayNote = 65,

SetTempo = 66,

SetInstrument = 67,

OpenProject = 68,

Comment = 69,

SetBackground = 70,

LeaveATrail = 26,

Repeat = 120,

RepeatForever = 121,

CheckOnceIf = 122,

Ability = 123,

CheckIfElse = 124,

ChangeScene = 125,

BroadcastMessage = 126,

RequestSeeds= 127,

Operator blocks, mostly unused in modern editor versions

Random = 233,

XPos = 234,

YPos = 235,

Random110 = 236,

Random1100 = 237,

Random11000 = 238,

Variable = 239,

Conditional operators

ConditionalOperatorEquals = 1000,

ConditionalOperatorNotEquals = 1001,

ConditionalOperatorLessThan = 1002,

ConditionalOperatorGreaterThan = 1003,

ConditionalOperatorAnd = 1004,

ConditionalOperatorOr = 1005,

ConditionalOperatorGreaterThanOrEqualTo = 1006,

ConditionalOperatorLessThanOrEqualTo = 1007,

ConditionalOperatorMatches = 1008,

ConditionalOperatorNot = 1009,

CoditionalOperatorIsFlipped = 1011,

HS_END_OF_CONDITIONAL_OPERATORS = the last conditional operator + 1,

Object traits

TraitRotation = 2000,

TraitXPosition = 2001,

TraitYPosition = 2002,

TraitInvisibility = 2003,

TraitSize = 2004,

TraitSpeed = 2005,

TraitCloneIndex = 2006,

TraitTotalClones = 2007,

TraitWidth = 2008,

TraitHeight = 2009,

TraitZIndex = 2010,

TraitOriginX = 2011,

TraitOriginY = 2012,

TraitCenterX = 2013,

TraitCenterY = 2014,

TraitText = 2015,

TraitTempo = 2016,

TraitInstrument = 2017,

TraitObjectName = 2018,

HS_END_OF_OBJECT_TRAITS = the last object trait + 1,

User traits

TraitUsername = 2500,

TraitTime = 2501,

TraitYear = 2502,

TraitMonth = 2503,

TraitDay = 2504,

TraitHour = 2505,

TraitMinute = 2506,

TraitSecond = 2507,

HS_END_OF_USER_TRAITS the last user trait + 1,

Stage traits

StageTraitWidth = 3000,

StageTraitHeight = 3001,

StageTraitTiltUp = 3002,

StageTraitTiltDown = 3003,

StageTraitTiltLeft = 3004,

StageTraitTiltRight = 3005,

StageTraitLastTouchX = 3006,

StageTraitLastTouchY = 3007,

StageTraitTotalObjects = 3008,

HS_END_OF_STAGE_TRAITS = the last stage trait + 1,

Math operators

MathOperatorAdd = 4000,

MathOperatorSubtract = 4001,

MathOperatorMultiply = 4002,

MathOperatorDivide = 4003,

MathOperatorRandom = 4004,

MathOperatorPower = 4005,

MathOperatorSquareRoot = 4006,

MathOperatorSine = 4007,

MathOperatorCosine = 4008,

MathOperatorRound = 4009,

MathOperatorAbs = 4010,

MathOperatorModulo = 4011,

MathOperatorTangent = 4012,

MathOperatorInverseSine = 4013,

MathOperatorInverseCosine = 4014,

MathOperatorInverseTangent = 4015,

MathOperatorMaximum = 4016,

MathOperatorMinimum = 4017,

MathOperatorFloor = 4018,

MathOperatorCeiling = 4019,

HS_END_OF_MATH_OPERATORS = The last math operator + 1,

Color operators

ColorOperatorRandom = 5000,

ColorOperatorRGB = 5001,

ColorOperatorHSB = 5002,

HS_END_OF_COLOR_OPERATORS = the last color operator + 1,

Rule blocks

Rule = 6000,

RulePreview = 6001,

Event operators

EventOperatorStart = 7000,

EventOperatorTap = 7001,

EventOperatorIsTouching = 7002,

EventOperatorHold = 7003,

EventOperatorTiltRight = 7004,

EventOperatorTiltLeft = 7005,

EventOperatorTiltUp = 7006,

EventOperatorTiltDown = 7007,

EventOperatorLoudNoise = 7008,

EventOperatorShake = 7009,

EventOperatorBump = 7010,

EventOperatorSwipeRight = 7011,

EventOperatorSwipeLeft = 7012,

EventOperatorSwipeUp = 7013,

EventOperatorSwipeDown = 7014,

EventOperatorEnterTheWorld = 7015, when I am cloned

EventOperatorTiltRightEditor = 7016,

EventOperatorTiltLeftEditor = 7017,

EventOperatorTiltUpEditor = 7018,

EventOperatorTiltDownEditor = 7019,

EventOperatorNotPressed = 7020,

EventOperatorGamePlaying = 7021,

EventOperatorTouchEnds = 7022,

EventOperatorHearMessage = 7023,

EventOperatorMessageMatches = 7024,

EventOperatorIsNotTouching = 7025,

HS_END_OF_EVENT_OPERATORS = the last event operator + 1,

Event parameter blocks

Event parameter types and variable types

Object = 8000,

AnyObject = 8001,

ScreenEdge = 8002,

Game = 8003,

Self = 8004,

OriginalObject = 8005,

Local = 8006,

User = 8007,

Product = 8008,

Scoped = 8009,

HS_END_OF_EVENT_PARAMETER_BLOCKS = the last event parameter block + 1,

Text operator blocks

TextOperatorCharAtIndex = 9000,

TextOperatorCharsInRange = 9001,

TextOperatorLength = 9002,

HS_END_OF_TEXT_OPERATOR_BLOCKS = the last text operator block + 1

HSParameterType

Parameter types

Default = 42,

LineWidth = 43,

LineColor = 44,

RandomLow = 45,

RandomHigh = 46,

Variable = 47,

VariableValue = 48,

Conditional = 49,

HSObject = 50,

Sound = 51,

Event = 52,

SetText = 53,

Object = 54,

TextOnly = 55,

Scene = 56,

MultiPurposeNumberDefault = 57,

Product = 58,

Rhythm = 59,

MusicNote = 60,

Instrument = 61

HSObjectType

Objects

monkey = 0,

text = 1,

octopus = 2,

gorilla = 3,

cupcake = 4,

bear = 5,

dino = 6,

frog = 7,

greenman = 8, Jody

mustache = 9,

spacepod = 10,

Halloween

zombieBear = 11,

ghoulopus = 12,

bats = 13,

frankenrilla = 014,

jodyWitch = 15,

cauldron = 16,

pumpkin = 17,

broom = 18,

lantern = 19,

Jungle

parrotFlying = 20,

mandrill = 21,

mosquito = 22,

missChief = 23,

venus = 24,

jeepers = 25,

banyan = 26,

More characters

stargirl = 27,

astro = 28, Cody

chillanna = 29,

robo = 30,

raccoon = 31,

bird = 32,

HS_END_OF_CHARACTERS = 33,

Shapes. Not used in modern editors

square = 34,

circle = 35,

hexagon = 36,

triangle = 37,

rightTriangle = 38,

rectangle = 39,

heart = 40,

star = 41,

arch = 42,

parallelogram = 43,

squiggle = 44,

donut = 45,

tetrisZ = 46,

tetrisT = 47,

tetrisL = 48,

corner = 49,

flower = 50,

threeProngedBoomerang = 51,

squishedBox = 52,

bead = 53,

chevron = 54,

xShape = 55,

tetrisLine = 56,

HS_END_OF_SHAPES = 57,

More characters

toucan = 58,

anteater = 59,

crocodile = 60,

sloth = 61,

iguana = 62,

hut = 63,

Winter

penguin = 64,

winterQueen = 65,

shyYeti = 66,

deer = 67,

elf = 68,

snowGlobe = 69,

polarbear = 70,

sleigh = 71,

mistletoe = 72,

snowMan = 73,

snowflake = 74,

Full size shapes. Some used in modern editors some not.

roundedSquareFullSize = 100,

squareFullSize = 101,

circleFullSize = 102,

hexagonFullSize = 103,

triangleFullSize = 104,

rightTriangleFullSize = 105,

rectangleFullSize = 106,

heartFullSize = 107,

starFullSize = 108,

archFullSize = 109,

parallelogramTallFullSize = 110,

squiggleFullSize = 111,

donutFullSize = 112,

tetrisZFullSize = 113,

tetrisTFullSize = 114,

tetrisLFullSize = 115,

cornerFullSize = 116,

flowerFullSize = 117,

fanbladeFullSize = 118,

squishedBoxFullSize = 119,

roundedRightTriangleFullSize = 120,

arrowRoundedFullSize = 121,

beadFullSize = 122,

parallelogramWideFullSize = 123,

chevronFullSize = 124,

xFullSize = 125,

tetrisLineFullSize = 126,

V3 shapes. These are used in modern editors.

hexagonV3 = 150,

triangleV3 = 151,

rectangleV3 = 152,

heartV3 = 153,

starV3 = 154,

archV3 = 155,

squiggleV3 = 156,

tetrisZV3 = 157,

tetrisTV3 = 158,

tetrisLV3 = 159,

fanbladeV3 = 160,

arrowRoundedV3 = 161,

beadV3 = 162,

parallelogramWideV3 = 163,

chevronV3 = 164,

HS_END_OF_FULL_SIZE_SHAPES = the last v3 shape + 1,

Other

HS_NUMBER_OF_OBJECTS = HS_END_OF_FULL_SIZE_SHAPES + 1,

image = 2000,

HS_START_OF_CHARACTERS2 = 3000,

crocodileJaws = 3001, Modern crocodile

lanternFullSize = 3002, Modern lantern

HS_END_OF_CHARACTERS2 = 3003,

nil = 10000,

edgeOfScreen = 30000

10 Likes

Great writeup! I’ll need to use this as a reference. :)

5 Likes

Nice! And if you ever want a quick JSON of updated object types, parameter types, and blocks in the webplayer, you can pull that straight from the HS Tools API at this URL

6 Likes

This is a great and comprehensive guide which I’ve wanted for a long time because I’ve thought about exploring JSON modding for a long time now. Thanks for making this!

2 Likes

Imagine copying it and you find a link