Skip to main content

Metadata Integration

Metadata is the secret sauce that makes your themes dynamic. Instead of showing static text or images, metadata pulls live information from games and systems. One theme, infinite variations!

What is Metadata?​

Static content:

Text: "Pac-Man"
Image: pacman_logo.png

Same for every game. Boring.

Dynamic metadata:

Text: {GameName}
Image: {GameArt}

Changes for EVERY game automatically. Magic!

Metadata = placeholders that get filled in with actual game/system information.

How Metadata Updates Dynamically​

The Auto-Update System​

When you navigate in HyperSpin:

  1. User scrolls wheel to different game
  2. HyperSpin sends game information to theme
  3. Theme receives new metadata
  4. All metadata layers update instantly
  5. You see new game's information

This happens automatically - no configuration needed!

Real-Time Updates​

Metadata layers are smart:

  • Connected to HyperSpin's wheel position
  • Update on every wheel movement
  • No delay or lag (instant updates)
  • Works with all metadata types simultaneously

Example in action:

Wheel position: Game 1 → Metadata shows Game 1 info
User scrolls...
Wheel position: Game 2 → Metadata shows Game 2 info
User scrolls...
Wheel position: Game 3 → Metadata shows Game 3 info

All text and images update in sync!

What Updates​

When wheel changes, these update:

  • ✅ Metadata Text (game name, year, etc.)
  • ✅ Metadata Images (box art, screenshots, etc.)
  • ✅ Metadata Icons (system/game icons)
  • ✅ Metadata Video URLs (gameplay videos)
  • ❌ Static text (doesn't change)
  • ❌ Regular images (stay the same)
  • ❌ Animations (continue playing)

Only metadata layers respond to wheel changes.

Why Use Metadata?​

Without metadata:

  • Create separate theme for each game
  • Manually update text and images
  • Thousands of games = thousands of themes
  • Maintenance nightmare

With metadata:

  • Create ONE theme
  • Metadata fills in automatically
  • Works for ALL games in the system
  • Update once, applies everywhere

This is the power move for theme designers!

Types of Metadata​

HyperTheme supports two main categories:

Game Metadata​

Information about individual games:

  • Game name
  • Description/overview
  • Release year
  • Developer/publisher
  • Genre
  • Rating (ESRB)
  • Player count
  • Box art, screenshots, videos

System Metadata​

Information about gaming systems/platforms:

  • System name
  • Description
  • Manufacturer
  • Release year
  • Hardware specs (CPU, RAM, etc.)
  • System logo
  • Category

Metadata Fields Available​

Game Metadata Fields​

Text Fields:

  • Name - Game title (e.g., "Super Mario Bros.")
  • Overview - Game description/synopsis
  • Developer - Who made it (e.g., "Sega")
  • Publisher - Who published it
  • ReleaseYear - Year released (e.g., "1985")
  • ReleaseDate - Full date (e.g., "September 13, 1985")
  • Genres - Game genres (e.g., "Platformer, Action")
  • Players - Number of players (e.g., "1-2")
  • Platform - System/console (e.g., "Genesis")
  • FileName - ROM filename
  • ESRB - Rating (E, T, M, etc.)

Media Fields:

  • BoxArt - Front box/cover art
  • Icon - Game-specific icon (small image)
  • SystemIcon - System/platform icon
  • Screenshot - In-game screenshot
  • ClearLogo - Logo with transparent background
  • Banner - Wide banner image
  • VideoUrl - Gameplay video

System Metadata Fields​

Text Fields:

  • Name - System name (e.g., "Sega Genesis")
  • Description - System description
  • Manufacturer - Who made it (e.g., "Sega")
  • CPU - Processor info
  • Memory - RAM specifications
  • Graphics - GPU/graphics info
  • Sound - Audio chip info
  • Display - Resolution/display specs
  • Media - Media type (cartridge, disc, etc.)
  • MaxControllers - Maximum controllers supported
  • Category - System category/generation

Media Fields:

  • Logo - System logo
  • Icon - System icon

Adding Metadata to Your Theme​

Metadata Text​

Add dynamic text that changes per game:

  1. Click the metadata text icon in bottom toolbar
  2. Or right-click canvas (if context menu available)
  3. Select Metadata Text
  4. A text element appears with placeholder
  5. Configure in Properties (right panel)

In the Properties panel:

  • Field - Choose which metadata field to display
    • Name, Developer, ReleaseYear, etc.
  • Font - Typography settings
  • Color - Text color
  • Size - Font size
  • Alignment - Left, center, right
  • All standard text properties

Example setup:

Field: GameName
Font: Arial Bold
Size: 48
Color: White
Position: Top-center

Result: "Pac-Man" (or whatever game is selected)

Metadata Images​

Add dynamic images that change per game:

  1. Click the metadata image icon in bottom toolbar
  2. Select Metadata Image
  3. An image placeholder appears
  4. Configure in Properties (right panel)

In the Properties panel:

  • Field - Choose which image field to use
    • BoxArt, Screenshot, ClearLogo, Banner, VideoUrl
  • Fit Mode - How image scales
    • Contain (fit inside, maintain aspect)
    • Cover (fill space, may crop)
    • Stretch (fill space, may distort)
    • Actual size (no scaling)
  • All standard image properties (position, scale, etc.)

Example setup:

Field: BoxArt
Fit Mode: Contain
Width: 400px
Height: 600px
Position: Center-left

Result: Shows box art for current game

Metadata Icons​

Add dynamic icons that update per game/system:

Icon Types:

  • Game Icons - Small game-specific graphics
  • System Icons - Platform/console icons
  • Multiple formats supported

How to add:

  1. Click the metadata icon button in bottom toolbar
  2. Icon element appears with placeholder
  3. Configure in Properties (right panel)

Properties:

  • Icon Type - Choose game icon or system icon
  • Size - Width and height
  • Position - Where to place icon
  • All standard transform properties

Use cases:

  • Small game identifier icons
  • System badges in corners
  • Icon strips showing features
  • Platform indicators

Example setup:

Icon Type: System Icon
Size: 64x64px
Position: Top-right corner
Opacity: 80%

Result: Shows system logo for current game's platform

Pro tip: Icons are perfect for compact visual indicators without taking up much space!

Metadata Video​

For video backgrounds:

Field: VideoUrl

  • Points to gameplay video
  • Auto-plays in theme
  • Loops continuously (usually)

Use cases:

  • Background gameplay footage
  • Trailer playing behind UI
  • Dynamic, living themes

Metadata Layout Strategies​

The Classic Wheel Theme​

Standard layout:

┌─────────────────────────────────────┐
│  [System Logo]              [Year]  │
│                                     │
│          [Game Name]                │
│                                     │
│  [Box]  [Box]  [BOX]  [Box]  [Box] │
│               ^^^^^^                │
│           (selected)                │
│                                     │
│         [Description]               │
│                                     │
│  Genre: {Genre}  Players: {Players} │
└─────────────────────────────────────┘

Metadata elements:

  • Game Name (large, top-center)
  • Box Art (in wheel, changes per game)
  • Description (smaller text, bottom)
  • Genre, Players, Year (info bar)

The Details Panel​

Information-heavy layout:

┌─────────────────────┬───────────────┐
│                     │               │
│                     │  Game Name    │
│   [Large Box Art]   │               │
│                     │  Developer    │
│                     │  Year         │
│                     │  Genre        │
│                     │               │
│                     │  Description  │
│                     │  paragraph    │
│                     │               │
└─────────────────────┴───────────────┘

Shows:

  • All available metadata
  • Comprehensive information
  • Good for browsing/discovery

The Minimalist​

Clean, simple:

┌─────────────────────────────────────┐
│                                     │
│                                     │
│                                     │
│          [Clear Logo]               │
│                                     │
│           {Genre}                   │
│                                     │
│                                     │
└─────────────────────────────────────┘

Just essentials:

  • Logo (transparent)
  • One or two key facts
  • Let the art speak

The Video Background​

Immersive experience:

┌─────────────────────────────────────┐
│ {VideoUrl as background}            │
│                                     │
│     [Overlay with game info]        │
│                                     │
│     Game Name                       │
│     Developer - Year                │
│                                     │
└─────────────────────────────────────┘

Dynamic video:

  • Gameplay footage plays behind UI
  • Changes per game
  • Very engaging!

Styling Metadata​

Text Styling​

Make metadata look good:

Fonts:

  • Bold for game names (emphasis)
  • Regular for descriptions
  • Condensed for fitting more text

Colors:

  • High contrast for readability
  • Match theme color scheme
  • Consider background (video/images behind text)

Outlines/Shadows:

  • Add outline for text on busy backgrounds
  • Drop shadows for depth
  • Glow effects for sci-fi themes

Example styling:

Game Name:
  Font: Montserrat Bold
  Size: 72px
  Color: White
  Outline: 3px black

Developer:
  Font: Roboto Regular
  Size: 24px
  Color: Light gray
  No outline

Image Styling​

Present metadata images well:

Frames:

  • Add border layer around box art
  • Makes it pop
  • Professional look

Reflections:

  • Duplicate box art
  • Flip vertically
  • Low opacity
  • Positioned below original
  • Classic reflection effect!

Shadows:

  • Drop shadow behind images
  • Adds depth
  • Separates from background

3D Effects:

  • Slight rotation (5-10 degrees)
  • Perspective using projection points
  • Looks like physical media

Animating Metadata​

Metadata elements can be animated like any layer!

Text Animations​

Entrance effects:

  • Fade in while game changes
  • Slide in from side
  • Scale up from center

Idle animations:

  • Subtle glow pulse
  • Gentle float
  • Slight scale breathing

Avoid:

  • Scrolling text (use Scrollable Text instead)
  • Too much motion (hard to read)
  • Constant animation (distracting)

Image Animations​

Box art animations:

  • Selected item: Scale up, glow
  • Unselected items: Scale down, dim
  • Transition smoothly between states

Entrance:

  • Fade in when game changes
  • Slide in from direction
  • 3D rotation effect

Idle:

  • Gentle float
  • Subtle rotation
  • Pulse/breathing effect

Example: Selected box art

Scale: 1.0 → 1.2 (selected gets bigger)
Opacity: 0.7 → 1.0 (selected fully visible)
Glow: Add bloom effect
Duration: 0.5s
Easing: Back.Out

Fallback Handling​

What happens when metadata is missing?

Missing Text Data​

If field is empty:

  • Shows blank/nothing
  • Or placeholder text (depends on theme)
  • Design around this!

Strategies:

  • Use multiple fields (if Name missing, show FileName)
  • Design works without text
  • Test with games that have incomplete data

Missing Images​

If image field is empty:

  • Shows placeholder/nothing
  • Or broken image icon

Strategies:

  • Use fallback images (generic box art)
  • Design layout works without image
  • Test with games missing artwork

Best practice:

  • Test theme with incomplete game data
  • Make sure it doesn't look broken
  • Graceful degradation!

Metadata Best Practices​

Design Considerations​

Readability:

  • Text must be readable against backgrounds
  • Use outlines/shadows on busy backgrounds
  • Sufficient contrast
  • Appropriate font sizes

Layout:

  • Leave space for long text
  • Game names can be lengthy!
  • Descriptions vary in length
  • Design for maximum content

Consistency:

  • Same position for metadata across games
  • Predictable layout
  • User knows where to look

Testing​

Test with various games:

Short names:

  • "ICO"
  • "Doom"
  • "Fez"

Long names:

  • "The Legend of Zelda: Breath of the Wild"
  • "Sid Meier's Civilization VI: Rise and Fall"
  • "Tom Clancy's Rainbow Six Siege"

No artwork:

  • Games with missing box art
  • Missing screenshots
  • No video

Complete data:

  • Games with everything
  • Verify it all displays correctly

Testing checklist:

  • Short game names display well
  • Long game names don't break layout
  • Missing images don't break theme
  • Missing text fields handled gracefully
  • All metadata positions correctly
  • Readable on all backgrounds

Advanced Metadata Techniques​

Conditional Styling (Manual)​

Different styles based on content:

Since HyperTheme doesn't have conditional logic (yet), you simulate it:

Multiple layers approach:

Layer 1: Game Name (normal position)
Layer 2: Game Name (alternate position for long names)

Designer picks which to use per theme variant

Multi-Language Support​

If metadata has multiple languages:

  • Check what language metadata provides
  • Design for longest language (usually German or French)
  • Test with non-English games

Metadata + Filters​

Style metadata images dynamically:

Example: Unselected box art

  • Add Grayscale filter (0.7)
  • Reduce opacity (0.5)
  • Blur slightly (2px)
  • Makes selected stand out!

Example: Retro theme

  • Add CRT filter to all metadata images
  • Pixelate screenshots
  • Consistent retro aesthetic

Metadata Combinations​

Combine multiple metadata fields:

Example: Info string

{Developer} • {Year} • {Genre}

Displays as:
"Sega • 1991 • Platformer"

Implementation:

  • Three separate metadata text elements
  • Position next to each other
  • Add separator graphics (bullets) between

Metadata Workflow​

Design Process​

  1. Plan layout

    • Sketch where metadata goes
    • Which fields to show
    • Priority of information

  2. Add placeholders

    • Add metadata elements
    • Position them
    • Set fonts and styling

  3. Test with real data

    • Preview with actual games
    • Check various game types
    • Verify nothing breaks

  4. Animate

    • Add entrance/exit effects
    • Idle animations
    • State changes (selected/unselected)

  5. Polish

    • Fine-tune positioning
    • Adjust styling
    • Handle edge cases

Common Workflows​

Wheel theme workflow:

  1. Background (static or video)
  2. Game name at top (metadata text)
  3. Wheel items with box art (metadata images)
  4. Info bar at bottom (multiple metadata texts)
  5. Animate selected item

Detail view workflow:

  1. Large box art (metadata image)
  2. Game information (multiple metadata texts)
  3. Description (scrollable metadata text if supported)
  4. Background video (metadata video)
  5. Smooth transitions between games

Metadata Reference​

Game Fields Quick Reference​

FieldExampleTypeNotes
Name"Pac-Man"TextGame title
Developer"Namco"TextCreator
Publisher"Atari"TextPublisher
ReleaseYear"1980"TextYear only
Genre"Arcade"TextCan be multiple
Players"1-2"TextPlayer count
ESRB"E"TextRating
Overview"Eat dots..."TextDescription
BoxArt[image]ImageCover art
Screenshot[image]ImageIn-game shot
ClearLogo[image]ImageTransparent logo
VideoUrl[video]VideoGameplay video

System Fields Quick Reference​

FieldExampleTypeNotes
Name"Genesis"TextSystem name
Manufacturer"Sega"TextWho made it
CPU"Ricoh 2A03"TextProcessor
Memory"2KB RAM"TextRAM specs
ReleaseYear"1983"TextLaunch year
Logo[image]ImageSystem logo

Next Steps​

Pro Tip: Design your theme to look good even when metadata is missing. That's the mark of a professional theme designer! 🎮✨