Games - cressie176/Load64 GitHub Wiki

1. Overview

┌──────────────────────────┐                                                                      ┌──────────────────────────┐
│                          │╲                                                                    ╱│                          │
│          System          │──┼───────────────┐                                ┌────────────────○─│ ThirdPartyCatalogueEntry │
│                          │╱                 │                                │                 ╲│                          │
└──────────────────────────┘                  │                                │                  └──────────────────────────┘
                                              ○                                │
                                             ╱│╲                               ┼
┌──────────────────────────┐           ┌──────────────────────────────────────────────┐           ┌──────────────────────────┐
│                          │╲          │                                              │╲         ╱│                          │
│        GameControl       │─○────────┼│                     Game                     │─○───────○─│      GameCompilation     │
│                          │╱          │                                              │╱         ╲│                          │
└──────────────────────────┘           ├──────────────────────────────────────────────┤           └──────────────────────────┘
                                       │ id: integer [pk]                             │
┌──────────────────────────┐           │ title: text [required]                       │           ┌──────────────────────────┐
│                          │╲          │ sort_title: text [required]                  │           │                          │
│          Player          │─○─────────│ year: integer                                │┼─────────┼│          ROMSet          │
│                          │╱          │ publisher: text                              │           │                          │
└──────────────────────────┘           │ notes: text                                  │           └──────────────────────────┘
                                       │ colour_encoding: colour_encodings [required] │
                                       │ true_drive_emulation: boolean [required]     │
                                       └──────────────────────────────────────────────┘           ┌──────────────────────────┐
                                                              ┼               │                  ╱│                          │
                                                              │               └─────────────────○─│           Media          │
                                                              │                                  ╲│                          │
                                                              ┼                                   └──────────────────────────┘
                                                  ┌───────────────────────┐
                                                  │                       │
                                                  │  LaunchConfiguration  │
                                                  │                       │
                                                  └───────────────────────┘

games/
└── <slug>/
    ├── disks/
    ├── media/
    ├── roms/
    └── snapshots/

A game represents a single title in the library. Each game targets exactly one System — the platform it will be launched on. Each game also has exactly one ROMSet, one LaunchConfiguration, and belongs to zero or more Compilations. Games may also be associated with one or more ThirdPartyCatalogueEntry records linking to third party catalogues such as GameBase64.

Every game is added to the "Untested Games" compilation on import. The user removes it from that compilation once they have verified the game works correctly.

ROM files, media, snapshots, and additional disk images are stored on disk under the game's directory. The directory name is the game's slug (e.g. last-ninja-the--b4e8f1c2). See ID Strategy for details on folder naming and re-association.

The disks/ directory is the default location for additional disk images, including blank disks created outside of LoadC64. It is not created automatically — LoadC64 creates it on first use when the user selects "Other disk…" and saves a file there.

2. Ordering

Games are ordered in the carousel and all compilations by sort_key. Neither sort_title nor sort_key is shown to the user.

sort_title derivation

sort_title is derived by the application from title whenever it changes. It is persisted in the database so it can be used efficiently in the sort_key generated column. The article-normalisation step cannot be expressed cleanly as a SQLite generated column, so the application owns this derivation.

If the title begins with a leading article (The, A, An), move it to the end preceded by a comma (e.g. "The Last Ninja" → "Last Ninja, The").

title	sort_title
The Last Ninja	Last Ninja, The
Atic Atac	Atic Atac
Kung-Fu Master	Kung-Fu Master

sort_key derivation

sort_key is a SQLite GENERATED ALWAYS AS ... STORED column, computed from sort_title, publisher, year, colour_encoding, and the first 8 characters of the ROMSet's rsid. Null values are coalesced to an empty string so they sort consistently.

sort_key = sort_title
        || ' ' || COALESCE(publisher, '')
        || ' ' || COALESCE(CAST(year AS TEXT), '')
        || ' ' || colour_encoding
        || ' ' || SUBSTR(rsid, 1, 8)

Because rsid is unique per ROMSet, sort_key is unique across all games. No fallback to game id is needed.

