Welcome Pocketeers and Tinkerers!

Shovel Knight Pocket Dungeon’s Early Preview for the Paradox Pack has been out on Steam for a few weeks now, and we’ve had a lot of great feedback from the community! We’ve been seeing some great ideas and progress posted in

We’ve also seen some requests for a start guide for those who might not be as well versed in coding or game development, and who best to explain the process but one of the gameplay programmers themselves! So on that note, we are happy to introduce you to Cruise Elroy!

If you would like to check out any of his work, check out his itch.io! 

Need help getting started with making mods? You’ve come to the right place! This guide will walk you through the basics of creating mods for Shovel Knight Pocket Dungeon.

Shovel Knight Pocket Dungeon is like a treasure chest filled with modding possibilities – from tweaking playable characters and boss battles to messing around with relics and stages. But today, we're keeping it simple. Our goal? Teaching you how to create a new enemy unit! Enemies cover most of the fundamentals you’ll need to know for mod-making, so once you’re ready to work some more modding magic on other things, be sure to check out the full documentation here for all the possibilities.

Assets will be provided to follow along with, so art skills aren’t necessary for this guide! The final example mod will also be available for download at the end of this guide for you to cross-reference.

Downloading GMEdit

You can download GMEdit here. GMEdit was created by Vadym "YellowAfterlife" Diachenko, one of the other programmers on Pocket Dungeon, and is available as “Name Your Own Price”. So pay what you can to support him, but you can always click the “No thanks, just take me to the downloads” link if you can’t spare the extra gems right now.

You’ll also want to download the GML dialect for Shovel Knight Pocket Dungeon! A GML dialect essentially contains data for how GMEdit should highlight its syntax, and it will help with understanding how mod functions ought to be used.

If you are on Mac, your computer may block you from opening GMEdit and you may need to take a few extra steps to be able to open the program. After you’ve downloaded GMEdit, unpack and run it. If your Mac blocks the program and shows you this warning, click cancel and proceed to the next step

To get around this error, navigate to:
System Settings > Privacy and Security

In the Security sub-menu, select “App Store and identified developers”. Below that, you’ll see a notification that GMEdit was blocked from running. Select to run the application and confirm the approval: 

To install Pocket Dungeon’s GML Dialect, follow these instructions

1. Download both GMEdit and Pocket Dungeon’s GML dialect.

2. Open GMEdit once the download is complete, then open the menu and select Preferences. 

3. Navigate to Other useful things at the very bottom, then click on “GML dialects directory”. 

4. Copy and paste the “skpd” folder from the GML dialect download directly into the window that pops up.

5. After this, go back to GMEdit, click on “Reload GMEdit” just below the “GML dialects directory”, and GMEdit is now ready to be used!

Locating the Mods Folder

Mods are stored in two different locations, depending on if you saved the mod locally, or if you subscribed to it on the Steam Workshop. Local mods are saved in the mods sub-directory, right next to your save data. 

Personal Location

On Windows: 

\AppData\Roaming\Yacht Club Games\Shovel Knight Pocket Dungeon\{steamID}\mods

On Mac: 

/Library/Application Support/Yacht Club Games/Shovel Knight Pocket Dungeon/{steamID}/mods

{steamID} is the ID of your Steam account.  It will be a folder named as a long string of numbers

Steam Workshop Location 

Mods you have subscribed to via Steam Workshop are located in the Steamapps directory. This location will only appear after you’ve subscribed to a Workshop item. 

On Windows: 

\Program Files (x86)\Steam\steamapps\workshop\content\1184760

On Mac: 

/Library/Application Support/Steam/steamapps/workshop/content/1184760

(Note: If your Steam library isn’t installed in this default location, you can do a search for the Shovel Knight Pocket Dungeon App ID (1184760) to locate it.)

It’s recommended to create new mods locally before uploading them to the Steam Workshop, so that’s what we’ll be doing in this guide!

Creating a New Mod

