Skip to content

Server Plugins

ChostPulse provides official plugins for game servers to send telemetry data to the monitoring backend. Currently supported platforms: PocketMine-MP and Bukkit/Spigot.

Installation

Download

Download the latest ChostPulse.phar from the releases page.

Install

  1. Place the .phar file into your server's plugins/ directory
  2. Start or reload PocketMine-MP
  3. The plugin will automatically generate a secret token on first run

Verify

After startup, check the console for your badge URLs:

[ChostPulse] Your Badge URLs:
[ChostPulse] Status:   https://your-domain.com/api/badge?id=srv_pub_xxx&type=status
[ChostPulse] Players:   https://your-domain.com/api/badge?id=srv_pub_xxx&type=players
[ChostPulse] TPS:      https://your-domain.com/api/badge?id=srv_pub_xxx&type=tps
[ChostPulse] Software: https://your-domain.com/api/badge?id=srv_pub_xxx&type=software

Download

Download the latest ChostPulse-Bukkit.jar from the releases page.

Install

  1. Place the .jar file into your server's plugins/ directory
  2. Restart the server
  3. The plugin will automatically generate a secret token on first run

Verify

Check the console for your Public ID and badge URLs on startup.

Configuration

Both plugins use config.yml in their respective config directories:

# Secret token (auto-generated)
token: "sk_live_550e8400-e29b-41d4-a716-446655440000"

# API endpoint (your deployed worker URL)
api_url: "https://your-domain.com/api/heartbeat"

# Heartbeat interval in seconds
interval: 60

# Send software/version info
send-software: true

# Enable debug logging
debug: false

Configuration Options

Option Type Default Description
token string auto-generated Secret key for API authentication
api_url string required URL of your deployed ChostPulse worker
interval integer 60 Seconds between heartbeats
send-software boolean true Include software name in telemetry
debug boolean false Enable verbose logging

Building from Source

# Clone repository
git clone https://github.com/newlandpe/chost-pulse-pocketmine.git
cd chost-pulse-pocketmine

# Install dependencies
composer install

# Build PHAR
php -dphar.readonly=0 -r "
    \$phar = new Phar('ChostPulse.phar');
    \$phar->startBuffering();
    \$phar->buildFromDirectory('src');
    \$phar->stopBuffering();
"

# Or use DevTools
php -dphar.readonly=0 /path/to/DevTools.phar --make ./ --out ChostPulse.phar

# Clone repository
git clone https://github.com/newlandpe/chost-pulse-bukkit.git
cd chost-pulse-bukkit

# Build with Maven
mvn clean package

Token System

The plugins use a dual-token system:

  • Secret Token (sk_live_<uuid>): Stored in config, used for authentication. Keep it private.
  • Public ID (srv_pub_<hash>): Derived from secret token, safe to share publicly.

The public ID is generated by SHA-256 hashing the UUID portion of the secret token.

Troubleshooting

Heartbeat Failed

  • Verify your API URL is correct and accessible
  • Check internet connectivity on the server
  • Enable debug: true in config for detailed logs

Invalid Token

  • Delete the config file and restart the server
  • A new token will be generated automatically

Badge Not Updating

  • Badges expire after 5 minutes (TTL)
  • Ensure heartbeats are being sent successfully
  • Check that the public ID in the badge URL matches your server