ccmod.json

ccmod.json

The ccmod.json file is located in the root directory of a mod and defines mod metadata and how a mod is loaded. It is an alternative to package.json. If both exist then ccmod.json will be picked.

The ccmod.json format

It is a JSON file, the object is described here:

declare type Manifest = {
    /** The internal name. */
    id: string;
    /** The version in the format "major.minor.patch". */
    version: string;

    /** The displayed name. **/
    title?: LocalizedString;
    /** The displayed description. **/
    description?: LocalizedString;
    /** The used licence for the mods source code. **/
    license?: string;
    /** An URL of the mods homepage. If multiple are provided the one with the current language will be picked. */
    homepage?: LocalizedString;
    /** A set of keywords and tags associated with the mod. */
    keywords?: LocalizedString[];
    /** Maintainers of the mod. */
    authors?: Person[];
    /** A map of icon sizes such as the recommended "24" to file paths relative to the mod's root directory. */
    icons?: Record<string, string>;

    /** A map of dependencies needed for loading mods. "crosscode" and "ccloader" are allowed as well. Version ranges are the same as node's semver ranges. */
    dependencies?: Record<string, string>;

    /** An optional array of filenames relative to the mods `/assets/mods/<mod>/assets/` folder. This is only useful to allow mods to run in browser mode. If not defined ccloader will fill the array automatically. */
    assets?: string[];

    /** A filepath relative to the mod folder describing a plugin script. See the plugin section for more details. */
    plugin?: string;

    /** A filepath relative to the mod folder describing a preload script. See The Load Order for more details. */
    preload?: string;
    /** A filepath relative to the mod folder describing a postload script. See The Load Order for more details. */
    postload?: string;
    /** A filepath relative to the mod folder describing a prestart script. See The Load Order for more details. */
    prestart?: string;
    /** A filepath relative to the mod folder describing a poststart script. See The Load Order for more details. */
    poststart?: string;
}
declare type LocalizedString = Record<Locale, string> | string;
declare type Person = PersonDetails | string;
declare type PersonDetails = {
    name: LocalizedString;
    email?: LocalizedString;
    url?: LocalizedString;
    comment?: LocalizedString;
}

Plugins

Plugins are a special form of script.

They are always ES6 modules, that export a default class. The following functions will be called if they exist

class Plugin {
	/**
        * @param currentMod The metadata of the current mod including it's current directory.
        */
	constructor(currentMod: Mod);
	// The loading process is blocked on the returned promise, if any.
	// Defined scripts occur after plugin scripts.
	preload(): Promise<void>;
	postload(): Promise<void>;
	prestart(): Promise<void>;
	poststart(): Promise<void>;
}

Assets

If the mod has a sub-directory called assets, then that directory is scanned for available assets. Structurally, that sub-directory mirrors the CrossCode assets directory. The scan finds some subset of the files in that sub-directory (recursively, so it includes sub-sub-directories and so on), and hooks at least CrossCode's image loading, audio loading, and AJAX requests to redirect requests for files with those names.

The subset must contain least those files with extensions: .png, .json, .json.patch, .ogg. Other extensions may also be supported.

The Load Order

There are a few 'phases' to mod loading, each can have a script. Within a given 'phase', mods must be loaded in 'dependency order' - the dependencies of a mod must be loaded and run before that mod.

The 'phases' are:

0. plugin. Plugins should not perform complex logic in this step as literally nothing (including the window object) is loaded and it's only purpose is to allow mods to export the plugin class.
1. preload. This is executed before game.compiled.js is executed.
2. postload. This is executed after game.compiled.js is executed and before the window onload event.
3. prestart. This is executed before ig.main.
4. poststart. This is executed after the game has loaded all resources and the title menu beginns playing.