Game Kat·a·log - User Guide#

Game Kat·a·log is a private, multi-account library for physical and digital video games. It is designed for fast desktop use, compact phone use, and large collections.

The four main workspace headers use the same geometry and branded titles: My Kat·a·log, Public Kat·a·log, Kat·a·log Signal, and Kat·a·log Forum. None uses a leading “The.” Their smaller kicker and description provide context without changing the heading scale or shifting the cover fan. On desktop, every header action has a compact themed tooltip below the control; these hints are suppressed on the icon-based mobile header. My Kat·a·log draws its fan only from covered games you own; wishlisted games are excluded. Every other view receives a newly randomized fan from public Kat·a·log covers plus your owned covers when signed in, or public covers alone as a guest.

When a game has multiple copies, its existing platform badge becomes a compact dropdown without adding another row to the card. Open it and choose any recorded platform directly; the themed menu flips upward when there is not enough room below. Platform badges and menu choices use researched product identities as restrained accents. Different hardware generations keep distinct treatments where published branding differs, multicolor marks use subdued gradients, and monochrome or ambiguous platforms stay neutral instead of receiving a guessed color. Text remains neutral and fills stay charcoal, so red identifies Nintendo hardware only where that identity belongs without resembling an error or destructive action. The badge keeps the platform label on one line and adds a record number when two copies share that platform. Nintendo Entertainment System and Super Nintendo Entertainment System appear using their familiar NES and SNES abbreviations, while the full canonical names remain stored for filtering and matching. Its stars, favorite, ownership, details, and edit action all belong to the selected copy. Rating it does not change another platform's rating. The selection stays during live updates in the current session. The details and edit dialogs also offer a full copy selector showing platform, format, and record number. Changing the Platform field edits the current record; it does not select another copy. Changing a title or platform to an existing copy prompts for confirmation. Switching copies in the editor discards unsaved form changes.

Search fields have a themed clear button that also reflects restored filters. Header cover art is decorative and stays independent of the current search.

Getting started#

Open http://localhost:3005 in a browser. To use another device on the same network, replace localhost with the server computer's LAN address.

Creating an account#

1. Select Register.
2. Choose a username. Matching is case-insensitive.
3. Optionally enter an email address.
4. Choose a password with at least eight characters and enter it again for confirmation.
5. Select Create account.

Every account has an isolated library. Game ownership is attached to the account's internal numeric ID, so changing a username does not affect its collection.

Account settings also contain an optional Public collector profile switch. It is off by default. When enabled, a visitor can select your name in Kat·a·log Signal to see your avatar, collector level and title, join month, aggregate collection counts, public contribution count, and every platform represented by an owned, non-hidden game. Individual games, ratings, notes, email, location, and account settings are never included. Hide from Kat·a·log Signal remains independent: a public profile does not make hidden Signal events appear.

Signing in and out#

• Use Login with an existing username and password.
• A secure HttpOnly cookie carries the random session identifier. Page scripts cannot read it, and the app puts no authentication data in local or session storage.
• Sessions remain valid for two weeks and are extended while used. Revoked or expired sessions also close their live-update stream within about 20 seconds.
• Select the username in the top-right corner, then Log out, to end the current session.
• Five incorrect passwords temporarily lock the account for 15 minutes. A local administrator can also lock an account until they explicitly unlock it; that action signs it out everywhere.
• Select Forgot? to replace the sign-in form with the reset-request panel, then enter a username or email. The branded email has a clickable Reset password button and a linked fallback address; it opens a dedicated new-password panel. Links expire after one hour and all existing sessions are signed out after a successful reset. An account needs an email address and the local administrator must have configured SMTP delivery.

During refresh, a compact Mounting authenticated library… screen remains visible only while the secure session cookie is checked. The app then appears immediately in its loading state; a green-outline controller marks an empty grid while library data arrives, and header and background covers fill in afterward. Existing cards remain visible during later refreshes instead of being replaced by the loader. The public login and registration interface is shown only if that session is absent or invalid.

Public Kat·a·log#

Select Kat·a·log from the login-page footer or signed-in header to browse the shared release index at /katalog. While signed in, the application shell stays in place: only the content beneath the header changes; Kat·a·log, My Kat·a·log, and +Game remain in their fixed header positions, with the current view visibly inactive. Direct public pages use the same shell treatment, including its subtle shared-cover spread. This page is public and search-engine-visible; it can be searched by title, publisher, platform, IGDB genre, or IGDB theme and filtered to one platform. With no platform filter, one card represents a canonical game and lists its available platform releases; applying a platform filter deliberately shows the matching release rows separately. IGDB identity keeps differently named editions of the same game together and keeps unrelated games with similar titles apart. Records without IGDB metadata use the previous normalized-title fallback. A release detail dialog shows its cover, PEGI details, publisher and year, all available HowLongToBeat estimates, optional IGDB ratings, credits, genres, and themes, plus links to the other public platform editions.

