> ## Documentation Index
> Fetch the complete documentation index at: https://catalyst.leifiyo.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# CatalystAnalytics plugin

> Bundled plugin behavior, data model, configuration, commands, and build notes.

CatalystAnalytics is the bundled Bukkit/Paper-style plugin used by Catalyst for server analytics. Catalyst can install it automatically for Paper and Purpur servers.

## Current integration mode

<Check>
  Catalyst reads the plugin's local `analytics.json` file. No REST API is required for the desktop app integration.
</Check>

The plugin source includes an HTTP API server class, but the current main plugin startup path does not start that server. Treat HTTP endpoints in source as inactive unless the plugin is changed to enable them.

## Files

| File                                            | Purpose                                   |
| ----------------------------------------------- | ----------------------------------------- |
| `plugins/CatalystAnalytics.jar`                 | Plugin JAR copied by Catalyst.            |
| `plugins/CatalystAnalytics/config.yml`          | Tracking and retention configuration.     |
| `plugins/CatalystAnalytics/data/analytics.json` | Combined analytics data read by Catalyst. |

## Tracked data

<Tabs>
  <Tab title="Players">
    UUID, name, online state, first join, last join, join count, playtime, client version, client brand, operating system, chat count, command count, deaths, kills, blocks placed, and blocks broken.
  </Tab>

  <Tab title="Server">
    Current online players, peak online, unique players, total joins, new players, returning players, uptime, current TPS, current MSPT, memory used, and memory max.
  </Tab>

  <Tab title="History">
    Player count timeline, TPS history, MSPT history, memory history, hourly joins, version distribution, client distribution, and operating system distribution.
  </Tab>
</Tabs>

## Configuration highlights

| Setting                            | Default | Meaning                                |
| ---------------------------------- | ------- | -------------------------------------- |
| `data.retention-days`              | `30`    | Number of days to keep analytics data. |
| `data.save-interval-seconds`       | `30`    | How often the plugin saves data.       |
| `collection.tps-interval`          | `60`    | TPS sample interval.                   |
| `collection.memory-interval`       | `60`    | Memory sample interval.                |
| `collection.player-count-interval` | `300`   | Player count sample interval.          |
| `tracking.track-geolocation`       | `false` | Optional IP geolocation tracking.      |

## Commands

```text theme={null}
/analytics status
/analytics reload
```

Permission:

```text theme={null}
catalystanalytics.admin
```

## Build the plugin

From the `catalyst-plugin` folder:

```bash theme={null}
./gradlew jar
```

The project builds a `CatalystAnalytics.jar` artifact under `build/libs/`. The plugin targets Paper-compatible servers and declares `api-version: 1.13`.