TOSEC - cressie176/Load64 GitHub Wiki

TOSEC (The Old School Emulation Center) is a retrocomputing initiative dedicated to the cataloguing and preservation of software, firmware, and resources for retro systems. The TOSEC DAT files for the Commodore 64 are used to seed the LoadC64 Catalogue — matching ROM files by SHA-1 hash and extracting structured metadata from TOSEC filenames.

This page documents the TOSEC Naming Convention (TNC v4, 2015-03-23) as it applies to C64 software, with notes on how each field maps to LoadC64 concepts.

The authoritative specification is at https://www.tosecdev.org/tosec-naming-convention.

A TOSEC filename encodes all metadata about a ROM image. The full structure is:

Title version (demo) (date)(publisher)(system)(video)(country)(language)(copyright)(devstatus)(media type)(media label)[dump flags][more info].ext

Only Title, (date), and (publisher) are mandatory. All other fields are optional and appear in the order shown above when present.

Two bracket types are used throughout:

Last Ninja, The (1987)(System 3)(PAL)[cr Steve][!].d64

Mandatory. The display title of the software.

• Articles (The, A, An, De, Die, Le, La, Les) are moved to the end, preceded by a comma and space: The Last Ninja → Last Ninja, The.
• Subtitles are appended after - (space-hyphen-space): Robocop - The Last Chapter.
• Forbidden characters are never present: / \ ? : * " < > |
• Apostrophes and hyphens are permitted.
• Numbers and symbols are permitted.

The seeding utility must reverse article normalisation to recover a natural display title:

Detection rule: if the title ends with , The or , A or , An, move the suffix to the front.

Optional. Appears immediately after the title, before the first parenthesis.

The seeding utility should capture this as part of the title or store it separately for reference, but it does not map to a LoadC64 Game field.

Optional. Appears after version, before the date.

Seeding note: Demo entries should be excluded from the LoadC64 Catalogue — they are not complete games.

Mandatory. Always the first parenthesised field after title/version/demo.

Seeding mapping: Extract the four-digit year where known. If the year contains x (e.g. 19xx, 198x), treat as unknown and omit the year field.

Mandatory. Always the second parenthesised field.

Seeding mapping: Map to publisher. If the value is (-), set publisher to null. Strip outer parentheses.

Optional. Used in multi-system DATs to indicate which hardware variant an image is for.

Common C64-relevant values: (C64), (C128), (+4), (VIC-20).

Seeding note: For C64-specific DATs this field is typically absent. If present and not C64, the entry should be excluded from the C64 catalogue.

Optional. Specifies the TV standard when it cannot be inferred from the country.

Seeding mapping: Map to colour_encoding:

Optional. ISO 3166-1 alpha-2 codes, uppercased. Multiple countries separated by - in alphabetical order: (DE-FR), (EU-US).

Selected codes relevant to C64 software:

Seeding mapping — colour_encoding inference from country when video field is absent:

Optional. ISO 639-1 codes, lowercased. Multiple languages in alphabetical order: (en-fr). More than two: (M3) etc.

English is the default — absence of a language field implies English or language-neutral.

Seeding note: Language is not a LoadC64 Game field. Capture in TOSEC notes only.

Optional.

Seeding note: Not a LoadC64 field. May be useful for filtering — PD and Freeware titles are unambiguously safe to include.

Optional.

Seeding note: Prototypes and betas represent distinct ROM variants and should be included as separate ROMSet entries under their game, but flagged in the label field (e.g. "Beta (1986)").

Optional. Describes multi-part media.

Seeding mapping: The total count (of N) determines how many ROM files belong to a ROMSet. Individual files with the same title and publisher that form a set should be grouped into a single ROMSet. The media type and number map to roms[].label (e.g. "Disk 1", "Side A").

Optional. The last parenthesised field before square brackets. Describes the label printed on a physical disk, used to identify which disk to insert at runtime.

Examples:

• (Disk 1 of 2)(Program)
• (Disk 2 of 2)(Data)
• (Disk 3 of 3)(Character Disk)

Seeding mapping: Append to roms[].label for disambiguation where needed: "Disk 1 – Program".

Square bracket flags [ ] describing the image's condition or modification history. Multiple flags on a single file are ordered: modification flags first (alphabetically), then dump process flags.

Numbering: Multiple instances of the same flag are numbered from the second: [a], [a2], [a3]. There is no [a1].

Multiple crackers/hackers: Separated by - within the flag: [h PDX - TRSi].

The seeding utility should apply the following rules based on dump flags:

Square bracket field [ ] appearing after all dump flags. Free-text supplementary information not covered by other fields.

Examples:

• [aka House of TOSEC] — alternate name
• [Req TRS-DOS] — software requirement
• [source code] — source code image
• [data disk] — data-only disk
• [docs] — documentation disk

Seeding mapping: [aka ...] values are useful for matching games that are known under alternate titles. [data disk], [docs], and [source code] entries should be excluded from the game catalogue as they are not playable software.

Multiple programs in one filename, separated by & (space-ampersand-space):

Amidar (19xx)(Devstudio) & Amigos (1987)(Mr. Tosec)

Each segment carries its own metadata. Global flags (shared by all programs in the set) are separated by - before the flag:

Amidar (19xx)(Devstudio) & Amigos (1987)(Mr. Tosec) -(PD)[!]

Seeding note: Multi-image compilations in a single file represent a different use case from a multi-disk game. A compilation file should not be added to the catalogue as a game — its component titles may already exist as individual entries. Skip compilation entries during seeding.

Relevant extensions for C64 software:

The seeding utility should parse a TOSEC filename as follows:

1. Strip the file extension.
2. Split on & — if more than one segment results, this is a compilation; skip it.
3. Extract dump info flags: match all [...] tokens from the right of the string. Remove them from the working string.
4. Extract more info flags: these are [...] tokens that follow all dump flags. In practice, extract all [...] tokens; classify by content.
5. Extract parenthesised fields: match all (...) tokens from the string in order. Remove them from the working string.
6. The remaining text is the title (plus optional version and demo fields).
7. Parse the title for a trailing version string (v\d, Rev \d, vYYYYMMDD).
8. Parse the title for a trailing demo flag ((demo...) — already removed in step 5, but check the ordered list).
9. Parse parenthesised fields in order:
   • Field 1: date
   • Field 2: publisher
   • Field 3+: system, video, country, language, copyright, devstatus, media type, media label — identify by content pattern

Match each (value) token against these patterns in order — use the first match:

1. Video field if present
2. Country field inference if video absent
3. unknown if neither is present or inference is ambiguous

TOSEC provides no TDE flag. Default to false; allow manual override in the catalogue.

TOSEC provides no multiplayer data. Default to unknown; allow manual override in the catalogue.

Build a human-readable romsets[].label from available context:

<video or country> <devstatus> <notable dump flags>

Examples:

The seeding utility should skip a TOSEC entry if any of the following apply:

• The filename contains & (compilation)
• The demo field is present (demo version)
• Any [more info] flag contains data disk, docs, or source code
• Dump flags include [b], [v], [o], or [u]
• The system field is present and is not C64 (or the expected target platform)
• The [m] (modified) flag is present