When signed in, choose collection and media format in a release detail dialog, then select Add to my Kat·a·log. The app creates an ordinary private library row with the release facts already filled. Your ownership, format, play state, favorite, notes, and other tracking remain private and editable. If that title and platform already exist in your account, the dialog shows Already in your Kat·a·log instead of add controls. Opening My Kat·a·log from either state closes the details dialog first, leaving the private library immediately interactive. The server keeps duplicate protection as a safeguard if another tab adds it while the dialog is open.

The Kat·a·log grows conservatively from member libraries. A release publishes automatically only when all of these are present:

• A durable locally stored cover with an exact normalized title match.
• Substantive PEGI metadata.
• A HowLongToBeat record with at least one timing estimate and an exact normalized title match.

Complete records with an ambiguous cover or HLTB title wait for localhost administrator review. Incomplete records do not enter the shared index. The public copy contains factual release metadata only // never the contributing account, ownership, media format, play state, personal rating, favorite, cartridge number, notes, or private game-row ID. From the first linked private rating, it can show an anonymous community average and rating count. It also owns a separate cover copy, so editing or deleting a private game does not break the public page.

Public Kat·a·log matches also appear between games already in your library and optional IGDB or SteamGridDB title suggestions while typing in the add dialog. Selecting one opens its public release details over the Kat·a·log, where you can inspect the metadata before adding it. Each release also has a stable shareable URL for search engines; opening one directly lands on the same Kat·a·log detail dialog, and closing it returns to the Kat·a·log without creating a redundant browser-history entry. While signed in, a compact Owned pill marks every public card whose grouped releases include one you own. If the same canonical release is already in your library, with normalized title and platform used for records without IGDB identity, its details state whether it is owned or wishlisted instead of showing the add form. Open my Kat·a·log returns to your unchanged private filters and immediately opens that exact private game's details.

Dashboard#

The ten compact cards summarize the current account and act as one-click major filters:

Selecting a summary card applies its corresponding library filter and highlights the active card. Total clears search and every library filter while retaining the selected sort order.

Stats for Nerds#

Select Stats in the desktop header, the fixed mobile community dock, or the login footer to open the public telemetry panel. On phones, the community dock floats against the lower-left edge of the viewport while scrolling and keeps Signal, Forum, Stats, Patch, and Ping beside the existing lower-right add-game control; it is not part of the page footer. Primary Kat·a·log and account navigation stays in the compact header. The panel follows the same compact three-column idea as Gamebooks on desktop, becomes two columns on narrower screens, and uses one scrollable column on phones. It stays within 80 percent of the desktop viewport, uses the application scrollbar, closes with Escape or a genuine backdrop click, and does not close when a text selection begins inside it and ends outside.

The sections are adapted to games: collectors, private-library aggregates, play status, public Kat·a·log growth, metadata coverage, combined HLTB estimates, half-star ratings, XP progression, Forum and Signal activity, leading public platforms, server hardware, and application storage/uptime. Large HLTB totals are converted from decimal hours into compact years, days, and hours, using 365-day years. Average collector level is floored to a whole level. App level follows Gamebooks' pooled curve: total community XP is scaled by the complete registered collector count before applying the standard quadratic level formula. The XP event-type total counts every supported award definition, including types that have not yet occurred. Server statistics include the deployment CPU's age and clock speed. The application section includes cumulative HTTP traffic received and sent, plus running session averages for CPU use, heap used, heap total, and resident memory after the first sample. Uptime uses two decimal places and accumulates every observed heartbeat gap as downtime; the 15-second threshold controls only whether a restart begins a new uptime session. Counts refresh when the panel opens and may remain cached for up to 15 seconds to protect the public endpoint from repeated expensive scans.

Only aggregate numbers are public. The response never contains usernames, emails, account locations, credentials, private game titles, notes, descriptions, or individual library rows. Public-profile privacy and Signal visibility settings remain independent of these anonymous totals.

Finding games#

The library updates as filters change.

Search#

Search matches the game title, publisher, notes, description, IGDB genres, and IGDB themes. It is case- and accent-insensitive, so Pokemon also finds Pokémon, and starts after a short typing delay. The public Kat·a·log and both administrator indexes use the same delayed live search. On the public Kat·a·log, typing, clearing a query, selecting a genre or theme chip, filtering, and paging update only the result cards rather than refreshing the page.

