Skip to main content

KnotLink and Integration Mod

MineRewind's hot backup/restore depends on KnotLink transport plus an integration mod.

If you want the user-facing installation and command walkthrough for the MineBackup mod first, read MineBackup Integration Mod Deep Dive. This page focuses on protocol commands and event-level integration.

Source mapping​

CapabilityCore methodsLocation
Command definitionsGetKnotLinkCommandDefinitions()MinecraftSavesPlugin.KnotLink.cs
Command dispatchTryHandleKnotLinkCommandAsync(...)MinecraftSavesPlugin.KnotLink.cs
Handshake response handlerHandleHandshakeResponseAsync(...)MinecraftSavesPlugin.KnotLink.cs
World-saved signalHandleWorldSavedAsync(...)MinecraftSavesPlugin.KnotLink.cs
Save-exit complete signalHandleWorldSaveAndExitCompleteAsync(...)MinecraftSavesPlugin.KnotLink.cs
Rejoin result signalHandleRejoinResultAsync(...)MinecraftSavesPlugin.KnotLink.cs

Required setup​

  • FolderRewind + MineRewind (host version compatible)
  • Integration mod that supports handshake/save/rejoin events
  • Working KnotLink service

Command matrix (external -> MineRewind)​

CommandArgsMeaningTypical response
BACKUP_CURRENTOptional noteBackup current active worldOK:Backup started...
LIST_BACKUPS_CURRENTNoneList backups of current worldOK:file1;file2;...
RESTORE_CURRENT_LATESTNoneHot restore to latest backupOK:Hot restore triggered...
RESTORE_CURRENTbackup_fileHot restore to specified backupOK:Hot restore triggered...

If no active world or missing args, responses usually start with ERROR:.

Event protocol (MineRewind -> external)​

  • event=handshake: handshake + version negotiation
  • event=pre_hot_backup: request save before backup
  • event=pre_hot_restore: request save-and-exit before restore
  • event=restore_finished: restore stage result
  • event=rejoin_world: request world rejoin
  • event=hot_restore_complete: final chain status

Callback commands (external -> MineRewind)​

These are usually sent back by the integration mod:

  • HANDSHAKE_RESPONSE <mod_version>
  • WORLD_SAVED
  • WORLD_SAVE_AND_EXIT_COMPLETE (or alias SHUTDOWN_WORLD_SUCCESS)
  • REJOIN_RESULT <success|failure> [reason]

Minimal integration test script​

  1. Send BACKUP_CURRENT to verify shortest path.
  2. Send LIST_BACKUPS_CURRENT to verify query path.
  3. Send RESTORE_CURRENT_LATEST to verify hot restore main chain.
  4. Verify precise restore via RESTORE_CURRENT <backup_file>.

Compatibility points​

  • Plugin enforces minimum mod version checks
  • Handshake failure leads to fallback or cancellation
  • Unified response prefixes OK: / ERROR: are recommended

Handshake payload contains min_mod_version; record it explicitly on integration side for easier diagnostics.

Practical recommendations​

  • Start with BACKUP_CURRENT to verify shortest chain first
  • Then test RESTORE_CURRENT_LATEST end-to-end
  • Run LIST_BACKUPS_CURRENT before specified restore

Request/response examples​

Example 1: list backups​

Request:

LIST_BACKUPS_CURRENT

Response:

OK:world_2026-02-27_19-00.7z;world_2026-02-28_09-30.7z

Example 2: handshake callback​

Request:

HANDSHAKE_RESPONSE 1.2.0

Response:

OK:Handshake received. Version 1.2.0 (compatible)