To create a new mod, navigate to your local mods folder and create a new folder inside of it. The name of the folder doesn’t matter, as long as it doesn’t share a name with another mod’s folder. We’ll be naming this folder example_mod for this guide!

Once you create a new folder, next step is to create the file that will contain the basic information about the mod. Open the folder you just made, and create a new text file by right-clicking in the folder and going to New > Text Document . Name this file mod_info.ini. Be sure to include the .ini extension! When you change the extension on a file, a warning pop-up may come up saying that this could harm this file - in this case, it’s safe to click “Yes” and change the extension.

New Coder Tip! Secretly Plain Text Files

Sometimes files used in programs are actually plain text files with the .txt extension changed to something else! In the case of Pocket Dungeon Mod files, .ini and .gml files are plain text.

This means you can use basic text editor programs, such as Notepad (which is installed with every copy of Windows) or TextEdit (which is installed with every copy of MacOS) to open and edit them! Fancier tools such as GMEdit can make it easier to view and edit files like these that are used in coding.

New Coder Tip! Seeing extensions

If you can’t see the extension like .txt, .ini, or .gml after a filename, you can turn that on in File Explorer (Windows) or Finder (Mac) - which is the window you use to navigate files on your computer. You’ll need to do this to change the file from a .txt file to a .ini file.

Windows 10: Click on the arrow on top of File Explorer, and click View. Click the Checkbox that says “File name extensions”

Windows 11: Click on View, and hover over “Show > “, then select the option called “File Name Extensions”.

Mac: choose Finder > Settings, then click Advanced. Select or deselect “Show all filename extensions.”

Next, we need to add the information to the mod_info.ini file for the basic info on your new Mod. What information, exactly? That’s what we’ll be filling out! Open mod_info.ini with GMEdit or your text editor of choice and copy this block of code:

[general]
url="1875062006" // in case you want to update an item that is already uploaded to Steam Workshop (instead of creating a new one), provide a link to it here. Include only the id part of the link. You can only update an item if you are its author. Delete this line for a new item.
name="Mod Name" // 20 characters max (remaining will get cropped)
description="Mod Description" // no limit here :)
major_version="1" // the versions are automatically added together, e.g. "v1.0"
minor_version="0" // minor version is automatically increased by 1 when you push a mod update, e.g. "v1.0" -> "v.1.1"
icon="mod_icon.png" // .png image, your mod’s icon. Dimensions should be square.
[tags] // mark features your mod uses as "1" to apply corresponding Steam tags to your item:
units="0"
stages="0"
bosses="0"
prefabs="0"
relics="0"
quandaries="0"
modifiers="0"
items="0"
traps="0"

Every line in this block of code is used to define the mod’s information, such as its name, version number, icon, and relevant tags. Remove the url tag since we won’t be covering uploading to the Steam Workshop in this guide.

New Coder Tip! Comments in Code are Important

Coding languages have dedicated symbols for comments. These comments are useful for other developers to figure out what your code is doing, or make notes if you need to come back to something. In the case of Mod Support, any text after two forward slashes  // means it’s a coAll comment to tell you how this tag is used. No one will see these comments unless they open up your files in a text editing program.

For example what’s easier to figure out at a glance in this JavaScript:

var today = new Date(); var dd = String(today.getDate()).padStart(2, '0'); var mm = String(today.getMonth() + 1).padStart(2, '0');
var yyyy = today.getFullYear(); 

today = mm + '/' + dd + '/' + yyyy; document.write(today);

Or

//This code will display text that tells you what today's date is
var today = new Date(); var dd = String(today.getDate()).padStart(2, '0'); var mm = String(today.getMonth() + 1).padStart(2, '0');  //Use 0 for January is 0! February is 1, etc.

//These lines will format the date in the way you want it to look
var yyyy = today.getFullYear(); today = mm + '/' + dd + '/' + yyyy; document.write(today);

 So pay attention to the comments we’ve left for you in the templates!

