From 9528a11e1e863611d8a9ee7f0f2d9a40b490ac2c Mon Sep 17 00:00:00 2001 From: random-geek <35757396+random-geek@users.noreply.github.com> Date: Fri, 22 Jan 2021 15:48:41 -0800 Subject: [PATCH] Doc tweaks --- Manual.md | 109 +++++++++++++++++++++++++++--------------------------- README.md | 11 ++---- 2 files changed, 58 insertions(+), 62 deletions(-) diff --git a/Manual.md b/Manual.md index 7466c10..7b923fa 100644 --- a/Manual.md +++ b/Manual.md @@ -2,28 +2,21 @@ ## Introduction -MapEditr is a command-line tool for editing Minetest worlds, specifically -Minetest maps. Note that MapEditr is not a mod or plugin; it is a separate -program which operates independently of Minetest. +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. -Minetest *worlds* are stored in the `worlds` folder within Minetest's -installation directory. Each world is a folder containing a *map database*, -usually named `map.sqlite`, among other files. The map database contains the -physical layout of that world, including all nodes (blocks) and objects (mobs, -etc.). This file is what MapEditr reads and edits. +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. -Minetest stores map data in *mapblocks*. A single map block is a cubical, -16x16x16 node area of the map. The lower southwestern corner of a mapblock -(towards -X, -Y, -Z) is always at coordinates divisible by 16, e.g. -(0, 16, -48) or the like. +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. -For most commands to work, the mapblocks to be read and modified must already -be generated within Minetest. This can be achieved by either exploring the area -in-game, or by using Minetest's built-in `/emergeblocks` command. - -MapEditr supports map format versions 25 through 28, meaning all worlds -created since Minetest version 0.4.2-rc1 (released July 2012) should be -supported. Unsupported mapblocks will be skipped (TODO). +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 @@ -32,10 +25,9 @@ supported. Unsupported mapblocks will be skipped (TODO). Arguments: - `-h`: Show a help message and exit. -- ``: Path to the Minetest world to edit; this can be either a world -directory or a `map.sqlite` file. Note that only worlds with SQLite map -databases are currently supported. This file will be modified, so *always* shut -down the game/server before executing the command. +- ``: 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. - ``: Command to execute. See "Commands" section below. ### Common command arguments @@ -57,6 +49,21 @@ 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]` @@ -90,6 +97,19 @@ name is specified, only items with that name will be deleted. be deleted everywhere. - `--invert`: Delete objects *outside* the given area. +### deletetimers + +Usage: `deletetimers [--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] ` @@ -105,38 +125,29 @@ Arguments: - `--p1, --p2`: Area to fill. - `--invert`: Fill everything *outside* the given area. -### 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. - ### overlay -Usage: `overlay [--p1 x y z] [--p2 x y z] [--invert] [--offset x y z] ` +Usage: `overlay [--p1 x y z] [--p2 x y z] [--invert] [--offset x y z]` -Copy part or all of an input map into the main map. +Copy part or all of a source map into the main map. Arguments: -- `input_map`: Path to input map file. This will not be modified. +- `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 and param2, and metadata. If no -offset is used, entities and node timers may also be copied. +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. ### replacenodes @@ -235,15 +246,3 @@ Arguments: - **`--invert`**: Only search for nodes *outside* the given area. **Tip:** To only delete metadata without replacing the nodes, use the `--deletemeta` flag, and make `replaceitem` the same as `searchitem`. - -### `deletetimers` - -**Usage:** `deletetimers [--searchnode ] [--p1 x y z] [--p2 x y z] [--invert]` - -Delete node timers of a certain node and/or within a certain area. - -Arguments: - -- **`--searchnode`**: Name of node to search for. If not specified, the node timers of all nodes will be deleted. -- **`--p1, --p2`**: Area in which to delete node timers. Required if `searchnode` is not specified. -- **`--invert`**: Only delete node timers *outside* the given area. diff --git a/README.md b/README.md index 9ef6c45..fbea2c9 100644 --- a/README.md +++ b/README.md @@ -9,19 +9,16 @@ operations that would be impractical to do using WorldEdit. Since it is mainly optimized for speed, MapEditr is not as full-featured as in-game world editors such as WorldEdit. -MapEditr is originally based on [MapEdit][2], but rewritten in Rust, -hence the added "r". Switching to a compiled language will make MapEditr more -robust and easier to maintain in the future. +MapEditr is originally based on [MapEdit][2], but rewritten in Rust, hence the +added "r". Switching to a compiled language will make MapEditr more robust and +easier to maintain in the future. [1]: https://github.com/Uberi/Minetest-WorldEdit [2]: https://github.com/random-geek/MapEdit ## Installation -TODO: This section is vague. - -Pre-built binaries are available on the Releases page. This is the easiest way -to get MapEditr. +TODO: Pre-built binaries To compile from source, you must have Rust installed first, which can be downloaded from [here][3]. Then, in the MapEditr directory, run: