147 lines
3.6 KiB
Markdown
147 lines
3.6 KiB
Markdown
# 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](#overview)
|
||
- [Features](#features)
|
||
- [Requirements](#requirements)
|
||
- [Installation](#installation)
|
||
- [Configuration](#configuration)
|
||
- [Usage](#usage)
|
||
- [API Reference](#api-reference)
|
||
- [Frontend](#frontend)
|
||
- [Database Schema](#database-schema)
|
||
- [Sample Payload](#sample-payload)
|
||
- [Contributing](#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:
|
||
```bash
|
||
git clone https://github.com/yourusername/dereth-tracker.git
|
||
cd dereth-tracker
|
||
```
|
||
2. Create and activate a virtual environment:
|
||
```bash
|
||
python3 -m venv venv
|
||
source venv/bin/activate # Windows: venv\Scripts\activate
|
||
```
|
||
3. Install dependencies:
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
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:**
|
||
```json
|
||
{
|
||
"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:
|
||
|
||
```json
|
||
{
|
||
"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:
|
||
|
||
```json
|
||
{
|
||
"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](https://d3js.org/).
|
||
|
||
## 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.
|