Filters#

Dropdowns that currently restrict which games are visible use a muted blue-teal border, text, and underline, making forgotten filters apparent at a glance in both My Kat·a·log and the public Kat·a·log. The PEGI filter instead uses the established green, yellow, orange, red, or neutral rating color for its selected value. Sort by stays neutral because it changes order without hiding games. Select Clear filters to return to the complete library. Results are paginated in ten desktop rows; clearing filters still retrieves only the requested page rather than transferring the complete collection. Editing, rating, favoriting, changing ownership, or deleting an existing game keeps the current page selected. The pagination bar remains mounted during the background refresh, preventing the footer from jumping, and is briefly non-interactive until the refreshed page arrives. If deleting the final item removes the last page, the server returns the nearest remaining page automatically.

Set a game's play status to Hidden in the editor to remove it from the normal library, summary totals, decorative cover pool, public profile statistics, and automatic metadata scans. Hidden games have no dashboard card and appear only when Hidden is selected from the Library filter. Because hidden records do not expose their preserved underlying play state, selecting Hidden clears the Play status filter; selecting a play status while viewing Hidden returns Library to Everything. Choose any regular play status in the editor to return a hidden game to the normal library.

HLTB duration and IGDB score sorts always place games without that particular value after games with known data. This keeps missing data from appearing as a zero-hour game or a zero rating. Live batch updates use the same selected order as a full library reload.

Card and compact views#

Use the two view buttons beside My Kat·a·log:

• Card view gives titles more space and is the default.
• Compact view places each game on a denser horizontal row.
• The left card rail uses the PEGI color: green for 3/7, amber for 12/16, red for 18, and muted gray when unrated.
• The platform appears inside each card as its own label.
• With no platform filter, copies of the same canonical game are collected into one card. When more than one copy exists, open the platform badge and choose a copy from its themed dropdown. IGDB-linked copies can group even when their edition names differ; older or unmatched copies fall back to normalized titles. Applying a platform filter intentionally expands the matching records into separate cards.
• Selecting Multiple platforms keeps matching titles grouped and shows only games recorded on at least two distinct platforms. Two copies on the same platform do not qualify.
• Games with saved HLTB data show compact Main, Main +, 100%, and All Styles estimates.

The selected view, search text, every filter, and the sort order are stored with the account in SQLite. They follow the account to another browser, desktop, or phone; nothing is kept in local or session storage.

The signed-in workspace keeps the login screen's scattered box-art atmosphere at the same visibility behind the interface. It selects and randomizes durable local artwork from the current account when the app is entered; those same local files feed the public promo modules and header covers. Artwork finishes loading in the background and waits for an open filter menu to close before changing the decorative layer, so it cannot interrupt filtering. The decorative layer is non-interactive and does not affect the cards or controls.

The small release string beside Game Kat·a·log comes from the project's VERSION file and can be changed from the local administrator panel. A saved change appears immediately in open signed-in and public headers without a refresh.

Collector progression#

Your account has a private collector level. The persistent application header and account panel show its current level, title, total XP, and distance to the next level on My Kat·a·log, Signal, Forum, and the public Kat·a·log, including after a direct refresh. The same +Game control remains available in every signed-in view and opens the game form without navigating back to My Kat·a·log. Levels use the same triangular Gamebooks curve: level 1 starts at 1,000 XP, level 2 at 3,000 XP, level 10 at 55,000 XP, and the maximum level is 100. Header XP changes animate in queued, level-scaled segments: at level 16, each awarded update takes 1,600 ms.

XP recognizes durable collection work: adding a game; setting a cover, PEGI details, HLTB times, description, personal note, publisher, year, rating, favorite, wishlist, play state, or first avatar; opening a new platform shelf; contributing a game to the public Kat·a·log; starting a forum thread or reply; sparking a reply from another account; and collection, enrichment, and completion milestones. Recording a note awards 5 XP once per game; changing a Wishlisted game to Owned awards 25 XP once; publishing a contributed game to the Kat·a·log awards 30 XP once.

Each award is permanently recorded against the account, action, and relevant game or milestone. Removing a favorite, cover, or other field and adding it back cannot award XP twice. There is no passive, timed, login, or idle XP gain. Existing libraries are safely credited once on their first progression check. XP amounts are controlled only from the localhost administrator panel; the level curve and titles remain stable.

Kat·a·log Signal#

