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.

For most commands to work, the areas 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 areas of the map will be skipped (TODO). Note that only SQLite format maps are currently supported.

General usage

mapedit [-h] <map> <subcommand>

Arguments:

• -h: Show a help message and exit.
• <map>: Path to the Minetest world/map to edit; this can be either a world directory or a map.sqlite file within a world folder. This file will be modified, so always shut down the game/server before executing any command.
• <subcommand>: Command to execute. See "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: includes node, new_node, etc. Must be the full name, e.g. "default:stone", not just "stone".

Other tips

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 given area to a new location.

Arguments:

• --p1, --p2: Area to copy from.
• --offset: Offset to shift the area by. For example, to copy an area 50 nodes upward (positive Y direction), use --offset 0 50 0.

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

deleteblocks

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

Deletes all mapblocks in the given area.

Arguments:

• --p1, --p2: Area to delete from. Only mapblocks fully inside this area will be deleted.
• --invert: Delete only mapblocks that are fully outside the given area.

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.

deletemeta

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

Delete metadata of a certain node and/or within a certain area. This includes node inventories as well.

Arguments:

• --node: Name of node to modify. If not specified, the metadata of all nodes will be deleted.
• --p1, --p2: Area in which to delete metadata. If not specified, metadata will be deleted everywhere.
• --invert: Only delete metadata outside the given area.

deleteobjects

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

Delete objects/entities, including item entities (dropped items).

Arguments:

• --obj: Name of object to delete, e.g. "boats:boat". If not specified, all objects will be deleted.
• --items [item]: Delete item entities (dropped items). If an optional item name is specified, only items with that name will be deleted.
• --p1, --p2: Area in which to delete objects. If not specified, objects will be deleted everywhere.
• --invert: Delete objects outside the given area.

deletetimers

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

Delete node timers of a certain node and/or within a certain area.

Arguments:

• --node: Name of node to modify. If not specified, the node timers of all nodes will be deleted.
• --p1, --p2: Area in which to delete node timers.
• --invert: Only delete node timers outside the given area.

fill

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

Fills the given area with one node. The affected mapblocks must be already generated for fill to work.

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

Arguments:

• new_node: Name of node to fill the area with.
• --p1, --p2: Area to fill.
• --invert: Fill everything outside the given area.

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 source map/world. This will not be modified.
• --p1, --p2: Area to copy from. If not specified, MapEditr will try to copy everything from the input map file.
• --invert: If present, copy everything outside the given area.
• --offset: Offset to move nodes by when copying; default is no offset. Currently, an offset cannot be used with an inverted selection.

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

To ensure that all data is copied, make sure the edges of the selection are generated in the destination map, or the entire selection if an offset is used.

Tip: Overlay will be significantly faster if no offset is used, as mapblocks can be copied verbatim.

replaceininv

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

Replace a certain item with another in node inventories. To delete items instead of replacing them, use "Empty" (with a capital E) for replacename.

Arguments:

• item: Name of item to replace
• new_item: Name of new item to replace with
• --deletemeta: Delete metadata of replaced items. If not specified, any item metadata will remain unchanged.
• --node: Name of node to to replace in. If not specified, the item will be replaced in all node inventories.
• --p1, --p2: Area in which to search for nodes. If not specified, items will be replaced across the entire map.
• --invert: Only search for nodes outside the given area.

Tip: To only delete metadata without replacing the nodes, use the --deletemeta flag, and make new_item the same as item.

replacenodes

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

Replace all of one node with another node. Can 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: Area in which to replace nodes. If not specified, nodes will be replaced across the entire map.
• --invert: Only replace nodes outside the given area.

setmetavar

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

Set a variable in node metadata. This only works on metadata where the variable is already set.

Arguments:

• key: Name of variable to set, e.g. infotext, formspec, etc.
• value: Value to set variable to. This should be a string.
• --node: Name of node to modify. If not specified, the variable will be set for all nodes that have it.
• --p1, --p2: Area in which to modify nodes.
• --invert: Only modify nodes outside the given area.

setparam2

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

Set param2 values of a certain node and/or within a certain area.

Arguments:

• param2_val: Param2 value to set, between 0 and 255.
• --node: Name of node to modify. If not specified, the param2 values of all nodes will be set.
• --p1, --p2: Area in which to set param2.
• --invert: Only set param2 outside the given area.

vacuum

Usage: vacuum

Vacuums the database. This reduces the size of the database, but may take a long time.

All this does is perform an SQLite VACUUM command. This shrinks and optimizes the database by efficiently "repacking" all mapblocks. No map data is changed or deleted.

Note: Because data is 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!