This folder and information file are all that’s required to create a new mod! To see if this mod was created successfully, save any changes you’ve made to mod_info.ini and run Shovel Knight Pocket Dungeon. Navigate to the “mod support” option on the main menu to open the list of installed mods. (Note that you will have to clear the tutorial for this option to become available).

If the mod’s information was defined successfully, you should see a mod with the name “Mod Name” (or whatever was defined for name) on the list when you go to Mod Support in the game! New mods are enabled by default, but if your mod is disabled, press the action button to open the options for the selected mod, then press action again to enable/disable it.

Modifying Units

Defining Unit Info

Now that we have a mod created, let’s add some new content to it!

There are two ways to define units (and most of the other moddable elements): one is to modify a unit that already exists, and one is to create a new unit from scratch. Both will be covered in this guide, but we’ll start by modifying one of the more common units in the game, the Beeto.

To create a modded unit, make a new folder in the same directory as the mod_info.ini file. Unlike the name of the mod folder itself, folders within this folder do require certain names applied to them. In this case, any folder containing information for a unit must start with “unit_”. Anything after this prefix doesn’t matter, though. We’ll create a new folder called unit_beeto to store our modified Beeto’s information in.

In a unit’s folder, it is also required to have a file named unit.gml inside of it. This will contain all of the necessary information a unit needs to be defined. With this file created, we’re ready to enter our first lines of code!

Opening .gml Files

If you have GMEdit downloaded, we can open the mod project with GMEdit now to help with highlighting proper syntax.

There are a few ways to open up the mod in GMEdit, one way is to drag and drop the INI file into GMEdit. Otherwise you can use the methods below on Windows/Mac to open and associate the INI files with GMEdit.

Once you open the INI file in GMEdit, you should see mod_info.ini on the left-hand side of the window, along with any other folders/items within the mod folder. For example, opening unit_beeto should show us unit.gml inside of it! Double-click unit.gml to open it in a new tab.

If you don’t have GMEdit downloaded, you can open unit.gml with your preferred text editor of choice and write your code that way. Just be sure to double-check that everything is correct!

New Coder Tip! GMEdit vs Notepad

You can use a normal text editor to open these files, such as Notepad (which is installed with every copy of Windows) or TextEdit (which installed with every copy of MacOS) to open and edit them! Just right click the file and go to “Open With” and select “Notepad”.

Tools such as GMEdit can also open and edit these files, but they have the advantage of color coding parts of the text to make it easier to tell what is what. For example - here’s the same file, opened in GMEdit, and in Notepad:

All text programs that can read and highlight code will color things differently, but by default GMEdit with the special Pocket Dungeon GML Dialect installed will color the code like this:

• Purple Text = Don’t change or remove these! These sections are important for the game to read the INI file.

• Green = Tags - Don’t change these unless you’re told to or you know what you’re doing! Tags you won’t need can be removed entirely, though.

• White = Text you can edit. Don’t forget the “quotes” around the text!

Modifying Beeto

Here’s the first line of code you’ll want to write in unit.gml:

unit_id = "beeto";

The variable unit_id is used to define the unique identifier for this unit. Every unit in the game has a unique identifier, and the names are case sensitive. A full list of identifiers can be found in the documentation here. If this variable is set to anything already in the list, it will modify that unit. Otherwise, it will be treated as a new unit (more on this later!). Beeto’s ID is simply ”beeto”, so that’s what we’ll set unit_id to in order to modify the information for Beetos.

As a small example, if we wanted all Beetos to have 4 HP instead of 2, we can add this line of code:

hp = 4;

Save the file and re-run Shovel Knight Pocket Dungeon. If done correctly, all Beetos will now have 4 HP. Huzzah!

Beeto now has 4 HP rather than 2!

Adding Custom Sprites

Let’s add some custom sprites to our Beeto to differentiate it from the original! To add sprites to your mod, all sprites related to a specific modified item must be in its folder.

