Best Practices for Implementing the Gamesnack SDK with Wortal

This guide outlines best practices for integrating the Gamesnack SDK with Wortal, including initialization, event handling, and lifecycle management for a smooth and reliable experience.

---

1. Game Initialization

To start, the game should call Wortal.startGameAsync() after ensuring that Wortal is properly initialized. This triggers the Gamesnack SDK’s game.ready, which is required to mark the game as ready.

Example Usage

async function initializeWortal(wortalInstance: Wortal) {
    try {
        await wortalInstance.initializeAsync();
        // SDK is ready. Set loading progress to 100% and start the game.
        wortalInstance.setLoadingProgress(100);
        await wortalInstance.startGameAsync();
        console.log("Wortal initialized successfully");
    } catch (error) {
        console.error("Error initializing Wortal:", error);
    }
}

// Usage example
const wortalInstance = new Wortal();
initializeWortal(wortalInstance);

Key Points

• Ensure Wortal is fully initialized before calling startGameAsync.
• Use error handling to manage any issues during initialization.

---

2. Listening to Platform Audio Settings

Your game should follow the GameSnack platform's audio settings to ensure the best user experience. Subscribe to the audio status using Wortal.session.onAudioStatusChange to automatically adjust game audio.

Example Usage

// Listen for changes in the platform's audio settings and adjust game audio accordingly.
Wortal.session.onAudioStatusChange((isAudioEnabled: boolean) => {
    // Mute or unmute background music based on platform audio settings
    BGMManager.muteBGM(!isAudioEnabled);

    // Mute or unmute sound effects based on platform audio settings
    SFXManager.muteSFX(!isAudioEnabled);
});

Alternative Check

While you can use Wortal.session.isAudioEnabled to check the audio status manually, subscribing to audio changes using Wortal.session.onAudioStatusChange is recommended as it keeps the audio settings synchronized.

---

3. Handling App Lifecycle Events

To handle app lifecycle events, use Wortal.onPause() and Wortal.onResume() to manage the game state when it is backgrounded or foregrounded.

Example Usage

// Call Wortal.onPause() when gameplay is paused
function pauseGame() {
    // Pause gameplay or animations
    Game.pause();

    // Notify the platform that the game is paused
    Wortal.onPause();
}

// Call Wortal.onResume() when gameplay resumes
function resumeGame() {
    // Resume gameplay or animations
    Game.resume();

    // Notify the platform that the game has resumed
    Wortal.onResume();
}

Key Points

• Call Wortal.onPause() whenever gameplay is paused, stopping any animations or time-sensitive logic as needed.
• Call Wortal.onResume() whenever gameplay resumes, allowing players to continue from where they left off and resuming any paused logic.

---

4. Logging Game Events

Logging events like gameOver or levelComplete is essential. Use Wortal.analytics.logLevelEnd() to log the outcome of gameplay.

Example Usage

// Game over due to level failure
Wortal.analytics.logLevelEnd("1", "100", false);

// Game over due to successful completion
Wortal.analytics.logLevelEnd("1", "100", true);

Key Points

• Call Wortal.analytics.logLevelEnd() at the end of each gameplay session.
• For endless games, use a dummy level string, ensuring wasCompleted accurately reflects success or failure.

---

5. Updating High Scores and Progress Metrics

To enable features like leaderboards, it is essential to update scores or progress metrics using Wortal.stats.postStatsAsync() at the end of every gameplay session or whenever there’s a high score update. This step is mandatory for GameSnacks compatibility.

Example Usage

// Update score or progress at the end of each session 
Wortal.stats.postStatsAsync("Level", myScore) .then(() => { 
        console.log("High score posted successfully"); 
    }) .catch((error) => { 
        console.error("Failed to post high score:", error); 
});

Key Points

• Mandatory: Call Wortal.stats.postStatsAsync() after each gameplay session or high score update to keep scores up to date on GameSnacks.
• Levels: Use the actual level as the first parameter. If your game doesn’t have levels, pass a placeholder string (e.g., "Level").
• Error Handling: Log any errors to help identify issues with score updates.

---

Following these best practices ensures a seamless integration of the Gamesnack SDK with Wortal, enhancing player experience and enabling valuable platform features.

---

Note

The examples provided above are in TypeScript, but Wortal supports SDKs for various game engines, such as Unity, Cocos, GameMaker, Construct, and Defold. Be sure to consult the specific implementation guide for the engine you are using to integrate the correct function calls for each event. The core functions will remain the same across engines; it's the implementation syntax that may vary.