Navigation

Game + Mothership Integration Template

Complete guide for creating standalone games with pearl economy

Template Description

A pre-configured standalone game template with full Mothership pearl economy integration. Includes authentication, Supabase database schema, pearl reward system, leaderboard structure, and SDK integration. Perfect for rapidly deploying new idiom-learning games that connect to the Snappy Idioms ecosystem.

What's Included in the Template
All the core components you need to launch a new game

Supabase Schema

  • GameDeveloper entity (with game_id, secret_key, base_pearl_rate)
  • TransactionHistory entity (for pearl transactions)
  • GridironScore entity (or equivalent game score table)
  • UserPearlBalance sync structure
  • RLS policies pre-configured

Backend Functions

  • gameAPISupabase - Secure API endpoint with HMAC signing
  • Pearl calculation logic (hybrid model: 2 per game + 1 per 100 points)
  • Duplicate reward prevention (level_id tracking)
  • Nonce validation & timestamp verification
  • Developer credential management

Game Components

  • Leaderboard component (shows Games Played, not Rolls)
  • Game board/field component
  • Score tracking integration
  • Pearl reward display
  • Integration guide page

Security & Auth

  • HMAC signature verification
  • Request timestamp validation (5-minute window)
  • Nonce-based replay attack prevention
  • Secret key generation system
  • IP tracking for fraud detection

SDK Integration

  • Mothership SDK documentation
  • Example game completion calls
  • Progress sync patterns
  • Error handling examples
  • Offline support guidelines
Customization Checklist
Follow these steps to transform the template into your new game

1. Initial Setup

  • Clone the template in Base44
  • Rename the app to your game name (e.g., "Word Up Standalone")
  • Connect to your GitHub repository
  • Verify Supabase integration is active

2. Database Customization

  • Rename GridironScore entity to [YourGame]Score (e.g., WordUpScore)
  • Update score fields to match your game mechanics
  • Keep pearl tracking fields (pearls_earned)
  • Add any game-specific data fields (e.g., tiles_completed, words_found)
  • Update RLS policies if needed

3. Game Logic

  • Replace game board component with your game UI
  • Implement your scoring algorithm
  • Customize pearl calculation formula (keep base: 2 per game + points-based)
  • Update level_id generation to match your game structure
  • Test game completion triggers pearl rewards

4. Developer Credentials

  • Generate new game_id (e.g., "word_up_01")
  • Generate new secret_key for HMAC signing
  • Add GameDeveloper record to Supabase
  • Set base_pearl_rate for your game
  • Update integration guide with new credentials

5. API Endpoint

  • Update gameAPISupabase function endpoint routing
  • Customize /complete handler for your game events
  • Update pearl calculation logic if needed
  • Verify signature validation works
  • Test duplicate reward prevention

6. Leaderboard

  • Update leaderboard query to use your score entity
  • Customize displayed stats (Games Played, High Score, etc.)
  • Update sorting logic for your game
  • Test real-time updates
  • Add game-specific achievements if applicable

7. UI/Branding

  • Replace game logo and imagery
  • Update color scheme to match your game theme
  • Customize onboarding instructions
  • Update help text and tooltips
  • Add your game-specific icons

8. Integration Guide

  • Update GridironIntegrationGuide page with your game name
  • Customize SDK code examples
  • Update game_id in all documentation
  • Test credential generation flow
  • Verify copy-to-clipboard functions work

9. Testing

  • Test game completion → pearl reward flow
  • Verify duplicate rewards are blocked
  • Test leaderboard updates in real-time
  • Check HMAC signature validation
  • Test with multiple user accounts
  • Verify Supabase RLS policies work correctly

10. Deployment

  • Set Supabase environment variables
  • Deploy to production
  • Test production API endpoints
  • Monitor first real user transactions
  • Set up error logging/monitoring
Quick Reference

Pearl Formula:

2 pearls per game + 1 pearl per 100 points

Example game_id:

word_up_01, scrabble_01, crossword_01

Core Files to Customize:

  • entities/[YourGame]Score.json
  • functions/gameAPISupabase.js
  • pages/[YourGame]IntegrationGuide.jsx
  • components/games/[yourGame]/Leaderboard.jsx

This template powers all Snappy Idioms standalone games with consistent pearl rewards.

Need help? Check the integration guide page in each cloned app.