MapEditr/Manual.md

# The MapEditr Manual

## Introduction

MapEditr is a command-line tool for editing Minetest worlds. Note that MapEditr
is not a mod or plugin; it is a separate program which operates independently
of Minetest.

MapEditr reads and edits *map databases*, usually a file named `map.sqlite`
within each Minetest world directory. As such, the terms "world" and "map" may
be used interchangeably. Note that only SQLite format maps are currently
supported.

For most commands to work, the parts of the map to be read/modified must
already be generated. This can be done by either exploring the area in-game,
or by using Minetest's built-in `/emergeblocks` command.

MapEditr supports all maps created since Minetest version 0.4.2-rc1, released
July 2012. Any unsupported parts of the map will be skipped.

## General usage

`mapeditr [-h] [-y] <map> <SUBCOMMAND>`

Arguments:

- `-h, --help`: Print help information and exit.
- `-y, --yes`: Skip the default confirmation prompt (for those who feel brave).
- `<map>`: Path to the Minetest world/map to edit; this can be either a world
directory or a `map.sqlite` file. This world/map will be modified, so *always*
shut down the game or server before executing any command.
- `<SUBCOMMAND>`: Command to execute. See the "Commands" section below.

### Common command arguments

- `--p1 <x> <y> <z>` and `--p2 <x> <y> <z>`: Used to select a box-shaped
area with corners at `p1` and `p2`, similarly to how WorldEdit's area selection
works. Any two opposite corners can be used. These coordinates can be found
using Minetest's F5 debug menu.
- Node/item names, including `node`, `new_node`, etc.: Must be the full name,
e.g. "default:stone", not just "stone".

### Other tips

Optional arguments are indicated using [square brackets].

Text-like arguments can be surrounded with "quotes" if they contain spaces.

Due to technical limitations, MapEditr will often leave lighting glitches. To
fix these, use Minetest's built-in `/fixlight` command, or the equivalent
WorldEdit `//fixlight` command.

## Commands

### clone

Usage: `clone --p1 x y z --p2 x y z --offset x y z`

Clone (copy) the contents of an area to a new location.

Arguments:

- `--p1, --p2`: Area to clone.
- `--offset x y z`: Vector to shift the area's contents by. For example, to
copy an area 50 nodes downward (negative Y direction), use `--offset 0 -50 0`.
Directions may be determined using Minetest's F5 debug menu.

This command copies nodes, param1, param2, and metadata. Nothing will be copied
from or into mapblocks that are not yet generated.

Examples:

- Clone an area surrounding spawn 500 nodes west and 360 nodes north:
`clone --p1 200 80 200 --p2 -200 -15 -200 --offset -500 0 360`

### deleteblocks

Usage: `deleteblocks --p1 x y z --p2 x y z [--invert]`

Delete all mapblocks inside or outside an area. This command is often much
faster than Minetest's built-in `/deleteblocks` command.

Arguments:

- `--p1, --p2`: Area containing mapblocks to delete. By default, only mapblocks
fully within this area will be deleted.
- `--invert`: Delete all mapblocks fully *outside* the given area. Use with
caution; you could erase a large portion of your world!

**Note:** Deleting mapblocks is *not* the same as filling them with air! Mapgen
will be invoked where the blocks were deleted, and this sometimes causes
terrain glitches.

Examples:

- Delete all saved mapblocks below y = -200 and above y = 200:
`deleteblocks --p1 -31000 -200 -31000 --p2 31000 200 31000 --invert`

### deletemeta

Usage: `deletemeta [--node <node>] [--p1 x y z] [--p2 x y z] [--invert]`

Delete node metadata of certain nodes. Node inventories (such as chest/furnace
contents) are also deleted.

Arguments:

- `--node <node>`: (Optional) Name of node to delete metadata from. If not
specified, metadata will be deleted from any node.
- `--p1, --p2`: (Optional) Area in which to delete metadata. If not specified,
metadata will be deleted everywhere.
- `--invert`: Delete metadata *outside* the given area.

### deleteobjects

Usage: `deleteobjects [--obj <object>] [--items [items]] [--p1 x y z] [--p2 x y z] [--invert]`

Delete certain objects (entities) and/or item entities (dropped items).

Arguments:

- `--obj <object>`: (Optional) Name of object to delete, e.g. "boats:boat".
- `--items [items]`: (Optional) Delete only item entities (dropped items). If
one or more item names are listed after `--items`, only those items will be
deleted.
- `--p1, --p2`: (Optional) Area in which to delete objects. If not specified,
objects will be deleted everywhere.
- `--invert`: Delete objects *outside* the given area.

`--obj` and `--items` cannot be used simultaneously.

Examples:

- Delete all objects: `deleteobjects`
- Delete all cart entities: `deleteobjects --obj carts:cart`
- Delete dropped stone and gravel:
`deleteobjects --items default:stone default:gravel`

### deletetimers

Usage: `deletetimers [--node <node>] [--p1 x y z] [--p2 x y z] [--invert]`

Delete node timers of certain nodes.

Arguments:

- `--node <node>`: (Optional) Name of node to delete node timers from. If not
specified, node timers of any node will be deleted.
- `--p1, --p2`: (Optional) Area in which to delete node timers. If not
specified, node timers will be deleted everywhere.
- `--invert`: Delete node timers *outside* the given area.

### fill

Usage: `fill --p1 x y z --p2 x y z [--invert] <new_node>`

Set all nodes inside or outside an area. Mapblocks that are not yet generated
will not be affected.

This command does not affect param2, node metadata, etc.

Arguments:

- `--p1, --p2`: Area to fill.
- `--invert`: Fill all generated nodes *outside* the given area.
- `<new_node>`: Name of the node to fill with.

