SimpleLogs

---

🧠 What is SimpleLogs?

SimpleLogs is a production-grade server administration plugin built around a single philosophy: your server should know exactly what happened, when it happened, and who did it — without ever sacrificing performance.

From combat loggers to base griefers, chest thieves to suspicious explosions, SimpleLogs captures everything silently in the background using fully asynchronous I/O, smart rate limiting, and efficient data structures. No chunk scanning. No blocking operations. No compromise.

Built from the ground up for Paper compatibility, with full Paper compatibility out of the box.

---

⚔️ Combat Logging Prevention

Stop players from escaping fights unfairly. SimpleLogs tags both players the moment PvP begins and holds that tag until the combat timer expires.

- Combat Feedback — choose `KILL`, `PUNISH`, or `BOTH` when a tagged player disconnects - Combat Feedback — the combat logger's inventory drops at their exact location for the victor to collect - Combat Feedback — apply `BAN`, `TEMPBAN`, `WARN`, or `NONE` as your server policy dictates. Tempban durations are fully configurable (`10m`, `1h`, `1d`) - Combat Feedback — newly joined players are immune to combat tagging for a configurable window (default 5 seconds), preventing spawn-kill abuse - Combat Feedback — whitelist/blacklist engine blocks escape commands like `/spawn`, `/tp`, `/home` while always allowing chat commands like `/msg` and `/reply`. Fully configurable, bypass permission supported - Combat Feedback — ActionBar or BossBar timer display with configurable colors, styles, and formats. Combat-start sound plays once on entry (default: Ender Dragon growl). All UI elements are individually toggleable

---

💣 Explosion Forensic System

*Running a Private SMP? Ever needed to prove exactly who blew up someone's base?*

Activate `PRIVATE_SMP` mode to enable the full explosion forensics engine. Every detonation is captured as a timestamped forensic report containing everything you need for a thorough investigation.

Tracked explosion types: - TNT ignitions (with source player detection) - Bed detonations in the Nether and End - End Crystal explosions - Respawn Anchor misuse

Every report includes: - Explosion type and exact coordinates - Triggering player (or `UNKNOWN` if undetectable) - Full snapshot of all online players — names, worlds, and coordinates at the exact moment of detonation - Nearby suspects highlighted with precise block distance - Multi-timezone timestamps (IST, CET, EST, PST)

Anti-lag system built in — per-second rate limiting, per-location cooldowns, and automatic disabling under extreme spam (configurable threshold) ensure TNT machines and raid farms never degrade your TPS.

> *Radius calculations use `distanceSquared` exclusively for suspect detection — no square root overhead on the main thread.*

---

🧱 Block Logging

Track every block interaction across your server with surgical precision.

- Logs Per-player rate limiter and Per-player rate limiter independently — toggle each action in config - Per-player rate limiter — choose `BLACKLIST` mode to ignore junk blocks (dirt, stone, gravel, sand, leaves — 40+ defaults included) or `WHITELIST` mode to log only specific blocks you care about - Per-player rate limiter — configurable max events per second per player. Farms and mining machines never flood your logs - `GLOBAL` mode (single file) or `PER_PLAYER` mode (one file per player) - Query with `/sl blocklogs <player>` - Bypass permission for trusted staff or automated accounts

---

📦 Container Interaction Logging

Know exactly who opened what, and who took or placed what items.

Tracked containers: Chest, Barrel, Shulker Box, Hopper, Dropper, Dispenser, Furnace, Blast Furnace, Smoker, Brewing Stand

Tracked interactions: - `OPEN` — player opened the container - `TAKE` — player removed items (direct click, shift-click, partial pickup) - `PUT` — player placed items (direct placement, shift-click from inventory)

Null items and AIR are automatically ignored. Shift-click direction is correctly resolved — no duplicate logs, no missed interactions.

Per-player rate limiter and bypass permission included. `GLOBAL` or `PER_PLAYER` storage. Query with `/sl containerlogs <player>`.

---

🔍 Admin Investigation Tools

The most powerful feature of SimpleLogs 2.0 — a unified investigation command that aggregates data from every log system simultaneously. /sl investigate <player> /sl investigate <player> combat /sl investigate <player> blocks /sl investigate <player> containers /sl investigate <player> all

Running `/sl investigate <player>` fires three parallel async reads across combat logs, block logs, and container logs simultaneously. Results merge on the main thread and render as a single color-coded report — no waiting, no blocking, no lag.

- Combat entries shown in red - Block breaks in red, places in green - Container takes in red, puts in green, opens in gray - Configurable max entries per system - Fully async — the main thread is never touched during disk reads

---

⚙️ Smart Server Mode System

SimpleLogs adapts to your server type automatically.

| Mode | Behavior | |---|---| | `UNSET` | Prompts the first OP to join with clickable setup buttons | | `PRIVATE_SMP` | Full feature set — all logging systems active including explosion forensics | | `PUBLIC` | Lightweight mode — explosion forensics disabled for maximum performance |

Switch modes instantly with `/sl setmode private` or `/sl setmode public`. No restart required.

---

📜 Commands & Permissions

| Command | Description | Permission | |---|---|---| | `/sl reload` | Reload configuration | `simplelogs.reload` | | `/sl setmode <private|public>` | Set server mode | OP | | `/sl history <player>` | View combat log history | `simplelogs.history` | | `/sl explosions` | View recent explosions | `simplelogs.explosions` | | `/sl blocklogs <player>` | View block log history | `simplelogs.blocklogs` | | `/sl containerlogs <player>` | View container log history | `simplelogs.containerlogs` | | `/sl investigate <player> [filter]` | Full investigation report | `simplelogs.investigate` |

Bypass permissions: - `simplelogs.bypass` — bypass combat command restrictions - `simplelogs.blocklog.bypass` — exclude from block logging - `simplelogs.containerlog.bypass` — exclude from container logging

---

```

📂 Log File Structure

All logs are stored under `/plugins/SimpleLogs/`: SimpleLogs/ ├── CombatlogPlayers/ │ └── combat_log.txt (or <PlayerName>.txt in PER_PLAYER mode) ├── ExplosionLogs/ │ └── explosions.txt ├── BlockLogs/ │ └── block_log.txt (or <PlayerName>.txt) └── ContainerLogs/ └── container_log.txt (or <PlayerName>.txt) ```

All log entries are human-readable plain text with multi-timezone timestamps.

---

⚡ Performance Architecture

SimpleLogs was designed with performance as a first-class requirement — not an afterthought.

- In-memory ring buffer — all file I/O is exclusively asynchronous - In-memory ring buffer for combat sessions — thread-safe with no lock contention - In-memory ring buffer for container type lookups — fastest possible enum membership check - In-memory ring buffer — O(1) map lookup with lazy second-window cleanup - In-memory ring buffer for all radius checks — eliminates sqrt overhead - In-memory ring buffer — explosion listener only registered in PRIVATE_SMP mode - In-memory ring buffer for all combat expiration and UI updates — no per-player schedulers - In-memory ring buffer for recent explosions — `/sl explosions` never reads from disk

---

📊 bStats Analytics

SimpleLogs collects anonymous server statistics via bStats (Plugin ID: `30642`). Tracked metrics: server mode distribution. Can be disabled in the bStats global config.

---