Data and cache
Hyprism separates persistent player data from replaceable downloads and presentation caches
Application directory
| Platform | Default directory |
|---|---|
| Windows | %LOCALAPPDATA%/Hyprism |
| macOS | ~/Library/Application Support/Hyprism |
| Linux | $XDG_DATA_HOME/Hyprism, or ~/.local/share/Hyprism when unset |
HYPRISM_DATA overrides the complete application directory only if that directory already exists. InstanceDirectory changes only the instance root
At startup, the default HyPrism directory is renamed to Hyprism before Core opens data or runs file migrations. If both directories exist, the launcher merges them into Hyprism. Profiles and instance registries include entries from both directories. Settings from HyPrism take precedence when both have a configuration file. Other files already present in Hyprism take precedence; conflicting old files are preserved under Hyprism/.HyPrism-merge-conflicts/. Core migrations run again after a merge. This automatic rename does not apply when HYPRISM_DATA selects a custom directory.
Use an isolated directory for development:
hyprism_data="$(mktemp -d)"
HYPRISM_DATA="$hyprism_data" dotnet run \
--project Sources/Hyprism.Desktop/Hyprism.Desktop.csproj
Persistent state
| Location relative to application data | Contents |
|---|---|
Config.json | Settings and selected identifiers |
MigrationState.json | Completed durable Core data migrations |
Profiles/Profiles.json | Profile list, identity metadata, and total play time |
Profiles/<profile-id>/ | Profile data, sessions, skins, avatars |
Instances/Instances.json | Registry and display order under the instance root |
Instances/<instance-id>/Meta.json | Name, note, branch, version, installation and play-time metadata |
Instances/<instance-id>/logo.png | Optional custom icon saved by the instance editor at no more than 512 × 512 pixels. Existing icon.png and Icon.png files are also recognized. |
Instances/<instance-id>/UserData/ | Worlds, mods, and game-owned data |
Mirrors/*.mirror.json | User mirror definitions |
LocalNode/Accounts.json | Autonomous profiles, skins, and presence preferences |
LocalNode/Certificate/ | Local certificate authority and server certificates |
Runtime/GameProcesses.json | Process identities used across launcher restarts |
The instance locations above use the default root. When Desktop changes the location, it creates HyprismLibrary inside the selected directory and stores that path in InstanceDirectory. The registry and installation directories move together. Desktop only deletes the old default root or a custom HyprismLibrary root with its .hyprism-library marker after the copy and configuration update succeed. Older arbitrary custom roots remain in place after recognized instance data is copied.
Deleting an instance resolves its ID in the current and recognized legacy roots, removes that instance directory, and rebuilds Instances.json. A registry entry whose directory is already missing is removed during the same resync.
Back up profiles, worlds, configuration, and local account data before migration testing. Session files and certificate private keys must not appear in fixtures or bug reports
Replaceable content
| Location | Contents |
|---|---|
Cache/Game/Versions.json, Patches.json | Source metadata |
Cache/Game/Downloads/ | Game payloads and resumable .part files |
Cache/News/ | Feed and parsed articles |
Cache/Images/News/, Github/ | Encoded remote images |
Jre/, Butler/, DualAuth/ | Downloaded launch tools |
LocalNode/Sessions/<session-id>/ | Per-launch node runtime files and trust bundles |
Do not clear downloads or runtime files while an installation or related game is active. Clearing a cache makes Hyprism retrieve or recreate its contents when needed
Session logs
Each launcher process creates one directory
Logs/<yyyy-MM-dd_HH-mm-ss.fff>/
launcher.log
instance-<instance-id>.log
local-node-<port>.log
local-node-requests-<port>.ndjson
Instance logs capture game standard output and standard error as timestamp|level|source|message records. HytaleClient timestamps, levels, and sources are preserved; exception stack lines use the TRACE level. Local Node logs record route status, timing, lifecycle, and failures; unknown-request journals exclude headers and bodies. A node can continue writing to its original log directory after Desktop closes
Migration rules
Hyprism-owned JSON uses PascalCase filenames and property names. LauncherJsonFile recognizes earlier filenames and moves them to canonical names; deserialization stays case-insensitive
CoreMigrationRunner applies local data migrations before Desktop reads instances, profiles, sessions, or mods. It records a durable step only after the step returns successfully, while the migration itself remains safe to rerun after an interrupted launch
LegacyProfileConfigMigration moves old identity fields into the profile store. Instance and profile migrations preserve compatibility with older directory layouts. Cache migration moves old PWR downloads and remote images to the current directories
Version names are retryable enrichment rather than a one-time migration. Hyprism fills missing names in instance metadata when a configured source can resolve the stored build identifier
Keep migration tests based on temporary copies of old data, and avoid changing game-owned filenames or external protocol casing