Library and import

Every work on your shelf is a record in your local library. Importing never moves, renames or deletes game files: GalShelf only remembers where a game is and which catalogue entry it matches.

Import a folder#

• Desktop appAvailable in 0.2.8
• WebsiteNot applicable

Open Import and choose a folder. There are three scan modes:

A scan stops at 4,000 folders, 60,000 entries, 120 seconds or 300 games, so very large drives are best imported folder by folder.

For each game folder GalShelf picks a launch file. Installers, uninstallers, patchers, configuration tools and redistributables are skipped. When a folder contains both an original and a Chinese-localised executable (names such as CHS, _CN or 汉化), the localised one is proposed as the launch file and the other is recorded as the original. This is based on file names only, so check it and change it if needed. Version information inside the executable helps tell games from launchers.

Nothing is written until you confirm the review list.

How matching works#

Each candidate is matched against the catalogue sources you enabled and given a confidence:

• High: already linked by its path, a unique exact title, or a very close match with a clear margin. Pre-selected, but you can untick or change it.
• Medium: a plausible match that you must tick yourself.
• Low: search manually, or import it as a local-only record without a catalogue entry.

New works start as Want to play (想玩). When a candidate matches a work that is already on your shelf, only its empty path fields are filled in; nothing else is overwritten.

Catalogue sources: KUN Galgame (鲲 Galgame, preferred by default), VNDB, Shionlib and Bangumi. TouchGal appears only when API keys have been configured, and then only fills empty, unlocked fields. NextMoe can be enabled in the search settings.

When you edit a work's title, original title, cover, description, developer or release date by hand, that field is locked and later automatic refreshes leave it alone.

Fingerprints#

• Desktop appAvailable in 0.2.8
• WebsiteNot applicable

Game fingerprints also help identify releases and editions from the files themselves; any online lookup needs your consent. See Game fingerprints.

Steam games#

• Desktop appAvailable in 0.2.8
• WebsiteNot applicable

• Installed on this computer: GalShelf reads Steam's library folders and app manifests, and the local playtime Steam recorded for your account.
• Your whole Steam library: link Steam through the website (see Steam) or use your own Steam Web API key, which is used for that import only and not stored.

Only games with an exact Steam-to-VNDB release mapping are imported; others are listed as excluded or unresolved so you can handle them yourself. A "Japanese-only" filter is on by default. Playtime Steam doesn't report stays empty rather than becoming 0.

Add a work by hand#

• Desktop appAvailable in 0.2.8
• WebsiteAvailable

Use Add manually (手动添加) to create a record, or search a catalogue and add a work to your shelf without any files on disk. On the website, use Add works on your shelf (see The website shelf).

Drag and drop#

• Desktop appAvailable in 0.2.8
• WebsiteNot applicable

Drop a folder or a game executable onto the GalShelf window to open the same import review. Dropping onto a work card asks whether to update that work's path or to import the item as a new work.

Explorer context menu#

• Desktop appAvailable in 0.2.8
• WebsiteNot applicable

In Settings → Library & Import → Explorer context menu you can add two entries to the Windows Explorer menu: 添加到 GalShelf (Add to GalShelf) for .exe files and 用 GalShelf 扫描游戏 (Scan with GalShelf) for folders. They are per-user entries; on Windows 11 they appear under "Show more options". Turn them off in the same place before you delete GalShelf.

Watched folders#

• Desktop appAvailable in 0.2.8
• WebsiteNot applicable

Settings → Library & Import → Watched folders lets you watch up to 8 folders; type a path or pick one with Browse. Every 60 seconds, and whenever the list changes, GalShelf looks for new game folders up to two levels deep.

If a watched game's files are deleted, its record and play history stay; only the launch paths that no longer exist are cleared. A removed work can be restored within 30 days by importing it again.

Export, backup and import files#

• Desktop appAvailable in 0.2.8
• WebsiteNot applicable

These actions are in Settings → Advanced & Diagnostics → Data and backup.

• Export the full record asks for a folder and saves galshelf-library-<date>-<time>.json there (earlier exports are never overwritten) with your works, sessions and most settings.
• Create a local backup makes a snapshot of the library database in %LOCALAPPDATA%\GalShelf\backups. Automatic backups keep the latest 20.
• You can import a GalShelf or galbd v1 JSON file: after you choose it, the works it contains are listed and only the ones you tick are imported. The preview marks every work as New, Existing (the same VNDB id is already in your library) or Needs confirmation (the same title without a matching VNDB id, or a duplicate inside the file); for those you choose Merge or Keep separate before anything is imported. Existing works keep your own status, rating (including a zero rating), short review, tags, completion marks, progress, notes, route and display alias, and a work without a status stays “No status”. Records the preview cannot read are listed with the reason and left out.

Exports never contain pairing keys or Steam keys.

Restore a local backup#

GalShelf never restores a backup by itself. After a backup, Data and backup shows the backup file, the database in use and these steps:

1. Quit GalShelf completely, including the tray icon.
2. Keep your current data: move the database in use and any files next to it with the same name ending in -wal or -shm into a safe folder. Do not delete them.
3. With the same GalShelf version that made the backup, copy the backup to the original database location and give it the original file name.
4. Start GalShelf and check your works, play records and play time. If something is wrong, quit and put the kept files back.
5. If you moved or copied the data folder, also check screenshots, share-card templates and backgrounds.

A backup contains the account's work records, play sessions and play time, the path settings of this device and screenshot records. It does not contain screenshot images or other media files, share-card templates or exported cards, backgrounds and downloaded artwork, game saves (back those up on the work's page under Game tools or Cloud saves) or the games themselves. Importing a JSON record file adds or updates work records only; it is not a restore.