EnderTrax

# EnderTrax

A NeoForge mod for Minecraft 1.21.1 that integrates your dedicated server with a [MineTrax](https://github.com/MineTrax/minetrax) web suite installation. It reports server and player statistics to your MineTrax panel in real time and opens a bidirectional command channel so the web panel can interact with your server.

---

## Features

- **Server intelligence** — periodically reports TPS, memory, CPU, uptime, disk space, loaded chunks, and per-dimension world data to MineTrax.
- **Player session tracking** — tracks playtime, AFK time, deaths, kills, blocks mined/placed, items used/crafted/picked up, jumps, PvP damage, and more — all split into per-interval and cumulative counters.
- **Death & PvP reporting** — fires an instant report to MineTrax on every player death or PvP kill, including location, damage source, weapon, and the players involved.
- **Chat forwarding** — relays in-game chat messages to the MineTrax panel in real time.
- **Account linking** — players can run `/link <otp>` in-game to link their Minecraft account to their MineTrax web profile.
- **WebQuery server** — a lightweight TCP socket bridge that lets the MineTrax web panel push commands into your server (broadcast messages, run console commands, check player status, and more).

---

## Requirements

- Minecraft **1.21.1** (NeoForge server)
- NeoForge **21.1.222** or compatible
- Java **21**
- A running [MineTrax](https://github.com/MineTrax/minetrax) web suite instance

---

## Installation

1. Download or build the mod jar.
2. Place it in your NeoForge server's `mods/` folder.
3. Start the server once to generate the config file at `config/endertrax-common.toml`.
4. Stop the server, fill in the config (see below), then start it again.

---

## Configuration

The config file is located at `config/endertrax-common.toml` and is generated automatically on first run.

### Required settings

| Key | Description |
|-----|-------------|
| `apiHost` | Full URL of your MineTrax website, e.g. `https://your-website.com` |
| `apiKey` | API key from your MineTrax server settings page |
| `apiSecret` | API secret from your MineTrax server settings page |
| `serverId` | Server ID from your MineTrax server settings page |

The mod will not report anything until all four of these are set and `enabled = true`.

### Full config reference

| Key | Default | Description |
|-----|---------|-------------|
| `enabled` | `true` | Master switch — set to `false` to disable all reporting |
| `apiHost` | `""` | MineTrax website URL |
| `apiKey` | `""` | API key |
| `apiSecret` | `""` | API secret |
| `serverId` | `""` | Server ID |
| `webqueryHost` | `0.0.0.0` | Host/IP for the WebQuery listener |
| `webqueryPort` | `25569` | Port for the WebQuery listener |
| `enableServerIntel` | `true` | Toggle periodic server stats reporting |
| `enablePlayerIntel` | `true` | Toggle player session tracking |
| `enableChatReporting` | `true` | Toggle chat message forwarding |
| `serverIntelIntervalSeconds` | `60` | How often to report server stats (10–3600 s) |
| `playerIntelIntervalSeconds` | `300` | How often to flush player session data (30–3600 s) |

### Example config

```toml
[general]
    enabled = true
    apiHost = "https://your-website.com"
    apiKey = "your-api-key-here"
    apiSecret = "your-api-secret-here"
    serverId = "1"

    webqueryHost = "0.0.0.0"
    webqueryPort = 25569

    enableServerIntel = true
    enablePlayerIntel = true
    enableChatReporting = true

    serverIntelIntervalSeconds = 60
    playerIntelIntervalSeconds = 300
```

---

## WebQuery

The WebQuery system is a TCP socket server (default port `25569`) that allows your MineTrax web panel to push commands into the server in real time. All traffic is AES-CBC encrypted and HMAC-SHA256 signed using your `apiKey` and `apiSecret`.

**Make sure port `25569` is open in your firewall** if MineTrax is hosted on a separate machine.

Supported inbound commands from MineTrax:

| Command | Description |
|---------|-------------|
| `ping` | Returns online/max player counts |
| `status` | Returns the full online player list |
| `broadcast` | Broadcasts a message to all players |
| `user-say` | Broadcasts a message as a web user |
| `command` | Runs a console command |
| `check-player-online` | Checks if a player is currently online |
| `account-link-success` | Marks a player's account as linked |

---

## Commands

| Command | Permission | Description |
|---------|------------|-------------|
| `/link <otp>` | All players | Links your Minecraft account to your MineTrax web profile using the OTP from the website |

---