Game Sourcing
Overview
Games are never hosted directly by the platform. They are loaded and played inside iframes, regardless of where they come from. This applies to broker-sourced games, future developer-submitted games, and any experimental content.
Broker Integration
Phase 1: GameDistribution
The initial game catalog comes from GameDistribution, a third-party broker that provides browser games via iframes.
- Games are embedded using broker-provided iframe URLs
- Game metadata (title, description, categories, icons) is imported from the broker catalog
- Category mapping and post-processing are applied during import
Abstraction Layer
The system is designed to support multiple brokers without coupling to any specific one:
- Each broker is abstracted behind a common interface
- Adding or replacing a broker requires implementing the interface, not changing core logic
- Game data model is broker-agnostic; broker-specific identifiers are stored as metadata
Deduplication
- In Phase 1, deduplication is based on the broker + external ID pair (stored as
broker+brokerExternalIdin the Game model with a unique constraint) - Secondary check: iframe URL comparison to catch games with different external IDs pointing to the same content
- On duplicate detection during import: game is skipped and counted in the import report
- On duplicate detection during manual creation: admin sees a warning with a link to the existing game
- The deduplication system is designed to be extended with additional rules as new sources are added
Category Mapping
Broker categories often don’t map 1:1 to Playupi categories. The import process applies a mapping table:
| Step | Detail |
|---|---|
| 1. Exact match | If the broker category name matches a Playupi category name (case-insensitive), use it |
| 2. Alias lookup | A configurable alias table maps broker names to Playupi categories (e.g., “Arcade” → “Action”, “Brain” → “Puzzle”) |
| 3. Fallback | If no match is found, the game is imported without categories and flagged for manual review |
| 4. Multi-category | A broker game can map to multiple Playupi categories |
The alias table is stored as a JSON config file (config/category-aliases.json) and can be updated without a code deploy.
Broker API Integration
GameDistribution provides a REST API for catalog access:
| Detail | Value |
|---|---|
| Catalog endpoint | Public JSON feed of available games |
| Data provided | Title, description, categories, thumbnail URL, iframe URL, external ID |
| Data not provided | Instructions, author details (may need enrichment) |
| Rate limits | Respect broker API rate limits during bulk import |
| Auth | API key (stored as environment variable, not in code) |
Specific API URLs and keys are not documented here — they are external dependencies that may change. The import script abstracts these behind the broker interface.
Builds
Each game has one or more builds. A build represents a specific version of the game.
- Currently: one build per game (single iframe URL)
- Future: multiple builds per game to support versioning, A/B testing, and playtests
- One build is always marked as Live (the one shown to players)
The build structure is in place from the start even though multi-build is not enabled in the MVP.
Future: Developer Portal
A dedicated portal will allow game developers to:
- Submit games directly to the platform
- Manage builds, metadata, and visibility
- Access analytics for their games
Developer-submitted games will also use iframes, maintaining architectural consistency. The portal creates games through the same pipeline as broker imports.