Packaging and Release

Relevant source files

The following files were used as context for generating this wiki page:

Purpose and Scope

The packaging and release subsystem of XIVUpscaler transforms processed texture assets into distributable Penumbra mod packages and immutable, versioned filesystem archives. This tier serves as the final boundary between internal pipeline storage and user-facing distribution formats.

As a parent page, this document provides a high-level overview of the architectural components implemented in clarity/packaging/penumbra.py clarity/packaging/penumbra.py:1-163 and clarity/packaging/release.py clarity/packaging/release.py:1-183. For deep technical details, see the child pages:

7.1 Penumbra Mod Generation

Penumbra mod generation aggregates processed textures into logical mod directories structured for the Penumbra mod loader. The mapper maps internal game families (equipment, bg, human-body, etc.) into consolidated mod folders defined by MODS clarity/packaging/penumbra.py:23-42. To avoid system ANSI codepage decoding errors in FFXIV's native file loader, all mod folder names enforce strict ASCII-only constraints clarity/packaging/penumbra.py:16-22.

The packer function pack() clarity/packaging/penumbra.py:163 reads from the SQLite manifest and builds single-select tier option groups via options_for() clarity/packaging/penumbra.py:62-88. Metadata is serialized into meta.json conforming to Penumbra FileVersion 4 format via write_mod_json() clarity/packaging/penumbra.py:103-160.

graph TD
    A["ManifestDatabase"] -->|Query Records| B["pack() clarity/packaging/penumbra.py"]
    B -->|Categorize Families| C["MODS clarity/packaging/penumbra.py"]
    C -->|Build Tiers| D["options_for() clarity/packaging/penumbra.py"]
    D -->|Write Config| E["write_mod_json() clarity/packaging/penumbra.py"]
    E -->|Output| F["meta.json FileVersion 4"]

Sources: clarity/packaging/penumbra.py:1-163, tests/test_single_sources.py:1-19

For details, see Penumbra Mod Generation.

7.2 Versioned Release Export

Versioned release export handles the creation of immutable, distributed builds tied to specific FFXIV game revisions. The taxonomic structure of game data families is defined by CATALOG in clarity/packaging/release.py clarity/packaging/release.py:17-56. Version validation is handled by version_key() clarity/packaging/release.py:60-65 and version_for() clarity/packaging/release.py:68-78.

The export() function clarity/packaging/release.py:140-183 enforces that working products are never moved or requeued clarity/packaging/release.py:1. It uses a .building staging directory suffix clarity/packaging/release.py:149 to ensure that interrupted or incomplete exports never block subsequent attempts or leave corrupt state on disk.

graph TD
    G["CLI Command Dispatcher"] -->|Invoke Export| H["export() clarity/packaging/release.py"]
    H -->|Validate Version| I["version_for() clarity/packaging/release.py"]
    H -->|Stage Files| J[".building Staging Directory"]
    J -->|Commit Complete Build| K["Immutable Release Target"]
    K -->|Emit Metadata| L["release.json Summary"]

Sources: clarity/packaging/release.py:1-183

For details, see Versioned Release Export.

Home · Repository · Migrated from DeepWiki