This specification attempts to record all metadata that's needed to install, launch and update a mod. It's more or less a successor to the
FSO Installer's text files.
The actual spec
is available on GitHub.
The install process for a mod works like this:
- The installer has a list of packages it wants to install.
- It then recursively resolves the package's dependencies.
- For every package it needs to check which files are already present. If a file is missing or doesn't match the provided checksum, it will be added to the list of missing files.
- The installer then downloads the necessary archives, verifies their integrity by generating and comparing their checksum and then extracts them. Using the file list from the mod metadata, it moves the extracted files to the mod's folder.
- Now the mod folder should match the file list contained in the mod metadata.
- The installer should save a mod.json file in the mod folder which contains a list of installed packages for this mod.
- Important: You shouldn't parse the "actions" field. It's only used by the server to generate the "filelist" property.
- Note: There are two special mod IDs which can be used as dependencies: retail and self. The "self" dependency can be ignored during installation. It's only relevant if you need to generate a -mod flag (which is documented below). The "retail" dependency expresses that the mod depends on the retail VPs AKA it's not a TC.
A few notes on launching a mod:
- The launcher reads the mod.json contained in the mod folder. It then resolve the mod's dependencies.
- It should use the cmdline property from the metadata and any flags the user specified.
- To determine the "-mod" flag, it has to flatten the dependency tree. The following rules apply:
- If one of the dependencies has its own dependencies, they are added behind the dependency.
- If a mod appears several times in the list, only the last appearance is kept.
- The special mod ID "self" refers to the mod which listed it as a dependency.
- The special mod ID "retail" refers to the directory containing the retail VPs. If a mod doesn't list retail as a dependency, it's a TC and you should launch FSO without the retail VPs.
- The generated "-mod" flag has to be deterministic and should match the output of other launchers implementing this specification.
Here's an example:
A depends on Z, self and B.
B depends on C.
C depends on nothing.
Z depends on C.
If you wanted to run mod A, you'd get this: -mod Z,A,B,C
If you want to run mod B, you'd have to use -mod B,C
Other notes:
- The "environment" property lists special hardware/OS dependencies. If those dependencies aren't met, the package can't be installed and shouldn't be displayed to the user.
- The "executables" property contains all provided executables. This is used by the FSO and FSO Nightlies package. Mods should only use this if they need to provide a custom build.
- "files" contains all downloadable files. You should use "filelist" to determine where the files are saved.
The "official" server-side implementation is
Nebula. A prototype is running on
fsnebula.org.
Mod metadata is available at
https://fsnebula.org/repo/test.json. Here's the metadata for FSO 3.7.2 RC5 (also included in the previous link):
https://fsnebula.org/repo/fso_3.7.2_RC5.jsonKnown client-side implementations are
m!m's Launcher and
Knossos.
Thanks go to m!m and Hellzed who have helped me write this spec.
Feel free to post questions, constructive criticism and other comments. If you want to talk about Nebula or Knossos, please
post here.