File formats

The MCInstance format

An MCInstance file is basically a zip file with a specific organization. that's it. It doesn't have any password (so it's non-encrypted, this is important) or anything else that differentiates it from a standard zip file.

I chose to change the file extension to be .mcinstance in order to allow a potential use with 3rd party launchers in the future. Using a custom extension allows operating systems such as Windows or Linux to open .mcinstance files in a specific app instead of treating it like a normal zip file. This means, if a launcher ever adds support for it, that users will be able to double-click the file and it would immediately get installed with it.

File structure of the archive

Like said above, an mcinstance file is just a renamed zip.

This means that you can use your favorite zip file manager to open it. To create your first mcinstance file, just create an empty zip file and rename it to pack.mcinstance (so without .zip at the end). Then, save it in your .minecraft/config/mcinstanceloader folder. The pack file name is required for the mod to find the file, but it's not part of the file format itself. Afterwards, just set your system to launch .mcinstance files with your preferred archive manager.

Then, just make sure to respect this file structure in your mcinstance file:

* : Required, others are optional.

|__ metadata.packconfig*
|__ resources.packconfig
|__ optionals.packconfig
|__ overrides
    |__ mods
    |__ config
    |__ options.txt
    |__ ...
|__ client-overrides
    |__ mods
    |__ config
    |__ optionsof.txt
    |__ ...
|__ server-overrides
    |__ mods
    |__ config
    |__ fileAtRoot.txt
    |__ ...

As you can see, an mcinstance file can basically be split into two parts: the overrides folder and the packconfig files (see below).

The packconfig file format

As you might have noticed, many files in this archive have the .packconfig extension. This a custom config format meant for .mcinstance and by extension, this mod. It has a syntax close to TOML or INI files.

It is used for most things in this mod: Adding metadata, Downloading external resources, Configuring optional resources to download etc.

The reason i went with a custom config format for this mod is simple. I wanted something that would be easy to read, easy to use and easy to integrate in this mod. At first i looked at formats like JSON, which ends up being the opposite of what i want. It isn't great to read and use daily, and it would've required me to add another third-party library to the project, which i didn't want. There's also the markup-style formats such as XML or YAML, but i still think it would've been harder for users to use, which wasn't ideal.

Finally, i found the TOML and INI files, they have a fantastic syntax, they're easy to use and they're very flexible. The reason this mod doesn't use them though is just because of standards. TOML or INI files are vast and featureful, and i probably wouldn't have been able to add support for all of their features. Like i said i also didn't want to add yet another library just for config files. It would've also be annoying for users to try and use a certain feature just to find out that it doesn't work the same in my mod because it may be implemented differently or it may not have been implemented at all. So i went with a custom format that uses most of their syntax instead.

This also gives me more flexibility as i can for example use packconfig files to represent a list of distinct objects with their own unique properties, instead of just being a file where you look for a specific key in a specific category. The difference is subtle, but i can work with a variable amount of objects this way.

The packconfig syntax

Like i said above, packconfig files are very similar to TOML ones, here's an example:

#This is a comment. Everything after an # is ignored.

[object A] #The object name, should be unique for each object by convention.
key1 = value1
key2 = value2
key3 = 404
key4 = value4

[object B]
key1 = value1

# Booleans are true if the value equals to "true" (ignoring case). Otherwise, they're equal to false.
key2 = true

# The list below would be seen like this: [this is], [a list], [of strings], [strings can even include a comma (",") like that.]
key3 = this is, a list, of strings, strings can even include a comma ("\,") like that.

# Empty or incorrect lines and inexistant keys get ignored.
# Anything after the first equal is considered to be part of the value, even if it includes another equal (=) afterwards.
# Normal values are stripped from surrounding whitespaces, same for values inside lists.
# Everything is a string that gets parsed a specific way depending on what i need.

As you can see, those files are very easy to use. Using my own format also gives me the freedom of creating exactly the syntax i want, and adapt the parser on a per key level, which is pretty neat.