The Ultimate Guide To Modding Crypt of The NecroDancer

This guide will walk you through the basics of modding Crypt of the NecroDancer. from simple resource packs, to completely overhauling the base game, ranging from custom items, weapons,spells, enemies and more!

Welcome | Introduction

The following is an extract from Noita's (another game's) modding readme.txt:

As such I will welcome You as well, fellow seeker of knowledge.Crypt of the NecroDancer is an amazing game(but you knew that already) but documentation for modding is scarce. This Guide will attempt to break down a few of the nuanced concepts and make it easier for beginners to get into it.

Some Disclaimers

Before we start wearing our hacker hoodies, a few disclaimers:
In programming in general there are many different ways to do something. the methods i outline below might not be the most optimal, or best practices. But they have worked and for a beginner guide like this i think that is sufficient. if you are reading this and you are more experienced than me or know of a better solution. please let me know in the comments section. i do not know everything and I would like others better than me to help me improve this guide.

Secondly. Necrodancer has a very extensive achievement list, and any mods that change the beat-map, enemies or certain game-play elements will disable achievements, as well as leader-boards.
take note of that. You cannot just make an infinite potion mod and then go play as aria, if you care about the achievement.

Lastly. a very very big portion of modding. is research, reading documentation, and looking for bugs. if this is your first time modding a game, do not get discouraged if you are not actually playing the game as much as you thought you would have, half the fun is in experimenting. And also do not expect this guide to give you all the answers. I will try my best to explain as much as possible, but the best way to learn is to dig through the files and read the documentation.I can teach you the basics, but i cannot tell you how to make your very specific idea into a mod.

And Lastly. I have a life as well (believe it or not) so this guide will be released in sections. as I have the time and as I learn about modding and do my research. Yes I know that some sections are incomplete right now. I will get to them. if there is anything you want me to explain or put in this guide, or if you are having issues. let me know in the comment section.

Prerequisites/Requirements

As this mod is aimed at beginners, No prior programming experience is required. Necrodancer is modded through three main languages. XML, LUA and JSON. XML and JSON are very easy to understand and i will be giving a very very tiny lesson on that in this guide,but any more would be outside the scope of this guide, I will be linking resources where you can learn more about that. you will be able to make many resource packs for the game just by editing XML and JSON files. When it comes to LUA scripting however, LUA is a programming language that is very easy to learn if you have prior programming experience, but we will cross that bridge when we get there.

The only requisites for this guide, is that you have basic, computer literacy,(navigating folders,opening files,deleting etc) and knowledge about necrodancer itself, which if you are reading this you probably have both already.

OK enough rambling. Let's get started.

Getting Started | Digging For Files.

Actually before we get started we have to talk about code editors. Code editors are pieces of software that make it easy to read and write code.below you can see the difference from regular notepad, to a code editor

If you are an experienced programmer and already have a code editor of choice, I wont force you to use another, but if this is your first time writing code, I would highly suggest you download Sublime Text. it is the code editor i use and recommend. it is lightweight, highly customizable, and most importantly free, forever. It is not necessary but i highly recommend it.You can get it at:
https://www.sublimetext.com/
for Windows,MacOS and Linux. Go install that and come back here.

Now that you have a decent code editor let's look at some game files shall we.
Navigate to your Steam library page for Crypt, and click on the gear icon. I will show you some images to make it clearer.(care not about my abysmal achievement count)

click on properties from the dropdown. That should open up a new window.


from here click on local files. and then click on browse.


it should open the location of the game files for Crypt. Bookmark this folder. as you will be making frequent access to it

Click on the data folder. This is where all the meat of the game is stored.

Before you even write any code. go through each of these folders, and open the files. just get your hands messy. Get used to this folder structure. a lot of the time while modding you are just going to be looking through here. I know i did for a long time before I figured out what i was doing, but it gave me a big understanding of whats going on behind the scenes.

Even if you do not read it here is a summary of what those folders contain.
bestiary- contains artwork for every mob in the game that you see when you practice against them.
custom_music- don't mind this.
entities- contains sprite sheets for every mob in the game.
essentia- contains essentia, a c++ library which the game uses to detect the beat for custom music tracks.
gui - contains the boss-splash screens, as well as the sprites for the game HUD
items - contains sprites for all the weapons,items,spells,gold-piles, familiars etc in the game.
languages- contains localization information for a few languages.
level-contains sprites for the wall and floor tiles of each of the zones as well as sprites for each of the shrines.
lua - contains some lua scripts for a few enemies
mainmenu- contains the splash screens for the game.
mentor- I have no idea(anyone with more knowledge please let me know)
music- contains all of the soundtracks in the game as well as the txt files which correspond to the "beat" that you tap to in game
particles-contains sprites for a few effects you see in game.
sounds-contains all the sound effects in the game.
spells-contains spritesheets for spell effects.
swipes- contains spritesheets, for swipes. which are effects you see when weapons/enemies make their attack
text-contains images of the font necrosans. as well as some text you see in game
traps-contains sprites for all the traps in the game .duh :)
video-contains the videos for the cutscenes. if you want you can open the file credits_4.ogv and navigate to the timestamp 3:13 so you too can feel like you have attained necro-mastery.also,spoiler warning for the cutscenes(obviously)
save_data.xml- contains your save file. I really wouldn't mess with that as it might corrupt certain things.
The final file and probably the most important one is necrodancer.xml. this files basically contains the entire game information. from health values,damage numbers, spawn rates etc. it is quite an intimidating file. but again I would highly recommend that you go through it.

