Mirrors

A mirror definition tells Hyprism where a source lists versions and serves full images or differential patches. The launcher ships the official source and no preconfigured third-party game mirrors

Storage and validation

Definitions are stored under Mirrors/<id>.mirror.json in the application directory. IMirrorCatalog.Save validates the ID, name, schema version, source type, and required configuration section

IDs contain lowercase ASCII letters, digits, dots, hyphens, and underscores, start with a letter or digit, and have at most 64 characters. The current schema version is 1

Pattern source

This complete example uses a reserved example domain and a static version list. Replace the endpoint and version list with values supplied by the source operator:

{
  "SchemaVersion": 1,
  "Id": "example-source",
  "Name": "Example source",
  "Priority": 100,
  "Enabled": true,
  "SourceType": "pattern",
  "Pattern": {
    "BaseUrl": "https://example.org/game",
    "FullBuildUrl": "{base}/{os}/{arch}/{branch}/0/{version}.pwr",
    "DiffPatchUrl": "{base}/{os}/{arch}/{branch}/{from}/{to}.pwr",
    "VersionDiscovery": {
      "Method": "static-list",
      "StaticVersions": [7, 6]
    }
  }
}

Pattern field	Meaning
BaseUrl	Value substituted for {base}
FullBuildUrl	Full installation template
DiffPatchUrl	Optional differential template
VersionDiscovery	Version-list strategy
OsMapping, ArchMapping, BranchMapping	Override platform or branch strings
DiffBasedBranches	Branches that can use differential patches when a full build is unavailable

URL templates support {base}, {os}, {arch}, {branch}, {version}, {from}, and {to}. Internal platform strings include windows, linux, darwin, amd64, and arm64

For a fresh installation, Hyprism first requests a published full build, even if the branch appears in DiffBasedBranches. If the target has no full build, it follows published patch transitions from another full build. A manifest mirror can list both 0_to_<version>.pwr full builds and <from>_to_<to>.pwr patches for the same branch.

Discovery supports static-list, json-api with Url and JsonPath, manifest with a manifest Url, html-autoindex with Url and an optional HtmlPattern, and head-probe for mirrors without an index. Custom regular expressions are time-limited and invalid expressions are ignored.

head-probe checks full PWR files through FullBuildUrl with HTTP HEAD, beginning at build 1. It locates the highest consecutive build within MaxProbeVersion and checks each lower build before listing it. The default limit is 256. Set MinFileSizeBytes to reject redirect pages and incomplete archives. If the mirror has gaps followed by newer builds, discovery cannot find builds beyond the first gap without an index.

The root Headers object applies to discovery, availability checks, and file downloads. {hytaleAgent} expands to hytale-launcher/<version> and {hytaleVersion} expands to the current official launcher version. Automatic detection of protected PWR files adds User-Agent, x-hytale-launcher-version, and x-hytale-launcher-branch to the saved mirror definition.

Version names and builds

The launcher keeps the numeric build identifier separate from the human-readable game version. The build is used for download paths, patch chains, and instance compatibility, while the version name is shown in the instance creation list and instance details

For JSON API entries, JsonPath points to the version name or numeric build. When an entry is an object, the parser reads a numeric build, buildNumber, buildVersion, buildId, id, or number field when available. Use BuildJsonPath when the build field needs to be specified explicitly

{
  "VersionDiscovery": {
    "Method": "json-api",
    "Url": "{base}/versions",
    "JsonPath": "items[].version",
    "BuildJsonPath": "items[].build"
  }
}

Manifest discovery also reads names from versions[branch][build].version and from gameVersion in matching file entries. This supports manifests where the file path contains only the numeric build, such as 0_to_27.pwr. The files index supplies the actual patch transitions for the requested OS, architecture, and branch. The instance creator lists a build only when a route from a full archive exists. The global versions section supplies names but cannot make a build installable.

A manifest URL and its asset root can differ. If a manifest is available at the host root while its files are under /patches, Hyprism checks a listed file with a one-byte range request and uses the responding root for patch downloads. This also supports mirrors that expose the same manifest at both locations.

The official source reads the authenticated game-assets/version/{branch}.json manifest and follows its signed JSON URL when necessary. The returned name is paired with the latest numeric build from the patches API

The official source applies the same separation to metadata returned with patch steps. The version cache stores the numeric build and display name separately, and the patch cache stores the published transitions per mirror. A canceled fetch does not mark a branch as fresh or save a partial source list, so the next request fetches it again. Older version cache snapshots refresh once after this format change. Existing instance files without a version name continue to use the numeric build as a fallback.

JSON index source

A JSON index provides download URLs instead of constructing every URL from a template:

{
  "SchemaVersion": 1,
  "Id": "example-index",
  "Name": "Example index",
  "SourceType": "json-index",
  "JsonIndex": {
    "ApiUrl": "https://example.org/index.json",
    "RootPath": "hytale",
    "Structure": "flat"
  }
}

Structure accepts flat for branch → platform → filename → URL, or grouped with separate base and patch groups. PlatformMapping and FileNamePattern adapt source naming. Full file names default to v{version}-{os}-{arch}.pwr, differential files to v{from}~{to}-{os}-{arch}.pwr

Discovery and runtime selection

Desktop automatic setup uses IMirrorDiscovery to inspect a public HTTPS endpoint. The UI rejects duplicate endpoints, assigns an ID, saves through the catalog, and calls ReloadMirrorSources. HTTP is accepted only for loopback development

Availability probes check response latency and current-platform versions without downloading a game payload. The official probe needs a valid session from an official profile to query the authenticated patches API

The official source is preferred when it can serve the request. Mirror selection uses enabled sources and cached speed results. Reloading after a source change does not require restarting the launcher

Optional settings

Section	Purpose
Headers	Request headers, including supported {hytaleAgent} substitution
SpeedTest	Ping URL, timeout, and transfer sample size
Cache	Index and speed-test cache lifetimes

Keep private headers out of source control and documentation. The complete model is Sources/Hyprism.Core/Models/MirrorMeta.cs; runtime parsing lives in Game/Sources/JsonMirrorSource.cs

See download settings for the player workflow

Source: MirrorMeta, Mirror services