Kat·a·log Signal is a public page at /signal; the landing screen shows a short live preview and links to it. It shows every eligible event from the last 30 days // there is no event-count cap // and groups activity by your local day. On desktop, the feed uses a 55/45 newspaper-like split: the wider left KAT·A·LOG // UPDATES column carries frequent public contributions, while the right COLLECTORS // SIGNAL column carries new curators, collector level-ups, and gained titles. Both compact mastheads remain visible when their lane is quiet, and a full-height rule separates the two columns. Pinned and regular administrator announcements span the feed above them. On mobile, the same events return to one compact chronological stream rather than hiding activity behind tabs or placing one complete category before another. It intentionally contains only public-safe events: new accounts, collector level-ups, games contributed to the public Kat·a·log, and published administrator announcements. It uses a server-sent-event connection, so a new event appears without refreshing the page. Expanded contribution groups stay open when live updates arrive, including across the desktop and mobile layouts. Private library additions, wishlists, ratings, edits, metadata scans, and play status never appear there.

New accounts are announced by default with a randomly selected message. Level-up messages are also selected from the stored Signal templates and identify a newly gained collector title when one changes. Public game links use their PEGI color when one is recorded; unrated games retain the muted fallback link color. A compact platform pill beside each contribution uses the release platform's researched palette without recoloring the Signal row. Six or more public game contributions from one account on the same day collapse into one compact count; up to five remain separate. Select that contribution summary to inspect every contributed game. A curator name becomes a themed profile control only when that account has enabled Public collector profile; selecting it opens the aggregate profile without leaving Signal. Open Account settings and enable Hide from Kat·a·log Signal to hide all of your Signal events, including existing ones. Both choices are stored with your account and apply across devices.

The localhost-only administrator panel can compose announcements as drafts, edit them, publish or unpublish them, delete them, and pin one published notice. A pinned announcement stays above Signal regardless of age; other published announcements follow the normal 30-day window. Announcement text supports restrained **bold**, *italic*, __underline__, ~~strike~~, and {color:teal}color{/color} formatting.

Forum#

Forum is a public, search-visible discussion space at /forum. It keeps the same header and cover treatment as Signal and the public Kat·a·log, and switches below the signed-in shell rather than rebuilding the app header. Anyone can read the starting channels: General, Games & recommendations, Collections & hardware, and Kat·a·log.

Choose a channel before starting a thread: its inline composer appears within that channel and locks the selected channel, so a new discussion never falls into General by default. Thread cards identify their author; each thread-page post also shows that account's avatar or initial, username, and collector level. Sign in to start a thread or reply. You can edit or delete only your own thread or reply; deletion uses a themed second-click confirmation, deleting a thread removes its replies, while deleting a reply leaves a clear deleted marker in the conversation. Forum changes use a public server-sent-event stream, so open channels and threads refresh without manual reload. A localhost administrator manages channels and can pin, lock, or remove any thread. Starting a thread awards 25 XP once; each reply awards 5 XP once; a thread author earns 15 XP once when another account replies.

Patch and Ping#

Patch is the private operator link. Use it for bugs, ideas, and game-data corrections. Signed-in accounts automatically identify themselves; visitors can leave a name and optional email. Patch threads never enter Signal, the public Kat·a·log, or the forum.

Ping is the signed-in private inbox for Patch replies. It remains muted and unavailable until there is at least one conversation, then shows unread conversations, supports replying, and lets you hide a thread from your own list. Operator replies arrive live through the authenticated event stream, so the Ping badge updates without reloading the library and pulses until read. The operator account sees the same Patch conversations through Ping with the operator unread state, so later user replies become unread again. With SMTP configured, new Patches and user replies also email the operator, while an operator reply sends a branded Game Kat·a·log notice to any supplied user address. Every notice includes a button back to the app. The localhost-only admin panel has the matching Patch queue: it can read, reply to, and remove threads.

Adding a game#

Select Add a game on desktop or the + floating button on mobile.

Manual entry#

Only Title and Platform are required. Every other field can be added later.

After three title characters, matching games already in the current account appear first, with their platform and collection state. Public Kat·a·log matches follow and open their release-details dialog. When IGDB is connected, its richer title suggestions appear last and can apply a selected title, platform, publisher, year, description, cover, genres, themes, credits, and ratings. SteamGridDB title suggestions remain the fallback when IGDB is not connected. Select an existing result to open it instead of creating another entry. Pointer selection, arrow keys, Enter, and Escape are supported.

