Iron Curtain — Design Documentation

Backup Archive Format (D061)

ic backup create produces a standard ZIP archive containing the player’s data directory. The archive is not a custom format — any ZIP tool can extract it.

Structure

ic-backup-2027-03-15.zip
├── manifest.json                    # Backup metadata (see below)
├── config.toml                      # Engine settings
├── profile.db                       # Player identity (VACUUM INTO copy)
├── achievements.db                  # Achievement collection (VACUUM INTO copy)
├── gameplay.db                      # Event log, catalogs (VACUUM INTO copy)
├── keys/
│   └── identity.key                 # Ed25519 private key
├── communities/
│   ├── official-ic.db               # Community credentials (VACUUM INTO copy)
│   └── clan-wolfpack.db
├── saves/                           # Save game files (copied as-is)
│   └── *.icsave
├── replays/                         # Replay files (copied as-is)
│   └── *.icrep
└── screenshots/                     # Screenshot images (copied as-is)
    └── *.png

Manifest:

{
  "backup_version": 1,
  "created_at": "2027-03-15T14:30:00Z",
  "engine_version": "0.5.0",
  "platform": "windows",
  "categories_included": ["keys", "profile", "communities", "achievements", "config", "saves", "replays", "screenshots", "gameplay"],
  "categories_excluded": ["workshop", "mods", "maps"],
  "file_count": 347,
  "total_uncompressed_bytes": 524288000
}

Key implementation details:

• SQLite databases are backed up via VACUUM INTO — produces a consistent, compacted single-file copy without closing the database. WAL files are folded in.
• Already-compressed files (.icsave, .icrep) are stored in the ZIP without additional compression (ZIP Store method).
• ic backup verify <archive> checks ZIP integrity and validates that all SQLite files in the archive are well-formed.
• ic backup restore preserves directory structure and prompts on conflicts (suppress with --overwrite).
• --exclude and --only filter by category (keys, profile, communities, achievements, config, saves, replays, screenshots, gameplay, workshop, mods, maps). See decisions/09e/D061-data-backup.md for category sizes and criticality.

Screenshot Format (D061)

Screenshots are standard PNG images with IC-specific metadata in PNG tEXt chunks. Any image viewer displays the screenshot; IC’s screenshot browser reads the metadata for filtering and organization.

PNG tEXt Metadata Keys

Filename convention: <data_dir>/screenshots/<YYYY-MM-DD>-<HHMMSS>.png (UTC timestamp). The screenshot hotkey is configurable in config.toml.

ic-cnc-content Write Support

ic-cnc-content currently focuses on reading C&C file formats. Write support extends the crate for the Asset Studio (D040) and mod toolchain:

All binary encoders reference the EA GPL source code implementations documented in § Binary Format Codec Reference. The source provides complete, authoritative struct definitions, compression algorithms, and lookup tables — no reverse engineering required.

Planned deferral note (.mix write support): .mix encoding is intentionally deferred to M9 / Phase 6a as an optional creator-path feature (P-Creator) after the D040 Asset Studio base and D049 Workshop/CAS packaging flow are in place. Reason: loose-file mod packaging remains a valid path, so .mix writing is not part of M1-M4 or M8 exit criteria. Validation trigger: M9 creator workflows require retro-compatible archive packaging for sharing/export tooling.

Owned-Source Import & Extraction Pipeline (D069/D068/D049, Format-by-Format)

This section defines the implementation-facing owned-install import/extract plan for the D069 setup wizard and D068 install profiles, including the requirement that the C&C Remastered Collection import path works out of the box when detected.

It complements:

• D069 (first-run + maintenance wizard UX)
• D068 (install profiles and mixed-source content planning)
• D049 (integrity, provenance, and local CAS storage behavior)

Milestone placement (explicitly planned)

• M1 / P-Core: parser/readiness foundation and source-adapter contracts
• M3 / P-Core: player-facing owned-install import/extract baseline in D069 (Steam Remastered, GOG, EA, manual owned installs)
• M8 / P-Creator: CLI import diagnostics, import-plan inspection, repair/re-scan tooling
• M9 / P-Creator: SDK/Asset Studio inspection, previews, and provenance tooling over the same imported data

Not in M1-M3 scope:

• authoring-grade transcoding during first-run import (.vqa -> .mp4, .aud -> .ogg)
• SDK-era previews/thumbnails for every imported asset
• any Workshop mirroring of proprietary content (blocked by D037/D049 policy gates)

Source adapter model (how the importer is structured)

Owned-source import is a two-stage pipeline:

1. Source adapter (layout-specific)

   • Detects a source install and enumerates source files/archives.
   • Produces a source manifest snapshot (path, size, source type, integrity/probe info, provenance tags).
   • Handles source-layout differences (including the Remastered Steam install layout) and feeds normalized import candidates into the shared importer.

2. Format importer (shared, format-specific)

   • Parses/validates formats via ic-cnc-content (and source-specific adapters where needed)
   • Imports/extracts data into IC-managed storage/CAS
   • Builds indexes used by D068 install profiles and D069 maintenance flows
   • Emits provenance and repair/re-scan metadata

This keeps Remastered/GOG/EA path handling isolated while preserving a single import/extract core.

D069 import modes (copy / extract / reference-only)

D069 source selections include an import mode. The implementation contract is:

• copy (default for owned/proprietary sources in Quick Setup):
  • Copy required source files/archives into IC-managed storage.
  • Source install remains read-only.
  • Prioritizes resilience if the original install later moves/disappears.
• extract:
  • Extract playable assets into IC-managed storage/CAS and build indexes.
  • Also keeps source install read-only.
• reference-only:
  • Record source references + indexes without claiming a portable imported copy.
  • Deferred to M8 (P-Creator) for user-facing tooling exposure (advanced/diagnostic path). Not part of the M3 out-of-the-box player baseline.

Format-by-format handling (owned-install import/extract baseline)

Verification and provenance outputs (required importer artifacts)

Every owned-source import/extract run must produce:

• Source manifest snapshot (what was detected/imported, from where)
• Per-item import/verify results (success / failed parse / failed verify / skipped)
• Installed-content provenance records (owned local import vs downloaded package)
• Repair/re-scan metadata for D069 maintenance and D068 Installed Content Manager

These artifacts power:

• Repair & Verify
• Re-scan Content Sources
• source-switch guidance
• provenance visibility in D068/D049 UI

Execution overlay mapping (implementation sequence)

• G1.x (M1 format/import readiness substeps): parser coverage + source-adapter contracts + source-manifest outputs
• M3.CORE.PROPRIETARY_ASSET_IMPORT_AND_EXTRACT: player-facing D069 import/extract baseline (including Remastered out-of-box path)
• G21.x (M8 creator/operator support substeps): import diagnostics, plan inspection, re-extract/re-index tooling, and documentation

The developer checklists in 18-PROJECT-TRACKER.md mirror this sequencing and define proof artifacts per stage.