BuildingTools/README.md

# BuildingTools

Tools for building games, mainly focused on changing and displaying (F3) block properties.

## Commands
### Selection commands
Before changing any block with this mod, you need to select it in most cases. This is different than Gamecraft's box selection.

You can use all the commands starting with `select`, they all have descriptions to help and should be self-explanatory otherwise.

You can also run the desired block command for a cluster with a given object ID by adding the identifier as the last parameter.
In this case you don't need to select the blocks beforehand which can be useful in command computers.

Speaking of command computers, object signals can *also* be used, so if you have an object trigger set up and an object identifier enters that trigger, then all the blocks attached to it will be used as target blocks for the given block command that receives the signal.
To use this, add "Chan" at the end of the command name (like `colorBlocksChan`).

### Block commands
#### Color command

The `colorBlocks` command can color the selected blocks to the given color.
It works in both time stopped and running modes, although the color *will not* reset on time stop.

The darkness parameter is what can be selected in the game using `Ctrl+<num>` by default.
0 means default color, then lightest to darkest.

Usage (The object ID is optional):
```
colorBlocks "<color> <darkness> [objectID]"
```
**The usage for all other block commands are the following:**
```
<command> "<x> <y> <z> [objectID]"
```

### Scale blocks
The `scaleBlocks` command can be used to both scale *and* move the blocks so that the cluster stays together.
In this case, the block you're looking at is used as reference and won't be moved.

The `scaleIndividually` command only scales the blocks but doesn't move them so you can see between them.

Both commands take a *relative* scale, so specifying "1 1 1" will not change anything and "2 2 2" will double the scale in all directions.

Note that block connections will not be updated until you reload the save.

### Move blocks
The `moveBlocks` command will move the selected blocks by the specified amount. Use 0.2 for one block of change in position.

In time stopped mode, this will not update block connections, just like the scale commands.

In time running mode, this will move the whole chunks the selected blocks are a part of.

### Push blocks
The `pushBlocks` and `pushRotateBlocks` command will apply a specified (regular or angular) force to the selected blocks' chunks.
The directions are global, so a positive value for Y means push upwards.
Only works in time running mode.

## Other commands
### Push player
The `pushPlayer` and `pushRotatePlayer` commands will apply a specified (regular or angular) force to the player in any mode.

### Examples
* Select and move box selected blocks by 5 blocks in the +X direction:
```
selectSelectedBlocks
moveBlocks "1 0 0"
```
* Select and push the block you're looking at and all connected blocks by 10 in the +Y direction:
```
selectBlocksLookedAt false
<Start time>
pushBlocks "0 10 0"
```
* Change the color of the cluster with ID E to blue:
```
colorBlocks "blue 0 E"
```
* Color all clusters with an object ID that enter an object trigger hooked up to a command computer with this command:

(Can be filtered using an object filter)
```
colorBlocksChan "blue 0"
```