When an IGDB match is selected, an existing copy with the same IGDB identity and platform shows an Already in your library warning and an Open existing action. Without IGDB identity, the check falls back to an exact normalized title-and-platform pair. Saving a possible duplicate requires a themed Add anyway confirmation because multiple copies or editions can be legitimate. The same game on another platform remains a separate release. Suggestions are optional: any title can still be entered manually. If IGDB or SteamGridDB is unavailable, remote suggestions disappear silently while local duplicate detection and ordinary title entry continue working.

PC libraries can be tracked by storefront rather than only by operating system. The built-in platform list includes Steam, GOG, Epic Games Store, Microsoft Store, PC Game Pass, Xbox app, EA app and Origin, Ubisoft Connect and Uplay, Battle.net, Rockstar Games Launcher, itch.io, and Amazon Games. These remain distinct platforms for filtering and duplicate detection, while PEGI matching treats them as PC editions and preserves the chosen storefront when applying a generic PC result.

Select any non-control area of a library card to open its read-only record of metadata, description, PEGI and HLTB information, notes, and your rating. Use Edit details only when you want to change it.

PEGI-assisted entry#

1. Type at least two characters in Title.
2. Select Look up title.
3. Choose the correct result.
4. Review the filled fields, especially platform and release year.
5. Select Save game.

The lookup can fill title, PEGI rating, publisher, release year, descriptors, exact platform release dates, consumer advice, a brief outline, content-specific issues, and other issues. When PEGI divides matches across multiple result pages, Game Kat·a·log retrieves up to the first 10 pages and presents the merged result count above the choices. PEGI has no documented public developer API, so the app reads its public search pages only when you explicitly request a lookup. If PEGI is unavailable or changes its page, manual entry continues to work.

After selecting a result, PEGI details opens beneath the form. It contains:

• Content descriptors, also shown as compact badges on the saved game card.
• An amber warning when PEGI identifies in-game purchases or paid random items.
• Every exact platform and release date listed for that PEGI record.
• PEGI's consumer advice, brief outline, content-specific issues, and other issues.
• A link back to the PEGI source search.

The longer material stays collapsed when a saved game is opened, keeping routine edits compact. Select PEGI details to reveal it.

Importing a Steam library#

The server operator connects one shared Steam Web API key in the localhost admin panel. Collectors never see that key. In Account Settings, open Steam library import, enter a SteamID64, vanity name, or complete Steam Community profile URL, then select Connect. Once linked, the field becomes a disabled green Connected state. Select Replace profile to unlock it for a different Steam reference. Steam must be able to read the profile's owned-game list; if it cannot, make Game details public in the Steam profile privacy settings and try again.

Select Review library to fetch the current owned-game list without writing anything. The review separates titles into five states: entirely new Steam records, new Steam copies of titles owned elsewhere, one safe same-title Steam record without an AppID that can be linked, ambiguous same-title matches needing deliberate selection, and AppIDs already imported. New records, other-platform copies, and safe links are selected initially. Ambiguous matches are left unchecked, and already imported records cannot be selected. To keep very large libraries responsive, the review mounts at most 250 matching rows at once; use its title filter to reach a game outside that visible slice. Selection totals and Select importable still apply to the complete fetched library.

Search and adjust the selection, then select Import selected. A live themed meter reports the Steam refresh, database-writing, and collector-XP phases. The dialog cannot be dismissed while those writes are active. Work is split into small batches so the rest of the application and its live event stream remain responsive during a large import. New entries are created as owned digital Steam games in the backlog. Exact single-record Steam matches keep their existing personal data and gain the Steam AppID and playtime snapshot instead of becoming duplicates. The import re-fetches the owned library and validates every submitted AppID on the server, so a stale or altered browser selection cannot import an arbitrary title. Repeating the import skips already linked AppIDs, including when it resumes after a provider or process failure. Retry processing also reapplies missing one-time import XP idempotently to a record written by an earlier partial attempt. Imported games remain ordinary private records and do not enter the public Kat·a·log unless they later meet its normal enrichment rules.

Importing a GOG library#

In Account Settings, open GOG library import and select Authorize with GOG. Sign in only on GOG's own page. After GOG redirects to its blank success page, copy the complete address from the browser, paste it into Game Kat·a·log, and select Authorize. The one-time result is exchanged server-side; the GOG password and browser cookie never enter this app. Once linked, the field becomes a disabled green Connected state. Select Reconnect only when replacing or renewing the authorization.

The authenticated library read combines GOG's ordinary and hidden collections. A title hidden inside GOG is imported as an ordinary owned GOG game with the Backlog status; GOG's private display preference never turns into Game Kat·a·log's Hidden play status. The GOG profile and its library do not need to be public.

