Godot Integration

This guide will walk you through integrating the GameLoop Funtico SDK into your Godot project. The SDK enables your game to interact with the Funtico platform for features like user authentication, leaderboards, and score saving.

Since Godot games exported for the web run in a browser environment, we’ll use JavaScript as a bridge between your GDScript code and the SDK. Don’t worry if you’re not familiar with JavaScript – we’ll provide all the code snippets you need.

Prerequisites

Tip

This integration guide assumes you’re exporting your Godot game as an HTML5/Web build. The SDK is designed specifically for web-based games.

Step 1: Include the SDK Library

Before your game can use the Funtico SDK, you need to include the SDK library in your HTML export. This is done by adding a script tag that loads the SDK from our Content Delivery Network (CDN).

You have two options for adding this script:

Option A: Through Export Settings (Recommended)

1. Open your project in Godot
2. Go to Project → Export
3. Select your HTML5 export preset
4. Find the HTML → Head Include field
5. Add the following script tag:

<script src="https://funtico-frontend-js-sdk.pages.dev/funtico-sdk.min.js"></script>

Option B: Manual Addition

Alternatively, you can add the script tag directly to your export_presets.cfg file in the project root.

Caution

The SDK must be loaded before your game attempts to use it. Adding it to the HTML head ensures it loads before your game code runs.

Step 2: Initialize the SDK

Now we need to initialize the SDK when your game starts. This creates a connection between your game and the Funtico platform.

What's happening here?

We’re using Godot’s JavaScript bridge to execute JavaScript code from GDScript. This creates a global SDK object that your game can interact with.

Godot 4.x

# Add this to your main game scene or a dedicated SDK manager script
func _ready():
  # Initialize the Funtico SDK
  var js_code = """
    window.sdk = new FunticoSDK({
      authClientId: 'your-client-id',  // Replace with your actual client ID
      env: 'sandbox'  // Use 'production' for live games
    });
  """
  JavaScriptBridge.eval(js_code)

Godot 3.x

# Add this to your main game scene or a dedicated SDK manager script
func _ready():
  # Initialize the Funtico SDK
  var js_code = """
    window.sdk = new FunticoSDK({
      authClientId: 'your-client-id',  // Replace with your actual client ID
      env: 'sandbox'  // Use 'production' for live games
    });
  """
  JavaScript.eval(js_code)

Important

Always initialize the SDK in your main scene’s _ready() function or at game startup. Attempting to use SDK functions before initialization will result in errors.

Development vs Production

• Use env: 'sandbox' during development and testing
• Switch to env: 'production' when publishing your game
• Your client ID will be provided when you register your game on the Funtico platform

Step 3: Authenticate the User

Before you can use SDK functions like getting user info or saving scores, you need to authenticate the user. This redirects the user to Funtico’s login page, and after successful authentication, they are redirected back to your game.

Important

Authentication must be completed before calling other SDK functions like getUserInfo() or saveScore(). Without authentication, these calls will fail.

Godot 4.x

# Call this when user clicks a "Login" or "Play" button
func start_authentication():
  var js_code = """
    // Get the current page URL to redirect back to after login
    var callbackUrl = window.location.origin + window.location.pathname;

    // Start the authentication flow
    window.sdk.signInWithFuntico(callbackUrl)
      .catch(function(error) {
        console.error('Authentication failed:', error);
      });
  """
  JavaScriptBridge.eval(js_code)
  # User will be redirected to Funtico login page
  # After successful login, they'll return to your game

Godot 3.x

# Call this when user clicks a "Login" or "Play" button
func start_authentication():
  var js_code = """
    // Get the current page URL to redirect back to after login
    var callbackUrl = window.location.origin + window.location.pathname;

    // Start the authentication flow
    window.sdk.signInWithFuntico(callbackUrl)
      .catch(function(error) {
        console.error('Authentication failed:', error);
      });
  """
  JavaScript.eval(js_code)
  # User will be redirected to Funtico login page
  # After successful login, they'll return to your game

What happens during authentication?

1. User clicks login/play button in your game
2. User is redirected to Funtico’s authentication page
3. User logs in with their Funtico credentials (or is automatically authenticated if already logged in to another Funtico game)
4. User is redirected back to your game
5. SDK automatically handles the authentication tokens
6. Your game can now call other SDK functions

Seamless Experience: If the user has an active Funtico session from playing another game, they won’t need to enter their credentials again. They’ll be automatically authenticated and redirected back to your game.

Testing Authentication

When using the sandbox environment, you can use these test accounts:

• Email: [email protected] through [email protected]
• Password: GameLoop123!

Step 4: Calling SDK Functions

The Funtico SDK uses asynchronous functions (also called Promises in JavaScript). This means when you call an SDK function, it doesn’t return a result immediately. Instead, it returns a Promise that will either:

• Resolve with the requested data (success)
• Reject with an error message (failure)

Understanding Callbacks

Since JavaScript operations are asynchronous, we use callback functions to handle the results. Think of it like placing an order at a restaurant – you give your order (call the function) and provide your table number (callback), then the waiter brings your food when it’s ready (callback executes).

Implementation Differences Between Godot Versions

Godot 3.x and 4.x handle JavaScript differently:

• Godot 4.x uses JavaScriptBridge with create_callback() and get_interface()
• Godot 3.x uses JavaScript class and requires a different approach for callbacks

Example: Getting User Information

Godot 4.x

# Store callbacks as member variables to prevent garbage collection
var _onsuccess_callback
var _onerror_callback

