JSON Reference
Below is a full reference of the JSON files in Open Hexagon, including pack, level, style, and music metadata. JSONs are metadata files in Open Hexagon that help give information about different assets or provide data about various different levels and packs. JSONs are preloaded into the Open Hexagon engine and unlike Lua files, they do not update upon saving. To be able to update JSON assets in-game, you will need to press F5 in Debug Mode to perform an asset refresh on an individual level, which will only work if the "id" attribute matches the file name.
These are attributes to help tell the Open Hexagon engine what the JSON is and what it is about.
"id": <string>: The unique ID that corresponds to this JSON and helps give the file identity. It is a conventional standard to make the id the same name as the file name without the extension. This is a required attribute and must be provided in all JSON files!
Pack JSONs are what help define packs altogether and help pack developers keep their levels grouped into one place. Pack JSONs are also used to import dependencies. You will also see that pack JSONs are also called Pack Objects, as that terminology will be useful for dependencies.
"disambiguator": <string>: A string attribute that makes sure that your pack will not conflict with other packs that may have the same name. Make sure to get creative and original with these, as you don't want somebody else to have this.
"name": <string>: The name of your Open Hexagon pack.
"author": <string>: The author who created this pack. Be sure to jot your name down, along with any contributors who may have involvement in working on your pack levels.
"version": <int>: The current version of the pack. Not practical for actual packs, but does have importance for dependencies. Just keep this at 1 if you don't know how to fill this out.
"priority": <float>: Gives a priority value to this pack. Like with level priorities, Open Hexagon sorts packs on minimum priority, so lower values go earlier in the list. This attribute may be removed in a future version of Open Hexagon.
"dependencies": <JSON array of modified pack objects>: Any libraries or other packs will be imported if their pack object is specified in this array. Dependencies use modified pack objects because they replace the "version" attribute with a "min_version" attribute, which is useful to ensure version checking and that the dependency has all of the necessary scripts and functions needed to make the pack function as intended.
Level JSONs give the essentials of what makes a level selectable and playable. It takes other assets and links them together to create the level. Without these, you can't play any levels in a pack. Each attribute in a level JSON is crucial and you can't have a level without them. This gives a complete reference to how level JSONs work. Level JSONs use camel case for their naming convention.
These are basic descriptors that help give the player information about your level.
"name": <string>: The name of the level. You can have your JSON id match up to this if you want to, but it's not required.
"description": <string>: The description that you will put in to help describe your level. For a description, you can put in something whimsical if you want to if it helps establish a theme for your pack. However, it is also a good idea to use the description to describe any specific mechanics pertaining to the level and how to utilize them, so users know how the level works.
"author": <string>: The name of the person who made the level. You'll want to jot down your name here because I'm hoping that you are the one who made the level (Don't be a plagiarist!).
These are properties that don't necessarily describe the level to the user, but it tells Open Hexagon how to manage your level.
"menuPriority": <int>: An integer that gives a priority value for the level. Levels in Open Hexagon are organized by minimum priority, meaning lower values get placed earlier in their pack.
"selectable": <boolean>: A boolean that determines whether the level can be selected and played from the menu. For the most part, you want to set this to true. This attribute is currently broken at the moment. I gave a fix, but Vee won't accept it angery
"difficultyMults": <JSON array of floats>: A JSON array that contains different difficulty multipliers for the level. Values greater than 1 indicate a harder difficulty for more experienced players to play on, while a value less than 1 would indicate an easier difficulty for novice players. Adding 1 to the table is not needed, because 1 is already added by default to every level.
These are attributes that will reference other JSON ids and files to link the level together and create it.
"styleId": <string>: The JSON id that refers to a style the level will have. The corresponding style will show up in the menu and in the level until the style is changed through Lua.
"musicId": <string>: The JSON id that refers to the music the level will have. The music metadata from the JSON is applied to the menu and the music file in the JSON will play when the level starts.
"luaFile": <string>: The file path to a Lua file. This will give the level its logic and functionality. The starting directory for the file path is the pack folder itself, but by convention, it is a good idea to have a Scripts folder to contain all of your Lua scripts and a sub-directory for scripts to all of the levels. Most of the time, you will see Scripts/Levels/<level_name>.lua in this field.
Styles are what give levels their appearances, from the background panels all the way to wall color and even text. Colors are done either through dynamic colors, which rely on a hue cycle to display colors, to a static RGBA color that can pulse by an offset. However, you can also configure things like the skew or other 3D aspects through a style. Anything that has to do with appearance, you will use a style for. Style JSONs use snake case for their naming convention.
This gives a complete reference to how styles work and how they are parsed. Courtesy of Syyrion for originally writing this reference. Rewritten to work for markdown and additional style attributes by Synth Morxemplum.
These are attributes that directly involve setting the boundaries of the hue and how they work. By changing these settings, you are directing affecting all dynamic colors in the style. The range that hue can go is from 0-360. Any boundaries out of this range will have a lingering red.
"hue_min": <float>: The minimum hue value. 0 is equivalent to 360 in terms of color. When starting a level or changing styles, the hue value is reset to this value.
Default Value: 0
"hue_max": <float>: The maximum hue value. 0 is equivalent to 360 in terms of color. Must be greater than "hue_min". If not, the hue value gets stuck at "hue_min" if "hue_increment" >= 0 or "hue_max" if "hue_increment" < 0.
Default Value: 360
"hue_ping_pong": <boolean>: Does the hue cycle, or go back and forth? When graphed, does the hue follow a sawtooth pattern or triangle pattern?
Sawtooth: false Triangle: true
| /| /| / | /\ /
| / | / | / | / \ /
| / |/ |/ | / \/
+-------------- +------------
Default Value: false
"hue_increment": <float>: Amount to increment/decrement the hue value each frame.
Default Value: 0
Not to be confused with the level pulse, these attributes affect how objects with "color" fields are controlled by their associated "pulse" fields. Pulse always ping pongs in a triangle pattern.
"pulse_min": <float>: The minimum pulse value. When starting a level or changing styles, the hue value is reset to this value.
Default Value: 0
"pulse_max": <float>: The maximum pulse value. Must be greater than "pulse_min". If not, the pulse value changes erratically.
Default Value: 0
"pulse_increment": <float>: Amount to increment/decrement the pulse value each frame.
Default Value: 0
Here are some other miscellaneous basic style attributes that don't belong in other attributes.
"max_swap_time": <float>: The panel color swap time. Represents the length of one period in frames (i.e. setting it to 60 will swap the panels every 0.5 seconds (assuming 60 fps)). Set to 0 or less to disable.
Default Value: 100
These attributes, signaled by the "3D_" prefix, are directly involved in altering all of the 3D attributes in the game. Since the graphics engine doesn't render true 3D, these are considered the Pseudo-3D effects.
"3D_depth": <int>: How many layers to make and render. Must be a positive integer.
Default Value: 15
"3D_skew": <float>: The skew intensity, which directly involves the viewing angle. Higher values will result in lower viewing angles. This number is multiplied to the actual 3D skew value.
Default Value: 0.18
"3D_pulse_min": <float>: The minimum value for the skew. Values below 0 result in stretching the polygon vertically and render layers in the opposite direction.
Default Value: 0
"3D_pulse_max": <float>: The maximum value for the skew. Higher values result in lower viewing angles. Must be greater than "3D_pulse_min". If not, the skew gets stuck at "3D_pulse_min" if "3D_pulse_speed" >= 0 or "3D_pulse_max" if "3D_pulse_speed" < 0.
Default Value: 3.2
"3D_pulse_speed": <float>: Amount to increment/decrement the skew each frame.
Default Value: 0.01
"3D_spacing": <float>: The amount of spacing between layers.
Default Value: 1.0
"3D_perspective_multiplier": <float>: The multiplier for layer spacing. Directly affects "3D_spacing".
Default Value: 1.0
"3D_darken_multiplier": <float>: Modifies how dark the 3D layers are. Non-positive values evaluate to black. Values between 0 and 1 have unknown behavior. A value of 1 introduces no darkness. A color gets darker through an inverse relationship the higher the value.
Default Value: 1.5
"3D_alpha_multiplier": <float>: Modifies the alpha of the 3D layers. Positive integers only >= 1. The higher the number goes, the more transparent the layers get with an inverse relationship.
Default Value: 0.5
"3D_alpha_falloff": <float>: Modifies the alpha of the 3D layers, becoming increasingly transparent for each consecutive layer. Negative values decrease transparency instead. When overflow occurs, the pattern repeats.
Default Value: 3
"3D_override_color": <tuple (int, int, int, int)> (Optional): The 3D layers no longer focus on the main color and instead focus on this RGBA value. Unlike other color objects, this doesn't support a pulse or dynamic colors.
This section goes over all of the attributes of the color object. Colors are their own object in JSON and have their own specific set of attributes. However, for certain attributes that may use color objects, there may be more or fewer attributes of the color object. Any exceptions will be noted in the attribute when necessary.
"dynamic": <boolean>: Determines whether color is affected by hue options. If true, the "value" tag is ignored. However the "pulse" tag is not, so color can be affected by hue and pulse at the same time.
Default Value: false
"dynamic_darkness": <float>: Modifies the darkness of the color if "dynamic" is set to true. This tag is ignored if "dynamic" is false. This value exhibits similar behavior to "3D_darken_multiplier".
Default Value: 1.0
"dynamic_offset": <boolean>: Enables dynamic offset. This tag is ignored if "dynamic" is false. It is discouraged to use this attribute because its behavior is undefined and unpredictable.
Default Value: false
"offset": <float>: "dynamic_offset" value. This tag is ignored if "dynamic" is false. It is discouraged to use this attribute because it's behavior is undefined and unpredictable.
Default Value: 0
"hue_shift": <float>: How much the dynamic color is offset from the global hue pulse value. This tag is ignored if "dynamic" is false. Like with "hue_min" and "hue_max", keep the values between 0 and 360.
Default Value: 0
"value": <tuple (int, int, int, int)>: The per-channel RGBA values on static colors. Accepts integers only between 0 and 255. Any values outside this range are clamped.
Default Value: [0, 0, 0, 0] (Black Transparent)
"pulse": <tuple (int, int, int, int)>: The per-channel RGBA pulse factors. Each value is first multiplied by the current pulse value, then added to the respective value channel. Accepts integers from -255 to 255. Any values outside this range are clamped.
Default Value: [0, 0, 0, 0] (No Pulse)
These are the color attributes for the style. These tend to be the most focused on attributes for a style, as they make up for the colors you see in a level. Most of these attributes take in color objects, which is documented in the previous section.
"main": <color object>: The main color of the style. This will affect the color of standard walls, the polygon outline, the text color, and the player color. This is a required attribute and must be provided!
"cap_color": <multiple acceptable parameters> (Optional): This allows to configure the color of the cap (the part that fills the center polygon). There are multiple formats that can be accepted for this.
-
"cap_color": "main": When the string "main" is offered, the cap color will follow the exact same color as the"main"attribute, making it look like there is no cap at all. -
"cap_color": "main_darkened": When the string "main_darkened" is offered, the cap color will be based on the"main"attribute, but will be slightly darker than the actual main color. This is based on the first rediscovered builds of Open Hexagon 2.x. -
"cap_color": {"legacy": true, "index": 0}: When this is offered, the cap color will base its color on the first background panel, similar to how cap color is done in Open Hexagon Legacy (1.92). Changing the"index"field will change which background panel to reference color from. This is the fallback value for cap color if the cap color field is not given. -
"cap_color": { "legacy": false, <color object attributes>}: When this is offered, cap color will then start to accept color object attributes and can be fully customizable to the pack developer's liking.
"player_color": <color object> (Optional): Overrides the player color with the use of a color object.
Default Value: The color of "main".
"text_color": <color object> (Optional, but highly recommended): Overrides the text on the screen with the use of a color object. It is highly recommended to fill out this attribute, as it helps resolve visibility issues with a transparent "main" and also makes sure that your level is legible on the level selection menu.
Default Value: The color of "main".
"wall_color": <color object> (Optional): Overrides the color of the walls with a custom color object. Useful to recolor walls without the need for custom walls.
"colors": <JSON array of color objects>: Supplies the colors for the background panels in sequential order. The pattern repeats once the end of the list is reached. If there are more colors than sides, the leftover colors are discarded. This is a required attribute and must be provided!
Music JSONs work quite similarly to level JSONs: they link a music asset to the game. Music JSONs also give metadata about the track they are linked to and also give some properties on how they work in Open Hexagon. Music files must be in the OGG Vorbis format. Music may be subject to copyright. Please be sure that you are using music with the artist's permission or have the music licensed.
Some basic descriptors for the music information. In addition, it also helps link the JSON to an audio file.
"name": <string>: The name of the song that you are using for the level.
"author": <string>: The name of the artist or group that created the song.
"album": <string> (Optional): The album that the music comes from. This used to be a requirement for music JSONs in Open Hexagon Legacy, but it is now completely optional.
"file_name": <string>: The name of the audio file that contains the song (with the file extension). It is by convention that your music file has the name same as the JSON id.
This briefly goes over the timestamp JSON object, which is used to give timestamps on the music file.
"time": <float>: Refers to a specific time in the audio file in seconds.
This goes over some other properties that the music JSON has and how it affects the game.
"segments": <JSON array of Timestamp Objects>: The different possible segments where the music can start playing from. When a level session begins, it will always pick the first timestamp in the array. Any other attempt will pick a segment at random.