The review uses the same deliberate five-state workflow as Steam. GOG product IDs make repeat imports safe. A single exact-title GOG record without a product ID can be linked while retaining its personal metadata; another-platform copies become separate GOG records; ambiguous GOG matches remain unchecked. New records use owned, digital, GOG, and backlog defaults. A live meter reports page-by-page progress across both GOG collection states while the initial review is assembled. The server re-reads every paginated library page before writing, validates the selected IDs against that fresh response, commits in small batches, and reports fetching, writing, and XP progress live. Disconnecting GOG removes the stored authorization but never removes games already imported.

Cover-assisted entry#

Account Settings keeps each artwork and metadata service collapsed into a compact status row. Select a row to reveal its source links, scan action, matching policy, and any account-specific connection controls.

1. Open Account Settings to inspect the shared SteamGridDB and IGDB availability or connect your own TheGamesDB key. For TheGamesDB, select Sign in / register first, then return and select View API key; its key page is available only to signed-in site accounts. The server operator manages SteamGridDB and IGDB once through the localhost admin panel, and both become available to every account when connected.
2. Type a title in the game form and select Request cover.
3. Review the portrait artwork and game names, then select the correct edition.
4. Or select Upload cover to choose your own JPEG, PNG, or WebP image. The preview is local until you save; the server then normalizes it to the same durable cover format used by provider artwork.
5. Save the game. Select Remove cover before saving if the match is wrong.

After TheGamesDB validation, its disabled field shows Connected in green. Secrets are deliberately never returned to the browser. Select Replace key to open an empty replacement field. Shared SteamGridDB and IGDB credentials never appear in Account Settings.

Scan actions stay disabled while Account Settings checks the current account and if a status request fails, rather than reusing an earlier connection or missing-game count. TheGamesDB keeps its account-specific connection field available if its status request fails.

Request cover searches every connected source plus HowLongToBeat and labels each result with its provider. This includes IGDB when it is connected. HLTB is available only in this deliberate per-game request flow // it is never used for a bulk cover scan. When the game is saved, Game Kat·a·log downloads the selected JPEG, PNG, or WebP into public/covers/ and stores its public /covers/... path, provider, and match title. The card therefore remains independent of the provider CDN and the image is directly accessible through https://gamekat.net/covers/.... Provider artwork carries a source-credit link.

TheGamesDB's smaller preview derivatives are not reliable, so its chooser rows load the authoritative original artwork directly. This avoids broken preview tiles; selecting and saving a result still stores the app's own optimized durable copy.

HowLongToBeat-assisted entry#

1. Type at least two characters in Title.
2. Select Look up times.
3. Review the result names and four estimates, then select the correct edition.
4. Save the game. Select Remove times before saving if the match is wrong.

The selected result stores Main Story, Main + Sides, Completionist, and All Styles estimates, plus a link back to its HowLongToBeat page. Missing or unreported estimates display as a dash. HLTB lookup is optional: provider or network failure never prevents manual game creation or editing.

Fill existing games#

When the server operator has connected SteamGridDB, select Fill missing covers in Account Settings. The scanner runs for your account in the background and reports its progress. It only auto-selects artwork when exactly one normalized, exact-title game match exists. Ambiguous editions and non-exact matches remain blank for manual review rather than receiving a likely-wrong cover.

TheGamesDB has its own Fill with TheGamesDB action. Its scan is platform-aware and requires exactly one normalized title record for the saved platform. Run it after SteamGridDB to fill remaining gaps; it touches only games that still have no cover.

IGDB information#

The server operator connects IGDB from the localhost-only admin panel with the Game Kat·a·log Twitch application's Client ID and Client Secret. Create that Twitch application as Confidential, using http://localhost as its otherwise-unused OAuth redirect URL; Public clients cannot generate the secret required by IGDB. The credentials stay on the server and become available to every Game Kat·a·log account without being exposed to them. Account Settings shows only availability and the per-account scan action. The app obtains and refreshes the short-lived access token itself. When IGDB is unavailable, its manual lookup and scan controls are disabled while ordinary entry continues to work.

While adding or editing a game, select Look up on IGDB to inspect matches. Applying one stores the IGDB identity, user score and vote count, critic score and review count, developer, genres, themes, source link, and any blank publisher, release-year, description, or cover fields. Existing personal and provider data is not blindly overwritten. Game details display genres and themes as distinct compact groups rather than mixing both taxonomies: genre chips use teal and theme chips use violet. Selecting one of those chips searches the current private or public Kat·a·log without adding another permanent filter control. The existing search fields also match genre and theme text directly. IGDB ratings and classifications appear in the read-only game details dialog and public release details, not on library cards.

