This document covers the preset catalog infrastructure, download flow, update detection mechanism, session XML baking for UCM presets, and the .catalog_state.json sidecar format.

UCM distributes presets through two GitHub-hosted catalogs:

Both catalogs are fetched over HTTPS from GitHub's raw content CDN. The app uses HttpClient with a 10-second timeout and a User-Agent header of UltimateCameraMod/3.0.

The catalog is a JSON object with a top-level presets array. Each entry in the array has the following shape:

{
  "presets": [
    {
      "id": "panoramic-v2",
      "file": "panoramic-v2.ucmpreset",
      "name": "Panoramic v2",
      "author": "0xFitz",
      "description": "Wide cinematic camera with smooth transitions.",
      "url": "https://www.nexusmods.com/crimsondesert/mods/438",
      "version": "1.2",
      "sha256": "a1b2c3d4e5f6...",
      "size_bytes": 48320,
      "tags": ["cinematic", "wide", "steadycam"]
    }
  ]
}

In CommunityBrowserDialog.xaml.cs, catalog entries are deserialized into a private sealed class:

private sealed class CatalogEntry
{
    public string Id { get; set; } = "";
    public string File { get; set; } = "";
    public string Name { get; set; } = "";
    public string Author { get; set; } = "";
    public string Description { get; set; } = "";
    public string Url { get; set; } = "";
    public string Version { get; set; } = "";
    public string Sha256 { get; set; } = "";
    public long SizeBytes { get; set; }
    public string[] Tags { get; set; } = Array.Empty<string>();
}

Parsing uses System.Text.Json.JsonDocument with manual property extraction via TryGetProperty. This is deliberate: it makes the parser tolerant of missing fields and avoids exceptions when the catalog evolves.

Presets are stored in directories relative to the executable:

UltimateCameraMod.V3.exe
ucm_presets/
    catalog_state.json          <-- sidecar for update detection
    panoramic-v2.ucmpreset
    heroic.ucmpreset
    ...
my_presets/
    my-custom-camera.ucmpreset
community_presets/
    some-community-preset.ucmpreset
    ...
import_presets/
    ...

The directory constants are defined in MainWindow.xaml.cs:

private const string UcmPresetsDirName = "ucm_presets";
private const string MyPresetsDirName = "my_presets";
private const string CommunityPresetsDirName = "community_presets";
private const string ImportPresetsDirName = "import_presets";

The CommunityBrowserDialog is a WPF Window that serves both UCM and community preset browsing. It is parameterized at construction time:

public CommunityBrowserDialog(
    string presetsDir,
    Action onPresetsChanged,
    string catalogUrl = "https://raw.githubusercontent.com/FitzDegenhub/UltimateCameraMod/main/community_presets/catalog.json",
    string rawBaseUrl = "https://raw.githubusercontent.com/FitzDegenhub/UltimateCameraMod/main/community_presets/",
    string title = "Community Presets",
    bool needsSessionXmlBake = false)

When opened for UCM presets, the caller passes:

• catalogUrl: points to the main branch catalog
• rawBaseUrl: the raw GitHub base URL for that branch
• needsSessionXmlBake: true: signals that downloaded presets contain only style definitions and need session XML generation

When opened for community presets, defaults apply and needsSessionXmlBake is false.

1. Fetch catalog: FetchCatalogAsync() fires on Loaded. The raw JSON is fetched, parsed, and stored in _catalog.

2. Render cards: RenderPresetList() iterates the catalog entries. For each entry, IsPresetDownloaded() checks whether the file already exists on disk. Downloaded presets show a disabled "Downloaded" button; others show an active "Download" button.

3. Download click: OnDownloadClick handler:

   • Disables the button and shows "Downloading..."
   • Fetches raw bytes from _rawBaseUrl + entry.File
   • Enforces a 2 MB size cap (MaxPresetSize = 2 * 1024 * 1024)
   • Validates the downloaded content is valid JSON containing either session_xml, RawXml, or style_id
   • Saves raw bytes to disk (not re-serialized, to preserve the exact SHA hash)
   • Updates .catalog_state.json with the entry's SHA-256 hash (UCM presets only)
   • Invokes _onPresetsChanged callback to refresh the sidebar

4. Filename resolution:

   • UCM presets (needsSessionXmlBake == true): use entry.File directly as the filename
   • Community presets with a File field: use Path.GetFileName(entry.File)
   • Fallback: {entry.Id}.ucmpreset

In addition to the browser dialog, UCM performs an automatic background fetch on every launch via FetchUcmPresetsAsync() in MainWindow.Community.cs. This method:

1. Fetches the UCM catalog
2. Iterates entries and checks whether each file exists locally
3. Downloads only missing presets (does not update existing ones)
4. Updates .catalog_state.json for each new download
5. Calls RefreshPresetManagerLists on the dispatcher to update the sidebar

Existing presets with SHA mismatches are handled separately by the update detection system (see below), not by this initial fetch.

The .catalog_state.json file is a simple JSON dictionary mapping filenames to their SHA-256 hashes. It lives inside the ucm_presets/ directory.

