Kongregate Integration

Relevant source files

The following files were used as context for generating this wiki page:

• app/js/kongregate.js
• index.html
• app/js/core.js
• app/js/console.js
• src/renderer/save-manager.js
• src/main.js

The Kongregate integration module (skidinc.kongregate) provides functionality specific to the Kongregate gaming platform. Its primary purpose is to interact with the Kongregate API to handle user authentication, in-game purchases using Kreds, and incentivized video ads. These features are only active when the game is running on the Kongregate platform, identified by a URL parameter. When not on Kongregate, the features are gracefully disabled, and UI elements related to them are hidden or show an informational message.

The integration is initialized during the game's startup sequence and hooks into the game's UI and console systems to provide a seamless experience for Kongregate players.

Sources: app/js/kongregate.js, app/js/core.js:80, index.html:32

Architecture and Initialization

The integration is encapsulated within the skidinc.kongregate object. Initialization is triggered by skidinc.init() in the main game core.

Sources: app/js/core.js:80, app/js/kongregate.js:1

Initialization Flow

The skidinc.kongregate.init() function is the entry point. It checks if the game's URL contains the string kongregate. If it does, the Kongregate API is loaded and initialized. Otherwise, it configures the UI to show that platform-specific features are unavailable.

The following diagram illustrates the initialization process:

Key Functions

Function	Description
init()	Main entry point. Detects Kongregate environment and initializes the API and features.
userLogin()	Called for logged-in users. Fetches user details and owned items.
requestItemInventory()	Fetches the list of items the user owns from Kongregate.
buyTheme(i)	Initiates the purchase flow for a specific theme using Kongregate's MTX (microtransaction) service.
watchAd()	Shows an incentivized video ad to the player.
initAds()	Initializes the incentivized ad system and sets up event listeners for ad states.
domInit()	Binds Kongregate-related functions to DOM elements, like the 'Watch an ad' button.

Sources: app/js/kongregate.js

User and Session Management

The system distinguishes between guest and logged-in Kongregate users. This status determines whether a user can make purchases.

• Guest Users: If a user is a guest (kongregate.services.isGuest() is true), the theme shop shows a message prompting them to log in. A listener is attached to the login event to handle the transition from guest to a logged-in state.
• Logged-in Users: For logged-in users, the userLogin() function is triggered. It retrieves the user's Kongregate username and ID and then calls requestUserItemList() to check for already purchased themes.

Sources: app/js/kongregate.js:7-15, app/js/kongregate.js:68-84

User Login and Inventory Check Sequence

This diagram shows the sequence of events when a logged-in user starts the game on Kongregate.

In-Game Purchases (Theme Shop)

The integration supports in-game purchases of cosmetic themes using Kongregate's virtual currency, Kreds.

UI Management

The theme shop modal (#modal-themes) has different states depending on the platform and user status:

• Not on Kongregate: Shows #modal-themes4kong with the message "Theme shop is only available for Kongregate players."
• Kongregate Guest: Shows #modal-themes4guests with the message "You need to be logged into Kongregate to purchase themes."
• Kongregate Logged-in: Shows #modal-themes4logged with the list of purchasable themes.

Sources: app/js/kongregate.js:12-14, app/js/kongregate.js:27-29, app/js/kongregate.js:71-72, index.html:367-370

Purchase Flow

When a user clicks a "Buy" button, skidinc.kongregate.buyTheme(i) is called. This function uses kongregate.mtx.purchaseItems() to initiate the transaction. Upon successful purchase, the onPurchaseDone callback updates the game state to unlock the theme and notifies the user via the in-game console.

// app/js/kongregate.js:118-122
function onPurchaseDone(res) {
    if (!res.success)
        return skidinc.console.print('<x>ERR</x> there was an error during the payment process. Please report this as a Powerup Reward bug, thanks.');
    
    // ... logic to unlock theme and print message
}

Sources: app/js/kongregate.js:101-129

Purchasable Items

The code defines two purchasable themes. When a user buys a theme or logs in, their inventory is checked, and the skidinc.options.themesUnlocked array is updated.

Item Identifier	In-game Name	Unlocks
stardust_theme	Stardust	Sets skidinc.options.themesUnlocked[1] = true. Activated with option theme stardust.
matrix_theme	Matrix	Sets skidinc.options.themesUnlocked[2] = true. Activated with option theme matrix.

Sources: app/js/kongregate.js:92-98, app/js/kongregate.js:124-128, index.html:374-385

Incentivized Ads

Players on Kongregate can watch incentivized video ads for in-game benefits. This feature is managed through the kongregate.mtx service.

Ad Flow

1. The ad system is initialized by initAds() five seconds after the Kongregate API loads.
2. A user can trigger an ad by clicking the "Watch an ad" button, which calls skidinc.kongregate.watchAd().
3. This function checks if the game is on Kongregate and then calls kongregate.mtx.showIncentivizedAd().
4. A series of events are fired by the Kongregate API to which the game listens to provide feedback to the user.

Sources: app/js/kongregate.js:16-18, app/js/kongregate.js:31-35, app/js/kongregate.js:132-134

Ad Event Handling

The initAds function sets up listeners for various ad-related events.

Event	Description	Game Action
adsAvailable	Fired when ads are ready to be shown.	Logs a warning to the browser console.
adsUnavailable	Fired when no ads are available.	Prints an error to the in-game console, advising to disable adblockers.
adOpened	Fired when the ad display has opened.	Logs a warning to the browser console.
adCompleted	Fired when the user has successfully watched the ad.	Logs a warning to the browser console. The reward is handled by Kongregate's backend.
adAbandoned	Fired if the user closes the ad before completion.	Prints a warning to the in-game console that no reward will be given.

Sources: app/js/kongregate.js:37-57

Platform-Specific Context

The integration is designed to be conditional. Code outside the kongregate.js module also checks for the platform before attempting to use its features. For example, the watchAd function first verifies it's running on Kongregate before proceeding.

// app/js/kongregate.js:31-33
skidinc.kongregate.watchAd = function() {
    if (typeof skidinc.kongregate.isGuest == 'undefined' && window.location.search.indexOf('kongregate') == -1)
        return skidinc.console.print('<x>ERR</x> this feature is only available for Kongregate players.');

This pattern of checking the execution environment is common throughout the codebase, such as in the Electron-specific save-manager.js, which checks for window.electronAPI before enabling desktop-only features.

Sources: app/js/kongregate.js:31-35, app/js/console.js:103-105, src/renderer/save-manager.js:5-8

Summary

The Kongregate integration is a well-defined module that adds platform-specific monetization and user engagement features. It correctly isolates Kongregate-dependent logic and ensures the game remains fully functional when played on other platforms or as a standalone Electron application. The system leverages the Kongregate API for user identification, microtransactions, and incentivized ads, hooking into the main game's UI and state management to provide a cohesive experience.