HStats Backend

HStats Backend is the API and ingest service for HStats.dev, a lightweight analytics platform for the Hytale modding community.

It receives anonymous server heartbeats from Hytale servers, tracks plugin usage, stores historical player/server metrics, and serves the data used by the HStats frontend, embeds, Discord tools, and developer dashboards.

Visit HStats.dev

What This Backend Does

• Accepts server heartbeat data for active server/player counts.
• Tracks plugin usage by private server reporting keys.
• Exposes public plugin, developer, embed, and global stats endpoints.
• Stores hourly global and plugin history.
• Supports account sessions, Discord OAuth, reCAPTCHA-protected registration, and plugin management.
• Provides Discord admin commands for maintenance, repairs, backups, and support tooling.
• Generates SVG stat cards for plugins and developer profiles.

Privacy Model

HStats is designed to collect aggregate mod usage data, not player identity.

The backend does not collect:

• Player usernames.
• Player IP addresses.
• Player UUIDs.
• Per-player activity.

The backend does collect:

• Server UUIDs generated by reporting servers.
• Active server/player counts.
• Plugin reporting UUIDs and plugin versions.
• Operating system, Java version, CPU core count, and country-level region.
• Account data required for dashboard login and plugin ownership.

Public and Private Plugin UUIDs

Plugins have two identifiers:

• Public plugin UUID: safe for frontend routes, public API responses, embeds, and sharing.
• Private plugin UUID: server reporting key used by Hytale servers to submit stats.

Only the private UUID should be used by a server/plugin integration. Public pages and frontend links should use public UUIDs.

Requirements

• Node.js 20 or newer recommended.
• npm.
• SQLite-compatible local filesystem.

Setup

Install dependencies:

npm install

Create an environment file:

Copy-Item .env.example .env

Generate required account encryption keys:

node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"

Use separate generated values for:

• ACCOUNT_DATA_KEY
• ACCOUNT_DATA_HMAC_KEY
• ACCOUNT_PASSWORD_PEPPER
• SESSION_SECRET

Run the backend:

node server.js

Environment Configuration

See .env.example for all supported environment variables.

Required for normal API startup:

• ACCOUNTS_DB
• PLUGIN_DB
• SERVERS_DB
• PLUGIN_STATS_DB
• SESSION_SECRET
• ACCOUNT_DATA_KEY
• ACCOUNT_DATA_HMAC_KEY

Required for production registration:

• RECAPTCHA_SECRET_KEY

Required only when Discord features are enabled:

• DISCORD_BOT_ENABLED=true
• DISCORD_BOT_TOKEN
• DISCORD_CLIENT_ID
• DISCORD_GUILD_ID

Optional integrations:

• DISCORD_OAUTH_CLIENT_ID
• DISCORD_OAUTH_CLIENT_SECRET
• DISCORD_BACKUP_WEBHOOK
• SITE_LOGS_WEBHOOK

Discord Bot

Discord bot startup is disabled by default.

To enable it:

DISCORD_BOT_ENABLED=true
DISCORD_BOT_TOKEN=...
DISCORD_CLIENT_ID=...
DISCORD_GUILD_ID=...

Deploy slash commands:

node discord/deployCommands.js

Database Files

SQLite database files are intentionally ignored by Git. Do not commit live .db files.

Default local database paths are:

• databases/accounts.db
• databases/plugins.db
• databases/servers.db
• databases/plugin_stats.db
• databases/important_dates.db
• databases/sessions.db

Documentation

Additional API notes live in docs/:

• docs/plugin-uuid-migration.md
• docs/private-plugin-uuid-refresh.md
• docs/embed-endpoint.md
• docs/important-date-markers.md
• docs/account-usernames-and-plugin-links.md
• docs/discord-oauth.md

Security

Please read SECURITY.md before deploying or reporting a vulnerability.

Do not publish:

• .env
• SQLite database files
• Discord webhook URLs
• Discord bot tokens
• reCAPTCHA secret keys
• account encryption keys