Ideas for a statistics api

[ajh123]

An API for tracking player statistics across multiple minigames would be an excellent addition, especially if you want to centralize and standardize data collection for leaderboards, performance metrics, or player insights. Here's a breakdown:

Player Statistics API

Purpose: Centralize the collection, storage, and retrieval of player statistics across all minigames.

Key Features

1. Data Collection

   • Track statistics such as:
     • Games played, wins, and losses.
     • Time spent in each minigame.
     • Points scored, objectives completed, or other minigame-specific metrics.
   • Store raw and aggregated data for flexible reporting.

2. Player Profiles

   • Maintain a centralized profile for each player with cumulative stats across all minigames.
   • Include metadata like join date, favorite minigame, or highest rank achieved.

3. Game-Specific Stats

   • Allow minigames to report their unique stats (e.g., kills in PvP, blocks placed in a building competition).
   • API endpoints for submitting and retrieving minigame-specific data.

4. Leaderboards

   • Generate global, per-minigame, or custom leaderboards based on specific metrics (e.g., top scorers, fastest completion times).
   • Allow filtering by timeframe (e.g., weekly, monthly, all-time).

5. Real-Time Updates

   • Enable real-time updating of statistics during gameplay, useful for live dashboards or spectator modes.

6. Analytics and Insights

   • Provide aggregate statistics for server admins, such as the popularity of different minigames or average player performance.
   • Expose trends like player retention or progression rates.

Implementation Notes

• Database Design: Use a relational database to store statistics.
• Performance Optimization: Cache frequently requested data like leaderboards to reduce database queries.
• Minigame Integration: Provide an SDK or library that minigames can use to easily report stats to the API.
• Statistics are stored as key value pairs on a "Minigame object", each player has their own set of key value paris for every minigame. Minigame objects will control which keys are available and determine the structure / type of the value.

[ajh123]

Database Models

1. Players

Stores centralised information about each player.

Column Name	Type	Description
id	UUID	Unique identifier for the player's Minecraft account.
miners_online_id	UUID	Unique identifier for the player's Miners Online account.
username	VARCHAR(255)	The player’s username.
join_date	TIMESTAMP	Date and time the player joined.
metadata	JSONB	Additional metadata (e.g., preferences).
created_at	TIMESTAMP	Timestamp when the profile was created.
updated_at	TIMESTAMP	Last update timestamp.

2. Minigames

Defines each minigame and its allowed statistic keys.

Column Name	Type	Description
id	UUID	Unique identifier for the minigame.
name	VARCHAR(255)	Minigame name.
description	TEXT	Description of the minigame.
stat_keys	JSONB	Defines allowed statistic keys and types (e.g., kills: INT, time_played: FLOAT).
created_at	TIMESTAMP	Timestamp when the minigame was added.
updated_at	TIMESTAMP	Last update timestamp.

3. Player_Stats

Stores statistics for each player and minigame.

Column Name	Type	Description
id	UUID	Unique identifier for the stat entry.
player_id	UUID	Foreign key referencing players.id.
minigame_id	UUID	Foreign key referencing minigames.id.
stats	JSONB	Key-value pairs of stats (e.g., {"kills": 10, "time_played": 360.5}).
created_at	TIMESTAMP	Timestamp when the stats were created.
updated_at	TIMESTAMP	Last update timestamp.

4. Leaderboards

Pre-computed leaderboard data for fast access.

Column Name	Type	Description
id	UUID	Unique identifier for the leaderboard.
minigame_id	UUID	Foreign key referencing minigames.id.
metric	VARCHAR(255)	The leaderboard metric (e.g., "kills", "time_played").
timeframe	VARCHAR(50)	Leaderboard timeframe (e.g., "weekly", "all-time").
data	JSONB	Array of leaderboard entries (e.g., [{player_id: UUID, score: INT}]).
last_generated	TIMESTAMP	Timestamp of the last update.

5. Analytics

Aggregated analytics for server admins.

Column Name	Type	Description
id	UUID	Unique identifier for the analytics entry.
metric	VARCHAR(255)	The aggregated metric name (e.g., "popularity").
data	JSONB	Aggregated data (e.g., {minigame_id: UUID, value: 123}).
created_at	TIMESTAMP	Timestamp when the analytics were generated.

Relationships

1. Players ↔ Player_Stats:

   • One-to-many relationship where Player_Stats tracks individual player stats for each minigame.

2. Minigames ↔ Player_Stats:

   • One-to-many relationship to associate stats with specific minigames.

3. Minigames ↔ Leaderboards:

   • One-to-many relationship to store leaderboard data for each minigame.

Key Features Support

1. Flexible Key-Value Statistics:

   • Player_Stats.stats stores minigame-specific data as JSONB for dynamic key-value flexibility.

2. Cumulative Stats:

   • Use SQL or application logic to aggregate Player_Stats.stats for each player.

3. Real-Time Updates:

   • Player_Stats.updated_at allows tracking the last update, enabling real-time dashboards.

4. Leaderboards:

   • Pre-compute leaderboards in the Leaderboards table for performance optimisation.

5. Analytics:

   • Use Analytics to store aggregated data for admin insights.

[ajh123]

Closed in favour of #6