Sprites are contained within sprite sheets - an image with a single row of every frame of animation that the sprite uses. This means that, for your sprite sheet’s width, in pixels, it should be the width of each frame multiplied by how many frames the sprite has. (For example, a 96x96 sprite with four frames of animation should have a sprite sheet the size of 384x96.)

Each sprite has its origin at 48, 64, meaning the sprite will have its point of rotation at the 48th pixel horizontally and 64th pixel vertically. While these sprite sheets can be of any size, the origin point cannot be modified (unless you’re using the sprite_add function), so we recommend keeping it to 96x96 pixels per frame for regular units (or 192x192 pixels for big units). These files must be exported with a .png extension.

For this example, we’ll be giving our Beeto big googly eyes. You can make your own sprite sheet if you’d like, but an example sheet is available to download here.

Notice how this sprite sheet is filled with a bright green? When making your own sprites, this color can be anything, but the color chosen here is important - whichever color occupies the pixel in the bottom left of the image will be treated as the “transparent” color. If you’re making a sprite that occupies the corners of the image, make sure you have enough room to put a transparent pixel in the bottom left, or else the sprite will display incorrectly in the game!

Save the Beeto’s replacement sprite sheet with the file name “beeto.png” in the same directory as unit.gml. The folder should now look like this:

Open unit.gml again and add this line of code:

sprite_idle = "beeto.png";

The variable sprite_idle is used to define a unit’s default sprite. Some units make use of multiple sprites, but most will only need to use their idle sprite. You can read more about all the types of sprite units can use here.

The string specified for sprite_idle is the file name of the sprite sheet that will be used. The name of the file can be anything as long as it matches the name of a file in the unit’s folder.

(Tip: you can also store sprites in subfolders within a unit’s folder! For example, if you have a folder named sprites that contains beeto.png within it, you can reference this sprite with the string ”sprites/beeto.png”.)

Adding Custom Portraits

We’ve defined a custom sprite for the unit’s in-game sprite, but what about its portrait? A unit’s portrait can be seen when a unit is attacked or otherwise interacted with, so we’d like to update it for our mod too!

Portraits work differently from animated sprites - unlike sprite sheets, which can be at any given size, a portrait’s sheet must be at a size of 160x160 pixels per frame. Each frame for a portrait is drawn on top of each other in layers, from left to right for the bottom to top layers, respectively. These layers are what give the portraits their bouncy animations in-game. By default, portraits have 6 layers to work with, so the size of the portrait’s sheet will usually be 960x160 pixels, but you can change how many layers are drawn by using variables such as portrait_idle_frames.

(Tip: every sprite can have its amount of frames changed in a similar way! The documentation tells you what variables to use for certain sprites, as well as their default values.)

Every unit has an “idle” and “hurt” portrait that gets drawn during gameplay, but playable characters and bosses also have a “win” portrait that may be drawn sometimes. Beetos are not playable characters or bosses though, so we’ll only need an idle and hurt portrait! Again, you can download ready-to-implement assets here.

We’ll save the idle and hurt portraits as “beeto_portrait_idle.png” and “beeto_portrait_hurt.png”, respectively. Here’s what your unit_beeto folder should look like:

Add these lines of code to unit.gml to add the portrait sprites to the unit’s data:

portrait_idle = "beeto_portrait_idle.png";

portrait_hurt = "beeto_portrait_hurt.png";

While we’re at it, let’s also give a new name and description to our googly-eyed goofball! Add these two new lines of code:

name = "Big-Eyed Beeto";

description = "Just looking!";

(Note: you can only display a maximum of 15 characters for a name and a maximum of 150 characters for a description.)

And with that, we have all the essentials in place for our modded unit! Here’s how it looks in action:

Creating New Units

We now know how to modify an existing unit, but what if we want to create a new unit entirely? Thankfully, not much needs to be changed! To make a brand new unit similar to Beetos, we need to do two things: give the Big-Eyed Beetos a unique ID, and use Beetos as a template. To accomplish this, we’ll replace the value specified in unit_id and add a new variable, unit_template:

