SingleCommand Reference

This is a reference for both the online version and the command-line version of SingleCommand.



Syntax: conditional Command

Puts the command into a conditional command block. The command will only run if the previous command succeeded.


Syntax: define Name [=] Value

Defines a macro, which can be inserted with ‘{Name}’.


Syntax: import Filename

Imports a SingleCommand script, taking its commands, macros, and options.

Importing a script is equivalent to including its contents directly, except for line numbers.

Note that importing scripts is disabled in the online utility.


Syntax: init Command

Runs a command once, even in a repeat script.

See repeat.


Syntax: option OptionName Value

Sets an option. Option values are specified as Python literals.


Syntax: repeat Command

Runs a command at 20Hz, even in an impulse script.

See init.


Syntax: silent Command

Disables output tracking for that command.

See the ‘track’ command and the track_output option.


Syntax: if Expression

Only runs the next command or code block if the expression succeeds.

{ ... }

Syntax: {

Groups the commands together into a single command block as if they had been put through SingleCommand separately, and spawns the FallingSand stack above the current command block tower.

If the block only contains one command and the simplify_single option is enabled, then the braces will have no effect.

begin ... end

Syntax: begin

An alternate form of code block.


Syntax: [Name] Command

Puts the command into a command block with the specified name. This will be used instead of ‘@’ to identify the command block in console messages.

#   //   --

Syntax: # Comment

Lines starting with ‘#’, ‘//’, or ‘--’ are comments, and are ignored.


Syntax: comm

Continues the previous command or macro definition.

If the ellipsis is followed by whitespace, a single space will be entered in place of the line break. Multiple whitespace characters are ignored.


You can define macros with the define command, and insert them with ‘{Name}’.

If a macro does not exist and has no default, the tag will be left as it is. This means that JSON objects will not cause conflicts.


You can define a default value to be used if a macro does not exist with ‘{MacroName || DefaultValue}’.


To call a macro as a function, use ‘{MacroName(Args)}’. The arguments to a function are parsed like a Unix shell.

When a macro is called with arguments. As well as normal macros, you can use ‘{$1}’ for the first argument, ‘{$2}’ for the second argument, ‘{$3}’ for the third argument, etc., ‘{$*}’ for all arguments, and ‘{$0}’ for the name of the macro.

Functions and defaults can be combined.

Built-In Function Macros

There are a number of function macros built into SingleCommand.


Usage: {upper_case(String)}

Converts the arguments to upper case.


Usage: {lower_case(String)}

Converts the arguments to lower case.


Usage: {random_integer(Max)} or {random_integer(Max Min)}

Returns a random integer between Min and Max - 1.


Usage: {escape_for_json(String)}

Escapes the string for use as a JSON string. ‘\’ and ‘"’ are escaped with ‘\’.


Usage: {regex_replace(Input RegularExpression Replacement [Count [Flags]])}

Replaces all instances of RegularExpression with Replacement in Input. RegularExpression is a Python regular expression.

If Count is specified, it will limit the number of substitutions. Otherwise, all instances will be replaced.

The Flags argument is case-insensitive, and can be any combination of ‘I’ (case-insensitive), ‘M’ (makes ‘^’ and ‘$’ match the beginning and end of lines as well as the entire string), ‘S’ (makes ‘.’ match new-lines, as well as other characters), and ‘X’ (allows comments and ignores whitespace).


Usage: {get_macro(MacroName [Default])}

Gets a macro or option by name. This allows you to use a macro value in the name of a macro.


Usage: {get_singlecommand_option(OptionName)}

Gets an option by name.


SingleCommand supports a number of options, which can be set either from the GUI or command line, or with the ‘option’ command.

Option values are specified as Python literals. ‘True’ and ‘False’ are capitalised.


Default: False

If True, command blocks will activated once and then be destroyed, unless prefixed with ‘repeat’.

If False, command blocks will be activated at 20Hz, unless prefixed with ‘init’.


Default: False

If this option is True, command blocks which aren't named will be identified by their line numbers. This increases the length of the command, but may make debugging easier.


Default: False

Outputs strict JSON instead of Minecraft-style JSON.


Default: True

Allows the insertion of macros created with the define command.


Default: False

If True, the repeating command block at the top of the chain will be set to ‘Needs Redstone’. This means that the repeat chain will only run when the top block is given a Redstone signal.


Default: False

If True, block IDs will not have the ‘minecraft:’ prefix.


Default: False

Removes the manually-placed command block which was used to create the repeat chain.


Default: 1

Spawns the stack of command block FallingSand entities n metres above the original command block.

This can be changed to spawn the stack underneath the original block, to add a delay, or to spawn a chain from inside another chain.


Default: '~', '$', '~'

A list or tuple containing three coordinates, which can be ints, floats, or strings. Use '$' for spawn_height.


Default: True

If True, command blocks will track their output unless prefixed with ‘silent’.

If False, command blocks will not track their output unless prefixed with ‘track’.

Tracking output causes lag; not tracking output increases the length of the command.


Default: False

Uses the deprecated ‘Riding’ tag instead of the ‘Passengers’ tag, for use on pre-15w41a snapshots.


Default: True

If this is True, when given a script or code block consisting only of a single init command, SingleCommand will yield the command unchanged.