Migration Guide: From Google Play Games Plugin for Unity to Essential Kit Game Services

This guide provides step-by-step instructions for migrating from Google Play Games Plugin to Essential Kit's Game Services. The migration process involves updating your authentication, achievements, leaderboards, and friends management code to use Essential Kit's unified cross-platform API.

Prerequisites

• Essential Kit package installed and configured

• Existing Google Play Games Plugin project to migrate

• Platform IDs for your existing leaderboards and achievements

Migration Overview

Aspect	Google Play Games Plugin	Essential Kit Game Services
Namespace	using GooglePlayGames;	using VoxelBusters.EssentialKit;
Platform Support	Android only	iOS + Android unified
Initialization	PlayGamesPlatform.Activate()	GameServices.Initialize() (optional)
Authentication	Social.localUser.Authenticate()	GameServices.Authenticate()
Platform Abstraction	Unity's Social API + Google extensions	Essential Kit unified API

Step 1: Configuration Setup

1.1 Remove Google Play Games Plugin Configuration

// REMOVE: Old Google Play Games initialization
PlayGamesPlatform.Activate();
PlayGamesPlatform.Instance.AddIdMapping("high_scores", "CgkIabcdefghijklmnop");
PlayGamesPlatform.Instance.AddIdMapping("first_win", "CgkIxyzuvwabcdefgh");

1.2 Configure Essential Kit Settings

1. Open Window → Voxel Busters → Essential Kit → Settings

2. Navigate to Game Services section

3. Configure your leaderboards and achievements:

Leaderboards Configuration:

Leaderboards:
├── [0] High Scores
│   ├── Id: "high_scores"
│   ├── iOS Platform Id: "com.yourgame.highscores" 
│   ├── Android Platform Id: "CgkIabcdefghijklmnop"
│   ├── Title: "High Scores"
│   └── Score Format Type: Integer
└── [+] Add New Leaderboard

Achievements Configuration:

Achievements:
├── [0] First Victory  
│   ├── Id: "first_win"
│   ├── iOS Platform Id: "com.yourgame.firstwin"
│   ├── Android Platform Id: "CgkIxyzuvwabcdefgh" 
│   ├── Title: "First Victory"
│   ├── Description: "Win your first game"
│   └── Point Value: 100
└── [+] Add New Achievement

Step 2: Namespace and Initialization Migration

2.1 Update Using Statements

// REMOVE: Old namespaces
// using GooglePlayGames;
// using GooglePlayGames.BasicApi;
// using UnityEngine.SocialPlatforms;

// ADD: Essential Kit namespaces
using VoxelBusters.CoreLibrary;
using VoxelBusters.EssentialKit;

2.2 Update Initialization Code

// OLD: Google Play Games initialization
void InitializeLegacyPlugin()
{
    PlayGamesPlatform.Activate();
    Social.localUser.Authenticate(OnAuthenticate);
}

// NEW: Essential Kit initialization (optional - auto-initializes from settings)
void InitializeEssentialKit()
{
    // Subscribe to auth status changes
    GameServices.OnAuthStatusChange += OnAuthStatusChange;

    // Authenticate (returns immediately if already signed in)
    GameServices.Authenticate();
}

Step 3: Authentication Migration

3.1 Authentication Status Handling

// OLD: Google Play Games authentication
private void OnAuthenticate(bool success)
{
    if (success)
    {
        Debug.Log("Authenticated successfully");
        string playerId = Social.localUser.id;
        string playerName = Social.localUser.userName;
    }
    else
    {
        Debug.Log("Authentication failed");
    }
}

// NEW: Essential Kit authentication
private void OnAuthStatusChange(GameServicesAuthStatusChangeResult result, Error error)
{
    if (error == null)
    {
        switch (result.AuthStatus)
        {
            case LocalPlayerAuthStatus.Authenticated:
                Debug.Log("Player authenticated successfully");
                var localPlayer = GameServices.LocalPlayer;
                string playerId = localPlayer.Identifier;
                string playerName = localPlayer.DisplayName;
                break;
                
            case LocalPlayerAuthStatus.NotAvailable:
                Debug.Log("Authentication state unavailable or player signed out");
                break;
                
            case LocalPlayerAuthStatus.Authenticating:
                Debug.Log("Authentication in progress...");
                break;
        }
    }
    else
    {
        Debug.LogError($"Authentication error: {error.Description}");
    }
}

3.2 Check Authentication Status

