Skip to content

AGENTS.md

Latest commit

 

History

History
84 lines (59 loc) · 4.24 KB

AGENTS.md

File metadata and controls

84 lines (59 loc) · 4.24 KB
Raw

AGENTS.md

Project Overview

This is the Talo Godot Plugin - a self-hostable game development backend plugin for the Godot Engine (v4.6+). 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.

Architecture

Core Structure

The plugin is an autoload singleton called Talo (defined in talo_manager.gd) that initializes on _ready() and provides access to all APIs, settings, and utilities.

Key architectural components:

  1. TaloManager (talo_manager.gd) - Main autoload singleton

    • Initializes all API instances, crypto manager, continuity manager, and socket
    • Manages current player/alias state
    • Handles app quit and focus events to flush pending data

  2. TaloClient (talo_client.gd) - HTTP client wrapper

    • Used by all API classes (via apis/api.gd)
    • Triggers continuity system on failed requests
    • Version: Auto-updated by pre-commit hook

  3. TaloSettings (talo_settings.gd) - Configuration management

    • Reads/writes settings.cfg
    • Key settings: access_key, api_url, socket_url, auto_connect_socket, continuity_enabled, debounce_timer_seconds
    • Feature tags: talo_dev (force debug), talo_live (force release)

  4. Continuity System (utils/continuity_manager.gd) - Offline resilience

    • Automatically retries failed POST/PUT/PATCH/DELETE requests

  5. TaloSocket (talo_socket.gd) - WebSocket communication

    • Requires ticket creation via socket_tickets_api.gd
    • Used by channels, player presence and player relationships

API Layer

All API classes extend TaloAPI (apis/api.gd), which provides a TaloClient instance.

Entity System

Entity classes in addons/talo/entities/ represent API data models.

Utilities

Key utilities in 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)
  • TaloDebouncedAPI (apis/debounced_api.gd) - Base class for debounced APIs. Provides flush_updates() -> FlushResult and per-update awaiters. Player and save updates debounce by default but can be awaited for entity-specific results.

GDScript Standards

This project enforces strict type safety - all warnings are set to error level (2) in project.godot:

  • 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:

Talo="*res://addons/talo/talo_manager.gd"

Settings are in addons/talo/settings.cfg - this file is auto-generated and should be filled with the user's access key.

Important Notes

  • Auto accept quit: Disabled to ensure proper flush on exit (talo_manager.gd)
  • 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)