Metadata Plugin Guide

Metadata Plugin Guide

Metadata plugins scrape game information from external sources - descriptions, ratings, screenshots, cover art.

Hooks

Hook	Returns	Purpose
metadata_provider_name()	str	Display name in UI (e.g. "PPE.pl")
metadata_provider_id()	str	Unique ID (e.g. "ppe")
metadata_search_game(query)	list[dict]	Search for games by title
metadata_get_game(provider_game_id)	dict or None	Fetch full metadata
metadata_get_cover_url(provider_game_id)	str or None	Get cover image URL

Search Results Format

metadata_search_game() must return a list of dicts:

[
    {
        "provider_id": "ppe",           # Your provider ID
        "provider_game_id": "https://...",  # Unique ID (URL, API ID, etc.)
        "name": "The Witcher 3",        # Game title
        "snippet": "Open world RPG...", # Short description
    }
]

Game Metadata Format

metadata_get_game() must return a dict:

{
    "provider_id": "ppe",
    "provider_game_id": "https://...",
    "title": "The Witcher 3",
    "description": "Full game description...",
    "rating": 92.5,                    # Numeric score
    "genre": "RPG",
    "release_date": "2015-05-19",      # YYYY-MM-DD format
    "developer": "CD Projekt Red",
    "screenshots": [                    # List of image URLs
        "https://example.com/ss1.jpg",
        "https://example.com/ss2.jpg",
    ],
    "source_url": "https://ppe.pl/gry/wiedźmin-3",
}

All fields except provider_id are optional.

Example: PPE.pl Scraper

The PPE.pl plugin shows a complete implementation:

1. Search - finds game pages via Bing/DuckDuckGo
2. Fuzzy matching - compares search result titles with query (65% threshold)
3. Scraping - parses HTML with BeautifulSoup
4. CAPTCHA handling - detects and skips CAPTCHA pages

Key patterns from the example:

• Use httpx for async-safe HTTP requests
• Use BeautifulSoup for HTML parsing
• Implement fuzzy title matching to avoid wrong results
• Handle errors gracefully (return None or empty list)

Config Schema

Use config_schema in plugin.json for user-configurable options:

{
  "config_schema": {
    "enabled": {
      "type": "boolean",
      "default": true,
      "label": "Enable scraper"
    },
    "search_engine": {
      "type": "select",
      "options": ["bing", "duckduckgo"],
      "default": "bing",
      "label": "Search engine"
    },
    "min_match_score": {
      "type": "number",
      "default": 0.65,
      "label": "Minimum match score (0-1)"
    }
  }
}

Settings render in Settings > Plugins > Your Plugin.

Dependencies

List pip packages in requires (plugin.json) or requirements.txt:

"requires": ["beautifulsoup4", "httpx"]

Dependencies are installed automatically when the plugin is installed.