// OLD: Check authentication status
bool isAuthenticated = Social.localUser.authenticated;

// NEW: Check authentication status
bool isAuthenticated = GameServices.IsAuthenticated;

Step 4: Achievement Migration

4.1 Reporting Achievement Progress

// OLD: Google Play Games achievement reporting
Social.ReportProgress("first_win", 100.0, (bool success) =>
{
    if (success)
        Debug.Log("Achievement unlocked!");
});

// Alternative Google method
PlayGamesPlatform.Instance.UnlockAchievement("first_win", (bool success) => 
{
    Debug.Log($"Achievement unlock: {success}");
});

// NEW: Essential Kit achievement reporting
GameServices.ReportAchievementProgress("first_win", 100.0, (success, error) =>
{
    if (success && error == null)
    {
        Debug.Log("Achievement unlocked!");
    }
    else
    {
        Debug.LogError($"Achievement error: {error.Description}");
    }
});

4.2 Loading Achievements

// OLD: Google Play Games load achievements
Social.LoadAchievements((IAchievement[] achievements) =>
{
    foreach (var achievement in achievements)
    {
        Debug.Log($"Achievement: {achievement.id}, Progress: {achievement.percentCompleted}");
    }
});

// NEW: Essential Kit load achievements
GameServices.LoadAchievements((result, error) =>
{
    if (error == null)
    {
        foreach (var achievement in result.Achievements)
        {
            Debug.Log($"Achievement: {achievement.Id}, Progress: {achievement.PercentageCompleted}");
        }
    }
    else
    {
        Debug.LogError($"Load achievements error: {error.Description}");
    }
});

4.3 Show Achievements UI

// OLD: Google Play Games show achievements
Social.ShowAchievementsUI();

// NEW: Essential Kit show achievements
GameServices.ShowAchievements((result, error) =>
{
    if (error == null)
    {
        Debug.Log("Achievements UI closed");
    }
});

Step 5: Leaderboard Migration

5.1 Reporting Scores

// OLD: Google Play Games score reporting
Social.ReportScore(1000, "high_scores", (bool success) =>
{
    Debug.Log($"Score reported: {success}");
});

// NEW: Essential Kit score reporting
GameServices.ReportScore("high_scores", 1000, (success, error) =>
{
    if (success && error == null)
    {
        Debug.Log("Score reported successfully");
    }
    else
    {
        Debug.LogError($"Score report error: {error.Description}");
    }
});

// NEW: Score reporting with context tag
GameServices.ReportScore("high_scores", 1000, (success, error) =>
{
    if (success && error == null)
    {
        Debug.Log("Score reported successfully with tag");
    }
    else
    {
        Debug.LogError($"Score report error: {error?.Description}");
    }
}, tag: "level_1");

5.2 Loading Leaderboards

// OLD: Google Play Games load leaderboard
var leaderboard = Social.CreateLeaderboard();
leaderboard.id = "high_scores";
leaderboard.LoadScores((bool success) =>
{
    if (success)
    {
        foreach (var score in leaderboard.scores)
        {
            Debug.Log($"Score: {score.value}, Player: {score.userID}");
        }
    }
});

// NEW: Essential Kit load leaderboard
GameServices.LoadLeaderboards((result, error) =>
{
    if (error == null)
    {
        foreach (var leaderboard in result.Leaderboards)
        {
            Debug.Log($"Leaderboard: {leaderboard.Id}, Title: {leaderboard.Title}");
        }
    }
});

5.3 Show Leaderboard UI

// OLD: Google Play Games show leaderboard
Social.ShowLeaderboardUI();

// Or specific leaderboard
PlayGamesPlatform.Instance.ShowLeaderboardUI("high_scores");

// NEW: Essential Kit show leaderboards
GameServices.ShowLeaderboards(LeaderboardTimeScope.AllTime, (result, error) =>
{
    if (error == null)
    {
        Debug.Log("Leaderboards UI closed");
    }
});

// Or specific leaderboard
GameServices.ShowLeaderboard("high_scores", LeaderboardTimeScope.AllTime, (result, error) =>
{
    Debug.Log("Leaderboard UI closed");
});

Step 6: Friends Management Migration

6.1 Loading Friends

// OLD: Google Play Games load friends
Social.localUser.LoadFriends((bool success) =>
{
    if (success)
    {
        foreach (var friend in Social.localUser.friends)
        {
            Debug.Log($"Friend: {friend.userName}");
        }
    }
});