Examples:

- Carve out a large hole in the ground:
`fill --p1 224 50 347 --p2 817 -40 73 air`
- Build a long obsidian glass wall travelling north/south:
`fill --p1 0 -30 -10000 --p2 0 30 10000 default:obsidian_glass`

### overlay

Usage: `overlay <input_map> [--p1 x y z] [--p2 x y z] [--invert] [--offset x y z]`

Copy part or all of a source map into the main map.

Arguments:

- `<input_map>`: Path to the source map/world. This map will not be modified.
- `--p1, --p2`: (Optional) Area to copy from. If not specified, MapEditr will
try to copy everything from the source map.
- `--invert`: Copy everything *outside* the given area.
- `--offset x y z`: (Optional) Vector to shift nodes by when copying; default
is no offset. Currently, an offset cannot be used with an inverted selection.

**If an area and/or offset is used:** To ensure that all data is copied, make
sure at least the "edges" of the destination area are generated, or the entire
destination area if using an offset.

This command will always copy nodes, param1, param2, and metadata. If no
offset is used, objects/entities and node timers may also be copied.

**Tip:** Overlay will be significantly faster if no offset is used.

Examples (your world/map paths will vary):

- Copy all of map `backup.sqlite` into the main world:
`overlay backup-maps/backup.sqlite`
- Copy world `test` into the main world, excluding the area within 120 nodes of
spawn: `overlay test --p1 -120 -120 -120 --p2 120 120 120 --invert`
- Copy an area from `map.sqlite` into the main world, moving it 32 nodes north:
`overlay map.sqlite --p1 6 36 -49 --p2 -9 74 -78 --offset 0 0 32`

### replaceininv

Usage: `replaceininv <item> [new_item] [--delete] [--deletemeta] [--nodes <nodes>] [--p1 x y z] [--p2 x y z] [--invert]`

Replace, delete, or modify items in certain node inventories.

Arguments:

- `<item>`: Name of the item to replace/delete.
- `[new_item]`: (Optional) Name of the new item, if replacing items.
- `--delete`: Delete items instead of replacing them.
- `--deletemeta`: Delete metadata of affected items. May be used with or
without `new_item`, depending on whether items should also be replaced.
- `--nodes <nodes>`: (Optional) Names of one or more nodes to modify
inventories of. If not specified, items will be modified in any node with an
inventory.
- `--p1, --p2`: (Optional) Area in which to modify node inventories. If not
specified, items will be modified everywhere.
- `--invert`: Modify node inventories *outside* the given area.

Examples:

- Delete all lava buckets:
`replaceininv bucket:bucket_lava --delete`
- Replace all written books in chests with unwritten books, deleting metadata:
`replaceininv default:book_written default:book --deletemeta --nodes default:chest default:chest_locked`

### replacenodes

Usage: `replacenodes <node> <new_node> [--p1 x y z] [--p2 x y z] [--invert]`

Replace one node with another node. Can also be used to remove unknown nodes
or swap a node that changed names.

This command does not affect param2, metadata, etc.

Arguments:

- `<node>`: Name of node to replace.
- `<new_node>`: Name of node to replace with.
- `--p1, --p2`: (Optional) Area in which to replace nodes. If not specified,
nodes will be replaced across the entire map.
- `--invert`: Replace nodes *outside* the given area.

Examples:

- Replace all legacy PB&J pup nodes with mese blocks:
`replacenodes pbj_pup:pbj_pup default:mese`
- Remove fire nodes near ground level:
`replacenodes fire:basic_flame air --p1 -31000 -80 -31000 --p2 31000 200 31000`

### setmetavar

Usage: `setmetavar <key> [value] [--delete] [--nodes <nodes>] [--p1 x y z] [--p2 x y z] [--invert]`

Set or delete a variable in node metadata of certain nodes. This only works on
nodes where the variable is already set.

Arguments:

- `<key>`: Name of variable to set/delete, e.g. `infotext`, `formspec`, etc.
- `[value]`: Value to set variable to, if setting a value. This should be a
string.
- `--delete`: Delete the variable.
- `--nodes <nodes>`: (Optional) Names of one or more nodes to modify. If not
specified, any node with the given variable will be modified.
- `--p1, --p2`: (Optional) Area in which to modify node metadata. If not
specified, nodes will be modified everywhere.
- `--invert`: Modify node metadata *outside* the given area.

Examples:

- Clear infotext of signs:
`setmetavar infotext --delete --nodes default:sign_wall_steel default:sign_wall_wood`
- Set "player1" as the owner of all steel trapdoors:
`setmetavar owner player1 --nodes doors:trapdoor_steel`

### setparam2

Usage: `setparam2 [--node <node>] [--p1 x y z] [--p2 x y z] [--invert] <param2>`

Set param2 values of certain nodes.

Arguments:

- `--node <node>`: (Optional) Name of node to modify. If not specified, the
param2 values of any node will be set.
- `--p1, --p2`: (Optional) Area in which to set param2 values. If not
specified, param2 will be set everywhere.
- `--invert`: Set param2 values *outside* the given area.
- `<param2>`: New param2 value, between 0 and 255.

An area and/or node is required for this command.

### vacuum

Usage: `vacuum`

Rebuild the map database to reduce its size. Vacuuming may take a long time for
large maps.

This command simply executes the SQLite `VACUUM` command, which shrinks and
optimizes the map database by efficiently "repacking" all mapblocks. No map
data is changed or deleted.

**Note:** Because data is temporarily copied into another file, vacuum could
require as much free disk space as is already occupied by the map. For example,
if map.sqlite is 10 GB, make sure you have **at least 10 GB** of free space!