Versions, dependencies and platforms

Version numbers

The version is version in plugin.json. The LonelyIce catalog requires this form:

The launcher compares versions part by part as numbers, so 1.10.0 is newer than 1.9.0. The full rules are in How the package manager works.

A new version is how players get anything from you. Every change needs one:

• The launcher offers an update only when a catalog has a strictly newer version.
• The server runs the database updater over plugin SQL only when a loaded plugin's version, its SQL file names or their contents change (or plugins or database connections change). A file edited in place is noticed, but players only get the edit with a new package, and that needs a new version (On the next server start).
• A rebuild for a new core ABI needs a new version too (see Core ABI).

When to bump what

LonelyIce itself gives no meaning to the three numbers. Your dependents' ranges do: ^1.2 accepts every 1.x from 1.2.0 on and refuses 2.0.0, and ~1.2 accepts only 1.2.x. The table below is a recommendation that makes those ranges work for the people who depend on you.

Below 1.0.0, ranges are stricter: ^0.3.1 accepts only 0.3.x, and ^0.0.3 only 0.0.3. Move to 1.0.0 once other plugins depend on yours.

Dependencies

depends maps plugin ids to version ranges. Each value must be a string.

"depends": { "playerbots": "^1.0.0", "lonelyice.qol": ">=1.2.0 <2.0.0" }

What a dependency does:

Range syntax, as implemented (the complete table is in How the package manager works):

An operator may stand apart from its version (>= 1.0.0), ~> means ~, and a leading v and +build metadata are ignored. Not supported: || (1.x || 2.x), hyphen ranges (1.0.0 - 2.0.0) and pre-release suffixes (1.0.0-beta). The launcher, the server and this catalog read ranges the same way and refuse these.

Recommendation: depend on ^ of the version you built and tested against (^1.4.0). If your library links against the dependency's library, its exported functions must stay compatible, which is what its major version should tell you.

A disabled plugin does not count as a dependency: the launcher refuses to install or enable your plugin while a dependency is disabled, and names it ("enable it first"). It also refuses to disable a plugin that an enabled plugin needs.

Conflicts

conflicts lists plugin ids that must not be installed together with yours:

"conflicts": [ "someone.other-transmog" ]

The two sides check it differently:

• The launcher checks both directions: it refuses to install or enable your package while a listed plugin is enabled or chosen in the same install, and it refuses to install or enable a plugin that an enabled plugin's conflicts names. A disabled plugin counts for neither side.
• The server, at start, skips each plugin whose conflicts names a plugin it has.

Declare conflicts on your side. If you maintain both plugins, declare them on both sides.

The LonelyIce catalog copies conflicts into its index, and the entry --pkg pack prints for a catalog of your own carries them too.

Multi-platform packages

platforms lists the builds a package carries, one server/<platform>/ folder each:

your.plugin/
  plugin.json                          "platforms": [ "windows-x64", "linux-x64" ]
  server/windows-x64/your_plugin.dll
  server/linux-x64/libyour_plugin.so

To make one package from several builds:

1. Build the plugin on each platform against the LonelyIce core of the same release, with that platform's toolchain (Plugin format).
2. Copy each build's server/<platform>/ folder into one plugin folder.
3. List exactly those platforms in platforms.
4. Pack that folder once with LonelyIce.exe --pkg pack.

The upload fails with "Missing server build for …" when a listed platform has no library.

The launcher offers a package only on the platforms it lists. Adding a platform later means a new version, because a published version cannot change.

A plugin without server code (data, SQL, patch recipes, addons, settings only) has neither server nor platforms. The catalog reports "No server code: works with any core", and the launcher offers it everywhere. Do not list platforms without a library: the launcher then treats the package as server code and offers it only where core matches, so the catalog refuses the upload ("platforms without server").

Core ABI

core.abi names the binary interface your library was built against. lonelyice-ac-2 is the AC_PLUGIN_ABI of current LonelyIce releases. The LonelyIce build sets it (First plugin). C++ plugins share classes and the runtime with the core, so a library only works with the core it was compiled against. The ABI name is fixed per release and changes whenever a core change can break existing libraries (Plugin format).

The ABI is checked at every stage:

Do not edit core.abi by hand to make an old build load. The library reports its own ABI, and the server refuses the mismatch.

When the ABI changes

A LonelyIce release with a new ABI changes what players see:

• Its launcher no longer offers packages built for the old ABI.
• Installed plugins built for the old ABI are not loaded (built for core lonelyice-ac-1, this server is lonelyice-ac-2), and neither are the plugins that depend on them.
• Players get your plugin back through Updates once you publish a rebuild.

To publish the rebuild:

1. Update your build tree to the new LonelyIce release.
2. Rebuild the plugin on every platform you ship.
3. Set core.abi to the new name. The rebuilt libraries report it themselves.
4. Raise version. The catalog refuses the same number, and launchers only offer strictly newer versions.
5. Pack, upload and submit as usual (Publishing a package). Also rebuild and republish any dependency you own, first.

Older versions stay in the catalog's index. A launcher still on the old ABI keeps finding them and ignores the new one. A later fix for the old ABI would still need a number above the rebuild's, because every upload must be newer than the newest published version. The catalog also accepts it only while the old ABI is still listed as supported.

Languages

locales lists the languages your plugin's texts are translated into: chat and gossip texts, *_locale rows, localized strings in patch recipes, addons and launcher settings. The format is in Plugin format.

locales does not affect installation. A player can install a package in any language, and the launcher shows name and description in its own language, then en, then any. Give at least en in every localized string.