Skip to content

CLAUDE.md

Latest commit

 

History

History
97 lines (71 loc) · 5.82 KB

CLAUDE.md

File metadata and controls

97 lines (71 loc) · 5.82 KB

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 Unity Package, a self-hostable game development SDK providing leaderboards, player authentication, event tracking, game saves, stats, live config, channels, and more. The package is distributed via Unity Asset Store, GitHub releases, and itch.io.

The codebase uses git submodules for dependency management (run git submodule update --init after cloning).

Project Structure

All Talo code is located in Assets/Talo Game Services/Talo/:

  • Runtime/ - Core SDK implementation
    • APIs/ - API client classes for each service (Events, Players, Leaderboards, Saves, Stats, etc.)
    • Entities/ - Data models (Player, GameSave, LeaderboardEntry, etc.)
    • Requests/ - Request payload classes
    • Responses/ - Response payload classes
    • SocketRequests/ & SocketResponses/ - WebSocket message types
    • Utils/ - Internal utilities (ContinuityManager, CryptoManager, SavesManager, etc.)
    • Vendor/ - Third-party dependencies (WebSocket client)
    • Talo.cs - Main static entry point and API access
    • TaloManager.cs - MonoBehaviour managing lifecycle and timers
    • TaloSocket.cs - WebSocket connection handler
    • TaloSettings.cs - ScriptableObject configuration
  • Tests/ - NUnit test suite
  • Samples/ - Demo scenes (Leaderboards, Saves, Authentication, Chat, etc.)

Architecture Patterns

Singleton Pattern

Talo.cs is the main static singleton providing access to all services (e.g., Talo.Players, Talo.Events, Talo.Saves). It initializes a TaloManager MonoBehaviour on first access, which persists across scenes.

API Architecture

All API classes inherit from BaseAPI.cs, which handles HTTP requests via Unity's UnityWebRequest. Each API class (e.g., PlayersAPI, SavesAPI) exposes public async methods returning typed responses.

Continuity System

The ContinuityManager queues failed network requests (POST/PUT/PATCH/DELETE) to disk and replays them when connectivity is restored. It excludes certain endpoints like /health-check and /players/auth.

Offline Mode

The SDK supports offline operation via TaloSettings.offlineMode. When offline, requests are queued for continuity replay. The HealthCheckAPI monitors connectivity and triggers connection lost/restored events.

WebSocket Integration

TaloSocket.cs manages WebSocket connections for real-time features (channels, presence). It uses the com.mikeschweitzer.websocket package (vendored in Runtime/Vendor/).

Event Flushing

Events are batched and flushed on application quit/pause/focus loss. On WebGL, events flush every webGLEventFlushRate seconds (default 30s) due to platform limitations.

Debouncing

Player updates and save updates are debounced to prevent excessive API calls during rapid property changes. APIs that need debouncing inherit from DebouncedAPI<TOperation> (a generic base class) and define a DebouncedOperation enum for type-safe operation keys. The base class uses a dictionary to track multiple debounced operations independently.

The debounce is leading and trailing: the first call fires immediately (leading), and if further calls arrive during the debounce window they are coalesced into a single trailing call executed after the window closes. The window is defined by debounceTimerSeconds (default: 1s) and resets on each subsequent call.

To add debouncing to an API:

  1. Define a public enum DebouncedOperation with your debounced operations
  2. Inherit from DebouncedAPI<YourAPI.DebouncedOperation>
  3. Call Debounce(DebouncedOperation.YourOperation) to queue an operation
  4. Implement ExecuteDebouncedOperation(DebouncedOperation operation) with a switch statement
  5. The base class's ProcessPendingUpdates() is called by TaloManager.Update() every frame

Example: PlayersAPI defines enum DebouncedOperation { Update } and inherits from DebouncedAPI<PlayersAPI.DebouncedOperation>. When Player.SetProp() is called, it calls Debounce(DebouncedOperation.Update). The first call fires immediately; subsequent calls within the debounce window result in a single trailing API call at the end of the window.

Key Configuration

TaloSettings

Settings are managed via a ScriptableObject asset (Resources/Talo Settings):

  • accessKey - API authentication key
  • apiUrl - Backend URL (default: https://api.trytalo.com)
  • socketUrl - WebSocket URL (default: wss://api.trytalo.com)
  • autoStartSession - Auto-authenticate with saved session token
  • autoConnectSocket - Auto-connect WebSocket on startup
  • continuityEnabled - Enable failed request replay
  • offlineMode - Simulate offline for testing
  • debounceTimerSeconds - Debounce interval for player updates, saves, and health checks (default: 1s)

Assembly Definitions

  • Talo.Runtime (TaloRuntime.asmdef) - Main runtime assembly
  • Talo.Tests (TaloTests.asmdef) - Test assembly with NUnit references

Important Implementation Details

Identity & Sessions

Players must be identified via Talo.Players.Identify() before using most APIs. The SDK stores the current alias in Talo.CurrentAlias and player in Talo.CurrentPlayer. Sessions are managed by SessionManager with tokens stored in PlayerPrefs.

Test Mode Detection

The SDK detects when running under NUnit (checks for nunit.framework assembly) and enables test mode, which uses RequestMock instead of real HTTP calls.

Error Handling

  • RequestException - HTTP errors
  • PlayerAuthException - Authentication-specific errors with error codes
  • SocketException - WebSocket errors
  • ContinuityReplayException - Continuity replay failures

Git Workflow

  • Submodules: Required for WebSocket dependency
  • Pre-commit hook: Auto-updates version in BaseAPI.cs using the content from Assets/Talo Game Services/Talo/VERSION