sort_title	publisher	year	colour_encoding	rsid (first 8)	sort_key
Last Ninja, The	System 3	1987	pal	`b4e8f1c2`	`Last Ninja, The System 3 1987 pal b4e8f1c2`
Jet	Atlantis	1983	pal	`f1a2b3c4`	`Jet Atlantis 1983 pal f1a2b3c4`
Jet	Mikrogen	1984	pal	`a9b8c7d6`	`Jet Mikrogen 1984 pal a9b8c7d6`

3. Slugs

The slug has up to four parts separated by --: the slugified sort_title, the slugified publisher (if set), the year (if set), and the first 8 characters of the ROMSet's rsid. Each part is slugified by applying the following rules:

Lowercase ASCII letters (a-z)
Digits (0-9)
Hyphens (-) as word separators
Must not begin or end with a hyphen
Must not contain consecutive hyphens

sort_title	publisher	year	rsid (first 8)	slug
Last Ninja, The	System 3	1987	`b4e8f1c2`	`last-ninja-the--system-3--1987--b4e8f1c2`
Atic Atac	Ultimate	1983	`a3f9c2d1`	`atic-atac--ultimate--1983--a3f9c2d1`
Kung-Fu Master			`c5d7e0b3`	`kung-fu-master--c5d7e0b3`
Ikari Warriors	Elite	1987	`d6c6f9a4`	`ikari-warriors--elite--1987--d6c6f9a4`
Ikari Warriors	Data East	1987	`e7b5g8h5`	`ikari-warriors--data-east--1987--e7b5g8h5`

The rsid suffix ensures uniqueness even when all other parts are identical. The slug is initialised at import and does not change if title, publisher, or year is later edited.

3. Tables

Game

Field	Type	PK	FK	Nullable	Unique	Description
id	integer	yes				Surrogate primary key.
system_id	integer		System.id			The system this game is launched on.
title	text					Human-readable display title (e.g. `"The Last Ninja"`).
sort_title	text					Article-normalised title. Derived by the application from `title`; not user-facing.
sort_key	text				yes	Generated column combining `sort_title`, `publisher`, `year`, `colour_encoding`, rsid.
slug	text				yes	Unique identifier and folder name (e.g. `last-ninja-the--system-3--1987--b4e8f1c2`).
year	integer			yes		Year of original publication.
publisher	text			yes		Name of the original publisher.
colour_encoding	colour_encodings					The TV colour encoding standard the game requires.
true_drive_emulation	boolean					Whether the game requires true drive emulation in VICE.
notes	text			yes		Free-text notes about the game.

colour_encodings

Each value generates the corresponding VICE argument at launch time.

Value	Description	VICE Arguments
`pal`	PAL.	`-pal`
`ntsc`	NTSC.	`-ntsc`
`unknown`	Colour encoding not known.	(none)

true_drive_emulation

true_drive_emulation is a non-nullable boolean. The value generates the corresponding VICE arguments at launch time.

Value	VICE Arguments
`true`	`-drive8truedrive -drive9truedrive -autostart-handle-tde`
`false`	(none)

4. Computed VICE Arguments

Computed arguments are generated at launch time from colour_encoding and true_drive_emulation. They are computed fresh on every launch, take precedence over all profile and launch configuration arguments, and are never stored as ViceArgument records. See Vice Arguments for the full merging priority.

5. Import Defaults

The number of Player records created at import is determined by the game's multiplayer_mode as supplied by the LoadC64 Catalogue. The player count is not stored on the Game entity — it is derived from the Player records.

multiplayer_mode	Players created
`not_applicable`	0
`unknown`	1
`single`	1
`sequential`	1
`simultaneous`	2

Joystick players are created with the default game controls (up, down, left, right, fire, space) and default port assignments. The user may adjust players and controls during the import flow.

6. Example

game

id	system_id	title	sort_title	slug	year	publisher	colour_encoding	true_drive_emulation	notes
1	1	The Last Ninja	Last Ninja, The	last-ninja-the--system-3--1987--b4e8f1c2	1987	System 3	pal	false