x.1sav.label

Owner: these specifications, under a reserved name · Applies to: a save’s bundle header, and a card’s part as an index copy · Status: normative schema, optional to carry

What a console lists a save as, so a consumer can show a person a list of saves rather than a list of addresses. The name sits in the x tree because the value belongs to no single producer.

Schema

; ============================================================================
; x.1sav.label - what a console calls a save, and what it says beneath that
;
; An extension key for the Universal Saves Format, defined by these
; specifications under a name reserved in the Vendor Names registry because the
; value belongs to no single producer.
;
; The root here is the value carried under the key, not a bundle. A bundle
; validates against the format's own schema whatever this holds, since an
; extension value is `any` there; this file is what makes the shape checkable.
; ============================================================================

label = {
    0 => line,     ; title  - what the console lists this save as
  ? 1 => line,     ; detail - what it says about the save beyond its name
}

; Byte length rather than character count, and "" is absence, the way `path`
; has it in the format's own schema. The longest of these on real hardware is a
; PS1 title at 64 bytes, so the ceiling is headroom and not a target.
line = tstr .size (1..256)

title is the line the console lists the save under, and is required.

detail is what the save says about itself beyond its name: the progress a game reports, the point the player left off at, the status line printed under the title. A GameCube save keeps one in the second of its two comment strings, and a VMU keeps a longer description for the boot ROM menu than the one it shows in its own. A save that says nothing beyond its name omits it.

Neither field is a slot for whatever a format prints next. The name of the game or of the application that wrote the save is game, and a title a format breaks across two lines for layout is one title: a PS2 title carries a break offset into a single string, and both halves are title.

Where the text comes from

On nearly every format it is in the save’s payload rather than in the directory entry. GameCube keeps a comment address, PS1 keeps its 64-byte title in the save’s first block, a VMU’s descriptions are in the VMS header, a PS2 save keeps its title in icon.sys, and a Neo Geo game writes one into the first 20 bytes of its own data. N64 and Saturn are the exceptions: a controller pak’s note table holds the note name, and a Saturn entry holds a ten-byte comment beside its file name.

Where it goes

The header of the bundle that is the save, because the text travels with the save when it is sliced out. x.1sav.dirent sits on the part instead, being the card’s record rather than the save’s.

A producer MAY repeat the key on a card’s bundle part carrying the save, as an index copy so a consumer can list a card without stepping into payloads. Nowhere else: a device has a handful of components rather than a directory to list, and a collection already indexes its entries with system and game. Producers SHOULD keep the two consistent, and on a mismatch the inner header wins.

A consumer holding both this key and a description SHOULD show title, and MUST NOT treat a description that disagrees as malformed. One is what the console called the save, the other a free-form note the bundle’s author attached.

What a producer may write

A producer MUST NOT write a title or a detail line the save does not say. The latitude is normalization: transcoding out of Shift-JIS, trimming padding a format pads with. A consumer re-deriving the text from the same bytes may land on a slightly different string, and MUST NOT treat that as malformed.

The key is a projection and does not rebuild an entry. A writer copying an entry takes the bytes from dirent; a writer building one takes the fields from the format’s own key, such as x.1sav.dirent.gc-mc. A consumer MUST NOT prefer this key over either.

What does not go here

• When the card wrote the save down. x.1sav.dirent.
• Icons and banners. x.1sav.icon.
• The name the card’s directory holds. path, which a consumer matches on. A title is for showing a person, and the two are not always the same string.
• Which game the save belongs to, including the application that wrote it. game.

When to set it

Only when the producer read the text. A producer that would be guessing omits the key.

A save with no text anywhere has nothing to put here, and whether it has any is the game’s doing rather than the format’s. Neo Geo is where both cases sit side by side: Metal Slug 4 labels its saves METAL SLUG V3, and Fatal Fury 2 writes a binary header with no title in it. The first carries a title, the second carries no key at all, and a producer MUST NOT fill the gap from game.