mirror of
https://github.com/ryankazokas/turbovault-app.git
synced 2026-04-16 22:12:53 +00:00
115 lines
2.6 KiB
Markdown
115 lines
2.6 KiB
Markdown
# IGDB Integration
|
|
|
|
TurboVault integrates with the [Internet Game Database (IGDB)](https://www.igdb.com/) to automatically enrich your games with metadata, cover art, and genre information.
|
|
|
|
## How It Works
|
|
|
|
1. **Background sync** runs every 30 minutes (configurable)
|
|
2. **Searches IGDB** for games without metadata
|
|
3. **Creates suggestions** with confidence scores (0-100%)
|
|
4. **Users review** and approve/reject matches
|
|
5. **Metadata applied** when approved (cover art, genres, release dates)
|
|
|
|
## Setup
|
|
|
|
### Get IGDB Credentials
|
|
|
|
1. Create account at https://dev.twitch.tv
|
|
2. Register an application
|
|
3. Copy Client ID and Client Secret
|
|
|
|
### Configure
|
|
|
|
Add to `.env`:
|
|
|
|
```bash
|
|
IGDB_CLIENT_ID=your_client_id_here
|
|
IGDB_CLIENT_SECRET=your_client_secret_here
|
|
```
|
|
|
|
### Enable for Users
|
|
|
|
New users have IGDB sync enabled by default. Users can opt-out in Settings.
|
|
|
|
## Usage
|
|
|
|
### Review Matches
|
|
|
|
Visit `/igdb_matches` to see pending suggestions.
|
|
|
|
Each suggestion shows:
|
|
- Game title
|
|
- Cover art
|
|
- Platform
|
|
- Confidence score
|
|
- Genres from IGDB
|
|
|
|
**Actions:**
|
|
- ✅ **Approve** - Apply metadata to your game
|
|
- ❌ **Reject** - Dismiss suggestion
|
|
- 🔄 **Sync Now** - Manually trigger sync for your games
|
|
|
|
### Manual Commands
|
|
|
|
```bash
|
|
# Trigger sync manually
|
|
task igdb:sync
|
|
|
|
# Check sync status
|
|
task igdb:status
|
|
|
|
# Clear stuck jobs
|
|
task igdb:clear
|
|
```
|
|
|
|
## How Matching Works
|
|
|
|
**Confidence scoring:**
|
|
- Title match: 0-70 points
|
|
- Platform match: 0-30 points
|
|
- 100% = exact title + platform match
|
|
|
|
**Fallback search:**
|
|
- First tries with platform filter
|
|
- Falls back to no platform if no results
|
|
|
|
**Genre mapping:**
|
|
IGDB genres are automatically mapped to your local genres (e.g., "Role-playing (RPG)" → "RPG").
|
|
|
|
## Platform Support
|
|
|
|
26 platforms supported including:
|
|
- Nintendo (NES, SNES, N64, GameCube, Wii, Switch)
|
|
- PlayStation (PS1-PS5, PSP, Vita)
|
|
- Xbox (Xbox, 360, One, Series X/S)
|
|
- Sega (Genesis, Dreamcast, Saturn)
|
|
- PC platforms (Steam, Epic, GOG)
|
|
|
|
## Background Job
|
|
|
|
**Schedule:** Every 30 minutes
|
|
**Configuration:** `config/queue.yml`
|
|
**Job:** `IgdbSyncJob`
|
|
|
|
The job:
|
|
- Only processes users with `igdb_sync_enabled: true`
|
|
- Skips games with `igdb_id` already set
|
|
- Creates up to 3 match suggestions per game
|
|
- Respects rate limits (4 requests/second)
|
|
|
|
## API Rate Limits
|
|
|
|
- **Limit:** 4 requests per second
|
|
- **Handled:** Automatic 0.3s delay between requests
|
|
- **Caching:** Games cached in `igdb_games` table
|
|
|
|
## Disabling IGDB
|
|
|
|
Users can disable in Settings → "Enable IGDB metadata sync"
|
|
|
|
Admins can disable globally by removing env vars or stopping the recurring job.
|
|
|
|
## Attribution
|
|
|
|
IGDB attribution link in footer (required by IGDB terms).
|