Synopsis

clicraft <action> [args]

Description

clicraft(1) provides example action scripts that can be used and modified to extend clicraft’s functionality. To set up one of these scripts, use the clicraft enable command:

clicraft enable backup

This will set up a symlink to the action script so that it’s visible to clicraft. If you installed clicraft by compiling it instead of through your system’s package manager, and if you also plan on editing the script, it’s recommended to use the --copy flag when enabling it so that your changes aren’t overwritten the next time you upgrade.

clicraft enable --copy backup

An action script created using either of the two methods above will get executed when running clicraft backup.

For more info on action scripts, see clicraft.conf(5).

Actions

backup

Backs up world data.

This action has these clicraft.conf(5) options:

BACKUP_DIR="/path/to/directory"

The directory to place the backup in. Defaults to "$SERVER_DIR/backups".

BACKUP_FILE="/path/to/file"

The file to back up to. Defaults to "$BACKUP_DIR/world-timestamp.zip" where world is the value of level-name in server.properties and timestamp is the current date and time in YYYYMMDD-HHMMSS format.

BACKUP_TARGETS="file [file2 …]"

A space-delimited list of the files and directories to include in the backup. Defaults to "world world_*", where world is the value of level-name in server.properties.

BACKUP_COMMAND="command [args]"

The command to run to make the backup. Defaults to "zip -r $BACKUP_FILE $BACKUP_TARGETS".

BACKUP_LIMIT="number"

The number of backups to keep before removing old backups. Set to 0 to keep backups indefinitely. Defaults to 7.

When removing old backups past the BACKUP_LIMIT, this action sorts all files in BACKUP_DIR by filename and removes them until BACKUP_LIMIT is satisfied. You must therefore take care to set BACKUP_FILE so that old files are sorted before new ones.

blocks

Scrape the Minecraft Wiki for valid block ids and print them in a human-readable format usable as a whitelist for clicraft prune.

This action displays block data in three or more space-delimited fields. The first is the decimal block id. The second is the hexadecimal block id. The remaining fields represet the block’s name.

cmd

This action script shouldn’t be used directly. Instead, it should be used via a symlink pointing to it. If such a symlink was created with e.g. clicraft enable cmd foo, the command clicraft foo … is equivalent to clicraft cmd -v foo …. The purpose of this is to make it simpler to send the foo command to the console.

explore <size> [x z]

Generates a world roughly size by size centered on coordinates x and z (spawn by default) using mcexplore(1).

Using this action is equivalent to running mcexplore -p SERVER_DIR -c START_COMMAND -x x -z z size. For information regarding SERVER_DIR and START_COMMAND, see clicraft.conf(5).

map [args]

Maps the world using c10t(1). Any additional args get passed to c10t, which must be in your PATH, HOME/bin, or SERVER_DIR. For valid args, see c10t --help.

With a default install of minecraft, using this action is equivalent to running c10t -w SERVER_DIR/world -o $HOME/maps/world-date.png [args], where date is today’s date in YYYY-MM-DD format and world is the value of level-name in server.properties. For information regarding SERVER_DIR, see clicraft.conf(5). If the $HOME/maps directory does not exist, it is created.

pregen <player> <size> [x z]

Generates a world roughly size by size centered on coordinates x and z (spawn by default) by teleporting player around.

This action has these clicraft.conf(5) options:

PREGEN_TIMEOUT="seconds"

The amount of time, in seconds, that clicraft will wait between teleports. Defaults to $TIMEOUT.

prune [dim]

Prunes the map using mmat. Valid values for dim are overworld, nether, or end. If no dim is provided, the overworld is pruned.

This action has these clicraft.conf(5) options:

MMAT_JAR="/path/to/mmat.jar"

The mmat.jar file. Defaults to "$SERVER_DIR/mmat.jar".

PRUNE_RADIUS="chunks"

The radius, in chunks, of data to preserver surrounding whitelisted blocks. Defaults to 15.

OVERWORLD_WHITELIST="/path/to/file"

The file that defines what blocks to preserve when pruning the overworld. Each line in the file should start with a block id followed by a whitespace character. Lines not following this format are ignored. Defaults to "$CLICRAFT_CONFIG/overworld-blocks.conf"

NETHER_WHITELIST="/path/to/file"

The file that defines what blocks to preserve when pruning the nether. Each line in the file should start with a block id followed by a whitespace character. Lines not following this format are ignored. Defaults to "$CLICRAFT_CONFIG/nether-blocks.conf"

END_WHITELIST="/path/to/file"

The file that defines what blocks to preserve when pruning the end. Each line in the file should start with a block id followed by a whitespace character. Lines not following this format are ignored. Defaults to "$CLICRAFT_CONFIG/end-blocks.conf"

restart [options]

Restarts the server. This action script overrides clicraft’s default restart script to provide additional functionality through the options described below.

Command line options:

-c, --if-crashed

Do nothing if the server is running. This option requires lsof in order to work correctly.

-e, --if-empty

Do nothing if there are players online. This options requires that the list entry in the regex database is configured correctly.

-w, --warn

This option is the same as the one documented in clicraft(1).

restore [file.zip] [files]

Restores world data by extracting files from file.zip. If files is not provided, all files are extracted from file.zip. With no arguments, print a list of files that can be restored from.

This action is implemented in $CLICRAFT_CONFIG/action.d/backup.sh.example. See clicraft.conf(5) for a description of $CLICRAFT_CONFIG.

sh [command]

Evaluate command within clicraft’s environment. If no command is given, open an interactive bash session with an environment that mimics clicraft’s.

sync [target]

Synchronizes target using rsync. If no target is given, synchronizes all targets in SYNC_TARGETS.

The names of the clicraft.conf(5) options available to this action depend on the targets you will be syncing. The options below are described using an example foo target.

SYNC_TARGETS=( "list" "of" "targets" )

The list of targets to sync if no target is supplied on the command line.

SYNC_FOO_OPTS="--rsync-options"

The options to pass to rsync when syncing target foo.

SYNC_FOO_SRCS=( "list" "of" "source" "files" "and" "directories" )

A list of the files and directories to sync for target foo.

SYNC_FOO_DEST="/path/to/directory"

The directory to put SYNC_FOO_SRCS in when syncing target foo.

SYNC_FOO_TYPE="push"|"pull"|"local"

The method used to sync target foo. Valid values are "push" (update the remote host from local sources), "pull" (update the local host from remote sources), or "local" (update the local host from local sources).

SYNC_FOO_HOST="host"

The remote hostname or ip address to use when syncing target foo. This option is not used if SYNC_FOO_TYPE is "local".

SYNC_FOO_USER="user"

The user to use on the remote host when syncing target foo. This option is not used if SYNC_FOO_TYPE is "local".

Examples

clicraft explore 320 500 500

Generate a 320x320 region (20 by 20 chunks) centered on (x=500, z=500).

clicraft map -R 250 -r 270

Generate a map centered on spawn out to a radius of 250 chunks, and rotate it 270 degrees.

Configuration

See clicraft.conf(5) for details on configuring clicraft and clicraft-actions(5) for writing custom action scripts.

See Also

clicraft(1), clicraft.conf(5), clicraft-actions(5), mcexplore(1), c10t(1)

The clicraft project page is located at http://dmbuce.github.com/clicraft/.

Bugs

Report any and all bugs to the clicraft issue tracker with as much detail as possible.

Authors

To see a full list of contributors, use git shortlog -s in the clicraft git repository.