Metadata and updates

module.json

Metadata describes a module to the manager and updater. A local module example:

{
    "name": "hello-toolbox",
    "author": "Your name",
    "description": "A minimal module",
    "version": "1.0.0",
    "disableAutoUpdate": true,
    "options": {
        "cliName": "Hello",
        "guiName": "Hello Toolbox",
        "settingsVersion": 1
    }
}

If you specify settingsVersion, provide a settings migrator. Otherwise remove that field from a minimal module.

The manager uses dependency keys when loading; the updater uses their URLs to install missing dependencies. For mod.require.library, the dependency must be named library. Local load/update toggles can be stored separately in module.config.json.

manifest.json

An update manifest contains files: relative path → content SHA-256. The updater converts hashes to uppercase before comparison, so the generator can write lowercase hashes. This example illustrates the schema: replace the placeholders with actual file hashes.

{
    "files": {
        "index.js": "SHA256_OF_INDEX_JS",
        "module.json": "SHA256_OF_MODULE_JSON",
        "config-example.json": {
            "hash": "SHA256_OF_CONFIG_EXAMPLE",
            "overwrite": false
        }
    }
}

A hash string updates the file when its hash differs. An object with overwrite: false installs a missing file but preserves an existing one. Do not list user-owned module_settings.json as an overwritten file.

Automatic .manifest.js generator

The generator creates manifest.json from the module's files, removing the need to calculate and copy SHA-256 values manually. It requires Node.js but no third-party npm packages.

Download .manifest.js

1. Save the script as .manifest.js in the module root, alongside module.json and index.js.
2. Explicitly configure the settings file path in module.json, as shown below.
3. Open a terminal in the module directory and run:

node .manifest.js

The result is a new or updated manifest.json in the same directory. The script resolves files relative to its own location (__dirname), not the terminal's working directory. Run it for each release after finalizing files and before publishing.

Protecting configuration files

The generator identifies the main configuration file through options.settingsFile in module.json; if that field is not set, it checks the legacy top-level settingsFile. Use the modern form:

{
    "name": "hello-toolbox",
    "options": {
        "settingsVersion": 1,
        "settingsFile": "module_settings.json"
    }
}

This example assumes a settings migrator and an existing module_settings.json. Nested paths such as config/settings.json are supported; manifest keys normalize separators to /.

For the selected file, the generator writes an object:

{
    "overwrite": false,
    "hash": "SHA256_OF_SETTINGS_FILE"
}

The actual output contains a calculated SHA-256 in hash. The configuration file remains in the manifest: a missing file is downloaded on installation, while an existing user configuration is preserved.

Automatic protection applies specifically to the configured settingsFile, not to every JSON file or every file named config. Without an explicit path, the generator does not assume module_settings.json, even though Toolbox itself uses that default. If the configuration is absent or excluded from traversal, the generator warns and does not add a new entry.

For additional configuration files, predefine an object with overwrite: false and a hash field in manifest.json, as shown above. Subsequent runs update the hash of an existing object entry while preserving its other properties. The configured primary settingsFile always receives overwrite: false.

Included and excluded files

The script recursively scans the module directory and hashes file contents. New ordinary files are stored as path → hash.

The scan excludes:

• manifest.json, manifest-generator.js, manifest-generator.bat, manifest-generator.exe, node.exe;
• files and directories whose names start with . or _, at any nesting level.

Thus .manifest.js, .git and directories such as _backup are not added. Ordinary directories, including node_modules, have no special exclusion: check that the module directory contains only files intended for distribution.

An existing valid manifest.json is used as a starting point: top-level properties are preserved, entries for missing files are removed, and discovered files receive updated hashes. Exclusion from scanning does not itself remove an old entry if its file still exists; review these entries when changing release contents. If the manifest is missing or cannot be read, a fresh files object is created. A missing or invalid module.json stops generation with an error.

Publishing an update

Place files and the manifest under a base URL listed in servers; appending manifest.json or a relative file path must produce its download URL. The updater tries alternative servers after a failure. For a release, update files, run node .manifest.js, review the file list and configuration protection, then publish the result. Test both a fresh installation and an upgrade with modified user settings. Do not edit distributed files after generation without rerunning the script: their hashes will change. An initial module.json can be sufficient to bootstrap the remaining files.

Packet declarations in older manifests do not replace .def compatibility or checking versions for the target server. Do not disable hash verification to work around an incorrect manifest.

Sources: .manifest.js, node_modules/tera-mod-management/index.js, bin/update.js, bin/mod.js.