Media - cressie176/Load64 GitHub Wiki

1. Overview

┌───────────────────────────────┐            ┌────────────────────────────────────────────┐
│                               │           ╱│                                            │
│             Game              │┼─────────○─│                   Media                    │
│                               │           ╲│                                            │
└───────────────────────────────┘            ├────────────────────────────────────────────┤
                                             │ id: integer [pk]                           │
                                             │ game_id: integer [fk, required]            │
                                             │ slot: media_slots [unique(Game), required] │
                                             │ filename: text [required]                  │
                                             └────────────────────────────────────────────┘

Media files for a game are stored in the game's media directory, organised into subfolders by type. The assignment of a file to a media slot (e.g. loading screen, gameplay screen) is recorded in the Media table. Filenames follow the conventions described in section 6.

Cover images are stored under media/cover/ and screenshot images under media/screenshots/. LoadC64 scans these subfolders when the relevant selection screen is displayed to build the list of candidate images. Candidates are ordered by file creation timestamp, oldest first.

games/
└── <game-slug>--<id>/
    └── media/
        ├── cover/
        │   ├── <filename>.png
        │   └── ...
        └── screenshots/
            ├── <filename>.png
            └── ...

For example, a game with slug knight-lore and id 42 might have:

games/
└── knight-lore--42/
    └── media/
        ├── cover/
        │   └── knight-lore--a3f8c1.jpg
        └── screenshots/
            ├── knight-lore--b92d04.png
            ├── knight-lore--c71e3a.png
            └── knight-lore--d40f82.png

With corresponding Media records:

id	game_id	slot	filename
1	42	loading_screen	knight-lore--b92d04.png
2	42	title_screen	knight-lore--c71e3a.png
3	42	gameplay_screen	knight-lore--d40f82.png
4	42	cover_thumbnail	knight-lore--a3f8c1.jpg

2. Media Table

Field	Type	Constraints	Description
id	integer	pk	Surrogate primary key.
game_id	integer	fk, required	Foreign key to Game.
slot	media_slots	unique(game_id), required	The media slot this file is assigned to.
filename	text	required	Filename of the image in the game's media directory.

At most one file may be assigned to each slot per game.

3. Slots

Slot	Required	Height (px)	Width (px)	Notes
cover_thumbnail	no	360	270	Portrait thumbnail used in carousel and library views.
loading_screen	no	800	1280	Screenshot of the original C64 loading screen.
title_screen	no	800	1280	Screenshot of the title screen shown in the game details view.
gameplay_screen	no	800	1280	In-game screenshot displayed in the game details view.

4. Image Scaling

When LoadC64 loads images, they are scaled proportionally to fit entirely within the specified bounding box, maintaining the original aspect ratio. Images are letterboxed if necessary and centered both vertically and horizontally. Images smaller than the bounding box are centered and upscaled.

5. Supported Formats

LoadC64 supports both JPEG and PNG formats.

6. Filename Conventions

How a file is named depends on how it was added.

Added from local file — the original filename is preserved. LoadC64 copies the file into the appropriate media subfolder unchanged. If a file with that name already exists it is overwritten.

Downloaded from URL or fetched from catalogue — the filename is derived from the image content: <game-slug>--<shorthash>.<ext>, where <shorthash> is a short hexadecimal hash of the image bytes and <ext> is the file extension of the original image. For example: knight-lore--a3f8c1.jpg.

Content-based naming means that the same image obtained from different sources — different catalogues, different URLs — always produces the same filename. Fetching an image that is already present in the media directory is therefore idempotent: the existing file is overwritten in place and no duplicate is created.