---

🧠 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 Spigot as its primary platform, 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.

• Configurable Logout Actions — choose KILL, PUNISH, or BOTH when a tagged player disconnects
• Natural Item Drops — the combat logger's inventory drops at their exact location for the victor to collect
• Punishment Engine — apply BAN, TEMPBAN, WARN, or NONE as your server policy dictates. Tempban durations are fully configurable (10m, 1h, 1d)
• Grace Period Protection — newly joined players are immune to combat tagging for a configurable window (default 5 seconds), preventing spawn-kill abuse
• Command Interception — 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 breaks and places independently — toggle each action in config
• Material filter system — 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.

• Zero blocking main thread — all file I/O is exclusively asynchronous
• ConcurrentHashMap for combat sessions — thread-safe with no lock contention
• EnumSet for container type lookups — fastest possible enum membership check
• Per-player rate limiters — O(1) map lookup with lazy second-window cleanup
• distanceSquared for all radius checks — eliminates sqrt overhead
• Dynamic listener registration — explosion listener only registered in PRIVATE_SMP mode
• Single tick task 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.

---