Making a Custom Skin MOD

Ok now that we've covered the basics , let's go through making our first Re-skin mod.
Navigate to that main folder.
From there go into the data folder.
Take note of the format here.
go into entities and search for mushroom_light.png
copy this image and put it somewhere accessible.

Now navigate back to the main necrodancer folder. there should be a folder called mods.
if there isn't one , create one.(note that the folder called downloaded_mods will have the file for mods installed via the workshop.)

go into the mods folder and create a folder called blue_light.
go into that folder.
Remember the data folder from before.

this folder is now your new data folder for the purposes of modding. ANY file that you place here that matches with the file path from the main data folder, will OVERWRITE that of the main game. take note of folder and file names. humans can forgive misnaming things but a computer won't

now create a folder (within our blue_light folder) called entities. again we are overriding the game's default entities folder.
Now either open up Photoshop or Gimp. (not MS paint) we are going to edit the photo we copied.
if you do not have these software go to your browser of choice and go to https://kleki.com/
that is a free, online, browser only image editor. use the fill tool to re-colourize the image.
this is not a photo editing guide so i will assume that you have messed around in MS Paint before. but here are some screenshots


i used the fill tool shown above to colourize the mushroom. note that i left out the black sprites


save the image as mushroom_light.png. IT MUST BE NAMED THIS EXACTLY.

now navigate to your blue_light folder withing the mods folder.in the entities folder put your newly edited image there.
again to restate we are over writing the games default data.
the normal folder is data/entities/mushroom_light.png
the game will notice that there's a file called
mods/blue_light/entities/mushroom_light.png
and will use that edited photo instead.this does not only work for images. BUT ANY FILE THAT YOU PUT THAT MATCHES. more on that later :)

Now open necrodancer.
open settings and go to customize.



navigate to resource packs


you should see your mod show up.enable it and press done.


Now go down the Zone 2 staircase in the lobby. This assumes you have unlocked Zone 2
if not go do that and come back here.

when you go down the staircase you should be immediately greeted by your newly edited sprites.


Congratulations. you have just made your very first mod. To be specific you have made a resource pack that alters one of the game sprites. this kind of mod should not disable leaderboards or achievements as it does not alter the soundtrack or gameplay in anyway.(verification needed).

Give yourself a pat on the back. I'm serious. what you have just done in five minutes took me three weeks of research and figuring out.

Now if your'e not celebrating like the rest of us. here are a few common issues.

make sure your file is saved as mushroom_light.png and not mushroom_light.png.png
enabling VIEW FILE NAME EXTENSION may help with this.

your mod folder must match EXACTLY the path of the data folder.
mods/blue_light/entities/mushroom_light.png

its spelled entities not entites (yes I made that mistake)

make sure your image is the same size as the original. 48 pixels by 48 pixels.
you can view this by going to properties when you right click on the image. and going to the details tab.

make sure you have enabled your mod.

if your have done everything right so far and this is still not working let me know in the comments below.


Well Done. what you have done right now can be applied to any sprite in the entire game. I Know you wanna make your own custom weapons and enemies but we have to start somewhere and this is a really solid start. the next section will deal with making a custom music mod.

I know that things can be cleaned up even further, that will be discussed in the mod workshop upload section and will deal with mod thumbnails, uploading to steam workshop etc.


Enjoy some memes.

Making a Custom Music/Beat Track MOD

WORK IN PROGRESS

Making a Custom Language MOD

WORK IN PROGRESS

Necrodancer.xml Editing

WORK IN PROGRESS

Gameplay modding. Lua scripting.

WORK IN PROGRESS

Mod Cleanup and Workshop Upload

WORK IN PROGRESS

Final Comments

[Ɛ: ʎɥɔʇɐԀ]

nice memes tho, loved bolt one

[SoupToon]

that sounds cool, i will try messing around and see what i can do. i think it would be fun to add my OCs to the game with their own playstyles

[Noctowl]

Yeah. It requires at least a basic understanding of the .lua style and how CotND's components and such work together, but there are some seriously creative things you can do if you're dedicated enough to playing around with everything.

I've personally made a custom character with a unique lose condition and a unique, evolving weapon, and I can easily say way more is possible. I just haven't been doing quite much lately.

[SoupToon]

Is it possible to make an entirely unique character with their own moveset, weapons, and/or abilities?

[Shojo Dagger]

Thanks for the guide, I'm a bit disappointed that the gameplay/LUA section is't done yet, but the current parts are still a big help for getting started.

One issue: I checked out the recommended "free, forever" text editor. It costs money now. :(

From the site: "Sublime Text may be downloaded and evaluated for free, however a license must be purchased for continued use."
They also say: "There is currently no enforced time limit for the evaluation."

So it's actually: "sort of free, for now, until they change their minds"

For another possible editor you might try Notepad++ [notepad-plus-plus.org], a FOSS (free open-source software) text editing program w/ built in code editing options.

[Foxy Fox]

This was more handy then I'd like to admit

Also... is it possible to turn something like the "familiar_ice_spirit" which has no animation, to have an animation?

[nazeem]

Yes any sort of help with this guide would be greatly appreciated. i do not know much but I would like to create a fully detailed guide

[Noctowl]

Hey, I'm sure you've noticed like I did that there seems to be practically no guides on Steam about how to mod this game? I'd like to help fix that, even if I don't really know how to mod the game that much myself, but I've started digging around myself too. I was hoping maybe I could chat with you and help write this guide with you for others too?