Simplex Trimmer

Safe, focused world trimming for Paper — with Java menus, optional Bedrock forms and startup-only maintenance

Simplex Trimmer 12.1.2 is a standalone world-maintenance plugin for Paper servers. It lets administrators select individual dimensions, choose an InhabitedTime threshold, schedule a maintenance countdown, run MCA Selector during the next full server startup, and review how much disk space was reclaimed afterward.

No SimplexAdminSuite dependency. No built-in telemetry. Java inventory menus included. Optional native Bedrock forms through Floodgate.

⚠️ This plugin permanently deletes selected chunk data. Always create a complete, usable backup before trimming.

---

🛡️ Startup-only trimming

SimplexTrimmer 12 replaces the old live-world maintenance approach with a safer startup workflow:

1. Open /trimworld and select the dimensions you want to process.
2. Choose an activity threshold and maintenance countdown.
3. Confirm that you already have a complete backup.
4. SimplexTrimmer stores a one-shot maintenance job.
5. The plugin requests a normal server stop/restart.
6. On the next full startup, the queued trim runs before normal world loading continues.
7. MCA Selector processes the selected targets locally.
8. When maintenance finishes, normal startup continues and the result is written to history.

The default STOP mode is intended for hosting panels. Your panel must start the server again after shutdown. Optional RESTART mode delegates to Spigot's configured restart mechanism.

If Bukkit does not begin a normal shutdown within the configured timeout, SimplexTrimmer prints a clear SERVER STOP REQUIRED message so you know to stop the server manually. The queued job remains saved for the next full startup.

---

📊 Live MCA Selector console progress

During startup trimming, SimplexTrimmer captures MCA Selector's terminal progress and converts it into clean English server-console messages.

Progress lines can include:

• Active world or dimension
• Percentage complete
• Current/maximum region counter when available
• Current .mca region file when available
• Reclaimed disk space after a target finishes
• Elapsed time

Example:

[MCA Selector 1/3] world | 12% | 24/200 regions | r.-3.2.mca
[MCA Selector 1/3] world | 42% | 84/200 regions | r.-2.5.mca
[MCA Selector 1/3] world | 100% | 200/200 regions | r.4.3.mca
[Trim 1/3] Completed | world | Reclaimed: 6.81 GiB | Elapsed: 2m 14s

Repeated terminal redraws are suppressed so your console stays readable. The full raw MCA Selector output is still stored in plugins/SimplexTrimmer/data-v12/logs/ for troubleshooting.

---

✨ Features

• Standalone plugin: focused only on world trimming and maintenance.
• English interface: Java menus, Bedrock forms, command feedback, console messages, default maintenance messages and documentation are all English.
• Java inventory GUI: configure targets, thresholds, countdowns, confirmations and history without editing files manually.
• Optional Bedrock GUI: native Floodgate/Cumulus forms for Bedrock players; Floodgate is not required for Java-only servers.
• Per-dimension targeting: Overworld, Nether, End and discovered custom dimensions can be selected separately.
• Legacy + modern world discovery: supports classic region, DIM-1, DIM1, split Bukkit worlds and namespaced dimensions/<namespace>/<dimension> layouts.
• Explicit MCA Selector paths: terrain, POI and entity directories are supplied separately when available.
• Safer path handling: automatic discovery rejects unsafe symbolic-link targets and skips common backup/archive locations.
• Additional world roots: explicitly add offline/custom roots with world-trimmer.additional-world-roots.
• Persistent administrator sessions: selected dimensions and settings survive normal usage.
• Persistent maintenance jobs: queued and archived jobs are stored under data-v12/.
• Recovery mode: failed/interrupted jobs require administrator review instead of being treated as successful.
• History: keeps before/after sizes, reclaimed space, status and per-target information.
• World locking: prevents destructive processing of worlds that are genuinely locked by another process.
• Process supervision: an external guard supervises the MCA Selector child process and prevents duplicate trimmer guards.
• Preflight validation: checks targets, MCA Selector state, Java compatibility and available disk space before maintenance begins.
• Verified MCA Selector updater: downloads from the official Querz/mcaselector GitHub release and verifies the published SHA-256 digest before installation.
• Configurable performance: dedicated MCA Selector heap, process-thread cap and timeout.
• Countdown controls: immediate, 1-minute, 3-minute and 5-minute starts with public warnings, titles, sounds and cancellation.
• No built-in telemetry: no bStats module, Discord integration or world upload service.

---

🎮 Java + Bedrock administration

Java players use the inventory interface automatically.

When Floodgate is installed and a Floodgate player opens SimplexTrimmer, the plugin can use native Bedrock forms for:

• Dimension selection
• Threshold/settings controls
• Backup confirmation
• Maintenance start confirmation
• History
• Countdown cancellation
• Recovery actions

Geyser/Floodgate must be installed and configured separately. SimplexTrimmer does not bundle either project.

---

⏱️ Activity thresholds

SimplexTrimmer removes chunks based on Minecraft's accumulated InhabitedTime value.

Preset	Ticks	Notes
30 seconds	600	Lowest preset, still potentially destructive
1 minute	1,200	More chunks become eligible
3 minutes	3,600	Aggressive
5 minutes	6,000	Very aggressive
10 minutes	12,000	Extremely aggressive

Custom values are available with:

/trimworld ticks <20-1728000>

The filter is strictly:

InhabitedTime < threshold

Chunks with InhabitedTime exactly equal to the configured threshold are retained.

