Publishing plugins

Publishing plugins

Players install plugins from the Browse tab of the Mods menu. The tab lists the plugins of the ProLeak registry, authority/plugins.json in the organization's .github repository, and installs the latest GitHub release of each one. A plugin copied into ProLeak/plugins/ by hand still loads; the Mods menu marks it "Not from the registry".

Contents

• Preparing a release
• Getting listed
• Updates
• Testing an install locally

Preparing a release

• Keep plugin.yml at the root of the repository. ProLeak reads it from the release tag to show whether the plugin fits the player's ProLeak version before downloading anything.
• Tag each release v followed by the version in plugin.yml: v1.2.0 for version: 1.2.0. A release whose tag and manifest disagree is not installed.
• Publish the tag as a GitHub release. ProLeak installs the release GitHub marks as latest (drafts and prereleases never are).
• Set update: github: owner/repo to the repository the registry lists, or leave it out.
• Set the proleak: range to the ProLeak versions the plugin works with. ProLeak refuses to install or update a plugin whose range excludes the running version, and the Browse tab shows the range.

ProLeak downloads the release's source archive and extracts only these files, anywhere in the tree:

plugin.yml  *.py  *.js  *.css  *.json  *.yml  *.yaml  *.txt  *.md
*.png  *.jpg  *.jpeg  *.ogg  *.wav

Every other file is skipped and named in the log. An archive larger than 20 MB, with more than 2,000 entries, or with an absolute path, a .. segment or a link is refused.

Getting listed

Open a pull request against authority/plugins.json that adds one entry:

{"id": "my.wave-toast", "repo": "me/ltd2-wave-toast", "description": "Says what each wave is and how your value compares."}

id must equal the id in plugin.yml, and repo is the GitHub owner/name. Each id and each repository appears once. The repository's CI checks the file with ProLeak's own parser, so a malformed entry fails before players see it.

Updates

At startup ProLeak checks the latest release of every plugin installed from the registry. When a newer release fits the running ProLeak, the plugin's entry in the Mods menu shows "Update to x.y.z". The update unloads the plugin, swaps in the new files and loads them. If the new version fails to load (its plugin.yml is refused or on_load raises), ProLeak puts the previous files back, loads them again and shows the reason.

Installs and updates leave the plugin's settings (ProLeak/config/<id>.yml) and its files in ProLeak/data/<id>/ alone.

ProLeak keeps release lookups for an hour in ProLeak/cache/registry.json, because GitHub allows 60 unauthenticated API calls per hour from one address.

Testing an install locally

With dev: true in ProLeak/config/proleak.yml, three more keys point ProLeak at local files instead of GitHub:

dev: true
authority: file:///home/me/registry/authority.json
releases: /home/me/releases
release_key: /home/me/test-release.pem

authority names the file that holds the registry's URL, in the same format as authority/authority.json; in dev mode that URL may also be file://. releases is a folder with one subfolder per repository, <owner>/<name>/, each holding the release.json that the GitHub API would return for the latest release and the plugin.yml of that release. The download URLs inside release.json may be file://. release_key names a PEM public key that ProLeak trusts for its own updates besides the built-in ones, so a locally signed ProLeak release can be installed. Outside dev mode these keys are ignored, with a warning in the log.

---

Previous: Game updates | Next: Game logic