Prepare a gallery cover

阅读中文版

The gallery cover is the character's public first impression. It is not the canonical portrait and it is not an outcome illustration. A portrait may be selected as the cover, but the Creator must make that selection explicitly and author the crop, alternative text, hook, and disclosure boundary.

What to deliver

Provide one reviewed static image and the following Creator-owned presentation:

• a short hook that introduces why this relationship is worth opening;
• alternative text that describes only what the image visibly depicts;
• the focal point that must remain in frame when the image is cropped to 3:4;
• facts that the cover and hook are allowed to make public; and
• facts that the discovery presentation must not reveal.

The current machine-checked image formats are .avif, .jpeg, .jpg, .png, and .webp. The file suffix and image signature must agree, the file must not be empty, and catalog admission limits one cover to 16 MiB. Animated GIF and SVG files are not accepted as gallery covers. The gallery renders a 3:4 crop. A source image may use another ratio, but the Creator-provided focal point controls the crop.

For reliable results, we recommend a source image of at least 900 × 1200 pixels, with the face and identity-defining details clear at phone-card size. Keep essential details away from the outer edge and avoid baking titles, buttons, status labels, or other platform UI into the artwork. These are review recommendations; the current compiler validates the file type and typed crop, not pixel dimensions or subjective composition quality.

Exact visual.yaml shape

Add discovery beneath visual:

visual:
  identity:
    # Existing visual identity fields.
  portrait:
    # Existing canonical portrait asset.
  discovery:
    short_hook: She has one decision left to make before morning, and no safe answer.
    gallery_cover:
      content_version: 1
      asset:
        id: character_gallery_cover_v1
        source_path: assets/character-gallery-cover-v1.png
        provenance_ref: creator://reviewed-gallery-cover-v1
      alt_text: A young apothecary holds a glowing blue crystal in her stone-walled workshop.
      crop:
        aspect_ratio: "3:4"
        focal_point:
          x_percent: 50
          y_percent: 34
    public_fact_ids:
      - character_is_an_apothecary
    forbidden_fact_ids:
      - character_hidden_debt
  outcomes:
    # Existing outcome depictions.

The package may point gallery_cover.asset.source_path at the same reviewed file as portrait, but it still declares a separate cover asset and public presentation. This makes the choice explicit instead of treating a portrait as an accidental fallback.

Contract rules

• short_hook is Creator-authored public copy in the package's default locale, from 1 to 160 Unicode characters.
• content_version is a strict positive integer. It versions creative content; it does not prove approval or publication.
• asset.id is unique inside the package. source_path uses the same package-local or approved historical namespace as other visual assets.
• alt_text is from 1 to 500 Unicode characters and must not disclose more than the image and public_fact_ids permit.
• aspect_ratio is currently exactly "3:4".
• x_percent and y_percent are strict integers from 0 to 100. They locate the most important visual point for responsive object-fit: cover cropping.
• public_fact_ids contains unique, initially user-disclosable world facts.
• forbidden_fact_ids contains unique facts from the package fact graph. The public and forbidden sets cannot overlap.
• Hook, image, and alt text may express the visual identity and listed public facts. Omitting a fact from forbidden_fact_ids does not make it public.

provenance_ref records where an asset came from. It is not a rights grant, exact-asset approval, publication approval, or release eligibility. Those remain separate reviewed controls.

How the gallery uses it

The Creator package owns portrayal and public copy. The platform catalog owns whether an experience is playable or a creator_preview, its route, and its curated order. A user's private relationship overlay may later add truthful states such as “continue contact,” “waiting for news,” or “message available.” Neither platform status nor private relationship history belongs in visual.yaml.

A complete Creator package may still appear as creator_preview: that status means the platform has not opened a relationship route, not that the package is structurally incomplete. Consumer discovery and Creator Portal project browsing may read the same presentation, while a Portal card does not claim that a full Workbench detail or Test Lab projection exists.

A package without visual.discovery can still be read for backward compatibility, but it is not eligible for the package-driven gallery. A successful compile also does not publish the package.

Review checklist

• The image is recognizable at a small card size and survives the declared 3:4 crop.
• The focal point keeps the face and identity-defining prop or silhouette in frame on desktop and mobile.
• The hook creates curiosity without summarizing the whole plot or promising a route the current experience cannot deliver.
• Alt text is useful and factual, not marketing copy.
• No private motive, future outcome, hidden relationship state, or spoiler is visible in the image or copy.
• The exact bytes, provenance, allowed use, credit, and review scope are clear.
• The cover remains Creator intent even if the platform changes card layout, status copy, or catalog order.

For the rest of the seven-file package, continue with the technical quickstart and the shared field reference.