Hosting your own catalog

What a catalog is

A catalog is one index.json that lists packages, plus the package zips and icons it points to. The launcher reads any number of catalogs and merges their packages. A catalog can be:

Location	Example
A folder holding `index.json`	`D:\catalog`
A local index file	`D:\catalog\index.json`
An `http://` or `https://` URL of an index	`https://example.org/lonelyice/index.json`

No server software is needed: any static file hosting works, including a raw file URL of a Git repository. The default LonelyIce catalog, https://lonelyice.org/packages/index.json, is generated by the project site, but the launcher reads it like any static file.

The index format

{
  "format": 1,
  "name": { "en": "Example catalog", "ru": "Пример каталога" },
  "packages": [
    {
      "id": "example.greeter",
      "version": "1.0.0",
      "name": { "en": "Greeter" },
      "description": { "en": "Greets every player on login." },
      "core": "lonelyice-ac-2",
      "platforms": [ "windows-x64" ],
      "locales": [ "en" ],
      "depends": { "playerbots": ">=1.0.0" },
      "icon": "example.greeter-1.0.0.png",
      "url": "example.greeter-1.0.0.zip",
      "sha256": "3f5a…",
      "size": 48213
    }
  ]
}

Top level:

Field	Meaning
`packages`	Required, an array. An index without it is not an index.
`name`	Localized name shown in the launcher's catalog list. Without it the launcher shows the host or folder name.
`format`	`1`. Written for future versions; the launcher does not check it today.

Per package:

Field	Meaning
`id`, `version`, `url`	Required; an entry without one of them is skipped.
`name`, `description`	Localized strings, as in `plugin.json`.
`core`	The core ABI (`core.abi` of the manifest).
`platforms`	Platforms with a server build. A package with platforms is offered only when `core` equals the launcher's ABI and the running platform is listed. Without platforms (no server code) it is offered everywhere.
`locales`	Languages of the plugin's texts (`en`, `de`, `es`, `fr`, `ko`, `ru`, `zh-CN`, `zh-TW`, or `*` for none); the Plugins page can filter by it.
`depends`	Plugin id → version range. The resolver pulls these from all catalogs.
`conflicts`	Plugin ids that must not be enabled together with this one; the launcher checks both directions.
`icon`	A PNG, cached by the launcher in `plugins/.cache/icons`.
`page`	A web page for the package, opened from the Plugins page.
`sha256`, `size`	Hex SHA-256 (compared in any case; `--pkg pack` writes lowercase) and byte size of the zip. Checked after download when present.

url, icon and page may be relative: they are resolved against the index's location (its folder, or the URL up to the last /). Absolute URLs and paths are used as they are.

A catalog can list several versions of a package. The resolver takes the newest version that satisfies every range; when two catalogs offer the same id and version, the one listed first in the settings wins.

Build it with --pkg pack

--pkg pack makes the zip and prints its entry, but it does not write index.json. Pack every plugin into the catalog folder and collect the printed entries:

$out = 'D:\catalog'
$entries = foreach ($plugin in 'D:\build\plugins\example.greeter', 'D:\build\plugins\example.other') {
    & .\LonelyIce.exe --pkg pack $plugin $out
}
@"
{
  "format": 1,
  "name": { "en": "Example catalog" },
  "packages": [
$($entries -join ",`n")
  ]
}
"@ | Set-Content "$out\index.json" -Encoding utf8

Each printed entry holds id, version, name, description, core, platforms, locales, depends, conflicts, icon (when the plugin has an icon.png, copied next to the zip), url, sha256 and size. Add page by hand if you need it. --pkg pack refuses a plugin whose depends has a range it cannot read, or whose locales has an unknown code. Keep the entries of older versions if players should be able to pin them.

A package in the index must match its zip: on install the launcher compares the zip's plugin.json id and version with the entry and refuses a mismatch. Never change a published zip; publish a new version.

Add it to the launcher

Plugins page: open Catalogs…, add the folder, file or URL. The list shows each catalog's state; a catalog can be disabled without removing it.
lonelyice.ini: [packages] index holds the catalogs in use, disabled the ones kept but not read, both separated by ; (see lonelyice.ini). A location cannot contain ;.
Command line, for one command: LonelyIce.exe --pkg available --index D:\catalog. --index replaces the configured catalogs; separate several with ;.

A catalog that cannot be read is skipped and reported; the others keep working.

Integrity and trust

sha256 and size protect against broken or truncated downloads. Leave them out and nothing is checked; always include them.
There is no signing. A catalog is trusted as a whole: whoever controls the index controls what players install, and packages contain native code. Serve remote catalogs over https; certificate checks are on.
Players add catalogs themselves, so tell them where yours comes from and publish the source of every package in it.

Publishing on this site instead

If your plugin is meant for everyone, publish it in the LonelyIce catalog instead: it adds automatic checks and a review by a moderator. See Publishing a package.