{
  "panoramic-v2.ucmpreset": "a1b2c3d4e5f6789...",
  "heroic.ucmpreset": "9f8e7d6c5b4a321..."
}

This sidecar file records the SHA-256 hash of each preset file at the time it was downloaded from the catalog. It serves as the "last known remote state" for update detection.

Writing (after download):

string statePath = Path.Combine(_presetsDir, ".catalog_state.json");
var state = new Dictionary<string, string>();
if (File.Exists(statePath))
{
    string stateJson = File.ReadAllText(statePath);
    state = JsonSerializer.Deserialize<Dictionary<string, string>>(stateJson) ?? new();
}
state[destFileName] = entry.Sha256;
File.WriteAllText(statePath,
    JsonSerializer.Serialize(state, new JsonSerializerOptions { WriteIndented = true }));

Reading (during update check): ReadCatalogState() deserializes the file into a Dictionary<string, string>.

Downloaded preset files are written to disk as raw bytes (File.WriteAllBytesAsync), not re-serialized from parsed JSON. This is critical because re-serialization would alter formatting, whitespace, and key ordering, which would produce a different SHA-256 hash and break update detection.

UCM checks for preset updates at launch via two async methods:

• CheckUcmPresetUpdatesAsync() for UCM presets
• CheckCommunityPresetUpdatesAsync() for community presets

The algorithm for UCM presets:

1. Fetch the remote catalog and build a Dictionary<string, string> of filename -> sha256
2. Read the local .catalog_state.json sidecar
3. For each preset in the sidebar:
   • Skip non-UCM presets and placeholders
   • Look up the filename in the sidecar. If there is no sidecar entry, skip (the preset was manually placed or pre-installed, not downloaded through the app)
   • Compare the sidecar's stored SHA against the catalog's SHA
   • If they differ, set item.HasUpdate = true on the PresetManagerItem

Community presets do not use the sidecar file. Instead, the local file's SHA-256 is computed on the fly:

1. Fetch the remote catalog and build a Dictionary<string, string> of id -> sha256
2. For each community preset in the sidebar:
   • Read the local file bytes and compute SHA256.HashData(bytes)
   • Compare against the catalog hash
   • If they differ, set HasUpdate = true

When HasUpdate is true on a PresetManagerItem, the sidebar displays a pulsating update icon next to the preset name. Clicking this icon triggers OnPresetUpdateClick.

OnPresetUpdateClick presents a three-way dialog:

1. Yes: Duplicate the current version to my_presets/ with _old suffix before downloading the update
2. No: Overwrite directly without saving the old version
3. Cancel: Abort the update

The duplication logic:

string dupName = $"{item.Name}_old";
string dupPath = Path.Combine(MyPresetsDir, $"{SanitizeFileStem(dupName)}.ucmpreset");
// Read existing file, change name/kind/locked, write to my_presets

After downloading the update:

• UCM presets: raw bytes are written and the sidecar is updated
• Community presets: the file is rebuilt with metadata (name, author, description, url) preserved from the existing file where the download lacks those fields

After update, both CheckUcmPresetUpdatesAsync and CheckCommunityPresetUpdatesAsync are re-invoked to refresh update icons on other presets.

UCM presets and community presets differ fundamentally in what they contain:

The session_xml is the complete, modified playercamerapreset.xml content that gets compressed and written into the game's 0.paz archive. It is the final output of the camera modification pipeline.

UCM preset files in the repository contain a style definition (parameters like style_id, distance, height, offset values) but no session_xml. The session XML must be generated locally because it depends on the user's game installation:

1. Read vanilla XML: CameraMod.ReadVanillaXml(gameDir) extracts the unmodified camera XML from the game's PAZ archive or backup
2. Apply CameraRules: The style definition and user settings are passed through CameraRules.BuildModifications() to produce a ModificationSet
3. Generate modified XML: CameraMod.ApplyModifications(vanillaXml, modSet) produces the final session XML
4. Store: The session XML is saved into the preset file's session_xml field

This baking is performed by GenerateBuiltInPresets(), which is called:

• After the game directory is detected
• After new UCM presets are downloaded via the browser dialog

Community presets are authored by third parties who have already generated the full session XML against a specific game version. The preset file shipped in the community repository contains the complete session_xml, so it can be used directly without access to the user's vanilla game files. This also means community presets are tied to a specific game version and may need updates when the game patches.

The CommunityBrowserDialog constructor accepts a needsSessionXmlBake boolean. When true:

• The header subtitle changes to mention "official UCM camera presets"
• Downloaded files use entry.File directly as the local filename (not just Path.GetFileName)
• The main window's onPresetsChanged callback triggers GenerateBuiltInPresets() in addition to RefreshPresetManagerLists

The download system is designed to fail gracefully:

• Network timeouts (10s for catalog, 15s for individual downloads) prevent the UI from hanging
• Individual download failures are caught and shown on the button ("Failed") with a status bar message
• Catalog fetch failures show a full error panel with a "Retry" button
• Background fetch (FetchUcmPresetsAsync) catches all exceptions silently to avoid interrupting startup
• Invalid preset content (missing session_xml, RawXml, or style_id) is rejected with an "Invalid" label