Introduction & Architecture

Realistic Analytics is an analytics library for Roblox games. Instead of firing network requests every time an event occurs in your game, events are queued in memory and dispatched in batches every few seconds. This avoids hitting Roblox rate limits (like the 500 requests/minute HttpService limit) and prevents frame hitches on high-player servers.

System Architecture

flowchart TD
    subgraph Sources ["Event Ingestion"]
        Trackers["Automatic Trackers<br/>• Playtime & Sessions<br/>• Server Health & FPS<br/>• Badges & Retention<br/>• Deaths & Errors"]
        Custom["Game Scripts<br/>• Analytics:TrackEvent()<br/>• Analytics:Increment()<br/>• Analytics:StartTimer()"]
        Client["Client SDK<br/>• Device & Viewport<br/>• Heartbeat FPS<br/>• Client Errors"]
    end

    subgraph Core ["Processing Engine"]
        Dispatcher["EventDispatcher<br/>(Middleware pipeline, rate limiting, filters)"]
        Queue["BufferQueue<br/>(In-memory batching: flushes every 10s or 25 events)"]
    end

    subgraph Destinations ["Exporters"]
        Roblox["Roblox AnalyticsService<br/>(Roblox Creator Hub)"]
        Http["HttpExporter<br/>(Discord Webhooks, REST endpoints)"]
        Debug["DebugConsole<br/>(Roblox Studio Output)"]
    end

    Trackers --> Dispatcher
    Custom --> Dispatcher
    Client --> Dispatcher
    Dispatcher --> Queue
    Queue --> Roblox
    Queue --> Http
    Queue --> Debug

Key Design Principles

In-Memory Batching

Events are buffered in memory and flushed periodically (every 10 seconds by default, or immediately if the queue reaches 25 events). This ensures game scripts can call :TrackEvent() freely without worrying about network stalls.

Rate-Limit Friendly

Roblox caps external HTTP requests at 500 requests per minute per server. By bundling multiple events into single payloads, you can track tens of thousands of gameplay events without getting HTTP 429 errors.

Safe Shutdown Handling

When a server shuts down, game:BindToClose allocates up to 30 seconds before killing the instance. Realistic Analytics hooks into BindToClose with a dedicated 10-second flush budget to ensure all pending session times and final events are sent before the server terminates.

Exploit Prevention

Remote events coming from the client pass through token-bucket rate limiters and payload type validation. Clients cannot spam fake events or crash the server with oversized strings or nested tables.