HytaleTrackerAPI

A Hytale server plugin that tracks player data (UUID, skin, cosmetics) and exposes it via REST API endpoints for HytaleTracker.org.

Features

• Automatic Player Tracking: Captures player UUID, username, and full skin data when they join
• Persistent Storage: All tracked player data is saved to JSON and persists across server restarts
• REST API: Query tracked players via HTTP endpoints
• Login History: Tracks first seen, last seen, and total login count per player

Installation

1. Ensure you have the Nitrado WebServer plugin installed
2. Copy HytaleTrackerAPI-1.0.0-SNAPSHOT.jar to your server's mods/ folder
3. Restart the server

API Endpoints

All endpoints are available at https://<server>:5523/HyVote/HytaleTrackerAPI/

GET /stats

Returns tracking statistics.

Response:

{
  "success": true,
  "totalTrackedPlayers": 42,
  "totalLogins": 156,
  "oldestTracked": "2026-01-15T10:00:00Z",
  "newestActivity": "2026-01-15T17:00:00Z",
  "serverTime": "2026-01-15T17:03:33.783110Z"
}

GET /players

Returns a list of all tracked players.

Query Parameters:

• limit (optional): Max players to return (default: 100, max: 1000)
• offset (optional): Skip first N players (default: 0)
• brief (optional): If true, only returns UUID and username

Response:

{
  "success": true,
  "total": 42,
  "offset": 0,
  "limit": 100,
  "count": 42,
  "players": [
    {
      "uuid": "550e8400-e29b-41d4-a716-446655440000",
      "username": "PlayerName",
      "skin": { ... },
      "firstSeen": "2026-01-15T10:00:00Z",
      "lastSeen": "2026-01-15T17:00:00Z",
      "loginCount": 5
    }
  ]
}

GET /player

Look up a specific player by UUID or username.

Query Parameters:

• uuid: Player UUID (e.g., 550e8400-e29b-41d4-a716-446655440000)
• username: Player username (case-insensitive)

Response:

{
  "success": true,
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "username": "PlayerName",
  "skin": {
    "bodyCharacteristic": "BodyType1.SkinTone1",
    "underwear": "Underwear1.Color1",
    "face": "Face1",
    "ears": "Ears1",
    "mouth": "Mouth1",
    "eyes": "Eyes1.Color1",
    "haircut": "HairLong.Blonde",
    "pants": "Pants1.Blue",
    "undertop": "Shirt1.White",
    "shoes": "Boots1.Brown"
  },
  "firstSeen": "2026-01-15T10:00:00Z",
  "lastSeen": "2026-01-15T17:00:00Z",
  "loginCount": 5
}

Skin Data Structure

The skin object contains up to 20 components:

Category	Fields
Required	bodyCharacteristic, underwear, face, ears, mouth
Face	eyes, eyebrows, facialHair
Hair	haircut
Clothing	pants, overpants, undertop, overtop, shoes, gloves
Accessories	headAccessory, faceAccessory, earAccessory, skinFeature, cape

Each skin part uses the format: {assetId}.{textureId}.{variantId} (e.g., HairLong.Blonde.variant1)

Data Storage

Player data is stored in mods/HyVote_HytaleTrackerAPI/tracked_players.json.

Building from Source

mvn clean package

The built JAR will be in target/HytaleTrackerAPI-1.0.0-SNAPSHOT.jar.

License

MIT License - See LICENSE file for details.

Contributing

Contributions welcome! Please submit pull requests to the hyvote/HytaleTrackerAPI repository.