CKAN file naming conventions

[pjf]

My original plan was to have the file named META.json and placed in the root of a distribution's zip. This provides a simple, well-known place for tools to look. However it also means that users installing mods manually end up with a whole bunch of warnings about files wanting to overwrite each other, and that sucks.

Instead, I think it's going to be best to have files named shortname.ckan, where shortname is from the CKAN definition itself (and matches the name that ModuleManager would see the mod as). Hence one would have kOS.ckan and RealSolarSystem.ckan as filenames. This has two advantages:

• Users no longer have to worry about overwriting files on unzip
• Simply having these in GameData means that we can easily tell later on which mods have been installed.

The second point here is important, because it means CKAN clients can pick up previously installed mods that were placed by hand. It also minimizes the number of dependencies a client needs to run; we already know that any client already has the libraries to parse JSON and walk directories. The CKAN metadata is also living there alongside the mods themselves, meaning folks who have multiple KSP installs (like yours truly) doesn't have them interfere with each other.

It may make sense for an installer to place these files in GameData/CKAN, simply to keep them tidy, but I don't think they should have to live there.

KSP itself ignores files other than .cfg, models, and textures, so it will never try reading a .ckan file, which is what we want.

As always, feedback and thoughts are very much appreciated.

[erendrake]

Would you be open to the ckan files being in the mod's folder rather than in the root of gamedata? that way if someone removes a mod everything is contained in the one folder

[pjf]

@erendrake : That's what's currently turning over in my head. It makes everything a lot more robust in terms of manual installs and uninstalls, but it potentially means having to traverse the whole GameData tree, and that can get large (~ 7000 entries on my install, even after pruning out ActiveTextureManagement). However it does mean if we find a CKAN file, then we can be pretty sure that not only is that particular mod installed, but we can be pretty sure about which version is installed. That also means that mods which bundle other mods (eg: RealSolarSystem bundling CustomBiomes) can potentially include full CKAN files for those mods, which would be a big win.

Realistically, most tools should probably build their own cache to avoid having to re-scan the whole tree (with a user option to rebuild said cache if required).

So after thought, putting the CKAN file in the mod directory seems to make sense. A little bit more work for CKAN tools, but a lot more certainty to the validity of any data that is obtained when they scan.

[pjf]

And so we hit our first got gotcha, intersecting with #1 (multiple distributions per file). We have great metadata on mods that have been installed with a .ckan file, or from a .ckan file. We have terrible metadata on mods which have been bundled with an existing mod.

There are a few solutions:

• Generate and write a CKAN file for bundled mods. If we change the spec to say that name and abstract are optional, or we insist that bundled mods include that data, then we have enough information in the parent CKAN file to generate a minimal stub.
• Insist that bundled modules come with their own CKAN files.

The second increases the workload on mod authors quite a bit, so I'm shy to suggest it.

If we do change the spec so we can generate CKAN files for bundled files, then there's a question as to what we do with the download field. Having it point to the URL of the parent mod is technically correct, but is probably not useful if we wish to reinstall. We could say that download is not required if an optional bundled field is set to true, which also means we can easily identify bundled mods (and with a bundled_by we can figure out where they came from).

[pjf]

To update:

• We're using a registry to record what's installed.
• Metadata for installed mods will not be stored in CKAN files. Instead, they'll be in the registry.
• Any CKAN files in GameData will be from manual installs by the user. These may be used to hint at which mods are installed, but will not be considered authoritative.
• We will scan an entire zip file for embedded CKAN files. Having more than one embedded file will be considered an error.