vellum is a Minecraft: Bedrock Server (BDS) automation tool primarily made to create incremental (hot-)backups and render interactive maps of your world using PapyrusCS, all while the server is running without any server-downtime using BDS's save hold | query | resume commands.
- Table of contents
- Get started
- Configuration overview
- Parameters & Commands
- Compiling from source
- Disclaimer
Before starting to setting up this tool it is recommended to already have a Bedrock Dedicated Server configured. If you choose not to go with the self-contained release of this tool, you must have the latest .NET Core runtime installed aswell.
First of all grab the latest pre-compiled binary from the releases page (or compile from source). You will find three releases, two of them for Linux with a larger self-contained one which comes bundled with the .NET Core runtime and a smaller archive which depends on you having the .NET Core runtime already installed on your system, as well as a release for Windows.
Download and extract the archive and cd into the directory with the extracted files.
On Linux, you may need to give yourself execution permissions with:
chmod +x ./vellumNow run this tool for the first time by typing:
./vellumThis will generate a new configuration.json in the directory relative to the vellum executable and then exit. Edit this file and specify at least all required parameters (see below for an overview).
Now you can restart vellum once again with the same command as above. It should now spawn the BDS instance for you and perform backups on the specified interval (do not start the server manually). Once the server has launched through this tool you will be able to use the server console and its commands just like you normally would.
To create incremental world backups make sure the CreateBackups option is set to true. Backups will be stored in the directory specified by ArchivePath. This tool will automatically delete the oldest backups in that directory according to the threshold specified by the BackupsToKeep option (-1 to not delete any older archives) to prevent eventually running out of disk space.
Recent backups can be restored using the --restore (or -r) flag, followed by the path to an archive.
After successfully restoring a backup, vellum will start the server like usual. If you do not want the server to automatically start after restoring a backup, specify the --no-start flag.
Usage examples:
# Restore the specified archive from vellums backup directory and start the server
vellum -r "backups/2020-07-30_10-59_MyWorld.zip"
# Restore the specified archive from its absolute path and don't start the server afterwards
vellum -r "/home/server/vellum/backups/2020-07-30_10-59_MyWorld.zip" --no-startThis tool can automatically execute the PapyrusCS map-rendering tool on an interval. To do so you have to set EnableRenders to true and specify an interval in minutes with RenderInterval.
You can add your own arguments that will be attached when PapyrusCS is called. When configuring you will find two keys, PapyrusGlobalArgs and an array called PapyrusTasks. The value in PapyrusGlobalArgs specifies arguments that will be attached for each PapyrusCS task when executed, while PapyrusTasks represent an array of individual processes (or tasks). Adding an entry to the array represents another task that will be executed after the previous one has finished, this way it is possible to make PapyrusCS render multiple dimensions or have different configurations in general. Again, the same PapyrusGlobalArgs will be present for each of these tasks individually.
When specifying additional arguments for PapyrusGlobalArgs please make sure to append to the pre-generated entry (do not edit the -w and -o parameters!).
Please thoroughly verify that your paths and arguments are correct, you can find a configuration-example here.
When you run this tool for the first time, it will generate a configuration.json and terminate. Before restarting the tool, edit this file to your needs. Here is a quick overview:
KEY VALUE ABOUT
----------------------------------------------------------
REQUIRED SETTINGS
-----------------
BdsBinPath String (!) Absolute path to the the Bedrock Server
executable (similar to "/../../bedrock_server"
on Linux or "/../../bedrock_server.exe" on
Windows)
WorldName String (!) Name of the world located in the servers
/worlds/ directory (specify merely the name and
not the full path)
---------------
BACKUP SETTINGS
---------------
EnableBackups Boolean (!) Whether to create world-backups as .zip-archives
EnableSchedule Boolean (!) Whether to enable scheduled backups. If set to "false",
backups will be performed on the interval specified by
"BackupInterval".
Schedule String [Array] An array of clock times (in 24h format) where scheduled
backups should be performed (see the example configuration
below for formatting).
BackupInterval Double Time in minutes to take a backup and create a
.zip-archive
ArchivePath String Path where world-backup archives should be
created
BackupsToKeep Integer Amount of backups to keep in the "ArchivePath"-
directory, old backups automatically get deleted
OnActiviyOnly Boolean If set to "true", vellum will only perform a
backup if at least one player has connected
since the previous backup was taken, in order to
only archive worlds which have actually been
modified
StopBeforeBackup Boolean Whether to stop, take a backup and then restart
the server instead of taking a hot-backup
NotifyBeforeStop Integer Time in seconds before stopping the server for a
backup, players on the server will be
notified with a chat message
BackupOnStartup Boolean Whether to create a full backup of the specified
world before starting the BDS process
IMPORTANT: It is highly encouraged to leave
this setting on "true"
PreExec String An arbitrary command that gets executed before
each backup starts
PostExec String An arbitrary command that gets executed after
each has finished
---------------
RENDER SETTINGS
---------------
EnableRenders Boolean (!) Whether to create an interactive map of the world
using PapyrusCS
PapyrusBinPath String Absolute path to the papyrus executable (similar
to "/../../PapyrusCs" on Linux or
"/../../PapyrusCs.exe" on Windows)
PapyrusOutputPath String Output path for the rendered papyrus map
RenderInterval Double Time in minutes to run a backup and render map
PapyrusGlobalArgs String Global arguments that are present for each
rendering task specified in the "PapyrusArgs"-
array
IMPORTANT: Do not change the already provided
--world and --ouput arguments
PapyrusTasks String [Array] An array of additional arguments for papyrus,
where each array entry executes another
PapyrusCS process after the previous one has
finished (e.g. for rendering of multiple
dimensions)
LowPriority Boolean Start render process at lowest OS priority
(Default: false)
-------------------
ADDITIONAL SETTINGS
-------------------
QuietMode Boolean (!) Suppress notifying players in-game that vellum
is creating a backup and render
HideStdout Boolean (!) Whether to hide the console output generated by
the PapyrusCS rendering process, setting this
to "true" may help debug your configuration but
will result in a more verbose output
BusyCommands Boolean (!) Allow executing BDS commands while the tool is
taking backups
CheckForUpdates Boolean (!) Whether to check for updates on startup
StopBdsOnException Boolean (!) Should vellum unexpectedly crash due to an
unhandled exception, this sets whether to send a
"stop" command to the BDS process to prevent it
from keep running in detached mode otherwise
BdsWatchdog Boolean (!) Monitor BDS process and restart if unexpectedly
exited. Will try to restart process a maximum of
3 times. This retry count is reset when BDS
instance is deemed stable.
----------------------------------------------------------
* values marked with (!) are required, non-required values should be provided depending on your specific configuration
Below you'll find an example configuration.
Example configuration
{
"BdsBinPath": "/home/server/bedrock-server/bedrock_server",
"WorldName": "Bedrock level",
"Backups": {
"EnableBackups": true,
"EnableSchedule": true,
"Schedule": [
"00:00",
"06:00",
"12:00",
"18:00"
],
"BackupInterval": 60.0,
"ArchivePath": "./backups/",
"BackupsToKeep": 10,
"OnActivityOnly": true,
"StopBeforeBackup": false,
"NotifyBeforeStop": 60,
"BackupOnStartup": true,
"PreExec": "echo Starting!",
"PostExec": "echo Success!"
},
"Renders": {
"EnableRenders": true,
"PapyrusBinPath": "/home/server/papyruscs/PapyrusCs",
"PapyrusOutputPath": "/home/server/papyruscs_output",
"RenderInterval": 180.0,
"PapyrusGlobalArgs": "-w $WORLD_PATH -o $OUTPUT_PATH --htmlfile index.html --deleteexistingupdatefolder",
"PapyrusTasks": [
"--dim 0",
"--dim 1",
"--dim 2"
]
},
"QuietMode": false,
"HideStdout": true,
"BusyCommands": true,
"CheckForUpdates": true,
"StopBdsOnException": true,
"BdsWatchdog": true
}Overview of available launch parameters:
PARAMETER ABOUT
----------------------------------------------------------
-c | --configuration Specifies a custom configuration file.
(Default: configuration.json)
-h | --help Prints an overview of available parameters.
-r | --restore <archive path> Restores a backup from the specified archive.
--no-start In conjunction with the --restore flag, this tells the
application to not start the server after successfully
restoring a backup.
--no-backup-on-startup Disables the initial temporary backup on startup.
Parameters are optional and will default to their default values if not specified.
vellum also provides a few new, and overloads some existing commands that you can execute to force-invoke backup- or rendering tasks and schedule server shutdowns.
COMMAND ABOUT
----------------------------------------------------------
force start backup Forces taking a (hot-)backup (according to your
"StopBeforeBackup" setting)
force start render Forces PapyrusCS to execute and render your
world
stop <time in seconds> Schedules a server shutdown and notifies players
in-game
reload vellum Reloads the previously specified (or default)
configuration file
updatecheck Fetches the latest BDS & vellum version and
displays them in the console
If you want to compile vellum from source instead of using the pre-built binaries, you'll first need to install .NET Core for your operating system. Clone this repository and cd into the src directory. Then run the following command to build the vellum executable:
dotnet build vellum.csproj -c Release /p:OutputType=Exe /p:PublishSingleFile=false
If you want to build the library instead of the executable, run this command:
dotnet build vellum.csproj -c Release /p:OutputType=Library
Use this tool at your own risk! When using this software you agree to not hold us liable for any corrupted save data or deleted files. Make sure to configure everything correctly and thoroughly!
If you find any bugs, please report them on the issue tracker here on GitHub, our dedicated Discord server or send me an e-mail.