Making Your First Level Pack
This document will guide you through the process of making and uploading a level to the Steam Workshop.
Open Hexagon uses Lua as the main scripting language for custom levels, alongside JSON for level metadata and configuration files.
It is recommended to be somewhat familiar with both languages before diving into Open Hexagon content creation, but if you're feeling brave and have previous programming experience you can just try to "wing it" by modifying existing levels and learning on the fly. A quick and fun way of learning the syntax of the above languages is the "Learn X in Y minutes" website:
Check out the Lua Reference page for all the Lua functions you can use in the game. In addition, check out the JSON Reference page to know all of the attributes for the different types of JSONs in the game.
Open Hexagon custom content is organized in the following hierarchy:
-
Level Pack (folder)
-
pack.json(main JSON metadata file) -
Levels (folder containing level JSON metadata files)
mylevel.json
-
Music (folder containing music
.oggand JSON metadata files)mysong.oggmysong.json
-
Scripts (folder containing
.luascripts)mylevel.lua
-
Styles (folder containing visual style JSON metadata files)
mystyle.json
-
Therefore, the main unit of work that can be published and installed is a pack. Inside a pack, you can have an arbitrary number of levels, musics, scripts, and styles. A completed level requires a level .json metadata file, music .ogg file, music .json metadata file, level .lua script, and a style .json file. All the separate files are linked together by linking attributes, specified in the level .json metadata files.
The easiest way to get started is to subscribe to the "Example Workshop Level
" on the Steam Workshop, navigate to its contents (usually C:/Program Files (x86)/Steam/steamapps/workshop/content/1358090/2157745755), and copy-paste that folder into your Open Hexagon/Packs/ folder1.
After that, rename the pasted 2157745755 to something else (e.g. MyFirstPack), and start exploring its contents with your favorite text editor (personally, I use Visual Studio Code).
Delete the Example Workshop Level.workshop.json file (as it will be generated automatically when you upload your pack to the workshop), and the preview image .png file, as you will provide one yourself later.
Start by taking a look at pack.json - there are multiple fields to change. Note that Open Hexagon expects every single level pack to have a unique id - therefore, to minimize the chance of collisions between packs made by different authors, you should specify a sufficiently unique "disambiguator" that is very unlikely someone else might accidentally use. Such field will not be displayed in game, so it can be completely arbitrary. You should fill out the rest of the pack JSON with the information you like. All available attributes for the pack JSON can be found here.
After that, you should explore the other folders and see how things work. The .json and .lua files are commented, so you should have enough context to figure out how things are linked together and what role they play.
The level logic is stored in Scripts/Levels/examplelevel.lua. Please refer to the Lua Reference to figure out what the used functions do, and to discover new functions to play around with. You will notice a bunch of u_execScript and u_execDependencyScript calls at the top of the Lua file - these are other scripts that the level script depends on. Dependencies should always be provided as part of your pack folder2.
Now it's up to you! Explore the dependencies, experiment with the code, add your own music3, and - when you're satisfied - share your pack on the workshop and ask for feedback from other players, in order to perfect it. Keep in mind that you can join our official Discord before or during level development to ask for help and share your ideas - see Where to get Help for more information.
The current recommended way of uploading your level to the Steam Workshop is to use the provided OHWorkshopUploader.exe command-line tool available in your Open Hexagon folder4.
When running the tool, you'll see a few options:
Enter one of the following options:
0. Create a new workshop item.
1. Upload contents of an existing workshop item.
2. Set preview image of an existing workshop item.
3. Exit
If you intend to upload a brand new level, then write 0 and press enter. On success, the program will give you back a workshop item id:
Successfully created new workshop item: 2165863494.
Copy that id to your clipboard as you're going to need it for later. Once you have finished creating and testing your custom level, you should have a folder under Packs/ containing all its data. To upload it, write 1 and press enter. You will be prompted to enter the workshop item id you want to upload data to - you should now paste the id you previously copied5.
You will then be prompted to enter the path to the folder containing the data. Please insert an absolute path to the pack folder (e.g. C:/MySteamLibrary/common/Open Hexagon/Packs/MyFirstPack) and keep following the instructions on screen. Your data should now be uploaded to the workshop.
Finally, you can write 2 and press enter to add a preview image to your workshop item. A 620x620 .png image is recommended for this task - you will need to provide an absolute path to the image similarly to what you have done in the previous step.
1: If you are not sure where Open Hexagon is installed, you can navigate to the folder by right-clicking on Open Hexagon in your Steam library, selecting "Properties", going to the "Local Files" tab, and then clicking on the "Browse Local Files" button.↩︎
2: It is possible that in the future I will implement a solution to share dependencies between different packs, but that is not available yet and it is not a priority. For now, think of a level pack as a standalone self-contained entity.↩︎
3: Please ensure that the music files you upload to the Steam Workshop are not protected by copyright laws. If they are, you should get explicit permission from the copyright owner for them to be used as a custom Open Hexagon level, and always credit the original artists as part of your workshop item description.↩︎
4: If you are not sure where Open Hexagon is installed, you can navigate to the folder by right-clicking on Open Hexagon in your Steam library, selecting "Properties", going to the "Local Files" tab, and then clicking on the "Browse Local Files" button.↩︎
5: Or any existing id for a workshop item you own, if you intend to update it rather than creating a new one. If you need to get the ID for an existing pack you want to update, you can always extract it from the URL by visiting your pack on the Steam Workshop and taking the digits at the end of the URL.↩︎
