Dereth Tracker

Dereth Tracker is a real-time telemetry service for the world of Dereth. It collects player data, stores it in a SQLite database, and provides both a live map interface and an analytics dashboard.

Table of Contents

• Overview
• Features
• Requirements
• Installation
• Configuration
• Usage
• API Reference
• Frontend
• Database Schema
• Sample Payload
• Contributing

Overview

This project provides:

• A FastAPI backend with endpoints for receiving and querying telemetry data.
• SQLite-based storage for snapshots and live state.
• A live, interactive map using static HTML, CSS, and JavaScript.
• An analytics dashboard for visualizing kills and session metrics.

Features

• POST /position: Submit a telemetry snapshot (protected by a shared secret).
• GET /live: Fetch active players seen in the last 30 seconds.
• GET /history: Retrieve historical telemetry data with optional time filtering.
• GET /debug: Health check endpoint.
• Live Map: Interactive map interface with panning, zooming, and sorting.
• Analytics Dashboard: Interactive charts for kills over time and kills per hour using D3.js.

Requirements

• Python 3.9 or newer
• pip
• (Optional) virtual environment tool (venv)

Python packages:

• fastapi
• uvicorn
• pydantic
• pandas
• matplotlib

Installation

1. Clone the repository:

   git clone https://github.com/yourusername/dereth-tracker.git
   cd dereth-tracker
   

2. Create and activate a virtual environment:

   python3 -m venv venv
   source venv/bin/activate  # Windows: venv\Scripts\activate
   

3. Install dependencies:

   pip install fastapi uvicorn pydantic pandas matplotlib
   

Configuration

• Update the SHARED_SECRET in main.py to match your plugin (default: "your_shared_secret").
• The SQLite database file dereth.db is created in the project root. To change the path, edit DB_FILE in db.py.

Usage

Start the server using Uvicorn:

uvicorn main:app --reload --host 0.0.0.0 --port 8000

• Live Map: http://localhost:8000/
• Analytics Dashboard: http://localhost:8000/graphs.html

API Reference

POST /position

Submit a JSON telemetry snapshot. Requires header X-Plugin-Secret: <shared_secret>.

Request Body Example:

{
  "character_name": "Dunking Rares",
  "char_tag": "moss",
  "session_id": "dunk-20250422-xyz",
  "timestamp": "2025-04-22T13:45:00Z",
  "ew": 123.4,
  "ns": 567.8,
  "z": 10.2,
  "kills": 42,
  "deaths": 1,
  "rares_found": 2,
  "prismatic_taper_count": 17,
  "vt_state": "Combat",
  "kills_per_hour": "N/A",
  "onlinetime": "00:05:00"
}

GET /live

Returns active players seen within the last 30 seconds:

{
  "players": [ { ... } ]
}

GET /history

Retrieve historical snapshots with optional from and to ISO8601 timestamps:

GET /history?from=2025-04-22T12:00:00Z&to=2025-04-22T13:00:00Z

Response:

{
  "data": [ { ... } ]
}

Frontend

• Live Map: static/index.html – Real-time player positions on a map.
• Analytics Dashboard: static/graphs.html – Interactive charts powered by D3.js.

Database Schema

• telemetry_log: Stored history of snapshots.
• live_state: Current snapshot per character (upserted).

Sample Payload

See test.json for an example telemetry snapshot.

Contributing

Contributions are welcome! Feel free to open issues or submit pull requests.