Docs/SDKs/Godot

Godot

GDScript and C# integration guide for Ilara with Godot Engine.

12 min read

Requirements

Godot 4.0 or newer
GDScript or C# project

Installation

Method 1: Copy to Project

bash

# Clone to your addons folder
git clone https:class=class="code-string">"code-comment">//github.com/ilara/godot-sdk.git addons/ilara
 
# Or download and extract manually to addons/ilara/

Enable the plugin: Project → Project Settings → Plugins → Ilara → Enable

Method 2: Git Submodule

bash

git submodule add https:class=class="code-string">"code-comment">//github.com/ilara/godot-sdk.git addons/ilara

Quick Start

main.gd

gdscript

extends Node
 
func _ready() -> void:
    # Initialize the SDK
    Ilara.initialize(class="code-string">"pk_live_your_api_key")
 
    # Identify the player
    var player = await Ilara.identify_player(class="code-string">"player_123", {
        class="code-string">"level": 5,
        class="code-string">"country": class="code-string">"US"
    })
    print(class="code-string">"Player ID: ", player.id)
    print(class="code-string">"Lifecycle Stage: ", player.lifecycle_stage)
 
    # Track events
    await Ilara.track_event(class="code-string">"level_complete", {
        class="code-string">"level": 5,
        class="code-string">"score": 1500,
        class="code-string">"time_seconds": 120
    })
 
    # Check feature flags
    if await Ilara.is_flag_enabled(class="code-string">"double_xp_weekend"):
        apply_double_xp()
 
    # Get churn risk
    var risk = await Ilara.get_churn_risk()
    if risk.risk_level == class="code-string">"high":
        show_retention_offer()

Initialization

Initialize SDK

gdscript

# Initialize with API key
Ilara.initialize(class="code-string">"pk_live_xxx")
 
# Initialize with custom base URL(for development)
Ilara.initialize(class="code-string">"pk_test_xxx", class="code-string">"", class="code-string">"http:class="code-commentclass="code-string">">//localhost:18000/v1")
 
# Check if initialized
if Ilara.is_initialized():
    print(class="code-string">"Ready!")

Player Management

Identify Players

gdscript

# Identify player(creates or updates)
var player = await Ilara.identify_player(
    class="code-string">"your_player_id",           # External ID from your system
    {class="code-string">"level": 10, class="code-string">"vip": true}, # Custom attributes
    class="code-string">"device_abc",               # Optional device ID
    class="code-string">"[email protected]"        # Optional email
)
 
# Get current player UUID
var player_id = Ilara.get_current_player_id()
 
# Get player data
var player_data = await Ilara.get_player(player_id)
 
# Record a session
await Ilara.record_session(1800, class="code-string">"session_001")  # 30 minutes
 
# Get churn risk
var risk = await Ilara.get_churn_risk()
print(class="code-string">"Risk Level: ", risk.risk_level)  # low, medium, high
print(class="code-string">"Risk Score: ", risk.risk_score)  # 0.0 - 1.0
print(class="code-string">"Factors: ", risk.factors)

Event Tracking

Track Events

gdscript

# Track single event
await Ilara.track_event(class="code-string">"purchase", {
    class="code-string">"item_id": class="code-string">"sword_01",
    class="code-string">"price": 4.99,
    class="code-string">"currency": class="code-string">"USD"
})
 
# Track with session ID
await Ilara.track_event(class="code-string">"level_start", {class="code-string">"level": 6}, class="code-string">"session_001")
 
# Batch track events
await Ilara.track_events_batch([
    {
        class="code-string">"player_id": player_id,
        class="code-string">"event_name": class="code-string">"item_collect",
        class="code-string">"properties": {class="code-string">"item": class="code-string">"coin", class="code-string">"amount": 100}
    },
    {
        class="code-string">"player_id": player_id,
        class="code-string">"event_name": class="code-string">"enemy_defeat",
        class="code-string">"properties": {class="code-string">"enemy_type": class="code-string">"boss"}
    }
])

Feature Flags

Check Flags

gdscript

# Get all flags for current player
var flags = await Ilara.get_feature_flags()
for key in flags:
    print(class="code-string">"Flag %s = %s" % [key, flags[key]])
 
# Evaluate specific flag
var flag_result = await Ilara.evaluate_flag(class="code-string">"new_tutorial")
print(class="code-string">"Value: ", flag_result.value)
print(class="code-string">"Reason: ", flag_result.reason)
 
# Check boolean flag(with default)
if await Ilara.is_flag_enabled(class="code-string">"dark_mode", false):
    enable_dark_mode()
 
# Multivariate flags
var checkout_variant = await Ilara.evaluate_flag(class="code-string">"checkout_flow")
match checkout_variant.variant_key:
    class="code-string">"control":
        show_original_checkout()
    class="code-string">"variant_a":
        show_simplified_checkout()
    class="code-string">"variant_b":
        show_one_click_checkout()

Segments

Check Segments

gdscript

# Check segment membership
var membership = await Ilara.evaluate_segment(class="code-string">"segment_uuid_here")
if membership.is_member:
    print(class="code-string">"Player is in segment: ", membership.segment_name)

Signals

The SDK emits signals for key events:

Connect to Signals

gdscript

func _ready() -> void:
    Ilara.initialized.connect(_on_ilara_initialized)
    Ilara.player_identified.connect(_on_player_identified)
    Ilara.event_tracked.connect(_on_event_tracked)
    Ilara.error.connect(_on_ilara_error)
 
func _on_ilara_initialized() -> void:
    print(class="code-string">"Ilara is ready!")
 
func _on_player_identified(player_data: Dictionary) -> void:
    print(class="code-string">"Player identified: ", player_data.id)
 
func _on_event_tracked(event_name: String) -> void:
    print(class="code-string">"Event tracked: ", event_name)
 
func _on_ilara_error(message: String) -> void:
    push_error(class="code-string">"Ilara Error: " + message)

Data Models

IlaraPlayerData

gdscript

var player = IlaraPlayerData.from_dict(response)
print(player.id)              # UUID
print(player.external_id)     # Your player ID
print(player.lifecycle_stage) # new, active, engaged, at_risk, churned, returned
print(player.session_count)
print(player.total_revenue)
print(player.is_payer)
print(player.attributes)

IlaraChurnRisk

gdscript

var risk = IlaraChurnRisk.from_dict(response)
print(risk.risk_score)   # 0.0 - 1.0
print(risk.risk_level)   # low, medium, high
print(risk.factors)      # [class="code-string">"no_sessions_7_days", class="code-string">"declining_playtime"]
 
if risk.is_at_risk():
    show_special_offer()

Error Handling

Handle Errors

gdscript

# Connect to error signal
Ilara.error.connect(func(msg): push_error(class="code-string">"Ilara: " + msg))
 
# Or check responses manually
var result = await Ilara.track_event(class="code-string">"test", {})
if result.has(class="code-string">"error"):
    push_error(class="code-string">"Failed: " + result.error)

Best Practices

Initialize Early: Call Ilara.initialize() in your game's main scene _ready()
Identify Before Tracking: Always call identify_player() before tracking events
Use Meaningful Event Names: Use snake_case and be descriptive (level_complete, purchase_completed)
Track Key Moments: Session start/end, level completion, purchases, tutorial progress

Development Mode

Local Development

gdscript

# Point to local API server
Ilara.initialize(
    class="code-string">"pk_test_xxx",
    class="code-string">"",
    class="code-string">"http:class="code-commentclass="code-string">">//localhost:18000/v1"
)

Support

Unreal Engine

REST API