Reference

DH Snapshot

Stages a snapshot of the server's Distant Horizons data, stopping a running server for the copy.

Category
Action
Topics
Scheduler ยท Distant Horizons
01

Ports

DH Snapshotaction
  • triggercontrol
  • onCompletecontrol
  • onFailedcontrol
  • Staged folderstring
  • Bytes changednumber
  • Parts changednumber
  • Parts in allnumber
  • Downtime (s)number
Ports Control Data
Data types string number bool

Strings accept any data input.
Numbers accept boolean input.

02

Fields

Field What it does Default Limits
Destination of the last snapshot The bucket of the last published snapshot, which says which parts are already uploaded. None Optional; if set, must name a saved destination.
Key prefix Text added to the destination's key prefix when looking for the last snapshot. None No . or .. segments.
Staging folder (default: in the app data folder) The folder the snapshot is staged in, empty for this server's own folder in the app data folder. None An absolute path outside the server's folder.
Warn players this many seconds before How long before the stop the players are warned. 300 A whole number from 0 to 1800 s; 0 sends no warning.
Warning ({time} is the time left) The warning the players read, where {time} becomes the time left. The server will stop in {time} for a world snapshot and be back shortly. None
03

What a run does

The block holds this server's snapshot claim for the whole run.
A snapshot or publish already running for the server fails it.
Parts are slices of the databases, named by their hash.

  1. Checks the lead time, the Distant Horizons config, its jar, its databases and the free space.
  2. Reads the previous snapshot: the destination's latest.json, or the index.json already in the staging folder.
  3. Warns the players in chat at the lead time, and again at 1 minute and 10 seconds when the lead time is longer.
  4. Stops the server, waiting up to the Stop grace period from Settings.
  5. Reads each dimension's database and stages the parts the previous snapshot lacks, then writes index.json.
  6. Starts the server again, whether or not the copy worked.
  7. Removes staged parts the new snapshot no longer needs.

The warning goes over RCON, or through the server console when RCON is not confirmed.
A warning that cannot be sent stops the run with the server still up.
A server that is already stopped is copied as it is, nobody is warned, and it stays stopped.

It leaves by onComplete when the snapshot is staged, and by onFailed on any error.
Staged folder, Bytes changed, Parts changed and Parts in all are set after a successful run.
Downtime (s) is set whenever the server was stopped, even if the run failed.
Progress and failures appear in the server's console.
The block can run for up to 3 hours.

04

Errors

Message says Do
destination validation failed: DH Snapshot (node): the destination "name" does not exist. It was deleted or renamed in Settings, or this graph came from another install. Pick a destination that exists, or clear the field.
no DistantHorizons.sqlite found under world folder Let Distant Horizons create its data in the world first.
neither RCON nor the server's console can carry the warning, so the players could not be told before the stop: enable RCON (enable-rcon in server.properties) or start the server from Konnekt Enable RCON, start the server from Konnekt, or set the lead time to 0.
cannot read the previous snapshot from destination: reason Check the destination and the network, then run it again.
could not warn the players, so the server was not stopped: reason Check RCON and the console; the server was left running.
could not stop the server: reason Check the server's state, then run it again.
copying the databases failed: reason Read the reason; the server was started again.
the snapshot was staged, but the server could not be started again: reason Start the server by hand.
key prefix "prefix" must not contain "segment" Remove the . or .. segment from the prefix.
timed out after 10800s: reason Run it again; the server is started again when the copy stops.