Hosting a Package Repository

Hosting a Package Repository

This page is a practical guide for pack authors who want to publish their EmoTracker packs to other users — by hosting their own package repository, testing it locally, and (optionally) getting it listed in the official community repository list that ships with EmoTracker.

If you only want to install packs, use the in-app Package Manager instead.

Looking for the deeper backend internals (supported_games.json, the community package_repositories.json, client cache policies, etc.)? See Service Backend Reference.

What "hosting a repository" actually means

A package repository is just a single static file — repository.json — served over HTTPS, plus the pack .zip files it points at. EmoTracker downloads that JSON, lists each pack it describes in the Package Manager, and downloads the linked zip when the user clicks Install.

You do not need to run a server, an API, or any backend code. Anything that can serve static files over HTTPS works:

• GitHub Pages — most community repositories use this. Create a repo, enable Pages, commit repository.json and your .zip files. Done.
• Raw GitHub URLs — point at https://raw.githubusercontent.com/<user>/<repo>/<branch>/repository.json directly, with no Pages setup.
• Your own web server — any static HTTPS host works.

The minimum filesystem layout for a third-party repository is:

your-host/
├── repository.json
└── your_pack.zip      # Or hosted anywhere else reachable by URL

Step 1: Build your pack zip

Author your pack as usual and produce a .zip. Decide on its uid before you publish — this is the identity the client uses forever, so pick something specific and namespaced.

A good convention is <game>_<feature>_<author>, e.g. alttpr_keysanity_yourname. Avoid generic IDs like tracker or pack — uid collisions across repositories will cause one pack to overwrite another on install.

Step 2: Write your repository.json

This is the file every host serves. It lists the repository's display name and one entry per pack.

Minimum valid example

{
  "name": "My Tracker Packs",
  "packages": [
    {
      "name": "My Cool Pack",
      "game_name": "A Link to the Past Randomizer",
      "version": "1.0.0",
      "uid": "alttpr_my_cool_pack_yourname",
      "link": "https://example.com/packs/my_cool_pack.zip"
    }
  ]
}

That's enough to make a pack appear in EmoTracker. Everything below is optional.

Full pack entry

{
  "name":                 "<pack display name>",       // required
  "author":               "<author>",                  // optional, defaults to "Unknown"
  "game_name":            "<key from supported_games>",
  "version":              "1.0.7.14",                  // required, System.Version format
  "required_app_version": "2.3.8.8",                   // optional, System.Version format
  "uid":                  "unique_pack_identifier",    // required
  "link":                 "https://.../pack.zip",      // required
  "documentation_url":    "https://...",               // optional
  "flags": [ "map", "pins", "chathud", "autotracker" ],
  "variants": [
    {
      "name":  "Item Tracker",
      "flags": [ "chathud", "autotracker" ]
    },
    {
      "name":  "Standard Map Tracker",
      "flags": [ "map", "pins", "chathud", "autotracker" ]
    }
  ]
}

Field notes

• name (root) — Display name of your repository, shown as a section header in the Package Manager.
• packages — Array of pack entries.
• name (entry) — Pack display name. Required — entries without one are silently dropped.
• author — Defaults to "Unknown" if omitted.
• game_name — Should match a top-level key in supported_games.json. If your game isn't there, see Adding a new game.
• version — Parsed with System.Version.TryParse, so it must look like Major.Minor[.Build[.Revision]] (e.g. 1.0, 1.0.7.14). The entry is dropped entirely if this is missing or invalid — this is the most common reason a new pack fails to appear.
• required_app_version — Same format. If the user's installed EmoTracker is older than this, the Package Manager shows the pack but blocks installation until they update.
• uid — Unique pack identifier. Required, used as the local install filename (<uid>.zip). Must be unique across all repositories the user has loaded.
• link — Direct download URL for the pack .zip. Required.
• documentation_url — Optional link surfaced in the UI for users who want to read pack docs.
• flags — Array of capability strings (case-insensitive). Recognized values:
  • Map — pack provides a map tracker
  • Pins — pack supports map pins
  • ChatHUD — pack supports the chat HUD overlay
  • AutoTracker — pack includes an autotracker script
  • Unsafe — pack does things the user should be warned about
  • Official, Featured — privileged, see below
• variants — Optional list of pre-configured variants the pack ships with. Each variant has its own name and flags.

About Official and Featured: These flags are stripped by the client unless the pack's link URL contains the configured service_base_url. You can't mark your own third-party pack as Official or Featured — those badges are reserved for packs hosted on the community service.

Step 3: Choose where to host

Pick a static HTTPS host and upload repository.json plus your .zip files (or host the zips elsewhere — link can point anywhere). Common options:

Option	When to pick it
GitHub Pages	You already use GitHub and want a clean URL like https://yourname.github.io/your-repo/repository.json. Most community repositories use this.
Raw GitHub	You don't want to enable Pages — https://raw.githubusercontent.com/<user>/<repo>/<branch>/repository.json works just as well.
Your own server	You already host a static site and want to keep everything in one place.

The client uses standard HTTPS GETs and bypasses caches, so any reachable static host is fine.

Step 4: Test your repository locally

Before sharing it, verify the repository loads correctly in your own EmoTracker install:

1. Open EmoTracker's application_settings.json in ~/Documents/EmoTracker.
2. Find the package_repositories array.
3. Add the URL to your repository.json to the array, ex. "package_repositories": ["http://myawesome.package/repository.json"].
4. Reload the package list from the Package Manager.

Your repository should appear with its display name and your pack should be listable, installable, and (after install) loadable. If anything is missing, walk through this checklist:

Symptom	Likely cause
Repository doesn't appear at all	URL is wrong, returns 404, or the host is serving HTML instead of JSON. Open the URL in a browser to confirm you see raw JSON.
Repository loads but a pack is missing	The pack entry is missing one of the required fields (name, uid, link) or version isn't a valid System.Version (v1.0 → no, 1.0 → yes).
Pack appears but install fails	link points at a missing or non-zip file, or the host is rate-limiting downloads.
Pack installs but can't read game memory (autotracker)	The relevant region isn't covered by memory_watch_config.memory_range_whitelist for that game in supported_games.json. This is enforced client-side and is the responsibility of the service, not your pack — see Service Backend Reference → supported_games.json.
Two packs collide on install	Their uid values match. Pick a unique uid.
Official / Featured badges don't show	Expected — these are reserved for the official service URL.

Once everything works in your own client, you can share the URL and users can add it as an Additional Repository themselves with no further setup required.

Step 5: (Optional) Submit to the community list

If you want your repository to appear in every EmoTracker install by default — without users needing to paste a URL — submit it to the community-curated list.

1. Fork EmoTracker-Community/EmoTracker-Service.
2. Edit service/package_repositories.json.
3. Add a new key/value pair: a short, recognizable display name → the URL of your repository.json. Example:

   "yourname.github.io": "https://yourname.github.io/your-repo/repository.json"

4. Open a PR. Once it's merged, every EmoTracker client picks up the new repository on its next startup.

You can read more about how this list is consumed in Service Backend Reference → package_repositories.json.

See also

• Service Backend Reference — full reference for the EmoTracker service backend, including supported_games.json, package_repositories.json, and how the client loads each file.