Merge pull request #172 from TaloDev/develop

Release 0.39.0

Author: tudddorrr

.github/workflows/claude-code-review.yml

@@ -21,8 +21,7 @@ jobs:
     runs-on: ubuntu-latest
     permissions:
       contents: read
-      pull-requests: read
-      issues: read
+      pull-requests: write
       id-token: write
 
     steps:
@@ -37,23 +36,67 @@ jobs:
         with:
           claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
           prompt: |
-            Please review this pull request and provide feedback on:
-            - Code quality and best practices
-            - Potential bugs or issues
-            - Performance considerations
-            - Security concerns
-            - Backwards compatibility
-            - Documentation: public methods (not prefixed with _) should generally have docstrings (##) and classes should contain the @tutorial tag
-
-            For each of the points above, do not point out what works well, only what could be improved (if anything).
-            Be constructive and helpful in your feedback but do not repeat yourself - only summarise potential issues.
-            Test coverage is currently not a priority.
-            Prefix section headers with emojis and use dividers for better readability.
-            
-            Use the repository's CLAUDE.md for guidance on style and conventions. Be constructive and helpful in your feedback.
-            Use `gh pr comment` with your Bash tool to leave your review as a comment on the PR.
-          
-          # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
-          # or https://docs.anthropic.com/en/docs/claude-code/sdk#command-line for available options
-          claude_args: '--model sonnet --allowed-tools "Bash(gh issue view:*),Bash(gh search:*),Bash(gh issue list:*),Bash(gh pr comment:*),Bash(gh pr diff:*),Bash(gh pr view:*),Bash(gh pr list:*)"'
-          use_sticky_comment: true
+            You are reviewing PR #${{ github.event.pull_request.number }} in the repository ${{ github.repository }}.
+
+            Review this pull request and provide feedback focused only on improvements needed (not what works well):
+
+            **Categories to check:**
+            1. Code quality and best practices
+            2. Potential bugs or issues
+            3. Performance considerations
+            4. Security concerns
+            5. Backwards compatibility
+
+            **Process:**
+            - The PR number is: ${{ github.event.pull_request.number }}
+            - View the PR using: `gh pr view ${{ github.event.pull_request.number }} --repo ${{ github.repository }}`
+            - Read CLAUDE.md to understand best practices
+            - View the PR diff using: `gh pr diff ${{ github.event.pull_request.number }} --repo ${{ github.repository }}`
+            - If an issue spans multiple categories, list it only once in the most relevant section
+            - Prioritize by severity: 🔴 Critical → 🟡 Major → 🔵 Minor
+            - Focus only on changes introduced in this PR, not pre-existing code issues
+            - Test coverage is currently not a priority
+
+            **Review Workflow (Follow these steps):**
+            1. **Analysis Phase**: Review the PR diff and identify potential issues
+            2. **Validation Phase**: For each issue you find, verify it by:
+               - Re-reading the relevant code carefully
+               - Checking if your suggested fix is actually different from the current code
+               - Confirming the issue violates documented standards (check CLAUDE.md)
+               - Ensuring your criticism is actionable and specific
+            3. **Draft Phase**: Write your review only after validating all issues
+            4. **Quality Check**: Before posting, remove any issues where:
+               - Your "before" and "after" code snippets are identical
+               - You're uncertain or use phrases like "appears", "might", "should verify"
+               - The issue is theoretical without clear impact
+            5. **Post Phase**: Only post the review if you have concrete, validated feedback
+
+            **Edge Case Policy:**
+            Only flag edge cases that meet ALL of these criteria:
+            1. Realistic: Could happen in normal usage or common error scenarios
+            2. Impactful: Would cause bugs, security issues, or data problems (not just "it's not perfect")
+            3. Actionable: Can be fixed with reasonable effort in this PR's scope
+
+            Ignore theoretical issues that require multiple unlikely conditions or malicious input patterns.
+            Use the "would this bother a pragmatic senior developer?" test.
+
+            Maximum chain of assumptions: 2 levels deep. Skip exotic input combinations that violate documented assumptions.
+
+            **Feedback style:**
+            - Provide specific code examples or line references showing the issue
+            - Suggest concrete fixes with code snippets where helpful
+            - Keep total feedback under 500 words
+            - Use section headers with emojis and horizontal dividers (---)
+            - If no improvements needed in a category, simply state "No issues found"
+            - Use neutral language; focus on the code, not the author
+            - If the PR looks good overall, say so clearly rather than forcing criticism
+
+            **Comment Management (IMPORTANT):**
+            Post your review using this command, which will edit your last comment if one exists, or create a new one:
+            ```bash
+              gh pr comment ${{ github.event.pull_request.number }} --repo ${{ github.repository }} --edit-last --create-if-none --body "<review>"
+            ```
+
+            Ensure proper escaping of quotes and special characters in the comment body. Use single quotes around the body and escape any single quotes inside with '\''
+          claude_args: |
+            --allowedTools "Read,Bash(gh pr:*),Grep,Glob"

CLAUDE.md

@@ -0,0 +1,153 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+This is the **Talo Godot Plugin** - a self-hostable game development backend plugin for the Godot Engine (v4.4+). Talo provides leaderboards, player authentication, event tracking, game saves, stats, channels, live config, and more. The plugin is distributed via the Godot Asset Library and GitHub releases.
+
+## Development Commands
+
+### Building & Testing
+```bash
+# Export for all platforms (runs on push via CI)
+godot --headless --export-release 'Windows Desktop'
+godot --headless --export-release 'macOS'
+godot --headless --export-release 'Linux'
+godot --headless --export-release 'Web'
+
+# The CI checks for SCRIPT ERROR in build output and fails if found
+```
+
+### Running Samples
+The project includes sample scenes demonstrating plugin features. The main scene is configured as `res://addons/talo/samples/playground/playground.tscn`. To test samples, change the main scene in [project.godot](project.godot) or run scenes directly from the editor.
+
+Available samples:
+- **Playground**: Text-based playground for testing identify, events, stats, leaderboards
+- **Authentication**: Registration/login/account management flow
+- **Leaderboards**: Basic leaderboard UI
+- **Multi-scene saves**: Persist save data across multiple scenes
+- **Persistent buttons**: Simple save/load demo
+- **Chat**: Real-time messaging using channels
+- **Channel storage**: Shared player data storage
+
+## Architecture
+
+### Core Structure
+
+The plugin is an **autoload singleton** called `Talo` (defined in [talo_manager.gd](addons/talo/talo_manager.gd:20)) that initializes on `_ready()` and provides access to all APIs, settings, and utilities.
+
+**Key architectural components:**
+
+1. **TaloManager** ([talo_manager.gd](addons/talo/talo_manager.gd)) - Main autoload singleton
+   - Initializes all API instances, crypto manager, continuity manager, and socket
+   - Manages current player/alias state
+   - Emits `init_completed`, `connection_lost`, and `connection_restored` signals
+   - Handles app quit and focus events to flush pending data
+
+2. **TaloClient** ([talo_client.gd](addons/talo/talo_client.gd)) - HTTP client wrapper
+   - Used by all API classes (via [apis/api.gd](addons/talo/apis/api.gd))
+   - Builds authenticated requests with proper headers (access key, player/alias/session tokens)
+   - Logs requests/responses if enabled in settings
+   - Triggers continuity system on failed requests
+   - Version: Auto-updated by pre-commit hook
+
+3. **TaloSettings** ([talo_settings.gd](addons/talo/talo_settings.gd)) - Configuration management
+   - Reads/writes [settings.cfg](addons/talo/settings.cfg)
+   - Key settings: `access_key`, `api_url`, `socket_url`, `auto_connect_socket`, `continuity_enabled`, `debounce_timer_seconds`
+   - Auto-creates settings.cfg with defaults if missing
+   - Feature tags: `talo_dev` (force debug), `talo_live` (force release)
+
+4. **Continuity System** ([utils/continuity_manager.gd](addons/talo/utils/continuity_manager.gd)) - Offline resilience
+   - Automatically retries failed POST/PUT/PATCH/DELETE requests
+   - Excludes: health checks, auth, identify, socket tickets
+   - Stores encrypted requests in `user://tc.bin`
+   - Replays up to 10 requests every 10 seconds when online
+   - Ignores time scale for reliability
+
+5. **TaloSocket** ([talo_socket.gd](addons/talo/talo_socket.gd)) - WebSocket communication
+   - Connects to `wss://api.trytalo.com` by default
+   - Requires ticket creation via [socket_tickets_api.gd](addons/talo/apis/socket_tickets_api.gd)
+   - Handles player identification with socket token
+   - Polls in `_process()` loop
+   - Used by channels, player presence, and custom real-time features
+
+### API Layer
+
+All API classes extend `TaloAPI` ([apis/api.gd](addons/talo/apis/api.gd)), which provides a `TaloClient` instance. There are 14 API classes:
+
+- [players_api.gd](addons/talo/apis/players_api.gd) - Player identification and management
+- [player_auth_api.gd](addons/talo/apis/player_auth_api.gd) - Authentication and sessions
+- [events_api.gd](addons/talo/apis/events_api.gd) - Event tracking
+- [stats_api.gd](addons/talo/apis/stats_api.gd) - Player and global stats
+- [leaderboards_api.gd](addons/talo/apis/leaderboards_api.gd) - Leaderboard management
+- [saves_api.gd](addons/talo/apis/saves_api.gd) - Game save operations
+- [feedback_api.gd](addons/talo/apis/feedback_api.gd) - Player feedback collection
+- [game_config_api.gd](addons/talo/apis/game_config_api.gd) - Live config
+- [health_check_api.gd](addons/talo/apis/health_check_api.gd) - Connectivity checks (debounced)
+- [player_groups_api.gd](addons/talo/apis/player_groups_api.gd) - Player grouping
+- [channels_api.gd](addons/talo/apis/channels_api.gd) - Real-time messaging
+- [socket_tickets_api.gd](addons/talo/apis/socket_tickets_api.gd) - Socket authentication
+- [player_presence_api.gd](addons/talo/apis/player_presence_api.gd) - Online status
+
+### Entity System
+
+18 entity classes in [addons/talo/entities/](addons/talo/entities/) represent API data models. Key entities:
+- `TaloPlayer` - Player data with props
+- `TaloPlayerAlias` - Player identity/device association
+- `TaloLeaderboardEntry` - Leaderboard scores
+- `TaloGameSave` - Saved game state
+- `TaloLiveConfig` - Dynamic configuration
+- `TaloChannel` - Real-time messaging channels
+
+Most entities extend `TaloLoadable` ([entities/loadable.gd](addons/talo/entities/loadable.gd)) which provides JSON serialization and `from_api()` factory methods.
+
+### Utilities
+
+Key utilities in [addons/talo/utils/](addons/talo/utils/):
+- **SavesManager** - Handles save CRUD, caching, offline support
+- **LeaderboardEntriesManager** - Manages leaderboard entry state
+- **ChannelStorageManager** - Manages channel-based shared storage
+- **CryptoManager** - Encryption key generation/storage for offline data
+- **SessionManager** - Session token persistence
+- **DebounceTimer** - Debounces health checks, player updates, save updates (1s default, configurable via `debounce_timer_seconds`)
+
+## GDScript Standards
+
+This project enforces **strict type safety** - all warnings are set to error level (2) in [project.godot](project.godot:24-58):
+- All variables must be explicitly typed (`var foo: String`) unless their type can be easily inferred using the `:=` operator
+- No unsafe property/method access
+- No unsafe casts or call arguments
+- All function parameters and return types must be typed
+
+When writing code:
+- Always use explicit type annotations
+- Use `class_name` for all classes
+- Prefer `await` for async operations (avoid `yield`)
+- Follow existing patterns in API/entity/utility files
+
+## Plugin Configuration
+
+The plugin autoload is configured in [project.godot](project.godot:20):
+```
+Talo="*res://addons/talo/talo_manager.gd"
+```
+
+Settings are in [addons/talo/settings.cfg](addons/talo/settings.cfg) - this file is auto-generated and should be filled with the user's access key.
+
+## CI/CD
+
+GitHub Actions workflows in [.github/workflows/](/.github/workflows/):
+- **ci.yml** - Runs on every push, exports for all platforms, fails on script errors
+- **create-release.yml** - Automates releases
+- **tag.yml** - Handles version tagging
+- **claude-code-review.yml** - Automated code review
+
+## Important Notes
+
+- **Process mode**: TaloManager uses `PROCESS_MODE_ALWAYS` ([talo_manager.gd](addons/talo/talo_manager.gd:48))
+- **Auto accept quit**: Disabled to ensure proper flush on exit ([talo_manager.gd](addons/talo/talo_manager.gd:47))
+- **Identity checks**: Most API operations require `Talo.players.identify()` first
+- **Offline mode**: Setting `offline_mode = true` simulates no internet for testing
+- **Debouncing**: Health checks, player updates, and save updates are debounced (configurable via `debounce_timer_seconds`)
+- **Time scale**: Continuity manager and debounce timer ignore time scale for reliability

addons/talo/apis/health_check_api.gd

@@ -11,25 +11,37 @@ enum HealthCheckStatus {
 	UNKNOWN
 }
 
-var _last_health_check_status := HealthCheckStatus.UNKNOWN
+var _cached_result := HealthCheckStatus.UNKNOWN
+var _can_ping := true
+var _timer := TaloDebounceTimer.new(func (): _can_ping = true)
 
-## Ping the Talo Health Check API to check if Talo can be reached.
+func _ready() -> void:
+	add_child(_timer)
+
+## Check if the Talo API can be reached.
 func ping() -> bool:
+	var bust_cache := _can_ping or _cached_result == HealthCheckStatus.UNKNOWN
+	if not bust_cache:
+		return _cached_result == HealthCheckStatus.OK
+
+	_can_ping = false
+	_timer.debounce()
+
 	var res := await client.make_request(HTTPClient.METHOD_GET, "")
 	var success := true if res.status == 204 else false
-	var failed_last_health_check := true if _last_health_check_status == HealthCheckStatus.FAILED else false
+	var failed_last_health_check := _cached_result == HealthCheckStatus.FAILED
 
 	if success:
-		_last_health_check_status = HealthCheckStatus.OK
+		_cached_result = HealthCheckStatus.OK
 		if failed_last_health_check:
 			Talo.connection_restored.emit()
 	else:
-		_last_health_check_status = HealthCheckStatus.FAILED
+		_cached_result = HealthCheckStatus.FAILED
 		if not failed_last_health_check:
 			Talo.connection_lost.emit()
 
 	return success
 
 ## Get the latest known health check status.
 func get_last_status() -> HealthCheckStatus:
-	return _last_health_check_status
+	return _cached_result

addons/talo/apis/leaderboards_api.gd

@@ -84,8 +84,8 @@ func add_entry(internal_name: String, score: float, props: Dictionary[String, Va
 
 	match res.status:
 		200:
-			var entry = TaloLeaderboardEntry.new(res.body.entry)
-			_entries_manager.upsert_entry(internal_name, entry)
+			var entry := TaloLeaderboardEntry.new(res.body.entry)
+			_entries_manager.upsert_entry(internal_name, entry, true)
 
 			return AddEntryResult.new(entry, res.body.updated)
 		_:

addons/talo/apis/players_api.gd

@@ -17,8 +17,14 @@ signal identification_failed()
 ## Emitted after calling clear_identity().
 signal identity_cleared()
 
+var _update_timer := TaloDebounceTimer.new(_handle_update_timer_timeout)
+
 func _ready() -> void:
 	Talo.connection_restored.connect(_on_connection_restored)
+	add_child(_update_timer)
+
+func _handle_update_timer_timeout() -> void:
+	await Talo.players.update()
 
 func _handle_identify_success(alias: TaloPlayerAlias, socket_token: String = "") -> TaloPlayer:
 	if not await Talo.is_offline():
@@ -57,6 +63,10 @@ func identify_steam(ticket: String, identity: String = "") -> TaloPlayer:
 	else:
 		return await identify("steam", "%s:%s" % [identity, ticket])
 
+## Queue a debounced update to the current player. The timer will reset every time this method is called.
+func debounce_update() -> void:
+	_update_timer.debounce()
+
 ## Flush and sync the player's current data with Talo.
 func update() -> TaloPlayer:
 	if Talo.identity_check() != OK:

addons/talo/apis/saves_api.gd

@@ -28,6 +28,15 @@ var latest: TaloGameSave:
 var current: TaloGameSave:
 	get: return _saves_manager.current_save
 
+var _update_timer := TaloDebounceTimer.new(_handle_update_timer_timeout)
+
+func _ready() -> void:
+	add_child(_update_timer)
+
+func _handle_update_timer_timeout() -> void:
+	if _saves_manager.current_save:
+		await update_save(_saves_manager.current_save)
+
 ## Sync an offline save with an online save using the offline save data.
 func replace_save_with_offline_save(offline_save: TaloGameSave) -> TaloGameSave:
 	var res := await client.make_request(HTTPClient.METHOD_PATCH, "/%s" % offline_save.id, {
@@ -112,25 +121,37 @@ func register(loadable: TaloLoadable) -> void:
 
 ## Update the currently loaded save using the current state of the game and with the given name.
 func update_current_save(new_name: String = "") -> TaloGameSave:
-	return await update_save(_saves_manager.current_save, new_name)
+	if not _saves_manager.current_save:
+		return null
+
+	# if the save is being renamed, sync it immediately
+	if not new_name.is_empty():
+		return await update_save(_saves_manager.current_save, new_name)
+	# else, update the save locally and queue it for syncing
+	else:
+		_update_timer.debounce()
+		_saves_manager.current_save.content = _saves_manager.get_save_content()
+		return _saves_manager.current_save
 
 ## Update the given save using the current state of the game and with the given name.
 func update_save(save: TaloGameSave, new_name: String = "") -> TaloGameSave:
-	var content := _saves_manager.get_save_content()
+	var is_offline := await Talo.is_offline()
+	var can_update_save := Talo.identity_check() == OK or is_offline
+	if not can_update_save:
+		return null
 
-	if await Talo.is_offline():
-		if not new_name.is_empty():
-			save.name = new_name
+	if not new_name.is_empty():
+		save.name = new_name
+
+	var content := _saves_manager.get_save_content()
+	save.content = content
 
-		save.content = content
+	if is_offline:
 		save.updated_at = TaloTimeUtils.get_current_datetime_string()
 	else:
-		if Talo.identity_check() != OK:
-			return
-
 		var res := await client.make_request(HTTPClient.METHOD_PATCH, "/%s" % save.id, {
-			name=save.name if new_name.is_empty() else new_name,
-			content=content
+			name=save.name,
+			content=save.content
 		})
 
 		match res.status: