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
- Your own custom libraries
- The Custom Games library
- Downloading from the library
- Browsing layouts
- The Random Game picker
GamesDownloader treats "your games" as three parallel built-in 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. On top of these, an admin can create their own custom libraries.
| 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 | below |
| 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 three libraries above are built in, but an administrator can create additional custom libraries of their own - for example "Kids games", "VR titles", or "Handheld". They behave just like the Custom Games library (uploads, direct-URL downloads, torrents, and folder scans all work the same way) but are separate, top-level libraries with their own name, icon, and colour, shown alongside the built-in ones in navigation and on the home page.
Admins create and manage them under Settings > Libraries. A custom library can optionally be given its own folder on disk (under data/games/{slug}). When it has one, everything you add while viewing that library - Add game, Upload file, upload from a URL, add-via-torrent, and folder scans - lands in that folder and is filed under that library instead of the built-in Games library. This works identically across the Modern, Classic, Vapor, and Neon Horizon themes, which all drive these actions through one shared API.
A game can live only in a custom library (kept out of the default Games list), or belong to several libraries at once (membership) - you set this per game from the metadata editor's Libraries section, and games added while viewing a custom library start out belonging only to it. Games in any library can still be grouped into Collections.
Because the whole library list is data-driven, custom libraries also get per-user visibility and ordering, an editable icon and colour, and optional per-user access control (restrict a library to specific users). All of that, plus how to create, rename, and delete them, is covered in Users & Permissions.
Custom library vs Collection: a custom library is a separate library a game belongs to (with its own folder and files); a Collection is a curated grouping of games that already live in other libraries. Use a custom library to keep a distinct set of games apart on disk; use a Collection to shelve related titles together without moving anything.
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, either by uploading a local file (streamed with a live progress bar) or from a direct download URL (the server fetches it in the background and reports progress the same way). Completed files land under data/games/CUSTOM/.
Custom libraries: If you start the upload while viewing one of your own custom libraries (a library created with its own folder), the game and its files land in that library's folder and are added to it, instead of the built-in Games library. The same is true for Add game, add-via-torrent, and folder scans. This works identically across the Modern, Classic, Vapor, and Neon Horizon themes, which all drive these actions through one shared API.
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 the library and the game is automatically registered, so it appears alongside your other titles with no extra step. As with uploads, if you started the torrent from one of your custom libraries the finished game lands there (its folder and membership) rather than in the built-in Games library. 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.
When you run the scan from inside a custom library it walks that library's folder and assigns the games to it; the built-in Games scan additionally sweeps every folder-backed custom library in one pass, so each game is filed under the right library automatically.
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.