Select Fill IGDB information to scan the account in the background. Automatic matches require one normalized exact title on the saved platform. Ambiguous results remain untouched. A successful match can fill an empty description and cover, with selected artwork downloaded into the same durable local cover store. Progress and successful game updates arrive live without reloading the grid.

Game descriptions#

Each game has an editable Description field. Select Look up description to choose a result from Steam Store or, when connected, IGDB or TheGamesDB. The selected source is retained for the public Kat·a·log page; editing the text yourself marks it as manual.

Select Fill descriptions in Account Settings to scan games with an empty description. Steam Store is always tried first and only one normalized exact-title match is accepted. TheGamesDB is used only as a fallback and only when its existing account key is connected. The scan pauses rather than continuing if TheGamesDB rejects a request or reaches its API limit, so it does not burn through the remaining monthly allowance.

Select Fill PEGI details in Account Settings to scan existing games without a saved PEGI source record or extended PEGI metadata. The scanner searches the paginated PEGI catalog and prefers one exact-title result for the game's platform. Ambiguous matches are skipped for manual review. It updates only PEGI information, publisher, and release year; your title, platform, ownership, play state, format, notes, favorite state, and cover remain untouched.

Select Fill HLTB times in Account Settings to scan every game without timing data. Automatic matching requires exactly one normalized exact-title result. Platform is not used because HLTB times describe the title rather than a particular physical copy; ambiguous editions remain blank so you can choose one manually.

All metadata, description, and artwork scanners continue in the background while the app is open. Their counters update live, and each successfully enriched game card changes in place. If you manually add a cover, PEGI record, HLTB match, or description while a scanner is running, its queued copy is skipped and your newer choice is preserved. The full grid is not reloaded, the current filters stay active, and the page does not jump. Short network interruptions reconnect automatically and replay missed updates. A server restart stops an unfinished scan; saved results are retained and starting it again scans what is still missing.

Managing games#

Editing#

Select Edit details on a game. Change any field and select Save game.

Favorites#

Select the star in the top-right corner of a card. The change is saved immediately.

Moving a wishlist game to owned#

Wishlisted cards include Mark owned. It changes only the collection state; other metadata is preserved.

Deleting#

Open Edit details, select Delete, and confirm. Deletion is permanent for that account and cannot affect another user's library.

Dialog behavior#

• Select ×, Cancel, press Escape, or click directly on the backdrop to close a dialog.
• Selecting text and releasing the pointer outside the dialog does not close it.
• A backdrop close occurs only when the pointer starts and ends on the backdrop.
• Destructive actions use application-themed confirmation dialogs. Game Kat·a·log never invokes the browser's native alert, confirm, or prompt interface.

Account management#

Select the username in the top-right corner.

Account settings open with the non-text Close control focused. No form field is selected automatically, so a phone or tablet does not open its on-screen keyboard until you choose a field.

Add or change avatar#

Select the avatar or Change avatar, then choose an image. The browser center-crops it to a 512×512 square and compresses it before upload. The stored JPEG is limited to 256 KB. Select Remove to return to the username initial.

Downloaded game covers are also normalized automatically: each is stored as a JPEG with a maximum 900-pixel edge and a maximum size of 256 KB. This keeps card, header, and decorative background artwork quick to load without changing its public /covers/... availability.

Change username#

Enter the new username and current password, then select Save account. Usernames are case-insensitively unique and may contain letters, numbers, dots, dashes, and underscores.

Changing the username does not change ownership of existing games.

Add or change email#

Enter an optional email address and current password, then save. Email addresses are case-insensitively unique. The address is used only to deliver a password-reset link when SMTP has been configured by the local administrator.

Change password#

Enter the current password, enter the new password twice, and save. The new password must contain at least eight characters.

Changing a password invalidates all existing sessions for that account. Sign in again with the new password.

Mobile use#

The interface automatically changes for narrow screens:

• Summary cards become a single compact row.
• Filters use two columns.
• Games use one card per row.
• The desktop add button becomes a floating + button.
• Account and form dialogs fit within the visible screen and scroll internally.

The app manifest allows supported browsers to install Game Kat·a·log as a standalone home-screen app.

Local administrator panel#

On the computer running Game Kat·a·log, open http://127.0.0.1:3005/admin/. The panel deliberately refuses LAN and internet clients, including requests arriving through the public nginx proxy.

