AstroAutoSave Documentation

Requirements: Paper, Purpur, or Folia server running Minecraft 1.20+. Java 21+.

Default (every 5 minutes, with warning)

Drop-in replacement for vanilla autosave with a visible warning.

interval-seconds: 300
warning-seconds-before: 10
broadcast-warning: "&e[Server] &7Saving in 10 seconds..."
broadcast-complete: "&a[Server] &7Save complete (%duration%ms)"
broadcast-complete-enabled: true
silent-mode: false

Quiet mode for SMP

Save every 5 minutes but no broadcast — only logged to console.

interval-seconds: 300
warning-seconds-before: 0
silent-mode: true

Aggressive saves for unstable hosting

Save every 2 minutes if you suspect your host crashes often.

interval-seconds: 120
warning-seconds-before: 5
broadcast-warning: "&e[Save] &7Backup point in 5s"
broadcast-complete-enabled: false

Slow-save for huge worlds

On a server with a 50GB world, you want sparse saves.

interval-seconds: 1800  # 30 minutes
warning-seconds-before: 30
broadcast-warning: "&e[Server] &7Saving in 30 seconds. Brief lag possible."
broadcast-complete: "&a[Server] &7Save done (%duration%ms)"
worlds:
  - world
  - world_nether
  - world_the_end
  # Specify worlds explicitly to save only what matters

Config location

Coordinate auto-save with external backup script

Scenario: You run rsync backups every hour at :00. You want the auto-save to fire at :55 so backups capture a fresh world.

1. Set 'interval-seconds: 3600' (one save per hour).
2. Set 'start-offset-seconds: 3300' so first save is 55 minutes after server start, then every hour.
3. Schedule rsync at :00 (after the :55 save completes).
4. Test: watch logs to confirm save fires at :55 every hour.

Silent saves during event hours

Scenario: You host a PvP event every Saturday. You do not want save broadcasts spamming the event chat.

1. Before event: /autosave silent on (runtime override).
2. After event: /autosave silent off.
3. Or schedule via crontab to flip the config silent-mode value and /autosave reload.

Disable vanilla autosave but keep AstroAutoSave

Scenario: You want exactly one autosave path so you can debug performance.

1. In bukkit.yml, set 'ticks-per: autosave: 0' (disables vanilla autosave).
2. AstroAutoSave runs on its own scheduler — no conflict.
3. Verify by watching server.log: should only see AstroAutoSave's save messages, no Bukkit-generated ones.

Force a save before world reset

Scenario: You reset a competitive world every Monday morning. You want a save right before the reset for backup.

1. Schedule a cron job that runs Sunday 23:55: /autosave now via console.
2. Plugin executes a save synchronously (or with the standard async write depending on flag).
3. Followed by your world-reset script Monday 00:00.

Tip: Use LuckPerms to manage permissions per player or group.

ChunkMaster / FastChunkPregenerator

Chunk generators put heavy load on disk during pregen. Pair AstroAutoSave with a longer interval (interval-seconds: 1800) during pregen to avoid concurrent writes.

PlugMan / PlugManX

If you reload AstroAutoSave with /plugman reload AstroAutoSave, the scheduled tasks are cancelled and re-registered. Safer than full /reload.

EssentialsX

EssentialsX's /save-all is independent. AstroAutoSave's save runs Bukkit's saveAll() under the hood, so they are equivalent. No conflict.

CoreProtect

CoreProtect logs to its own database; AstroAutoSave does not touch it. No conflict.

Save broadcasts fire but world files do not update

Cause: World write-protection (filesystem read-only) or insufficient disk space.

Fix:

• Check df -h to confirm disk space.
• Check the world directory permissions: 'ls -la world/region/'.
• Look in the server log for 'World save failed' errors.
• Restart the server to re-mount the world directory if it is a symlink.

Save takes 30+ seconds and lags the server

Cause: Huge world, slow disk, or another plugin holding the world lock.

Fix:

• Move world data to an SSD if not already.
• Reduce the number of loaded chunks via Paper's view-distance / simulation-distance.
• Set 'use-paper-async-save: true' if running Paper 1.20+ — saves run off the main thread.
• Disable chunk pregeneration during peak hours.

Configured 5-minute interval but saves are happening every minute

Cause: Vanilla auto-save is still enabled and overlapping.

Fix:

• Set 'ticks-per: autosave: 0' in bukkit.yml.
• Or set vanilla autosave to a very high value like 72000 (1 hour) so AstroAutoSave's 5-minute interval is the dominant trigger.

No broadcast despite broadcast-warning being set

Cause: silent-mode is true, or a chat plugin is filtering the message.

Fix:

• Check 'silent-mode: false' in config.yml.
• Check that no anti-spam plugin is suppressing system messages.
• Run /autosave debug to test the broadcast pipeline.

Does this replace vanilla auto-save or work alongside it?

We recommend disabling vanilla auto-save (set 'ticks-per: autosave: 0' in bukkit.yml) and using AstroAutoSave as the only auto-save path. They can coexist but you will get double saves, which wastes I/O.

Will the save lag the server?

On Paper 1.20+, set 'use-paper-async-save: true' to run saves on a background thread. Lag is minimal (< 5 ticks). On older Paper / Spigot, saves are synchronous and can cause 1-3 second hitches on busy worlds.

How do I save only specific worlds?

Set 'worlds: [world, world_nether]' in config.yml. Default is all loaded worlds. Useful for excluding test worlds or backup worlds.

Can I trigger a save manually?

Yes. /autosave now runs an immediate save. Requires astroautosave.admin permission.

Is the save synchronous or async?

By default, synchronous (same as Bukkit's /save-all). On Paper 1.20+ with 'use-paper-async-save: true', it uses Paper's async save API which is faster.

Does it save player data too or just world data?

Both. Bukkit's saveAll() saves all loaded worlds plus all online player data files. No separate config needed.

What happens if a save fails?

The plugin logs an error and skips that save. The next save fires at the normal interval. If three saves in a row fail, the plugin sends a warning broadcast to ops (astroautosave.alerts permission).

Can I disable the broadcasts but keep the saves?

Yes. Set 'silent-mode: true'. Saves still fire on the schedule, only logged to console.

v1.0.02026-05-13

• Initial public release
• Configurable interval and warning
• Per-world save targeting
• Optional Paper async save
• /autosave now and /autosave reload commands
• astroautosave.admin permission
• Failure broadcast to ops