InhabitedTime is not a building or claim detector. A rarely visited base, pasted structure, claim, spawn area or newly built location can still have a low value.

---

🧰 Commands

Command	Purpose
/trimworld	Open the automatic Java/Bedrock menu
/trimworld java	Force the Java inventory menu
/trimworld scan	Refresh discovered dimensions and sizes
/trimworld update	Download and verify the latest supported official MCA Selector release
/trimworld ticks <20-1728000>	Set a custom activity threshold
/trimworld clear	Clear your selected dimensions
/trimworld history	Open saved trim history
/trimworld status	Show current maintenance state; console supported
/trimworld cancel	Cancel an active maintenance countdown
/trimworld recovery CONFIRM	Release recovery after manual inspection
/trimworld reload	Reload configuration while idle

Permission: trimmer.admin — defaults to OP.

Aliases: /simplextrimmer, /strimmer

---

🔒 Safety & recovery

SimplexTrimmer uses world/session locks during startup maintenance. Paper may already hold a world's session.lock inside the same JVM during early startup; current releases recognize that protected same-process state correctly while still rejecting a lock owned by another process.

If a trim is interrupted or fails after destructive work may have started, SimplexTrimmer enters recovery mode. Normal players are blocked until an administrator reviews the job.

There is no automatic rollback. Always inspect the raw logs and restore your backup if necessary before releasing recovery.

The only automatic retry exception is the specifically recognized preflight-only session.lock failure produced by SimplexTrimmer 12.1.0, and only when no trim target had started.

---

⚠️ Read before trimming

• Make a complete backup before every trim.
• SimplexTrimmer confirms that you say a backup exists; it does not create or validate that backup.
• Do not force-stop the server or MCA Selector while destructive processing is active.
• If a run fails, earlier dimensions may already have been modified.
• Deleted chunks can regenerate later when players revisit them.
• Regenerated terrain can differ after Minecraft updates, datapack changes or generator changes.
• There is no automatic Lands, WorldGuard, GriefPrevention, claim, spawn or building protection.
• Disk-space savings depend entirely on your world and selected threshold. No percentage is guaranteed.

---

✅ Requirements & compatibility

• Server: Paper or a compatible Paper-derived server with the required Bukkit/Paper APIs.
• MCA Selector: version 2.9 or newer for the current workflow.
• Java for MCA Selector 2.9: Java 21 or newer.
• Plugin bytecode: Java 17 target; your Minecraft/Paper server may require a newer Java version, which takes precedence.
• Floodgate: optional; only required for native Bedrock forms.
• Geyser: optional and installed separately when Bedrock players connect to the Java server.

Not supported as trimming targets:

• Folia
• Fabric
• Forge
• Proxy-only environments
• Native Bedrock LevelDB worlds

Bedrock players are supported through a Java Paper server using Geyser/Floodgate; SimplexTrimmer does not edit native Bedrock world databases.

---

🚀 Quick start

1. Stop the server and create a complete backup.
2. Remove older SimplexTrimmer JARs.
3. Install SimplexTrimmer-12.1.2.jar.
4. Start the server normally.
5. Run /trimworld as OP or with trimmer.admin.
6. Use Update MCA Selector to install/verify the official tool.
7. Select the dimensions you want to process.
8. Choose the InhabitedTime threshold and countdown.
9. Confirm that your backup exists.
10. Start maintenance.
11. Allow the server to stop normally.
12. Let your hosting panel/restart script start it again, or start it manually if required.
13. Watch the live trim progress in the server console during startup.
14. Review the final result in SimplexTrimmer history.

Do not use /reload as a substitute for a full maintenance restart.

---

🔧 Configuration & data

Version 12 operational data is stored under:

plugins/SimplexTrimmer/data-v12/

This includes the MCA Selector tool state, queued/archived jobs, logs, history, sessions and runtime state.

Existing v11 state is not automatically migrated into data-v12/. Bukkit also keeps an existing config.yml when you update the plugin, so newly introduced options use their built-in defaults until you add them to your configuration.

Useful configuration options include:

world-trimmer:
  restart-mode: STOP
  shutdown-warning-seconds: 30
  default-threshold-ticks: 600
  minimum-threshold-ticks: 20
  history-limit: 100
  additional-world-roots: []
  performance:
    heap: 2G
    process-threads: 2
    timeout-minutes: 120
  preflight:
    minimum-free-space-gib: 2

---

🔄 Upgrading from SimplexTrimmer 11.x

The supplied legacy 11.0-ULTIMATE build used a different workflow: it entered maintenance while the server was already running, kicked players, disabled autosave, saved/unloaded chunks, executed MCA Selector and then attempted a server restart.

Version 12.1.2 intentionally replaces that design with queued, startup-only processing, persistent job state, stronger path/lock validation, recovery handling and a supervised external MCA Selector process.

When upgrading:

• Remove the old JAR.
• Keep your backup.
• Do not copy old runtime/state files into data-v12/.
• Reinstall/update MCA Selector through the new interface.
• If you also use a SimplexAdminSuite build containing its own trimmer module, disable the duplicate trimmer there.

---

Credits & external tool

World editing is performed locally by MCA Selector, created by Querz and contributors:

https://github.com/Querz/mcaselector

MCA Selector is downloaded separately from its official GitHub release and is not bundled in SimplexTrimmer.

Your Minecraft world data is processed locally on your server and is not uploaded by SimplexTrimmer to an external trimming service.