func _ready():
  # Initialize SDK first (see Step 2)
  # ...

  # Create callbacks that JavaScript can call
  _onsuccess_callback = JavaScriptBridge.create_callback(_on_user_info_success)
  _onerror_callback = JavaScriptBridge.create_callback(_on_user_info_error)

  # Get the SDK interface and call getUserInfo
  var sdk = JavaScriptBridge.get_interface("sdk")
  sdk.getUserInfo().then(_onsuccess_callback).catch(_onerror_callback)

func _on_user_info_success(data):
  # The SDK returns an array with user data as the first element
  var user_info = data[0]
  var username = user_info.username
  var user_id = str(user_info.user_id)

  print("User logged in: ", username)
  print("User ID: ", user_id)

  # Continue with your game logic
  # For example: show main menu, load user progress, etc.

func _on_user_info_error(error):
  print("Failed to get user info: ", error[0])
  # Handle error - maybe show login screen or retry

Godot 3.x

# Godot 3.x requires a different approach since it doesn't have create_callback

func _ready():
  # Initialize SDK first (see Step 2)
  # ...

  # In Godot 3.x, we need to use a different pattern
  # We'll store the result in a JavaScript variable and poll it
  var js_code = """
    window.userInfoResult = null;
    window.userInfoError = null;

    window.sdk.getUserInfo()
      .then(function(data) {
        window.userInfoResult = data;
      })
      .catch(function(error) {
        window.userInfoError = error;
      });
  """
  JavaScript.eval(js_code)

  # Start checking for the result
  _check_user_info_result()

func _check_user_info_result():
  # Check if we have a result
  var result = JavaScript.eval("window.userInfoResult")
  var error = JavaScript.eval("window.userInfoError")

  if result != null:
    # Success! Process the user data
    var username = result.username
    var user_id = str(result.user_id)

    print("User logged in: ", username)
    print("User ID: ", user_id)

    # Clean up
    JavaScript.eval("window.userInfoResult = null;")

    # Continue with your game logic
  elif error != null:
    # Error occurred
    print("Failed to get user info: ", str(error))

    # Clean up
    JavaScript.eval("window.userInfoError = null;")

    # Handle error
  else:
    # Still waiting for response, check again in a moment
    yield(get_tree().create_timer(0.1), "timeout")
    _check_user_info_result()

Caution for Godot 4.x

Always store callbacks as member variables (not local variables) to prevent them from being garbage collected while waiting for the JavaScript response.

Godot 3.x Limitation

Since Godot 3.x doesn’t support create_callback(), we use a polling approach. This checks periodically if the JavaScript operation has completed. While less elegant, it’s reliable and works well for most use cases.

Reducing Boilerplate in Godot 3.x

You’ll notice that the polling pattern requires a separate _check_..._result() function for each SDK call, which can lead to repetitive code. While you could create a generic polling manager to handle all SDK responses and reduce this boilerplate, we’ve kept each example explicit and self-contained for clarity in this tutorial. Once you’re comfortable with the pattern, consider refactoring to a more DRY (Don’t Repeat Yourself) approach if your game makes many SDK calls.

Step 5: Common SDK Functions

Here are examples of commonly used SDK functions:

Save Score

Godot 4.x

var _onsuccess_callback
var _onerror_callback

func submit_score(score: int):
  _onsuccess_callback = JavaScriptBridge.create_callback(_on_score_submitted)
  _onerror_callback = JavaScriptBridge.create_callback(_on_submit_error)

  var sdk = JavaScriptBridge.get_interface("sdk")
  var promise = sdk.saveScore(score)
  promise.then(_onsuccess_callback).catch(_onerror_callback)

func _on_score_submitted(result):
  print("Score submitted successfully!")

func _on_submit_error(error):
  print("Failed to submit score: ", error[0])

Godot 3.x

func submit_score(score: int):
  var js_code = """
    window.submitResult = null;
    window.submitError = null;

    window.sdk.saveScore(%d)
      .then(function(data) {
        window.submitResult = true;
      })
      .catch(function(error) {
        window.submitError = error;
      });
  """ % [score]
  JavaScript.eval(js_code)

  _check_submit_result()

func _check_submit_result():
  var result = JavaScript.eval("window.submitResult")
  var error = JavaScript.eval("window.submitError")

  if result != null:
    print("Score submitted successfully!")
    JavaScript.eval("window.submitResult = null;")
  elif error != null:
    print("Failed to submit score: ", str(error))
    JavaScript.eval("window.submitError = null;")
  else:
    yield(get_tree().create_timer(0.1), "timeout")
    _check_submit_result()

Best Practices

Tips for Success

1. Always initialize the SDK first - Call the initialization code in your main scene before any SDK functions
2. Handle errors gracefully - Always provide error callbacks to handle network issues or other problems
3. Test in a web browser - The SDK only works in HTML5 exports, not in the Godot editor
4. Use member variables for callbacks (Godot 4.x) - Prevents garbage collection issues
5. Keep polling intervals reasonable (Godot 3.x) - 0.1 seconds is usually sufficient

Troubleshooting

Common Issues and Solutions

Issue	Solution
”sdk is not defined”	Ensure the SDK script is included in your HTML export and initialization code runs first
Callbacks never fire	In Godot 4.x, make sure callbacks are stored as member variables, not local variables
”Cannot read property of null”	The SDK hasn’t been initialized yet. Check your initialization code
Functions work in one browser but not another	Clear browser cache and ensure you’re using the latest SDK version

Testing Note

The SDK requires a web environment to function. It will not work when testing in the Godot editor. Always export your game as HTML5 and test in a web browser.