// NEW: Essential Kit load friends
GameServices.LoadFriends((result, error) =>
{
    if (error == null)
    {
        foreach (var friend in result.Players)
        {
            Debug.Log($"Friend: {friend.DisplayName}");
        }
    }
});

6.2 Adding Friends (Essential Kit Feature)

// NEW: Essential Kit specific feature - Add friend
GameServices.AddFriend("player_id_to_add", (success, error) =>
{
    if (error == null && success)
    {
        Debug.Log("Friend request sent successfully");
    }
});

Step 7: Advanced Features Migration

7.1 Server Credentials (Enhanced in Essential Kit)

// OLD: Google Play Games server access
PlayGamesPlatform.Instance.RequestServerSideAccess(true, (string authCode) =>
{
    if (!string.IsNullOrEmpty(authCode))
    {
        // Send auth code to your server
    }
});

// NEW: Essential Kit server credentials
GameServices.LoadServerCredentials((result, error) =>
{
    if (error == null)
    {
        var credentials = result.ServerCredentials;
#if UNITY_ANDROID
        Debug.Log($"Server Auth Code: {credentials.AndroidProperties.ServerAuthCode}");
#elif UNITY_IOS
        Debug.Log($"Public Key Url: {credentials.IosProperties.PublicKeyUrl}");
#endif
        // Send platform-specific values to your backend for verification
    }
});

7.2 Error Handling Improvements

// OLD: Google Play Games basic error handling
Social.ReportScore(1000, "leaderboard", (bool success) =>
{
    if (!success)
    {
        Debug.Log("Score report failed"); // Limited error info
    }
});

// NEW: Essential Kit comprehensive error handling
GameServices.ReportScore("leaderboard", 1000, (success, error) =>
{
    if (!success || error != null)
    {
        Debug.LogError($"Score report failed: {error.Description}");
        Debug.LogError($"Error Code: {error.Code}");
        Debug.LogError($"Domain: {error.Domain}");
        // Detailed error information for debugging
    }
});

Step 8: Event Management Migration

8.1 Subscribe to Game Services Events

// NEW: Essential Kit event subscriptions (in Start or Awake)
private void Start()
{
    // Subscribe to authentication status changes
    GameServices.OnAuthStatusChange += OnAuthStatusChange;
}

private void OnDestroy()
{
    // Unsubscribe to prevent memory leaks
    GameServices.OnAuthStatusChange -= OnAuthStatusChange;
}

Step 9: Platform-Specific Considerations

9.1 Handling iOS Game Center (New Capability)

// Essential Kit automatically handles iOS Game Center integration
// No additional code required - same API works on both platforms

#if UNITY_IOS
    // iOS-specific behavior (if needed)
    Debug.Log("Running on iOS with Game Center integration");
#elif UNITY_ANDROID
    // Android-specific behavior (if needed)
    Debug.Log("Running on Android with Play Games Services");
#endif

Step 10: Testing and Validation

10.1 Testing Checklist

• Authentication works on both platforms

• Achievement unlock/progress reporting functions correctly

• Leaderboard score submission and retrieval works

• UI dialogs display properly

• Friends management functions (if used)

• Error handling provides meaningful feedback

• Cross-platform ID mapping works correctly

10.2 Common Migration Issues and Solutions

Issue: Missing platform IDs

// SOLUTION: Ensure all platform IDs are configured in Essential Kit settings
// Check Window → Voxel Busters → Essential Kit → Configure

Issue: Authentication not working

// SOLUTION: Ensure event subscription and authentication call
GameServices.OnAuthStatusChange += OnAuthStatusChange;
GameServices.Authenticate();

Google Play Services Authentication

Issue: Cross-platform testing

// SOLUTION: Test on both platforms with proper platform IDs
#if UNITY_EDITOR
    Debug.Log("Testing in simulator mode");
#endif

Benefits After Migration

1. Cross-Platform Unity: Single codebase works on both iOS and Android

2. Improved Error Handling: Detailed error information for better debugging

3. Modern API Design: Cleaner, more intuitive method signatures

4. Visual Configuration: Inspector-based setup reduces code complexity

5. Enhanced Features: Additional functionality like AddFriend, server credentials

6. Future-Proof: Unified API insulates from platform-specific changes

This migration guide should help you transition from Google Play Games Plugin to Essential Kit Game Services while taking advantage of the enhanced cross-platform capabilities and improved developer experience.