Service Backend Reference

Service Backend Reference

This page documents the EmoTracker service backend — the static collection of JSON files that the EmoTracker client downloads at startup to discover supported games, community package repositories, and (historically) application updates.

It is a technical reference intended for contributors to the EmoTracker-Service repository and for anyone who needs to understand how the client consumes these files.

If you're looking for instructions on how to publish your own pack, see Hosting a Package Repository instead.

Source of truth: This page reflects the formats consumed by the avalonia branch of EmoTracker-Community/EmoTracker. The reference implementation lives in EmoTracker.Data/Packages/PackageManager.cs and EmoTracker.Data/Packages/PackageRepository.cs.

Overview

When EmoTracker starts, it talks to a "service" — a static collection of JSON files (and optional images) hosted over HTTPS. The service tells the client:

1. Which games are supported and what their metadata is — supported_games.json
2. Which package repositories the community publishes — package_repositories.json
3. For each repository, which packs are available — that repository's own repository.json (see Hosting a Package Repository for the per-repository file format).

The community service is hosted at:

https://emotracker-community.github.io/EmoTracker-Service/service/

This URL is the default value of the service_base_url setting in the EmoTracker client (ApplicationSettings.ServiceBaseURL). All relative paths in the service files are resolved against this base.

The service repository itself is EmoTracker-Community/EmoTracker-Service; changes to any of the files below are made via pull request there.

File layout

service/
├── supported_games.json         # Master list of games + memory access policy
├── package_repositories.json    # Map of community repositories
├── application_version.json     # Legacy; no longer read by the avalonia client
├── games/                       # Game logo images referenced from supported_games.json
│   ├── alttpr_logo.png
│   └── ...
└── packages/
    ├── repository.json          # The official EmoTracker repository
    └── *.zip                    # Pack downloads for the official repository

The packages/ directory is just the official repository — its repository.json is one of many entries in package_repositories.json and is consumed by the same code path as any community-hosted repository.

supported_games.json

The master list of games EmoTracker recognizes. The top-level value is an object keyed by game key. Each pack's game_name field (in a repository.json entry) must match one of these keys to associate the pack with a known game in the UI.

Parsed in PackageManager.cs:OnGameListDownloadCompleted.

Schema

{
  "<game key>": {
    "name":             "<display name>",        // optional, defaults to the key
    "series":           "<series name>",         // optional
    "image":            "games/<file>.png",      // optional, resolved against service_base_url
    "priority":         0,                       // optional int, default 10000 (lower = higher in list)
    "series_priority":  1,                       // optional int, default 10000
    "memory_watch_config": {                     // optional; controls autotracker memory access
      "memory_range_whitelist": [
        "0x00ffb0:0x00ffdf",
        "0x7e0000:0x7e00b0"
      ],
      "memory_range_blacklist": []
    }
  }
}

Field notes

• name — Display name shown in the package manager. If omitted, the JSON key is used.
• series — Used to group games together in the UI. Free-form string.
• image — A path relative to service_base_url (so games/alttpr_logo.png resolves to <service_base_url>games/alttpr_logo.png). If omitted, a default banner is used.
• priority / series_priority — Sort order. Lower numbers appear first; the default of 10000 puts unspecified games at the bottom. Note that the Development entry uses series_priority: 10001 to push it past the default and to the very end.
• memory_watch_config — Defines which memory regions an autotracker is allowed to read for this game. This is a security boundary, not a hint:
  • Each entry is a string "0xBEGIN:0xEND" (hexadecimal, inclusive). Parsing is done by PackageManager.Game.MemoryRange.TryParse.
  • END must be >= BEGIN, otherwise the entry is rejected.
  • If the memory_watch_config block exists but fails to parse, the entire address space is blacklisted (0x0 – 0xFFFFFFFFFFFFFFFF). Be careful with the syntax.
  • If the block is omitted entirely, no whitelist/blacklist is applied for the game.

Example

{
  "A Link to the Past Randomizer": {
    "name": "The Legend of Zelda: A Link to the Past",
    "series": "Legend of Zelda",
    "series_priority": 1,
    "priority": 0,
    "image": "games/alttpr_logo.png",
    "memory_watch_config": {
      "memory_range_whitelist": [
        "0x00ffb0:0x00ffdf",
        "0x7e0000:0x7e00b0",
        "0x7ef000:0x7ef500"
      ],
      "memory_range_blacklist": []
    }
  }
}

Adding a new game

To add a game to EmoTracker's master list, open a PR against service/supported_games.json adding a new top-level entry. If your pack uses an autotracker, include a memory_watch_config block listing the address ranges the tracker needs to read.

package_repositories.json

A flat object mapping a display name to a URL pointing at a repository.json. This is how the community curates the default list of repositories that ship with every copy of EmoTracker.

Parsed in PackageManager.cs:OnRepositoryListDownloadCompleted.

Schema

{
  "<display name>": "https://example.com/path/to/repository.json",
  "...": "..."
}

Behavior

• The client downloads this file at startup, then for each entry constructs a PackageRepository and downloads its repository.json.
• On reload, repositories that are no longer in the list are removed; new ones are added.
• After processing the community list, any user-configured "additional repositories" (from ApplicationSettings.AdditionalRepositories) are loaded as well, so users can subscribe to repositories that aren't in the official list.
• The display-name key is what appears in the UI when the repository's own name field hasn't loaded yet (or is missing).

Adding a repository to the community list

Open a PR against service/package_repositories.json adding a new key/URL pair pointing at your repository.json. Keep the key short and recognizable (typically the host name or your handle). See Hosting a Package Repository → Submitting to the community list for the full workflow.

repository.json

This is the per-repository file format that lists the actual packs. Because it's the file pack authors write themselves, its full schema and conventions are documented on the hosting page:

→ Hosting a Package Repository

It is parsed in PackageRepository.cs:MWebClient_DownloadDataCompleted.

Client behavior summary

File	Loaded from	Cache policy	Failure mode
supported_games.json	<service_base_url>supported_games.json	NoCacheNoStore	Game silently dropped on per-entry exception
package_repositories.json	<service_base_url>package_repositories.json	NoCacheNoStore	CommunityRepositoryListError = true
repository.json	URL from package_repositories.json or user's additional list	NoCacheNoStore	Repository marked DownloadStatus.Error
Pack .zip	link field of a repository.json entry	BypassCache	Repository entry marked DownloadError

The service_base_url is configurable in the user's ApplicationSettings; everything in this document assumes the default value pointing at the community service.

Legacy: application_version.json

The legacy WPF EmoTracker also consumed an application_version.json file at the service root for self-update. Its format was:

{
  "version": "2.3.8.21",
  "link": "https://emotracker.net/service/install/emotracker_setup_2_3_8_21.exe"
}

This file is no longer read by the avalonia branch — application self-update was removed in favor of distributing builds via GitHub releases. The file still exists in the service repo for compatibility with older WPF builds, but the avalonia client never requests it and new code paths can ignore it entirely.