Below is a comprehensive Markdown document that explains what the script does, how it works, and the commands/parameters you can use.
This CraftScript allows you to move a specified block type one block at a time within your WorldEdit selection. The movement can be performed in various directions—vertical (up, down), cardinal (north, east, south, west), and relative to your position (left, right, forward, back). The script processes the entire region in memory (by building a 3D array of the blocks), performs the movement for a specified number of iterations (or a percentage of the region’s maximum moves), and then updates the world in one pass.
This script—invoked with /cs gravity—is designed to “move” blocks in your selected region by swapping their positions with their neighbors. Each movement (or iteration) shifts the target block one cell in the chosen direction. The script supports:
- Vertical Movement:
up(u) anddown(d) - Cardinal Directions:
north(n),east(e),south(s), andwest(w) - Relative Movement:
left(l),right(r),forward(f), andback(b)
Additionally, you can specify the number of iterations either as a plain number or as a percentage (e.g., "50%") which is calculated against the maximum possible moves in that axis.
/cs gravity <direction> <block> [iterations]
<direction>: Specifies the direction to move the target block.
Allowed values include both full names and short forms:- Vertical:
up(u),down(d) - Relative:
left(l),right(r),forward(f),back(b) - Cardinal:
north(n),east(e),south(s),west(w)
- Vertical:
<block>: The block type you want to move (e.g.,mossy_block,stone, etc.).[iterations]: (Optional) A positive integer or a percentage (e.g., "50%") that defines how many times the move is applied.- When given as a percentage, the script calculates the maximum number of moves based on the region's size along the relevant axis and then uses that percentage to determine the iterations.
The script accepts both full and abbreviated forms:
-
Vertical:
- up (or u) – Moves the block one cell upward.
- down (or d) – Moves the block one cell downward.
-
Relative (based on player's facing):
- left (or l) – Moves the block one cell to the left relative to the player.
- right (or r) – Moves the block one cell to the right relative to the player.
- forward (or f) – Moves the block one cell in the direction the player is facing.
- back (or b) – Moves the block one cell opposite the direction the player is facing.
-
Cardinal (absolute):
- north (or n) – Moves the block one cell north (decreasing Z).
- east (or e) – Moves the block one cell east (increasing X).
- south (or s) – Moves the block one cell south (increasing Z).
- west (or w) – Moves the block one cell west (decreasing X).
Specify the target block that will be moved. The script uses the WorldEdit context.getBlock() function to parse this argument and validate it against known block types.
-
Numeric Value:
For example,3will move the target block 3 cells in the chosen direction (one cell per iteration). -
Percentage Value:
For example,50%calculates the maximum possible moves along the relevant axis (for instance, for vertical movement, if the region’s height is 10 blocks, the maximum moves is 9) and uses that percentage to determine the number of iterations (e.g., 50% of 9 → 4 iterations).
-
Input Validation and Parsing:
- The script verifies that a valid selection exists.
- It then maps any short direction codes (e.g.,
u,f) to their full names. - The block type is parsed and validated.
- The iterations parameter is parsed as either an integer or a percentage, calculating the number of iterations accordingly.
-
Building the In-Memory Representation:
- The script computes the region's dimensions and loads every block in the region into a 3D array.
- This minimizes repeated API calls and lets the script simulate the block movement in memory.
-
Simulating Block Movement:
- For each iteration, the script scans through the 3D array and, when it finds a block that matches the target block, swaps it with the neighboring cell in the desired direction.
- The swapping order is carefully chosen based on the movement direction to ensure that each block only moves one step per iteration.
-
Updating the World:
- After processing all iterations in memory, the script writes the updated block states back to the world in a single pass, applying one
setBlockcall per coordinate.
- After processing all iterations in memory, the script writes the updated block states back to the world in a single pass, applying one
-
Move mossy blocks upward 3 times:
/cs gravity up mossy_block 3 -
Move stone blocks forward by 50% of the maximum moves possible in that direction:
/cs gravity forward stone 50% -
Move target blocks to the left (relative to player) 5 times:
/cs gravity l target_block 5 -
Move blocks south by 10 iterations:
/cs gravity south block_name 10
-
WorldEdit Setup:
Ensure that your script is placed in the correct CraftScripts folder in your WorldEdit configuration (e.g.,plugins/WorldEdit/craftscriptsfor server setups). -
Block Comparison:
The script compares blocks using their string representations (toString()). Make sure that the block names you provide match the names expected by WorldEdit. -
In-Memory Processing:
Because the script processes all blocks in memory, it is optimized for fewer API calls. However, for very large selections, be aware of possible performance impacts. -
Relative Directions:
The directionsforward,back,left, andrightare calculated based on the player’s current yaw (facing direction). Ensure you are facing the intended direction before executing the command.
This comprehensive script gives you great flexibility to “move” blocks within a region in any direction using both absolute (cardinal) and relative (player-based) coordinates, with dynamic iteration control. Enjoy editing your world with Gravity CraftScript!