--- name: "taptap-godot-integration" description: "Integrate TapSDK v4 into Godot 4 Android games: login, anti-addiction, cloud save, leaderboard, friends. Invoke when adding TapTap features to a Godot Android project." --- # TapTap SDK v4 Godot 4 Android Integration Skill Complete integration guide for TapTap SDK v4 into Godot 4 Android games, covering login, anti-addiction, cloud save, leaderboard, and friends modules. ## Architecture Overview ``` ┌─────────────────────────────────────────────────┐ │ Godot 4 (GDScript) │ │ ┌──────────────────────────────────────────┐ │ │ │ TapTapManager (Autoload) │ │ │ │ - SDK lifecycle management │ │ │ │ - Signal bridging (plugin → game) │ │ │ │ - Cross-platform abstraction │ │ │ │ (Android / PC / Mock modes) │ │ │ └──────────────┬───────────────────────────┘ │ │ │ Godot Plugin API │ │ ┌──────────────▼───────────────────────────┐ │ │ │ TapTapPlugin.kt (GodotPlugin) │ │ │ │ - @UsedByGodot methods │ │ │ │ - Signal emission to GDScript │ │ │ │ - TapSDK v4 API calls │ │ │ └──────────────┬───────────────────────────┘ │ │ │ TapSDK v4 │ │ ┌──────────────▼───────────────────────────┐ │ │ │ TapTap SDK v4 │ │ │ │ Login | Compliance | CloudSave | │ │ │ │ Leaderboard | RelationLite │ │ │ └──────────────────────────────────────────┘ │ └─────────────────────────────────────────────────┘ ``` ## Prerequisites - Godot 4.x with Android export template - TapTap Developer account (https://developer.taptap.cn/) - TapSDK v4 credentials: Client ID, Client Token - Android Studio for building the Godot Android plugin ## Step 1: Project Configuration ### 1.1 Android Plugin build.gradle Add TapSDK v4 dependencies to your Godot Android plugin's `app/build.gradle`: ```gradle dependencies { implementation 'com.taptap.sdk:tap-core:4.10.2' implementation 'com.taptap.sdk:tap-login:4.10.2' implementation 'com.taptap.sdk:tap-compliance:4.10.2' implementation 'com.taptap.sdk:tap-cloudsave:4.10.2' implementation 'com.taptap.sdk:tap-leaderboard-androidx:4.10.2' // Note: -androidx suffix! implementation 'com.taptap.sdk:tap-relation-lite:4.10.2' compileOnly 'org.godotengine:godot:4.3.0.stable' } ``` **Important**: The leaderboard module uses `-androidx` suffix (`tap-leaderboard-androidx`), not `tap-leaderboard`. ### 1.2 Godot Android Plugin descriptor (.gdap) Create or update `android/plugins/TapTapPlugin.gdap`: ```ini [config] name="TapTapPlugin" binary_type="local" binary="res://android/plugins/TapTapPlugin.aar" [dependencies] local=["com.taptap.sdk:tap-core:4.10.2", "com.taptap.sdk:tap-login:4.10.2", "com.taptap.sdk:tap-compliance:4.10.2", "com.taptap.sdk:tap-cloudsave:4.10.2", "com.taptap.sdk:tap-leaderboard-androidx:4.10.2", "com.taptap.sdk:tap-relation-lite:4.10.2"] remote=["com.google.code.gson:gson:2.10.1"] ``` ### 1.3 AndroidManifest.xml Add required activities and permissions: ```xml ``` ## Step 2: Kotlin Plugin Implementation ### 2.1 TapTapPlugin.kt - Full Implementation ```kotlin package com.yourpackage.taptap import android.app.Activity import android.content.Intent import android.net.Uri import android.util.Log import android.os.Handler import android.os.Looper import org.godotengine.godot.Godot import org.godotengine.godot.plugin.GodotPlugin import org.godotengine.godot.plugin.SignalInfo import org.godotengine.godot.plugin.UsedByGodot import org.json.JSONObject // TapSDK v4 imports import com.taptap.sdk.core.TapTapSdk import com.taptap.sdk.core.TapTapSdkOptions import com.taptap.sdk.core.TapTapRegion import com.taptap.sdk.login.TapTapLogin import com.taptap.sdk.login.TapTapAccount import com.taptap.sdk.login.Scopes import com.taptap.sdk.kit.internal.callback.TapTapCallback import com.taptap.sdk.kit.internal.exception.TapTapException import com.taptap.sdk.compliance.TapTapCompliance import com.taptap.sdk.compliance.TapTapComplianceCallback import com.taptap.sdk.compliance.constants.ComplianceMessage import com.taptap.sdk.compliance.option.TapTapComplianceOptions import com.taptap.sdk.cloudsave.TapTapCloudSave import com.taptap.sdk.cloudsave.internal.TapCloudSaveRequestCallback import com.taptap.sdk.cloudsave.internal.TapCloudSaveCallback import com.taptap.sdk.cloudsave.ArchiveMetadata import com.taptap.sdk.cloudsave.ArchiveData import com.taptap.sdk.leaderboard.androidx.TapTapLeaderboard import com.taptap.sdk.leaderboard.callback.TapTapLeaderboardCallback import com.taptap.sdk.leaderboard.callback.ITapTapLeaderboardResponseCallback import com.taptap.sdk.leaderboard.data.request.LeaderboardCollection import com.taptap.sdk.leaderboard.data.request.SubmitScoresRequest import com.taptap.sdk.leaderboard.data.response.LeaderboardScoresResponse import com.taptap.sdk.leaderboard.data.response.UserScoreResponse import com.taptap.sdk.leaderboard.data.response.SubmitScoresResponse import com.taptap.sdk.leaderboard.data.response.common.Score import com.taptap.sdk.relation.lite.TapTapRelationLite import com.taptap.sdk.relation.lite.internal.TapTapRelationLiteCallback import com.taptap.sdk.relation.lite.internal.TapTapRelationRequestCallback import com.taptap.sdk.relation.lite.internal.model.RelationLiteUserItem class TapTapPlugin(godot: Godot) : GodotPlugin(godot) { companion object { private const val TAG = "TapTapPlugin" } private var isInitialized = false private var complianceInitialized = false private val mainHandler = Handler(Looper.getMainLooper()) private var currentArchiveId: String? = null override fun getPluginName(): String = "TapTapPlugin" override fun getPluginSignals(): MutableSet { return mutableSetOf( SignalInfo("on_login_success", String::class.java), SignalInfo("on_login_failed", String::class.java), SignalInfo("on_login_canceled"), SignalInfo("on_logout_finished"), SignalInfo("on_anti_addiction_callback", String::class.java, String::class.java), SignalInfo("on_cloud_save_result", String::class.java, String::class.java), SignalInfo("on_cloud_save_list", String::class.java), SignalInfo("on_cloud_save_data", String::class.java), SignalInfo("on_leaderboard_result", String::class.java, String::class.java), SignalInfo("on_leaderboard_scores", String::class.java), SignalInfo("on_leaderboard_user_score", String::class.java), SignalInfo("on_friends_list", String::class.java), ) } // Thread-safe signal emission private fun safeEmit(signalName: String, vararg args: Any) { try { if (Looper.myLooper() == Looper.getMainLooper()) { emitSignal(signalName, *args) } else { mainHandler.post { emitSignal(signalName, *args) } } } catch (e: Exception) { Log.e(TAG, "safeEmit failed: $signalName", e) } } // ==================== SDK Initialization ==================== @UsedByGodot fun initSDK(clientId: String, clientToken: String, serverUrl: String) { val activity = activity ?: return try { val sdkOptions = TapTapSdkOptions( clientId, clientToken, TapTapRegion.CN, // Use TapTapRegion.IO for international "", true, ) val complianceOptions = TapTapComplianceOptions(true, false) TapTapSdk.init(activity, sdkOptions, complianceOptions) isInitialized = true } catch (e: Exception) { Log.e(TAG, "Failed to initialize TapSDK v4", e) } } // ==================== Anti-Addiction ==================== @UsedByGodot fun initAntiAddiction(clientId: String) { try { TapTapCompliance.registerComplianceCallback( object : TapTapComplianceCallback { override fun onComplianceResult(code: Int, extra: Map?) { val msg = extra?.entries?.joinToString("; ") { "${it.key}=${it.value}" } ?: "" safeEmit("on_anti_addiction_callback", code.toString(), msg) } } ) complianceInitialized = true } catch (e: Exception) { Log.e(TAG, "Failed to register compliance callback", e) safeEmit("on_anti_addiction_callback", "500", "compliance_init_failed") } } @UsedByGodot fun checkAntiAddiction() { if (!isInitialized || !complianceInitialized) { safeEmit("on_anti_addiction_callback", "500", "not_initialized") return } val userId = TapTapLogin.getCurrentTapAccount()?.openId ?: "" if (userId.isEmpty()) { safeEmit("on_anti_addiction_callback", "500", "no_userid") return } TapTapCompliance.startup(activity!!, userId) } @UsedByGodot fun exitAntiAddiction() { if (complianceInitialized) TapTapCompliance.exit() } // ==================== Login ==================== @UsedByGodot fun login() { if (!isInitialized) return val activity = activity ?: return val scopes = arrayOf(Scopes.SCOPE_PUBLIC_PROFILE, Scopes.SCOPE_USER_FRIENDS) TapTapLogin.loginWithScopes(activity, scopes, object : TapTapCallback { override fun onSuccess(account: TapTapAccount) { val json = JSONObject().apply { put("name", account.name ?: "") put("avatar", account.avatar ?: "") put("user_id", account.openId ?: "") put("openid", account.openId ?: "") put("unionid", account.unionId ?: "") } safeEmit("on_login_success", json.toString()) } override fun onCancel() { safeEmit("on_login_canceled") } override fun onFail(exception: TapTapException) { safeEmit("on_login_failed", exception.message ?: "Unknown error") } }) } @UsedByGodot fun logout() { TapTapLogin.logout() currentArchiveId = null safeEmit("on_logout_finished") } @UsedByGodot fun isUserLoggedIn(): Boolean { return try { TapTapLogin.getCurrentTapAccount() != null } catch (_: Exception) { false } } @UsedByGodot fun getCurrentUserInfo(): String { val account = TapTapLogin.getCurrentTapAccount() ?: return "" return JSONObject().apply { put("name", account.name ?: "") put("avatar", account.avatar ?: "") put("user_id", account.openId ?: "") put("openid", account.openId ?: "") put("unionid", account.unionId ?: "") }.toString() } @UsedByGodot fun getDisplayUserId(): String { // Generate 8-digit display ID from openId hash val openId = TapTapLogin.getCurrentTapAccount()?.openId ?: return "" val hash = openId.hashCode().toLong() and 0xFFFFFFFFL return String.format("%08d", hash % 100000000L) } // ==================== Cloud Save ==================== @UsedByGodot fun initCloudSave() { TapTapCloudSave.registerCloudSaveCallback(object : TapCloudSaveCallback { override fun onResult(resultCode: Int) { when (resultCode) { 300001 -> safeEmit("on_cloud_save_result", "error", "need_login") 300002 -> safeEmit("on_cloud_save_result", "error", "init_failed") } } }) } @UsedByGodot fun setCurrentArchiveId(archiveId: String) { currentArchiveId = if (archiveId.isEmpty()) null else archiveId } @UsedByGodot fun saveToCloud(saveData: String, summary: String) { val activity = this.activity ?: return try { val saveFile = File(activity.cacheDir, "cloud_save.json") saveFile.writeText(saveData) val metadata = ArchiveMetadata.Builder() .setName("game_save") .setSummary(summary) .setExtra("") .setPlaytime(0) .build() val callback = object : TapCloudSaveRequestCallback { override fun onRequestError(errorCode: Int, errorMessage: String) { safeEmit("on_cloud_save_result", "error", "code=$errorCode msg=$errorMessage") } override fun onArchiveCreated(archive: ArchiveData) { currentArchiveId = archive.uuid safeEmit("on_cloud_save_result", "created", archive.uuid) } override fun onArchiveUpdated(archive: ArchiveData) { currentArchiveId = archive.uuid safeEmit("on_cloud_save_result", "updated", archive.uuid) } override fun onArchiveDeleted(archive: ArchiveData) { if (currentArchiveId == archive.uuid) currentArchiveId = null safeEmit("on_cloud_save_result", "deleted", archive.uuid) } override fun onArchiveListResult(archiveList: List) {} override fun onArchiveDataResult(archiveData: ByteArray) {} override fun onArchiveCoverResult(coverData: ByteArray) {} } if (currentArchiveId != null) { TapTapCloudSave.updateArchive(currentArchiveId!!, metadata, saveFile.absolutePath, null, callback) } else { // Query first to avoid duplicates TapTapCloudSave.getArchiveList(object : TapCloudSaveRequestCallback { override fun onRequestError(errorCode: Int, errorMessage: String) { TapTapCloudSave.createArchive(metadata, saveFile.absolutePath, null, callback) } override fun onArchiveCreated(archive: ArchiveData) {} override fun onArchiveUpdated(archive: ArchiveData) {} override fun onArchiveDeleted(archive: ArchiveData) {} override fun onArchiveDataResult(archiveData: ByteArray) {} override fun onArchiveCoverResult(coverData: ByteArray) {} override fun onArchiveListResult(archiveList: List) { if (archiveList.isNotEmpty()) { currentArchiveId = archiveList[0].uuid TapTapCloudSave.updateArchive(currentArchiveId!!, metadata, saveFile.absolutePath, null, callback) } else { TapTapCloudSave.createArchive(metadata, saveFile.absolutePath, null, callback) } } }) } } catch (e: Exception) { safeEmit("on_cloud_save_result", "error", e.message ?: "unknown") } } @UsedByGodot fun loadCloudSaveList() { TapTapCloudSave.getArchiveList(object : TapCloudSaveRequestCallback { override fun onRequestError(errorCode: Int, errorMessage: String) { safeEmit("on_cloud_save_list", "") } override fun onArchiveCreated(archive: ArchiveData) {} override fun onArchiveUpdated(archive: ArchiveData) {} override fun onArchiveDeleted(archive: ArchiveData) {} override fun onArchiveDataResult(archiveData: ByteArray) {} override fun onArchiveCoverResult(coverData: ByteArray) {} override fun onArchiveListResult(archiveList: List) { if (archiveList.isNotEmpty()) currentArchiveId = archiveList[0].uuid val json = JSONObject() val arr = org.json.JSONArray() for (archive in archiveList) { arr.put(JSONObject().apply { put("archiveId", archive.uuid) put("name", archive.name ?: "") put("summary", archive.summary ?: "") put("fileId", archive.fileId ?: "") put("modifiedTime", archive.modifiedTime) }) } json.put("archives", arr) safeEmit("on_cloud_save_list", json.toString()) } }) } @UsedByGodot fun loadCloudSaveData(archiveId: String, fileId: String) { TapTapCloudSave.getArchiveData(archiveId, fileId, object : TapCloudSaveRequestCallback { override fun onRequestError(errorCode: Int, errorMessage: String) { safeEmit("on_cloud_save_data", "") } override fun onArchiveCreated(archive: ArchiveData) {} override fun onArchiveUpdated(archive: ArchiveData) {} override fun onArchiveDeleted(archive: ArchiveData) {} override fun onArchiveListResult(archiveList: List) {} override fun onArchiveCoverResult(coverData: ByteArray) {} override fun onArchiveDataResult(archiveData: ByteArray) { safeEmit("on_cloud_save_data", String(archiveData, Charsets.UTF_8)) } }) } // ==================== Leaderboard ==================== @UsedByGodot fun initLeaderboard() { TapTapLeaderboard.registerLeaderboardCallback(object : TapTapLeaderboardCallback { override fun onLeaderboardResult(code: Int, message: String) { safeEmit("on_leaderboard_result", code.toString(), message) } }) } @UsedByGodot fun submitLeaderboardScore(leaderboardId: String, score: Long) { val scoreItem = SubmitScoresRequest.ScoreItem(leaderboardId, score) val request = SubmitScoresRequest(listOf(scoreItem)) TapTapLeaderboard.submitScores(request.scores, object : ITapTapLeaderboardResponseCallback { override fun onSuccess(result: SubmitScoresResponse) { safeEmit("on_leaderboard_result", "0", "submit_success") } override fun onFailure(code: Int, message: String) { safeEmit("on_leaderboard_result", code.toString(), message) } }) } @UsedByGodot fun loadLeaderboardScores(leaderboardId: String, collection: String, page: String) { val col = if (collection == "FRIENDS") LeaderboardCollection.FRIENDS else LeaderboardCollection.PUBLIC TapTapLeaderboard.loadLeaderboardScores(leaderboardId, col, page, null, object : ITapTapLeaderboardResponseCallback { override fun onSuccess(result: LeaderboardScoresResponse) { try { val json = JSONObject() json.put("leaderboard", JSONObject().apply { put("id", result.leaderboard?.id ?: "") put("name", result.leaderboard?.name ?: "") }) val arr = org.json.JSONArray() for (score in result.scores) arr.put(scoreToJson(score)) json.put("scores", arr) json.put("nextPage", result.nextPage ?: "") safeEmit("on_leaderboard_scores", json.toString()) } catch (e: Exception) { safeEmit("on_leaderboard_scores", "") } } override fun onFailure(code: Int, message: String) { safeEmit("on_leaderboard_scores", "") } }) } @UsedByGodot fun loadCurrentUserScore(leaderboardId: String, collection: String) { val col = if (collection == "FRIENDS") LeaderboardCollection.FRIENDS else LeaderboardCollection.PUBLIC TapTapLeaderboard.loadCurrentPlayerLeaderboardScore(leaderboardId, col, null, object : ITapTapLeaderboardResponseCallback { override fun onSuccess(result: UserScoreResponse) { val json = scoreToJson(result.currentUserScore ?: return) safeEmit("on_leaderboard_user_score", json.toString()) } override fun onFailure(code: Int, message: String) { safeEmit("on_leaderboard_user_score", "") } }) } private fun scoreToJson(score: Score): JSONObject { val userObj = JSONObject().apply { put("name", score.user?.name ?: "") put("openid", score.user?.openid ?: "") put("avatar", score.user?.avatar?.url ?: "") } return JSONObject().apply { put("rank", score.rank?.toString() ?: "0") put("rankDisplay", score.rankDisplay ?: "") put("score", score.score?.toString() ?: "0") put("scoreDisplay", score.scoreDisplay ?: "") put("user", userObj) } } // ==================== Friends ==================== @UsedByGodot fun initFriends() { TapTapRelationLite.registerRelationLiteCallback(object : TapTapRelationLiteCallback { override fun onRelationLiteResult(code: Int) { Log.i(TAG, "RelationLite callback: code=$code") } }) } @UsedByGodot fun getFriendsList(nextPageToken: String) { TapTapRelationLite.getFriendsList(nextPageToken = nextPageToken, callback = object : TapTapRelationRequestCallback() { override fun onFriendsListResult(friendsList: List, nextPageToken: String) { val json = JSONObject() val arr = org.json.JSONArray() for (friend in friendsList) { arr.put(JSONObject().apply { put("openid", friend.user?.openId ?: "") put("name", friend.user?.name ?: "") put("avatar", friend.user?.avatar ?: "") }) } json.put("friends", arr) json.put("nextPageToken", nextPageToken) safeEmit("on_friends_list", json.toString()) } }) } // ==================== Update Check ==================== @UsedByGodot fun initUpdate(clientId: String, clientToken: String) { // Intent-based update check } @UsedByGodot fun checkUpdate() { val activity = this.activity ?: return try { val intent = Intent(Intent.ACTION_VIEW, Uri.parse("taptap://taptap.cn/app?source=outer|update")) intent.flags = Intent.FLAG_ACTIVITY_NEW_TASK activity.startActivity(intent) } catch (e: Exception) { val webIntent = Intent(Intent.ACTION_VIEW, Uri.parse("https://www.taptap.cn/")) webIntent.flags = Intent.FLAG_ACTIVITY_NEW_TASK activity.startActivity(webIntent) } } } ``` ## Step 3: GDScript Autoload Manager Create `scripts/autoload/tap_tap_manager.gd` and register it as an Autoload: ```gdscript extends Node # ==================== Signals ==================== signal login_success(user_info: Dictionary) signal login_failed(error: String) signal login_canceled signal logout_finished signal sdk_initialized signal anti_addiction_callback(code: String, message: String) signal cloud_save_result(action: String, data: String) signal cloud_save_list(archives_json: String) signal cloud_save_data(save_json: String) signal leaderboard_result(code: String, message: String) signal leaderboard_scores(scores_json: String) signal leaderboard_user_score(score_json: String) signal friends_list(friends_json: String) signal sdk_api_ready # ==================== Variables ==================== var _plugin: Object = null var _is_logged_in: bool = false var _is_sdk_initialized: bool = false var _user_info: Dictionary = {} var _current_archive_id: String = "" var _login_time: float = 0.0 var _sdk_api_ready: bool = true var _api_ready_timer: Timer = null var _mock_mode: bool = false const PLUGIN_NAME: String = "TapTapPlugin" func _ready() -> void: if OS.get_name() == "Android" and Engine.has_singleton(PLUGIN_NAME): _plugin = Engine.get_singleton(PLUGIN_NAME) _connect_plugin_signals() else: _mock_mode = true print("TapTapManager: Running in mock mode") func _connect_plugin_signals() -> void: if not _plugin: return _plugin.on_login_success.connect(_on_login_success) _plugin.on_login_failed.connect(_on_login_failed) _plugin.on_login_canceled.connect(_on_login_canceled) _plugin.on_logout_finished.connect(_on_logout_finished) _plugin.on_anti_addiction_callback.connect(_on_anti_addiction_callback) _plugin.on_cloud_save_result.connect(_on_cloud_save_result) _plugin.on_cloud_save_list.connect(_on_cloud_save_list) _plugin.on_cloud_save_data.connect(_on_cloud_save_data) _plugin.on_leaderboard_result.connect(_on_leaderboard_result) _plugin.on_leaderboard_scores.connect(_on_leaderboard_scores) _plugin.on_leaderboard_user_score.connect(_on_leaderboard_user_score) _plugin.on_friends_list.connect(_on_friends_list) # ==================== Public API ==================== func is_available() -> bool: return _plugin != null or _mock_mode func is_mock_mode() -> bool: return _mock_mode func is_logged_in() -> bool: return _is_logged_in func is_sdk_logged_in() -> bool: if _mock_mode: return _is_logged_in if not _plugin: return false return _plugin.isUserLoggedIn() func init_sdk(client_id: String, client_token: String, server_url: String) -> void: if _mock_mode: _is_sdk_initialized = true sdk_initialized.emit() return if not _plugin: return _plugin.initSDK(client_id, client_token, server_url) _is_sdk_initialized = true sdk_initialized.emit() func init_anti_addiction(client_id: String) -> void: if _mock_mode: return if not _plugin: return _plugin.initAntiAddiction(client_id) func init_cloud_save() -> void: if _mock_mode: return if not _plugin: return _plugin.initCloudSave() if not _current_archive_id.is_empty() and _plugin.has_method("setCurrentArchiveId"): _plugin.setCurrentArchiveId(_current_archive_id) func init_leaderboard() -> void: if _mock_mode: return if not _plugin: return _plugin.initLeaderboard() func init_friends() -> void: if _mock_mode: return if not _plugin: return _plugin.initFriends() func init_update(client_id: String, client_token: String) -> void: if _mock_mode: return if not _plugin: return _plugin.initUpdate(client_id, client_token) func login() -> void: if _mock_mode: get_tree().create_timer(1.0).timeout.connect(_mock_login_success) return if not _plugin or not _is_sdk_initialized: return _plugin.login() func logout() -> void: if _mock_mode: _is_logged_in = false _user_info = {} logout_finished.emit() return if not _plugin: return _plugin.logout() func check_anti_addiction() -> void: if _mock_mode: get_tree().create_timer(1.0).timeout.connect(func(): anti_addiction_callback.emit("500", "LOGIN_SUCCESS") ) return if _plugin and _is_sdk_initialized: _plugin.checkAntiAddiction() func check_update() -> void: if _mock_mode: return if _plugin: _plugin.checkUpdate() func save_to_cloud(save_data: String, summary: String) -> void: if _mock_mode: get_tree().create_timer(1.0).timeout.connect(func(): cloud_save_result.emit("created", "mock_archive_id") ) return if not _plugin or not _sdk_api_ready: return _plugin.saveToCloud(save_data, summary) func load_cloud_save_list() -> void: if _mock_mode: get_tree().create_timer(1.0).timeout.connect(func(): cloud_save_list.emit('{"archives":[]}') ) return if not _plugin or not _sdk_api_ready: return _plugin.loadCloudSaveList() func load_cloud_save_data(archive_id: String, file_id: String) -> void: if _mock_mode: get_tree().create_timer(1.0).timeout.connect(func(): cloud_save_data.emit("") ) return if not _plugin: return _plugin.loadCloudSaveData(archive_id, file_id) func submit_leaderboard_score(leaderboard_id: String, score: int) -> void: if _mock_mode: get_tree().create_timer(0.5).timeout.connect(func(): leaderboard_result.emit("0", "submit_success") ) return if not _plugin or not _sdk_api_ready: return _plugin.submitLeaderboardScore(leaderboard_id, score) func load_leaderboard_scores(leaderboard_id: String, collection: String = "PUBLIC", page: String = "") -> void: if _mock_mode: return if not _plugin or not _sdk_api_ready: return _plugin.loadLeaderboardScores(leaderboard_id, collection, page) func load_current_user_score(leaderboard_id: String, collection: String = "PUBLIC") -> void: if _mock_mode: return if not _plugin or not _sdk_api_ready: return _plugin.loadCurrentUserScore(leaderboard_id, collection) func get_friends_list(next_page_token: String = "") -> void: if _mock_mode: return if not _plugin: return _plugin.getFriendsList(next_page_token) func get_user_info() -> Dictionary: return _user_info func get_user_name() -> String: return _user_info.get("name", "") func get_user_id() -> String: return _user_info.get("user_id", "") func get_display_user_id() -> String: if _mock_mode: return _user_info.get("openid", "mock_001") if _is_logged_in else "" if not _plugin: return "" return _plugin.getDisplayUserId() func get_current_user_info() -> Dictionary: if _mock_mode: return _user_info if _is_logged_in else {} if not _plugin: return {} if not _plugin.has_method("getCurrentUserInfo"): return {} var json_str = _plugin.getCurrentUserInfo() if json_str.is_empty(): return {} var json = JSON.new() if json.parse(json_str) != OK: return {} return json.data if json.data is Dictionary else {} # ==================== Signal Handlers ==================== func _on_login_success(user_json: String) -> void: var json = JSON.new() if json.parse(user_json) == OK and json.data is Dictionary: _user_info = json.data _is_logged_in = true _login_time = Time.get_ticks_msec() / 1000.0 _sdk_api_ready = false if _api_ready_timer == null: _api_ready_timer = Timer.new() _api_ready_timer.one_shot = true _api_ready_timer.timeout.connect(_on_api_ready) add_child(_api_ready_timer) _api_ready_timer.start(1.0) # Wait for SDK APIs to become available login_success.emit(_user_info) func _on_api_ready() -> void: _sdk_api_ready = true sdk_api_ready.emit() func _on_login_failed(error: String) -> void: login_failed.emit(error) func _on_login_canceled() -> void: login_canceled.emit() func _on_logout_finished() -> void: _is_logged_in = false _user_info = {} _login_time = 0.0 logout_finished.emit() func _on_anti_addiction_callback(code: String, message: String) -> void: anti_addiction_callback.emit(code, message) func _on_cloud_save_result(action: String, data: String) -> void: match action: "created", "updated": _current_archive_id = data "deleted": if _current_archive_id == data: _current_archive_id = "" cloud_save_result.emit(action, data) func _on_cloud_save_list(archives_json: String) -> void: if _current_archive_id.is_empty() and not archives_json.is_empty(): var json = JSON.new() if json.parse(archives_json) == OK and json.data is Dictionary: var archives = json.data.get("archives", []) if archives is Array and not archives.is_empty(): _current_archive_id = archives[0].get("archiveId", "") cloud_save_list.emit(archives_json) func _on_cloud_save_data(save_json: String) -> void: cloud_save_data.emit(save_json) func _on_leaderboard_result(code: String, message: String) -> void: leaderboard_result.emit(code, message) func _on_leaderboard_scores(scores_json: String) -> void: leaderboard_scores.emit(scores_json) func _on_leaderboard_user_score(score_json: String) -> void: leaderboard_user_score.emit(score_json) func _on_friends_list(friends_json: String) -> void: friends_list.emit(friends_json) func _mock_login_success() -> void: _user_info = {"name": "MockPlayer", "avatar": "", "user_id": "mock_001", "openid": "mock_001"} _is_logged_in = true _login_time = Time.get_ticks_msec() / 1000.0 login_success.emit(_user_info) ``` ## Step 4: Game Integration ### 4.1 Initialization Flow (main_menu.gd) ```gdscript const TAPTAP_CLIENT_ID: String = "your_client_id" const TAPTAP_CLIENT_TOKEN: String = "your_client_token" const TAPTAP_SERVER_URL: String = "" func _setup_taptap() -> void: if not TapTapManager.is_available(): return TapTapManager.login_success.connect(_on_taptap_login_success) TapTapManager.login_failed.connect(_on_taptap_login_failed) TapTapManager.anti_addiction_callback.connect(_on_anti_addiction_callback) if not GameManager.privacy_agreed: # Show privacy popup first privacy_popup.show_popup() else: _init_taptap_sdk() func _init_taptap_sdk() -> void: TapTapManager.init_sdk(TAPTAP_CLIENT_ID, TAPTAP_CLIENT_TOKEN, TAPTAP_SERVER_URL) TapTapManager.init_anti_addiction(TAPTAP_CLIENT_ID) TapTapManager.init_update(TAPTAP_CLIENT_ID, TAPTAP_CLIENT_TOKEN) TapTapManager.init_cloud_save() TapTapManager.init_leaderboard() TapTapManager.init_friends() # Handle cached login session if TapTapManager.is_sdk_logged_in(): _handle_cached_login() func _handle_cached_login() -> void: var user_info = TapTapManager.get_current_user_info() if user_info.is_empty(): return TapTapManager._is_logged_in = true TapTapManager._user_info = user_info TapTapManager._sdk_api_ready = false # Start API ready timer if TapTapManager._api_ready_timer == null: TapTapManager._api_ready_timer = Timer.new() TapTapManager._api_ready_timer.one_shot = true TapTapManager._api_ready_timer.timeout.connect(TapTapManager._on_api_ready) TapTapManager.add_child(TapTapManager._api_ready_timer) TapTapManager._api_ready_timer.start(2.0) TapTapManager.get_friends_list() _try_restore_cloud_save() TapTapManager.check_anti_addiction() ``` ### 4.2 Anti-Addiction Callback Handling ```gdscript func _on_anti_addiction_callback(code: String, message: String) -> void: match code: "500": # LOGIN_SUCCESS - can play _try_restore_cloud_save() _enter_bookshelf() "1000", "1001": # Need re-login ToastManager.show_toast(tr("请重新登录")) "1030": # Time restricted ToastManager.show_toast(tr("当前时间无法游戏")) "1050": # Time used up ToastManager.show_toast(tr("今日游戏时长已用完")) "1100": # Age restricted ToastManager.show_toast(tr("年龄限制，无法进入游戏")) "1200": # Network error ToastManager.show_toast(tr("网络错误，请检查网络")) _: _try_restore_cloud_save() _enter_bookshelf() ``` ### 4.3 Cloud Save Sync with Loading Mask ```gdscript var _cloud_save_restore_started: bool = false var _cloud_sync_mask: CanvasLayer = null var _cloud_sync_timeout: Timer = null var _pending_enter_bookshelf: bool = false # Spinner animation class class _CloudSyncSpinner extends Control: var _angle: float = 0.0 func _ready(): custom_minimum_size = Vector2(56, 56) func _process(delta): _angle = fmod(_angle + delta * 3.5, TAU) queue_redraw() func _draw(): var center = size / 2.0 var radius = min(size.x, size.y) * 0.4 if radius <= 0: return var arc_length = PI * 1.3 var segments = 30 var line_width = 4.0 for i in range(segments): var t1 = float(i) / float(segments) var t2 = float(i + 1) / float(segments) var alpha = 1.0 - t1 var a1 = _angle + t1 * arc_length var a2 = _angle + t2 * arc_length var p1 = center + Vector2(cos(a1), sin(a1)) * radius var p2 = center + Vector2(cos(a2), sin(a2)) * radius draw_line(p1, p2, Color(1, 1, 1, alpha), line_width, true) func _try_restore_cloud_save() -> void: if _cloud_save_restore_started: return if not TapTapManager.is_available() or not TapTapManager.is_logged_in() or TapTapManager.is_mock_mode(): return _cloud_save_restore_started = true GameManager.cloud_sync_in_progress = true var _finish_sync = func(): GameManager.cloud_sync_in_progress = false GameManager.cloud_sync_completed.emit() var do_load_list = func(): TapTapManager.cloud_save_list.connect(func(archives_json): if archives_json.is_empty(): _finish_sync.call() return var json = JSON.new() if json.parse(archives_json) != OK: _finish_sync.call() return var archives = json.data.get("archives", []) if archives.is_empty(): _finish_sync.call() return var latest = archives[0] var archive_id = latest.get("archiveId", "") var file_id = latest.get("fileId", "") if archive_id.is_empty() or file_id.is_empty(): _finish_sync.call() return TapTapManager.cloud_save_data.connect(func(save_json): if save_json.is_empty(): _finish_sync.call() return var comparison = GameManager.compare_with_cloud_save(save_json) if comparison["cloud_newer"]: GameManager.load_from_cloud_save(save_json) _finish_sync.call() , CONNECT_ONE_SHOT) TapTapManager.load_cloud_save_data(archive_id, file_id) , CONNECT_ONE_SHOT) TapTapManager.load_cloud_save_list() if TapTapManager._sdk_api_ready: do_load_list.call() else: TapTapManager.sdk_api_ready.connect(do_load_list, CONNECT_ONE_SHOT) func _enter_bookshelf() -> void: if GameManager.cloud_sync_in_progress: _pending_enter_bookshelf = true _show_cloud_sync_mask() if not GameManager.cloud_sync_completed.is_connected(_on_cloud_sync_completed): GameManager.cloud_sync_completed.connect(_on_cloud_sync_completed, CONNECT_ONE_SHOT) if _cloud_sync_timeout == null: _cloud_sync_timeout = Timer.new() _cloud_sync_timeout.one_shot = true _cloud_sync_timeout.timeout.connect(_on_cloud_sync_timeout) add_child(_cloud_sync_timeout) _cloud_sync_timeout.start(15.0) return _do_enter_bookshelf() func _show_cloud_sync_mask() -> void: if _cloud_sync_mask != null: _cloud_sync_mask.visible = true return _cloud_sync_mask = CanvasLayer.new() _cloud_sync_mask.layer = 10 add_child(_cloud_sync_mask) var mask = Control.new() mask.set_anchors_preset(Control.PRESET_FULL_RECT) mask.mouse_filter = Control.MOUSE_FILTER_STOP _cloud_sync_mask.add_child(mask) var bg = ColorRect.new() bg.set_anchors_preset(Control.PRESET_FULL_RECT) bg.color = Color(0, 0, 0, 0.6) mask.add_child(bg) var center_box = VBoxContainer.new() center_box.set_anchors_preset(Control.PRESET_CENTER) center_box.offset_left = -60 center_box.offset_top = -50 center_box.offset_right = 60 center_box.offset_bottom = 50 center_box.alignment = BoxContainer.ALIGNMENT_CENTER mask.add_child(center_box) var spinner = _CloudSyncSpinner.new() center_box.add_child(spinner) var label = Label.new() label.text = tr("正在同步云存档") label.horizontal_alignment = HORIZONTAL_ALIGNMENT_CENTER label.add_theme_color_override("font_color", Color(1, 1, 1, 1)) label.add_theme_font_size_override("font_size", 22) center_box.add_child(label) func _hide_cloud_sync_mask() -> void: if _cloud_sync_mask != null: _cloud_sync_mask.queue_free() _cloud_sync_mask = null if _cloud_sync_timeout != null: _cloud_sync_timeout.stop() _cloud_sync_timeout.queue_free() _cloud_sync_timeout = null func _on_cloud_sync_completed() -> void: _hide_cloud_sync_mask() if _pending_enter_bookshelf: _pending_enter_bookshelf = false _do_enter_bookshelf() func _on_cloud_sync_timeout() -> void: _hide_cloud_sync_mask() if _pending_enter_bookshelf: _pending_enter_bookshelf = false _do_enter_bookshelf() ``` ### 4.4 Leaderboard Data Layer ```gdscript # scripts/data/leaderboard_data.gd static var _global_cache: Array = [] static var _friends_cache: Array = [] static var _cache_timestamp: Dictionary = {} static var _dirty: bool = false var _taptap_global_loading: bool = false var _taptap_friends_loading: bool = false var _pending_collection: String = "" const LEADERBOARD_ID: String = "your_leaderboard_id" const REFRESH_INTERVAL_GLOBAL: int = 60 const REFRESH_INTERVAL_FRIENDS: int = 60 enum TabType { GLOBAL, FRIENDS } func get_leaderboard(tab: int, _region: String = "") -> Array: match tab: TabType.GLOBAL: return _get_global() TabType.FRIENDS: return _get_friends() return [] func _get_global() -> Array: var now = Time.get_unix_time_from_system() if not _dirty and not _global_cache.is_empty() and _cache_timestamp.has("global"): if now - _cache_timestamp["global"] < REFRESH_INTERVAL_GLOBAL: return _global_cache _dirty = false if TapTapManager.is_available() and TapTapManager.is_logged_in(): if not _taptap_global_loading: _taptap_global_loading = true _pending_collection = "PUBLIC" if not TapTapManager.leaderboard_scores.is_connected(_on_taptap_global_scores): TapTapManager.leaderboard_scores.connect(_on_taptap_global_scores) TapTapManager.load_leaderboard_scores(LEADERBOARD_ID, "PUBLIC") return _global_cache func _parse_taptap_scores(scores_json: String) -> Array: if scores_json.is_empty(): return [] var json = JSON.new() if json.parse(scores_json) != OK: return [] var data = json.data if not data is Dictionary: return [] var scores = data.get("scores", []) if not scores is Array: return [] var current_openid = "" if TapTapManager.is_logged_in(): current_openid = TapTapManager.get_user_id() var entries = [] for i in range(scores.size()): var s = scores[i] var user = s.get("user", {}) var openid = user.get("openid", "") var is_me = openid == current_openid and not openid.is_empty() var score_val = int(s.get("score", "0")) var avatar_url = "" var avatar_data = user.get("avatar", "") if avatar_data is Dictionary: avatar_url = avatar_data.get("url", "") elif avatar_data is String: avatar_url = avatar_data entries.append({ "user_id": openid, "nickname": user.get("name", ""), "avatar_url": avatar_url, "avatar_index": i % 12, "score": float(score_val), "score_display": str(score_val), "is_me": is_me, }) return entries func _on_taptap_global_scores(scores_json: String) -> void: _taptap_global_loading = false if _pending_collection != "PUBLIC": return _pending_collection = "" var entries = _parse_taptap_scores(scores_json) if not entries.is_empty(): entries.sort_custom(func(a, b): return a.score > b.score) for i in range(entries.size()): entries[i]["rank"] = i + 1 _global_cache = entries _cache_timestamp["global"] = Time.get_unix_time_from_system() static func mark_dirty() -> void: _dirty = true func invalidate_cache(tab: int = -1) -> void: if tab == -1: _global_cache.clear() _friends_cache.clear() _cache_timestamp.clear() return match tab: TabType.GLOBAL: _global_cache.clear() _cache_timestamp.erase("global") TabType.FRIENDS: _friends_cache.clear() _cache_timestamp.erase("friends") ``` ### 4.5 Leaderboard Score Submission ```gdscript # In game_manager.gd var _leaderboard_submit_timer: Timer = null func complete_puzzle(puzzle_id: String) -> void: # ... existing puzzle completion logic ... _submit_leaderboard_score() func _submit_leaderboard_score() -> void: if not TapTapManager.is_available() or not TapTapManager.is_logged_in(): return if _leaderboard_submit_timer == null: _leaderboard_submit_timer = Timer.new() _leaderboard_submit_timer.one_shot = true _leaderboard_submit_timer.timeout.connect(_do_leaderboard_submit) add_child(_leaderboard_submit_timer) if not _leaderboard_submit_timer.is_stopped(): _leaderboard_submit_timer.stop() _leaderboard_submit_timer.start(5.0) # 5-second debounce func _do_leaderboard_submit() -> void: var score = completed_puzzles.size() TapTapManager.submit_leaderboard_score(LeaderboardDataScript.LEADERBOARD_ID, score) ``` ### 4.6 Avatar Loading in Rank Rows ```gdscript # In rank_row.gd var _http_request: HTTPRequest = null const AVATAR_SIZE := Vector2(56, 56) func _load_avatar_from_url(url: String) -> void: if _http_request == null: _http_request = HTTPRequest.new() _http_request.request_completed.connect(_on_avatar_loaded) add_child(_http_request) _avatar.modulate.a = 0.0 _http_request.request(url) func _on_avatar_loaded(_result: int, _code: int, _headers: PackedStringArray, body: PackedByteArray) -> void: if body.is_empty(): _setup_fallback_avatar(0) _avatar.modulate.a = 1.0 return var img = Image.new() var err = img.load_png_from_buffer(body) if err != OK: err = img.load_jpg_from_buffer(body) if err != OK: err = img.load_webp_from_buffer(body) if err != OK: _setup_fallback_avatar(0) _avatar.modulate.a = 1.0 return img.convert(Image.FORMAT_RGBA8) img = _make_circular(img) _avatar.texture = ImageTexture.create_from_image(img) _avatar.modulate.a = 1.0 func _make_circular(img: Image) -> Image: var size = Vector2(img.get_width(), img.get_height()) var target = AVATAR_SIZE if size != target: img.resize(int(target.x), int(target.y), Image.INTERPOLATE_LANCZOS) var center = target * 0.5 var radius = min(target.x, target.y) * 0.48 for y in range(int(target.y)): for x in range(int(target.x)): if Vector2(x, y).distance_to(center) > radius: img.set_pixel(x, y, Color(0, 0, 0, 0)) return img ``` ## Key Technical Notes ### ScoreItem Limitations `SubmitScoresRequest.ScoreItem` only has `leaderboardId` and `score` fields. It does **NOT** support extra metadata (country, region, etc.). If you need region-based leaderboards, you must create separate leaderboards on the TapTap developer console. ### API Ready Timing After login, TapSDK APIs (cloud save, leaderboard) are not immediately available. Always wait for `sdk_api_ready` signal before calling these APIs. The recommended delay is 1-2 seconds after login callback. ### Cached Login Sessions When the app restarts, `TapTapLogin.getCurrentTapAccount()` may return a cached session. You must: 1. Call `getCurrentUserInfo()` to verify the session 2. Set `_is_logged_in = true` and `_user_info` manually 3. Start the API ready timer before calling any API 4. Trigger cloud save restore after API is ready ### Cloud Save Unauthenticated Error If you call cloud save APIs before the SDK is fully authenticated, you'll get `Unauthenticated: login required`. Always: 1. Check `_sdk_api_ready` before calling cloud save 2. For cached sessions, wait for `sdk_api_ready` signal 3. Use the loading mask pattern to prevent users from seeing stale data ### Leaderboard -androidx Suffix The leaderboard module dependency must use `tap-leaderboard-androidx`, not `tap-leaderboard`. Using the wrong one will cause compilation errors. ### Thread Safety All TapSDK callbacks run on background threads. Use `mainHandler.post {}` in Kotlin to emit signals on the main thread, or use the `safeEmit` helper pattern shown in the code. ### 8-Digit Display User ID Generate a user-friendly 8-digit ID from openId: ```kotlin val hash = openId.hashCode().toLong() and 0xFFFFFFFFL val displayId = String.format("%08d", hash % 100000000L) ``` ## Anti-Addiction Code Reference | Code | Meaning | Action | |------|---------|--------| | 500 | LOGIN_SUCCESS | Allow entry | | 1000/1001 | Need re-login | Prompt re-login | | 1030 | Time restricted | Show time restriction message | | 1050 | Time used up | Show time limit message | | 1100 | Age restricted | Block entry | | 1200 | Network error | Show network error | ## Cloud Save Data Flow ``` App Start → Check cached login → Restore session → Wait for API ready ↓ Load cloud save list → Get latest archive → Download save data ↓ Compare with local save → If cloud newer, apply cloud save ↓ Emit cloud_sync_completed → Enter game ``` ## Leaderboard Data Flow ``` User opens leaderboard → Check cache (with TTL) ↓ (cache miss) Call TapTapLeaderboard.loadLeaderboardScores() ↓ Receive on_leaderboard_scores signal → Parse JSON ↓ Extract: rank, score, user.name, user.openid, user.avatar.url ↓ Sort by score desc → Assign ranks → Update cache → Display ```

Taptap Godot Integration

Description

Latest Changes

Install Taptap Godot Integration with One Click