unit_id = "big-eyed beeto";

unit_template = "beeto";

By using Beetos as a template, we ensure they’ll be identical to how Beetos behave in the game, even if we have another mod that modifies them. This means the only differences between Beetos and Big-Eyed Beetos are the name, description, sprites, and starting HP.

If you don’t want to base a new unit off of any other unit in particular, you can delete the unit_template variable entirely. Note that you will need to define a unit’s behaviors manually this way, such as if the unit is an enemy, boss, or playable character, for example. You can read about behavior tags here.

One last important thing to note is that all new units (except for player units) will not appear in the game by default, and must be configured to appear via stage data or other means. This will remain out of the scope of this guide, however.

The Finishing Touches

Lastly, we’ll go back to covering some basic mod info. Open mod_info.ini again and modify a few lines:

[general]
name="Example Mod" // 20 characters max (remaining will get cropped)
description="A simple mod!" // no limit here :)
major_version="1" // the versions are automatically added together, e.g. "v1.0"
minor_version="0" // minor version is automatically increased by 1 when you push a mod update, e.g. "v1.0" -> "v.1.1"
icon="mod_icon.png" // .png image, your mod’s icon. Dimensions should be square.
[tags] // mark features your mod uses as "1" to apply corresponding Steam tags to your item:
units="1"
stages="0"
bosses="0"
prefabs="0"
relics="0"
quandaries="0"
modifiers="0"
items="0"
traps="0"

Since our mod has modified units in it, we’ll set the unit tag to 1! This will automatically update the tags on the Steam Workshop whenever you upload or update this mod, so others can know at a glance what your mod is adding to the game.

To give our mod an icon, we can save a file with the appropriate file name in the same directory as mod_info.ini. (Download link!) Icons are displayed in-game at a size of 90x90 pixels, and any icons that are bigger or smaller will be resized to fit. No need to worry about transparency issues for the icon!

This is the icon that will show up when the Mod is uploaded to Steamworks

Uploading to Steam

Once your mod is ready, you can upload it to Steam Workshop to share with the community! With your mod inside of your “Personal Location” folder (See the Locating the Mods folder section above), follow these steps:

1. Open Shovel Knight Pocket Dungeon - Make sure you are on the Early Preview branch. If you’re not sure how to check for this, see our “How to access Early Preview” section on  the build notes page

2. Go into the Mod support menu, and select your mod

A pop up will appear with the option called “Submit”. Select this option

This will open up Steam to show you the mod you’ve uploaded! From here you can upload screenshots, write descriptions, and generally make your mod’s page look more professional, and give the community an idea of what your mod does!

If Steam doesn’t open up after submitting your mod, you can go to the Shovel Knight Pocket Dungeon Workshop page and find your uploaded mods in Your Files, which is under the arrow next to your profile icon:

When you are ready to share it with the world, look under the Owner Controls panel and click on “Change Visibility” to the setting you would like for your mod.

• Public = Everyone can see your Mod

• Friends-Only = Only people on your friends list can see your mod

• Hidden = No one can see your mod

• Unlisted = You need to share a link with someone to see your mod

Wrapping Up

We hope that this helped you to take your first steps into modding Pocket Dungeon! Remember that you can always join the Yacht Club Games Discord and check in on the #mod-support-skpd channel to ask for advice, or to see what other fun mods the community is working on.

If you feel you’re ready to start diving into more complicated mods, feel free to download the full set of Mod Templates here or use these Sprites in the Game as a starting point! Enjoy!

Summary of Useful Links

“Example Mod” Files download

Full Mod support documentation

Download GMEdit

Pocket Dungeon GMEdit Dialect

Early Preview patch notesYacht Club Games Discord Mod Chat

More Template Examples

All Stage Sprites

All Unit Sprites