The compact terminal-style panel provides:

• Live process health (heap, RSS/CPU, cumulative traffic in/out, app age, and session uptime, refreshed each second) plus whole-database game, account, cover, description, PEGI, HowLongToBeat, rating, catalog, favorite, platform, ownership, media-format, and play-state summaries (refreshed each minute). The compact dashboard stacks related cards by library, community catalog, metadata coverage, runtime, and process/storage health. App age begins with the earliest user or game record. Every positive clean-stop or heartbeat gap is counted as downtime; the fifteen-second threshold determines only whether the next process begins a new uptime session.
• Account inspection, last-active and inactivity age, approximate country/city from recent authenticated activity, session revocation, manual lock/unlock, and typed-confirmation account deletion. Accounts inactive for 31 days or longer are tucked behind a compact reveal row, matching Gamebooks, while recent accounts remain immediately visible. Location is resolved locally from the connection address with the same offline GeoIP database used by Gamebooks; only the country code and city are stored, never the IP address. The Accounts table uses the available desktop width without an unnecessary horizontal scrollbar, while narrow screens retain deliberate horizontal access. Locking signs the account out everywhere; automatic temporary locks follow five incorrect passwords. The server's configured owner account cannot be locked or deleted. Deleting another account also deletes its avatar, games, sessions, integration settings, and saved interface preferences.
• SMTP host, port, transport security, credentials, sender address, and a send-test-email action for password resets. SMTP passwords are never returned to the browser after saving.
• Cross-account private-row search and deliberate, confirmed game deletion.
• Public Kat·a·log factual editing and moderation with candidate, published, and rejected states, confidence checks, supported-provider cover replacement, and independent shared-cover cleanup. Only review candidates have a Publish action; a published release can be returned to review or rejected, and a rejected release must first return to review before it can be published.
• Signal announcement drafting, editing, publishing, unpublishing, deletion, and a single pinned notice that stays above the public feed.
• Forum channel administration plus local thread pinning, locking, and removal.
• Patch queue triage, unread state, private replies delivered through Ping, and thread removal.
• An arbitrary release-string editor. Saving writes directly to VERSION; reload the main app to see the new string in its header.
• SQLite WAL checkpoint, query-planner optimization, and vacuum actions.
• Hourly compressed live backups stored in the ignored backups/ directory. One runs at startup and then on the hour; archives are retained for 15 days.

The admin panel is not a normal user account and has no public login screen. Its security boundary is the local machine itself. If remote administration is ever needed, use an explicitly secured tunnel rather than publishing /admin/ in nginx.

Troubleshooting#

A session expired#

If this notice appears after the library was open, sign in again. Sessions expire after two weeks of inactivity, and a password change invalidates all sessions. Opening or refreshing the normal logged-out login screen does not display an expiry notice.

PEGI lookup failed#

The app automatically retries brief PEGI rate-limit or server failures. If PEGI remains unavailable, wait a moment and try again or continue with manual entry. The failure does not prevent saving a game.

If a background PEGI scan encounters five consecutive provider errors, it stops to avoid hammering a failing service. Open Account Settings after PEGI is available again and restart the scan; already enriched games are not repeated.

The page still shows an older design#

Perform a hard refresh so the browser reloads the modular stylesheets and app.js.

The server is not reachable#

From the project directory run:

npm start

Confirm port 3005 is free and that the device can reach the host machine.

Data safety#

Persistent collection records live in games.db; durable cover binaries live separately in public/covers/. Create backup in the local admin panel intentionally archives the database only and does not include cover files. Do not copy only the main database file during active writes without also accounting for its WAL files.

The application has no cloud synchronization. Fully enriched factual release metadata can enter the app's own public Kat·a·log under the conservative rules described above; personal tracking and account identity remain private. A manual PEGI lookup sends the typed title to PEGI. Starting the PEGI background scanner sends each eligible game's title to PEGI in turn. Cover lookup sends the title and platform to each configured artwork provider // shared SteamGridDB and IGDB application connections plus the account's optional TheGamesDB connection // and their individual background scans do the same for eligible games. Public Kat·a·log autocomplete is local to this server. When the IGDB application is connected, typed text is sent after the third character; the shared SteamGridDB connection is the remote fallback. Failed remote autocomplete remains invisible. Connecting Steam sends the supplied profile reference to Steam's Web API for resolution. Previewing or importing sends the resolved SteamID and returns that profile's owned titles, playtime snapshots, and last-played timestamps; the shared API key remains server-side.

Generated from docs/user-guide.md. Do not edit this HTML directly.