Collections
A collection is a curated grouping of related games - a franchise, a studio's back catalogue, a "best of" shelf, or any theme you like. GamesDownloader treats a collection as a game-like entity in its own right: it has its own cover, description, year range and rating, but instead of a single title it groups several games from your library through a many-to-many membership.
Collections are admin-curated. Members always stay in their home library (GOG or Games); adding a game to a collection is purely additive and never moves it. A game can belong to any number of collections at once.
- How collections are organised
- What can be a member
- Creating a collection
- Adding and removing members
- Editing a collection
- Artwork: cover, hero and logo
- Metadata scraping
- Automatic vs manual facts
- Where collections appear
- Browsing a collection
- Deleting a collection
- API reference
Every collection lives inside a container library - a library of kind collections. Containers are created and managed like any other library (see Library); there is no permanent built-in container, and deleting a container removes the collections inside it. This lets you keep several separate shelves, for example a "Franchises" container and a "Curated" container, each with its own icon, colour and visibility.
Inside a container, each collection is stored with a URL slug derived from its name, so two collections cannot share the same name.
A collection is distinct from a library. A library is where a game lives; a collection is an additional grouping a game appears in. A game keeps its single home library (GOG or Games) and can additionally be a member of several collections.
Members are always local library games - any owned title in your Games or GOG library. This is deliberately broader than user-created libraries (which are Games-only): a GOG-sourced game you have downloaded can be collected too.
ROMs cannot be added to collections. Membership links to library game records only, so emulation titles in the ROM library are not eligible. Unowned GOG catalogue entries (which live on GOG's servers) also cannot be collected - only games that exist as records in your library.
Because members are ordinary library games, opening a member from a collection takes you to that game's normal detail page in its home library.
Creating collections is an admin action.
- Open a collections container library from the sidebar or home.
- In the grid view, click New collection (visible to admins).
- Enter a name and confirm.
The new collection is created empty inside that container and you are taken straight to its detail page, ready to add members and artwork. Its cover starts as an auto-stack of member covers until you set a custom one (see below).
Membership is edited from the game side, in the game's metadata editor, not from the collection. Open any Games or GOG title, open its metadata editor, and use the collections section to tick the collections that game should belong to. Because a game can live in several containers, each collection is shown with its container library name to disambiguate.
Saving replaces the full set of collections for that game in one operation. This is backed by the membership endpoints:
-
GET /api/collections/membership/{game_id}returns the collection slugs a game belongs to. -
PUT /api/collections/membership/{game_id}replaces that set (body:{"collections": ["slug-a", "slug-b"]}). Unknown slugs are ignored.
Removing a game from a collection is simply unticking it and saving. Deleting the collection itself, or deleting a member game, never harms the other side of the relationship.
Admins get an Edit button on a collection's detail view (and on its cover overlay in the Classic theme), which opens the collection metadata editor. The editor has five tabs:
| Tab | What it does |
|---|---|
| Cover | Search sources for a cover, or upload / revert a custom one |
| Hero | Search or upload the detail backdrop image |
| Logo | Search or upload a transparent clearlogo |
| Description | Fetch descriptions from multiple sources, plus manual long / short text fields |
| Details | Name, year range, rating and Time to Beat - each with an "Auto" toggle |
Edits are saved with PATCH /api/collections/{slug}. Only the fields you actually change are touched. Setting a field's override back to "Auto" clears it, so the collection falls back to values computed from its members.
A collection carries three pieces of artwork, mirroring a game:
- Cover - the portrait tile. When none is set, the UI renders an auto-stack: a fanned composite of the member covers, newest to oldest, generated client-side. A custom cover overrides the fan and keeps its own aspect ratio in the grid. Animated covers (animated WEBP / GIF) are detected and flagged.
- Hero - the large detail backdrop. When none is set, a random member's hero art is used as the backdrop, with the same blur and motion settings as a game detail.
- Logo - a transparent clearlogo shown in place of the text title. When none is set, the collection's name is shown as text.
Each can be set two ways:
Upload. PNG, JPG or WEBP up to 5 MB. Uploaded files are stored on the server under the resources directory and served locally from /resources/collection-covers/, never hotlinked.
Scrape. The editor searches external providers by the collection's name and shows candidates to pick from. When you pick a scraped image, its external URL is downloaded to the server on save so it is always served locally.
Cover, hero and logo searches each query a tailored set of sources:
| Asset | Sources searched |
|---|---|
| Cover (grids) | GOG + IGDB + SteamGridDB + LaunchBox + metadata plugins |
| Hero (backgrounds) | GOG + RAWG + SteamGridDB + metadata plugins |
| Logo (clearlogo) | GOG + SteamGridDB + LaunchBox + metadata plugins |
The cover search also supports an All / Static / Animated filter so you can restrict results to animated covers or exclude them. See Scrapers & Metadata for how these providers are configured.
The Description tab fetches candidate text for a collection in parallel from several sources and lets you apply any one of them:
- IGDB, RAWG and Steam - searched by the collection name.
- Wikipedia - via a metadata provider plugin, with a snippet shown up front and the full article fetched when you apply it.
- GOG - included in the source list but returns "not found" for collections, since a collection has no single GOG product.
A collection stores two descriptions, exactly like a game:
- a long description, shown in the detail About section (rendered as sanitised HTML), and
- a short description, used as the tagline in the container's list view.
You can apply a scraped description to either field, then hand-edit both in the manual text boxes before saving.
Several collection facts are computed from the members unless you override them. This keeps a collection sensible as you add or remove games, while still letting you pin exact values.
| Fact | Automatic value (when left on "Auto") |
|---|---|
| Start year / end year | Minimum / maximum member release year |
| Rating | Average member rating, normalised to a 0-5 scale |
| Time to Beat (main / completionist) | Average member playtime |
| Developers / publishers / genres / languages | Aggregated from all members |
| Platforms (Windows / macOS / Linux) | Supported if any member supports it |
| Member count | Number of games in the collection |
Setting a manual value in the Details tab overrides the computed one; clearing it (ticking "Auto") reverts to the member-derived figure.
Collection tiles on the home screen, across themes
| Modern | Classic |
 |
 |
| Neon Horizon | Vapor |
 |
 |
Home page. Each collections container shows a home card whose artwork is a fan of covers drawn from its collections, along with a count. Containers also get a "recently added" row listing the newest collections inside them, so a fresh collection surfaces on the home page. Clicking a collection opens its detail view.
Container grid. Opening a container shows all its collections as tiles. Each tile shows the fan (or a custom cover), a member-count badge, and the collection's year range. An alphabet sidebar jumps to a letter, and you can sort by name (A to Z / Z to A), newest, oldest, most games or fewest games, and switch between cover and list layouts.
Detail view. A collection's own page reads like a game detail:
- a cover hero (the fanned covers, or your custom cover) with the title or logo, rating and a year-range chip, over a blurred backdrop,
- a member strip - the collection's games as portrait cover tiles you can scroll and click,
- info cards aggregating developer / publisher / genres / source, languages / platforms, and collection facts (released, Time to Beat, rating, game count),
- an About section with the long description.
A collection detail view, across themes
| Modern | Neon Horizon | Vapor |
|---|---|---|
 |
 |
 |
Inside a collection's detail page you can browse its members two ways:
- Cover grid - the member games as cover tiles, with the collection's About and Details shown as a side panel. Cover size controls how many columns are shown.
- List view - the member games as full library-style rows, with the About and Details shown as a band above the list.
Members can be sorted A to Z, Z to A, newest, oldest or top rated. Selecting a member opens that game in its home library.
Admins can delete a collection from the editor or the detail cover overlay (DELETE /api/collections/{slug}). Deleting a collection removes the grouping and its artwork only; the member games themselves are left completely untouched.
All routes are prefixed with /api/collections.
| Method + path | Purpose | Access |
|---|---|---|
GET "" |
List collections (optionally scoped to one container via ?library=slug) with member count, cover-stack, aggregated rating and year range |
Read |
GET /{slug} |
A collection's metadata plus its member games | Read |
POST "" |
Create a collection in a container (name, library, optional description) |
Admin |
PATCH /{slug} |
Update metadata; explicit null clears an override | Admin |
DELETE /{slug} |
Delete the collection (members untouched) | Admin |
GET /membership/{game_id} |
Collections a game belongs to | Library read |
PUT /membership/{game_id} |
Replace the collections a game belongs to | Library write |
POST /{slug}/cover /hero /logo
|
Upload custom artwork (PNG / JPG / WEBP, max 5 MB) | Admin |
GET /{slug}/covers |
Search one source for cover / hero / logo images | Admin |
GET /{slug}/meta-sources |
Search one source for description candidates | Admin |
Example - fetch a container's collections:
curl -H "Authorization: Bearer <token>" \
"https://your-host/api/collections?library=franchises"Next: Library - Scrapers & Metadata