Chapter 1: Ready, Set, Mod!

Chapter 1: Ready, Set, Mod!

This chapter will have you to go through the process of creating a Friday Night Funkin' mod in this engine, using the systems made for loading mod content and scripts. Once your mod is complete, you will be able to place it in the mods/ folder in your game installation and use its content in-game without overriding stuff in assets/ and still maintain compatibility with other mods.

back in my day, we used to just override the base game assets cuz besides taking up with kade engine, it was the only way of modding of the game. ha, kids these days with their modding engines, their swag, SWAG mod loading system...

Anyways, this chapter goes through a lot of core concepts of modding in this game that will probably get used in the other chapters, so please make sure to read through it all carefully!

The Metadata File

To start making your mod, create a new folder inside the mods/ folder. (As an example, let's have the folder name be "exampleMod", though you can just name it whatever you want lol.) This is where you'll put your assets, data, and scripts there. Next up, create a new text file, and name it "_polymod_meta.json". Make sure you didn't leave the .txt thingy by accident, please!

So inside this file, we'll put the information needed for the game in order to load the mod in correctly. I recommend doing this stuff with a code editor like Visual Studio Code or Sublime Text, they'll correct you if you accidentally misplace a symbol like a comma or whatever lol.

Metadata Example:

{
  "title": "cool example mod",
  "description": "this is a json file used to store your metadata for your fnf mod",
  "contributors": [
    {
      "name": "charlesisfeline"
    }
  ],
  "homepage": "https://www.example.com",
  "dependencies": {
    "heroin": "1.2.1"
  },
  "optionalDependencies": {
    "crack": "1.6.9"
  },
  "api_version": "0.5.0",
  "mod_version": "1.0.0",
  "license": "Apache-2.0"
}

_polymod_meta.json contains the following fields:

• title: A readable name for your mod.
• description: A readable description for your mod.
• contributors: A list of Contributor objects, shown under this list.
• homepage: An URL link where users can learn more about your mod. It can be your GameBanana/GameJolt/GitHub/itch.io mod page or a website.
• dependencies: A map of mod IDs which are dependencies (that are mandatory), along with their version numbers (ex. 1.3.6).
  • These mods must also be loaded in order for this mod to load correctly, otherwise it will fail.
  • The mod list will be reordered so the dependencies will load first.
• optionalDependencies: It's like dependencies, except they are for optional dependencies.
  • These mods do not necessarily need to be installed for this mod to load right. They'll still force the mod list to be reordered so that the dependencies will load before this mod.
• api_version: A version number used to determine if a mod works best with your FNF copy. You can change this to the game's version number that you want to support, preferably the latest one. (0.5.0 as of the current revision of this page lol.) (LEAVE IT AS 0.5.0 FOR NOW BTW)
• mod_version: A version number, specifically for your mod. You can choose any version, or just leave it at 1.0.0.
• license: The license your mod is distributed under. Pick one from here or just leave it as Apache-2.0.

A Contributor contains the following fields:

• name: The name of your contributor.
• role: (OPTIONAL!!!) The role the contributor played. (ex. "Artist", "Programmer", or "Musician".)
• email: (OPTIONAL!!!) Your contributor's contact email.
• url: (OPTIONAL!!!) Your contributor's site/page URL

Many of these fields are intended to be displayed in the future by an upcoming interface that will allow users to manage their mods (reordering and stuff).

Mod Load Check

Now that you got a metadata file for your mod, you can now start the game! By the way, giving a swag tip for ya, if you run the game from the command prompt (just type cmd.exe on the address bar on your file browser and type funkin in the prompt), you can see a lotta useful debug msgs, including the ones below that tell you that your mod has successfully loaded!

source/funkin/modding/PolymodHandler.hx:316: Found 5 mods when scanning.
source/funkin/modding/PolymodHandler.hx:118: Attempting to load 5 mods...
...
source/funkin/modding/PolymodErrorHandler.hx:79: [INFO-] LOADING MOD - Preparing to load mod ../../../../example_mods/kentuckyfriedchicken
source/funkin/modding/PolymodErrorHandler.hx:79: [INFO-] LOADING MOD - Done loading mod ../../../../example_mods/kentuckyfriedchicken
...
source/funkin/modding/PolymodHandler.hx:169: Mod loading complete. We loaded 5 / 5 mods.

Cool, right? But so far, your mod is empty and just does nothing for now. So, let's put something there then.

Ride the Assets Over Em'!

Replacing Assets

One important thing Polymod lets you do is to replace the game's assets, done by adding those files to your mod's folder in the same place as they normally would go.

For example, you can replace BF_kit's sprites by placing your new sprites in the same location as they are inside the assets folder, which would be shared/images/characters/bfKit.png. (You can also replace the .xml file that the spritesheet comes with too, optionally.)

Putting it differently, structure your mod like this:

-assets
-lua
-manifest
-mods
 |-WHATISTHISMODIDK
   |-shared
     |-images
       |-characters
         |-bfKit.png
         |-bfKit.xml
   |-_polymod_meta.json
-plugins
-Funkin.exe
-icon.ico
-lime.ndll

When the game goes to load a character's sprites, it will request internally to get the bfKit.png file to use for the character's texture along with the .XML file used to split the texture into different frames. Now, replacing bfKit.png with your own, Polymod checks if the loaded mod has a file with the same name, if so, it will be used instead of the one in assets/.

Adding new Assets

Polymod also allows you to add new files to the game. Trying to add new files into the assets/ folder doesn't directly work as the game won't recognize them. Cache, am I right?

The game stills needs requests to load those assets so it can use them, however, there are many registries that parse all the files in a given folder, such as the Song Registry, Character Registry, Stage Registry, etc. Don't worry, we'll cover them in the next few chapters...

Get in the Line! (Loading Mods in Order)

So, you may be wondering, what happens when you have multiple mods providing a given file.

The answer is pretty straightforward; *mod order matters. Let's say you got two mods installed which replace a particular asset, the mod which loads last will get precedence over mods that get loaded earlier, y'know it's kinda like loading resource packs in Minecraft: Java Edition. This is evaluated on a per-file basis, so if one mod (Mod #1) replaces Milky and BF_kit and another mod (Mod #2) replaces only BF_kit, and one of them is loaded after the other, you'll see the Milky from Mod #1 and the BF_kit from Mod #2.

Right now, yes, there is an accessible way of altering mod load order (which being a mod menu, which can be accessed through the options menu), however it's kinda janky. Mods will load in alphabetical order by default, with the dependencies being loaded first.