StaffLens

StaffLens is a moderation audit plugin for Paper 1.21 servers.

The plugin records staff moderation and administration actions, stores them in SQLite or MySQL, and allows quick access through commands. Both built-in commands and supported plugin integrations are logged.

---

Features

• Log staff actions into a database
• View history by staff member
• View actions performed on a specific player
• Search through the moderation log
• View actions performed today
• Export history to a text file
• In-game notifications for critical actions
• Reload configuration without restarting the server

---

Logged Actions

The plugin can record:

• ban, unban, mute, unmute, kick, warn
• giving and removing OP
• permission/group changes
• teleports and staff movement
• fly, god, vanish, socialspy
• inventory and ender chest inspection
• giving items, clearing inventory, heal, feed, repair
• jail, unjail, nick, sudo, broadcast
• lookup commands such as seen and history
• gamemode changes

The exact list of logged actions is defined in the code through ActionType.

---

Supported Integrations

• Vanilla
• LiteBans
• BanManager
• AdvancedBan
• Essentials
• CMI
• LuckPerms

Each integration can be enabled or disabled in the configuration.

---

Requirements

• Java 21
• Paper 1.21.x

---

Installation

1. Build the plugin JAR.
2. Place it in the plugins folder.
3. Start the server.
4. Configure plugins/StaffLens/config.yml.
5. Run /sl reload if needed.

---

Database

Supported databases:

• SQLite
• MySQL

SQLite is used by default.

---

SQLite Setup

No additional setup is required. The database will be automatically created in the plugin folder.

---

MySQL Setup

Configure the following values in config.yml:

database.type: mysql
database.mysql.host
database.mysql.port
database.mysql.database
database.mysql.username
database.mysql.password

The table and indexes are created automatically on startup.

---

Commands

Main command:

/stafflens
/sl

Subcommands:

/sl log <player> [page]      - view actions performed by a staff member
/sl who <player> [page]      - view actions performed against a target player
/sl search <text> [page]     - search the log
/sl today [page]             - view actions performed today
/sl export <player>          - export a player's history to a file
/sl reload                   - reload configuration and integrations

---

Permissions

stafflens.use

Allows viewing logs.

stafflens.export

Allows exporting logs.

stafflens.admin

Allows using /sl reload.

stafflens.notify

Receive notifications about critical actions.

All permissions are granted to OP by default.

---

Configuration

File: plugins/StaffLens/config.yml

locale: en

database:
  type: sqlite
  mysql:
    host: localhost
    port: 3306
    database: minecraft
    username: root
    password: ""

log:
  retention-days: 90
  page-size: 15

notify:
  critical-actions:
    - OP_GIVE
    - PERMISSION_ADD
    - GROUP_ADD

integrations:
  LiteBans: true
  BanManager: true
  AdvancedBan: true
  Essentials: true
  CMI: true
  LuckPerms: true
  Vanilla: true

---

Configuration Options

• locale — language used for messages
• database.type — database type (sqlite or mysql)
• log.retention-days — how long logs are stored (in days)
• log.page-size — number of entries per page in commands
• notify.critical-actions — actions that trigger notifications
• integrations.* — enable or disable specific integrations

---

Localization

Localization files are located in the locale folder:

• en.yml
• ru.yml
• ua.yml

The language is selected using the locale setting in the configuration.

---

Export

The command

/sl export <player>

creates a text file in:

plugins/StaffLens/exports

The file contains:

• generation time
• list of actions
• target player
• reason
• additional details

---

Notifications

If an action is listed in notify.critical-actions, players with the permission:

stafflens.notify

will receive an in-game notification.

---

Log Storage

When the plugin starts, it removes records older than retention-days.

Indexes are automatically created for SQLite and MySQL to improve query performance.

When the plugin reloads, it waits for the logging queue to finish before closing the database connection.