Library
The Library is where GamesDownloader presents everything you own as a browsable, richly illustrated catalogue. Behind the single "library" idea sit three distinct sources - your synced GOG account, your own Custom Games, and your ROM collection - each with its own detail page, artwork, and metadata. This page covers how those libraries fit together, the Custom Games library in depth, how downloads stream to your browser, and the two built-in browsing layouts.
- The three libraries
- The Custom Games library
- Downloading from the library
- Browsing layouts
- The Random Game picker
GamesDownloader treats "your games" as three parallel libraries. They share the same metadata engine, artwork pipeline, and detail-page look, but differ in where the files live and how items get in.
| Library | What it holds | On-disk location | How items appear | More detail |
|---|---|---|---|---|
| GOG | Titles synced from your connected GOG account, published to the library once downloaded | data/games/GOG |
Sync the GOG account, download, then publish (or let auto-adopt pick up downloaded games) | GOG Integration |
| Custom Games | Any game you add yourself - uploads, torrents, or files dropped on disk | data/games/CUSTOM |
Web upload, add-via-torrent, or a folder scan | this page |
| ROMs | Retro ROM files per platform, playable in the browser | data/games/roms/{platform} |
Drop ROMs on disk, then Scan ROMs | ROMs & Emulation |
Note: All three libraries use the same scrapers and artwork sources, so covers, hero banners, descriptions, and ratings look consistent across them. See Scrapers & Metadata for how metadata is fetched and overridden. Games from any library can also be grouped into Collections.
Published GOG games do not duplicate their metadata: the library entry stores only identity and file links, and reads every other field back from the shared GOG record, so an edit in one place shows up in both.
The Custom Games library exists so you are not limited to GOG titles. Anything you can put on disk - a DRM-free installer, a bundle of extras, a patch - can become a first-class library entry with its own cover, screenshots, and download buttons.
There are three ways to get a game into it: upload files through the web UI, add it via torrent, or place files on disk and run a scan.
Administrators and uploaders can add game files straight from the browser. Uploads stream to the server with a live progress bar, and completed files land under data/games/CUSTOM/.
Upload guard: Streaming uploads are aborted and the partial file is deleted if they exceed the configured
max_upload_byteslimit (default 50 GB). See Configuration to change the limit.
Uploaded files can optionally be scanned for viruses on arrival when ClamAV is enabled - see Security.
Administrators can add games to the server library from a torrent, without any files being on disk first. Three inputs are accepted:
- a magnet link
- a .torrent URL
- an uploaded .torrent file
The download runs on the server through the built-in Transmission daemon. When it finishes, the completed files are moved into data/games/CUSTOM/ and the game is automatically registered in the library, so it appears alongside your other custom titles with no extra step. Full torrent behaviour, seeding, and speed limits are covered in Downloads & Torrents.
If you copy games onto the server yourself (for example over a network share), use the scan action to register them. Scanning walks data/games/CUSTOM/, creates a library entry for each new game folder, links the files it finds, and marks any file that has vanished from disk as unavailable. Re-running a scan is safe: existing games are updated in place rather than duplicated.
Every file attached to a game carries four organising attributes, so a single title can bundle a Windows installer, a Linux build, DLC, and localised versions cleanly:
| Attribute | Values | Meaning |
|---|---|---|
| OS |
windows, mac, linux, all
|
Which platform the file targets |
| File type |
game, dlc, extra
|
Whether it is the game itself, downloadable content, or a bonus (manuals, soundtracks, wallpapers) |
| Version | free text | Build or release version, shown next to the file |
| Language | free text | Localisation of the file |
When you scan, these attributes are inferred from the folder layout. Two folder conventions are recognised at the same time, so you can mix them:
-
Title-first:
CUSTOM/{Title}/{os}/files, or a flatCUSTOM/{Title}/files(which becomes OSall). -
OS-first:
CUSTOM/{os}/{Title}/files, with an optional innerextra/dlcfolder, orCUSTOM/{extra|dlc}/{Title}/files.
Folders whose names match these keywords act as OS or type containers rather than as games:
| Role | Recognised folder names |
|---|---|
| OS container |
windows, win, mac, macos, osx, linux
|
| Type container |
extras, extra, bonus, dlc
|
Games found under the same title through both layouts are merged into one entry. You do not have to rely on folder names, though: every attribute (display name, OS, type, version, language, availability) is editable per file from the game's detail page after the game exists.
Every available file has a download button that streams the file to your browser with a progress bar driven by the standard browser download manager. Downloads are served natively (the file streams straight from disk), honour any global or per-user speed limits, and record per-game and per-user statistics once the transfer finishes.
Beyond a direct download you can also:
- Generate a shareable download token for a single file, with optional password, expiry, and a maximum download count - no account needed for the recipient.
- Pull any file as a .torrent that the server seeds until it has been fully uploaded to at least one peer.
Both flows, plus per-platform packaging of GOG games and speed limits, are documented in Downloads & Torrents.
GamesDownloader ships two built-in layout modes for browsing the libraries. Choose the one you prefer under Settings → Appearance. Plugin themes can replace these entirely with custom layouts - see Themes.
| Grid view | List view |
 |
 |
The Modern layout is a storefront-style presentation:
- Cover grid with interactive tilt, shine, and glow effects on each card as you move the pointer.
- List view with Ken Burns hero backgrounds that slowly pan the game's hero artwork behind each row, shown with metadata, ratings, and banners.
- An alphabet sidebar for jumping straight to a letter in large libraries.
- An ambient background effect built from the current game's hero art.
Classic layout
The Classic layout is a compact, information-dense presentation built around a game-detail sidebar. It supports all three libraries (GOG, Custom Games, and ROM/Emulation) and includes a platform switcher for moving between ROM platforms, with SteamGridDB icons shown in the sidebar.
You can switch between Modern and Classic without reloading the page. The interface re-renders in place, so the swap is instant and you stay on the same view.
The library list supports several sort orders, and your chosen view mode and sort are remembered per library.
| Sort value | Order |
|---|---|
title_asc (default) |
Title, A to Z |
title_desc |
Title, Z to A |
rating_desc |
Highest rated first |
release_desc |
Newest release first |
created_desc |
Recently added first |
Access control: Non-admin users only see games they are allowed to view. Titles restricted through per-game access rules are hidden from the list, the popular rail, and direct links. See Users & Permissions for roles and per-game overrides.
Not sure what to play? The Random Game picker chooses a title for you and can be narrowed with filters for library, platform, genre, and file availability, so the pick is always something you can actually launch or download.
Next: Collections - group games from any library into curated shelves; or Downloads & Torrents - everything about getting files off the server.