HytaleStats Plugin

A lightweight server-side statistics collection plugin for Hytale servers.

HytaleStats automatically tracks player activity and combat data on your Hytale server and reports it to the
https://hytalestats.gg platform, where players can view leaderboards, profiles, and detailed stats.

Features

Automatic Data Collection

The plugin passively collects gameplay events without interfering with server performance.
Three built-in collectors handle different event categories:

Combat Collector
Tracks PvP kills, PvE kills, deaths, and damage dealt/received.
Each event includes weapon information, entity types, and positional data.
Session Collector
Records player logins, logouts, and accumulated playtime.
Playtime is tracked at configurable intervals (default: 60 seconds).
Progression Collector
Captures level-ups and achievement unlocks, including the specific achievement or level reached.

All collectors can be individually enabled or disabled in the configuration.

Auto-Registration

On first start, if no server credentials are configured, the plugin automatically registers itself with the HytaleStats backend using the server name and contact email from the configuration.

The returned token and secret are saved to config.yml — no manual API key setup required.

Player Privacy

Players can opt out of data collection at any time using /hytalestats optout.
Opted-out players are excluded from all event tracking.
Players can opt back in with /hytalestats optin.
IP addresses are anonymized by default (configurable).

Commands

Command	Description
/hs status	Show plugin status, connection state, and queue size
/hs optout	Opt out of statistics tracking
/hs optin	Opt back in to statistics tracking
/hs help	Show available commands

Configuration

The plugin generates a config.yml on first run with sensible defaults.

api:
  endpoint: "https://hytalestats.gg/api/v1"
  server_name: "My Hytale Server"
  contact_email: "admin@example.com"
  server_token: ""   # Auto-generated on first start
  server_secret: ""  # Auto-generated on first start

batching:
  batch_size: 100
  flush_interval: 30 # seconds

collectors:
  combat:
    enabled: true
  session:
    enabled: true
  progression:
    enabled: true
  blocks:
    enabled: false # High volume, opt-in only

privacy:
  respect_optout: true
  anonymize_ips: true

debug:
  verbose: false
  dry_run: false # When true, events are collected but not sent

Installation

Download hytalestats-1.0.1.jar from https://hytalestats.gg/about
Place the JAR in your server’s plugins/ directory
Start the server — the plugin will generate config.yml and auto-register
Edit config.yml to set your server name and contact email
Restart the server — data collection begins immediately

HitaleStats GG