Minecraft Region Scanner

This project is **a Minecraft 1.7.10 (only) command line utility to analyze and mass edit region files**.

It also fully supports the Lord of the Rings mod (LOTRmod) v35.3.

It can run on any platform with a Java Runtime Environment 1.8+ installed.

The project is completed. Things in red are not yet implemented ideas.

## Usage

It can:

* analyse and produce stats on the processed region files (**-s** / **--scan**)
	+ list generated chunks
	+ show blocks distribution
	+ list biomes (both Vanilla and LOTR mod biomes and variants)
		- provide the Middle-Earth map to use for LOTR biome identification (**-m** / **--map** with path/to/map.png argument)
			* If this option is omitted and a "map.png" file exists in the current directory, it will be used
	+ list entities (NPCs, and some items) with their location and (if set) NPC names:
		- show dropped items (with thrower's name if set)
		- show items in item frames
		- show LOTR Banner protection information
		- show NPCs spawned by Respawners
			* *NB: NPC names can be defined in other languages or character sets, such as Russian/Cyrillic for General Structures builds. Use the -n / --rename option to transliterate Cyrillic characters to Latin ones*
	+ list tile entities (specific blocks such as chests & containers, portals, red stone devices, (re)spawners, etc.) with their location
		- show items in containers (those with standard Itemstacks, plus LOTR Weapon Racks)
			* *NB: except for Ender Chests contents which are not stored in region files*
		- show content of LOTR Butterfly Jars and Bird Cages, Flower Pots (both vanilla and LOTR), Plates, Mugs, Mob Spawners (both vanilla and LOTR)
		- display text on signs and LOTR chiseled blocks
		- display commands of Command Blocks
		- *NB: Books, Signs and chiseled blocks can be written in other languages or character sets, such as Russian/cyrillic for General Structures builds. A possible fix would be to develop some translation option*
	+ identify cliffs by analysing borders height differences between internal chunks borders
		- *These cliffs could be caused by terrain generation bugs, importing region files with different seeds, terrain generation changes between different LOTR mod releases, etc.*
		- *NB: the processing would need to be completely different to do it between neighboring regions. So it would be a task for another utility*
	+ report structural and content errors while reading the file
	+ *NB: this scan action is the last one performed. The counts showed are those after all of the other actions have been processed...*
* mass edit blocks and items IDs in a Minecraft region file from those used in a input level.dat file to those used in a output level.dat file (**-f** / **--from** / **-t** / **--to** / with path/to/level.dat argument)
	+ if the input level.dat file is omitted:
		- a "level.dat" file in the current working directory will be used if it exists
		- or else default values for a vanilla Minecraft installation will be used
* fix unknown blocks and items by removing them (**-u** / **--fixunknown**)
* fix item stacks with more than 64 items (**-S** / **--fixstacks**)
	+ Any value above 64 is reset to 64
* fix excessive number of entities in a single spot (**-e** / **--fixentities** / with threshold)
	+ Entities of the same type in the same spot above the threshold will be removed
* replace or delete blocks and items (**-r** / **--replace** / with inline list or file reference)
	+ use this to fix blocks and items not available in the Middle-Earth dimension with @NotOfMiddleEarth.cfg
	+ inline list is done with the following syntax:
		- b,block\_source\_name,block\_target\_name or DELETE or AMBIANT
			* AMBIANT analyses the surrounding blocks and replace by the most common one, different from the block replaced (whatever its data value)
		- i,item\_source\_name,item\_target\_name or DELETE
			* this even works with LOTR pouches contents (pouches are the only item that can contains other items while stored in a container or throwed on the ground)
		- multiple blocks & items are separed by a slash character
	+ file references are done with the following syntax:
		- @path/to/file
		- The file contains one value per line
		- Lines starting with "#" are considered to be comments and are ignored
* clear entities (**-k** / **--kill** / with inline list of file reference)
	+ inline list is done with the following syntax:
		- ALL (including non living ones (such as "Item" (for clearing throwed items), "lotr:Banner"))
		- some ID indicated by the —scan option
		- multiple entities are separated by a slash character
* delete or preserve only a list of chunks (**-d** / **--delete** / **-p** / **--preserve** / with inline list or file reference)
	+ inline list is done with the following syntax:
		- absolute chunk coordinate in the form cx,cz
		- multiple chunks are separated by a slash character
	+ taking into account blocks marked with Minecraft Region Manager?
* transliterate Cyrillic characters in entities names, owners of LOTR items and written books authors (**-n / --rename**)

## Further development ideas

And perhaps (in no peculiar order):

* autocrop chunks around player made blocks (builds) including a specified surrounding distance of unbuilt terrain in chunks
	+ Would be useful for our Region Merger project
* smooth borders height differences
	+ *NB: but with no generation of surrounding chunks as this needs to be done in game*
	+ This would be useful to fix minor terrain glitches, not for merging whole sets of region files...
* generate a 512x512 heights map picture for each region file
* generate a 512x512 biomes map picture for each region file
* generate a 512x512 terrain map picture for each region file (showing player made or mod generated top level blocks): would be useful to locate structures
	+ Draw lines between special blocks (signs, LOTR banners) to show frontiers between players controlled territories
* change biomes in chunks, both Minecraft and LOTR mod variants
	+ *NB: LOTR mod biomes can’t be changed because they are defined in the mod’s map, not in region files*
* relocate a region file (ie. change all block’s and chunk’s coordinates references to those of the intended destination)
	+ *NB: for example, this can be useful if the LOTR mod map changes significantly (the case where Umbar coast got moved inland springs to mind...)*
* fix abnormal distribution of blocks (for example, way too much mithril in Moria general structure)
* report location of specified ordinary (=without NBT tags) blocks
* use some translation API to translate book contents, signs and chiseled blocks text from one language to another
* report invalid (or unknown) data values based on a config file (to be user modifyable)
* use a config file (for the display threshold in the region map, the excessive number of entities threshold, the default output preferences, etc.)

## Discarded ideas

* creating tile entities for blocks replaced by known blocks: Minecraft doesn't complain about missing tile entities for blocks that should have them and automatically creates them when closing the region file
* detecting orphaned or unmatching tile entities: these errors seems to be without consequences and would be tedious to detect as tile processing is done after blocks processing

## Examples

Region Scanner is a command line utility.

If you're using Microsoft Windows, that means that you can't just click on the jar file to run it.

Instead, open "cmd" from the "Run" windows, and then type your command line at the prompt.

Minimum syntax:

```
RegionScanner region_file_1.mca [region_file_2.mca ...]

```

**You MUST provide RegionScanner with the location of the level.dat file of your world** using the following option (to be inserted between the command name and the list of the MCA files to process):

```
--from path/to/level.dat

```

Of course, replace path/to/level.dat with the PATH to the level.dat file of your world. For convenience, you can copy it in your region files folder and you won't have to use this option.

Then you must at least use 1 action (parameters provided are just examples):

```
--delete 7596,1676/7595,1686
--delete @path/to/file
—-fixentities 200
--kill ALL
--kill Bat/lotr.MordorOrc
--preserve 5,10/5,11
--preserve @path/to/file
--replace b,minecraft:coal_ore,minecraft:diamond_ore/i,lotr:item.mugRedGrapeJuice,lotr:item.mugRedWine
--replace @path/to/NotOfMiddleEarth.cfg
--scan
--fixstacks
--to path/to/new_level.dat
--fixunknown
--rename

```

Other possible command line options:

```
--help
--logLevel 1
--logLevel 3 # debuging information (gore!)
--map path/to/map.png
--output new # modified region files are created as ".new"
--output old # modified region files are backuped to ".old"
--output overwrite # No backup of modified region files
```

## Caveats

* Although you can use LOTR maps for versions older than 34.3, Minecraft Region Scanner only supports RGB values and IDs from version 34.3 and above
* Processing is not guaranteed for region files generated with Minecraft versions above 1.7.10 because the file format changed in later versions (HeightMaps, Section Palettes & BlockStates, etc. ItemStacks started using names instead of values from version 1.8)
* When you replace a block with one that should have NBT data in an associated tile entity, no tile entity will be created because this tool will never know the NBT data for blocks added in any existing mod!
	+ NB: Minecraft doesn't complain about that and automatically creates the missing tile entities when closing the region file.
* When you replace an item the count is automatically set to 1, whatever the initial number of items, as we don't know how many of these items are stackable
* The Cyrillic tranlisteration option does not fully handle complex "LOTROwner" tags (for example, "Yagnákh, Гундабадский орк-лучник" gets transliterated to "Yagnákh, Gundabadskiy ork-luchnik", but not translated to "Yagnákh, Gundabad Orc Archer")

## Limits

* This tool does not handle more than 256 vanilla biomes, plus 256 LOTRmod biomes
* This tool does not hangle items with IDs above 8192 or with data values above 4096. Please report if you find such cases

## Download and contribution

You can download the binary distribution of the tool from our web site.

This tool's source code is available on GitHub for download or community improvement. Create a *new branch* with your edits and ask for a *pull request* to merge them in the *master branch* (check this tutorial to understand GitHub concepts).