Cheshire Cat Builder's Helper mod for Minecraft, v2.6
-----------------------------------------------------

Steve Shipway, Sep 2015
steve@steveshipway.org
http://www.steveshipway.org/forum/viewforum.php?f=44 (Support and blueprint library)

VERSION 2.7 : bugfixes, new branching control, improved mob rotation

This mod extends Minecraft to allow you to copy structures with one command, and to 
recreate saved structures with a single mouse click.  This is intended to assist
world builders, who want a fast way to create and duplicate structures while in the
world, without having to use an external third-party editor.

It also allows you to share your saved structures with other builders, and to 
accumulate a library of useful structures.

Finally, the definition language -- called a 'blueprint' -- allows for random 
elements and recursion.  This means that you can in fact generate random structures
from a single blueprint; such as a 'house' definition that each time creates a slightly
different house, with varying design, colour, contents, and so on; this makes more
realistic worlds easier to build.

A blueprint contains one or more plans.  A plan contains one or more directives.
Only public plans are generally listed.

There is support for the Ruins Template and MCEdit Scematics formats, which can be
read in and converted to Blueprint format.

The Undo option ( /bp undo ) will back out the last build; if you have autocommit set
to false in the configuration file, then you need to use /bp commit to commit changes.

This mod will mostly work in a server environment, but requires the client side to
have the mod as well.  In general it is intended for use in a single-player setup
for building work.

To run this mod, you need:
--------------------------

1. Minecraft.  Of course.  Version 1.7.10 or 1.8.0
2. Minecraft Forge installed and working (note that Forge for 1,8 is still beta)
3. Use the latest Java 1.8, whichever version of minecraft you have
4. A local single-player server.  The Builder's Helper features only work in
   single-player local mode.  You can remove the mod without problem after building
   your world and then run in multiplayer mode.

To install this mod:
--------------------

1. Copy the appropriate .jar file to your .minecraft/mods directory.
2. Optionally, copy the bp/ directory and its contents under the .minecraft/config directory
3. Copy the cheshirecat.cfg into your .minecraft/conf directory, and modify it if you wish
4. If you with to use the Ruins support, you can optionally copy the Ruins directory
   of templates under the bp directory to make them available.

Blueprint Files:
----------------

Blueprint files define structures which can be created in game.  These files should
be located under the .minecraft/config/bp directory, and should have a .bp extension
or a .cfg extension (.bp is recommended).

In addition, any files with a .tml extension will be assumed to be Ruins Templates, and
will be autoconverted into .bp files in the same directory.

Any files with a .schematic extension will be assumed to be MCEdit Schematic files, and
will be automatically converted to .bp files in the same directory as with tml files.

Other filenames will be ignored.  Directories not starting with a '.' will be recursively
scanned for blueprint files.


To use this mod:
----------------

1. Everything revolves around the "Magic Wand" object, which you will find in the
   Creative Mode 'tools' tab.  Each wand can be set to link to a specific plan name, which 
   will be created at the target block when right-clicked.

   The wand only works when held.

   The wand can also be created with the recipe rgr/gsg/rgr where r=redstone dust, g=glowstone
   dust, s=stick.  This can be disabled in the cheshirecat.cfg file.

2. There are three new commands.  These are player-only, and can only be used if you are
   either in Creative mode, or holding a Wand.

/blueprints : This manages the blueprints library.  It can be abbreviated to /bp

   /blueprints list
      List all the public defined blueprints
   /blueprints reload
      Reload all the blueprints from the config/bp folder
   /blueprints delete NAME
      Delete the plan called 'NAME' from memory (not from disk)
   /blueprints help NAME
      Show help line for blueprint NAME
   /blueprints build NAME
      Build plan NAME directly in front of the player
   /blueprints copy NAME x1 y1 z1 x2 y2 z2
      Copy the solid blocks from the volume bordered by the specified corfners,
      and store it in the new plan called NAME
   /blueprints save NAME
      Write the plan NAME to disk as config/bp/NAME.cfg
   /blueprints print NAME
      Print out the actual code for plan NAME.  Does not work well.
   /blueprints commit
      If not in autocommit mode, commit all changes in the current undo buffer.
   /blueprints undo
      Undo all changes since the last Commit.  In autocommit mode, a commit is
      done immediately before any build.  This will not undo mob placement, as they
      may have moved, and may have issues with replacing attached objects such as
      torches (which may fall off).
   /blueprints buffer
      Tell you how full the Undo buffer currently is.

/build : Shortcut to building.  Should work from console as well.

   /build NAME x y z rotation
      Build plan NAME at the specified location and rotation

/wand : Control the wand object in hand.  This only works on the wand that is
        currently being held, so obviously you must be holding a wand to use it.

   /wand show
      Display the plan name and description currently set for this wand.  You can also
      see this information by hovering over the item in the inventory.
   /wand set NAME
      Set the wand to produce the plan NAME when right-clicking
   /wand lock
      Lock the wand to the current plan.  This cannot be undone.
   /wand copy NAME
      Start copying to new plan NAME.  Right-click on the BOTTOM opposite corners of the 
      area to copy (height is worked out automatically)

3. Individual plans can be tagged as "Autogenerate" using the AUTO directive in the blueprint.
   If this is done, and autogenerate is enabled in the cheshirecat.cfg, then the plan will
   be randomly generated in new chunks as the world builds, according to the probability and
   list of biomes specified in the plan.  This, of course, requires the module to be loaded;
   however the generated structures will still work if the module is subsequently removed.
 

Examples 
--------

Example:  To create a cottage. 

  There is already a blueprint ( cottage.cfg ) that builds a cottage.  So, we set the wand to it.
  a) give yourself a wand object
  b) hold the wand object
  c) /wand set cottage
  d) Right-click where you want the cottage to be built.

Example:  To save a structure to disk

  a) Build your structure.
  b) note the coordinates of the top-left-front and bottom-right-back corners (use F3 if necessary)
     Lets say they are x,y,z and a,b,c (either order is fine)
  c) /bp copy mystructure x y z  a b c
  d) /bp save mystructure
  e) Now we have config/bp/mystructure.cfg which can be edited as required

Example: To copy a tree with the wand

  a) Hold a wand object
  b) /wand copy tree
  c) Right-click on the ground on one corner of the tree
  d) Right click on the ground on the opposite corner (the height is determined automatically)
  e) You can now right-click on the ground anywhere to create a copy of the tree.

Manual creation ( see bp/readme.cfg )
---------------

  The blueprint definition language is very simple, and can be more efficient than the
code generated by the '/bp copy' command.  There are many examples in the supplied blueprints.

  Each plan starts with "public plan NAME DESCRIPTION" to define a plan called NAME with
a description DESCRIPTION.  Use "private" instead of "public" if you want it hidden.  I suggest
you give a name that is prefixed with the name of the blueprint, and with an underscore if it
is private.  EG:  If the file is foo.cfg, the it might define the public plan "foo_bar" or
the private plan "_foo_baz".  The main public plan should be 'foo'.

  Each plan ends with "END".  

  Comments start with "#".

  You can specify options using "OPTION".  The only options currently available are "RECURSIVE"
"FLOAT" and "DRY", and 'recursive' is not properly implemented yet.

  A plan may CALL another plan, at a new position translated and rotated.  Note that translation 
is done AFTER rotation.  Rotation is specified in quarter-turns around the origin.  See the
plan 'dome.cfg' for an example on how to use this.

  A plan can set a BLOCK or an AREA with a specified block.  This can optionally specify a Data 
Value, and any NBT Block Entity data.  Examples exist in the supplied plans (see flower.cfg)

  Blocks can be specified as 'soft' with the '~' prefix.  Solf blocks will only replace
air or water, not existing blocks.  See water_table.cfg or dome.cfg for an example on how to
use this.

  The RANDOM and CHANCE directives allow you to add an element of randomness.  See the tower.cfg
definition for an example of how this can be used.

  The IFBIOME and IFBLOCK allow branching based on current biome or the content of a block
relative to the current plan origin.  This can be used in recursion.

  The BREAK directive will stop the current plan and return to the calling plan.  If there
is no calling plan, then it will end processing.

  'Metablocks' are block names such as OLD_STONE, which are replaced by a different block
depending on current biome and randomness.  See meta_cottage.cfg for an example of using these.

Auto Generation
---------------

The directive "AUTO <chance> <biome list>" allows a plan to be flagged as auto-generate.

The chance is a probability out of 100,000; the biome list uses the internal biome names 
(press F3 in Minecraft 1.8 to see the current biome); you can also use 'All'.  Multiple
names should be comma separated.

Plans will be generated based at a random point within the chunks, at ground level (not counting
trees and foliage).  The plan itself may also specify "float" and/or "dry" to make it be based
above or below water.  See the balloon and cottage example plans for autogeneration 
examples. 

Ruins Support
-------------

The popular Ruins module does a similar job to Builders Helper, defining structures in a
format it calls "Templates" with a .tml suffix.  Builders Helper can now read these files,
and will convert them to Blueprint format (though not as efficiently as possible), allowing
you to use the Ruins library of templates as well as the Blueprint library.

Schematics Support
------------------

The MCEdit Schematics format is used in many published definitions available on the internet.
These files have a .schematic suffix to their names.  Builders Helper can read in these files
and converts them to Blueprint format; by default, air blocks are 'soft', but you can set
an option in the module configuration file to change this.

Minecraft 1.7
-------------

The system will attempt to convert NBT and definitions using string object identifiers (such
as minecraft:dirt) to numerical, when building chest contents or blocks.  If a module name
is not given, 'minecraft:' is assumed.  There is also a pass done to attempt to correct 
common errors in chests and spawners; invalid chests will simply be empty, but invalid
spawners can crash the game.

Pictures from image files work, but take several seconds to display as they render 
progressively (as with maps).  This is caused by the Minecraft API.

Large paintings do not always render in the correct location.

Custom Blocks
-------------

If you have custom blocks, and they do not use one of the standard MC1.8 orientation
attributes, then you will need to tell the module how to rotate them.  Only DV-based
rotations are supported.  Edit the module configuration file and give the sequence of DV
values corresponding to quarter turns of the block -- there is an example in there
of how to format this.

KNOWN BUGS 
----------

  The rotation of custom blocks is not reliable.  If you block uses 'facing' as an EnumFacing
then rotation should work fine under 1.8.  There are custom rotation rules you can set in
the configuration file.

  It is possible to create an infinitely recursive plan, or one far too large.  This can cause
either the build or the copy to hang and break minecraft.

  This is intended to be used by a single-player local world.  While it may work in a remote
server, I've not tested this and doubt it would be reliable.

  This is a builder's tool, not intended for actual gameplay.  It would be a bit overpowered.

  There should be an option to '/bp copy' to allow copying water and/or air

  The 'recurse' option is not yet actioned.  All plans are implicitly recuseable.

  '/bp print' does not work correctly.

  Under Minecraft 1.7, an incorrectly defined Spawner or Potential (with an invalid EntityId or
Type) will cause the world to crash.  Minecraft 1.8 simply makes a Pig spawner.  The code will
attempt to fix most problems by replacing invalid NBT with a Chicken, but you can still cause
a crash if you try hard enough.  The crash occurs when the renderer attempts to draw the spawner
with a rotating central entity.

  Chest rotation is unreliable under Minecraft 1.7, though I'm not sure why.

  Rotation of paintings is unreliable under Minecraft 1.7; this appears to only affect
larger 4x4 paintings though.

  More feedback when there are errors in a plan would be better.  Currently, you need to look
in the Minecraft error log for details about syntax errors.

  Rotation of Command Blocks is unreliable as the internal command also needs to be rotated.
You may find issues with the CLONE, EXECUTE, and TESTFORBLOCKS commands, and with any custom
commands from mods.

FAQ
---

Q: Is this Open Source?

The source code in included with this package, and released under GNU GPLv2 or later.

Q: Do you have more pre-generated blueprints?

I will be adding them as I get them, probably to the website for download.  In particular, I
intend to make plans for various redstone constructs, like cannon, fire-arrow launcher,
and so on.  There are also a few pre-generated NBT files for use.

You can also now use Templates created for the Ruins mod system, which will be converted to
Blueprint format.  Most of these should work without modification.

Q: I recognise that house...!

For examples, I copied some structures from published maps.  These are credited in the
comments of the blueprint.  In particular, the gingerbread house came from Equestria, and
the balloon from Mountain Sky Village.  Both are very extensive and detailed maps, and I
recommend you download them if you like their style.  The temple is the one generated by 
the Lucky Blocks mod, and several other structures are ones I contributed to MCDungeon.

Q: Where can I submit my blueprint for inclusion?

Email it to me at steve@steveshipway.org, or visit the forum at www.steveshipway.org/forum
if Ive managed to set it up yet.

Q. My torch/trapdoor/sign keeps falling off the wall when I build the plan!

Make sure that you order your plan so that the block it is to be attached to is placed FIRST.
Otherwise, it may fall off when a nearby block placement causes a tile update.
Also, make sure you have the correct DV specified - possibly it is not being placed facing
in the correct direction.

The 2.6 version of the mod does a two-pass copy so that copied areas should be free of
this problem.

Q. Minecraft crashes on startup

Make sure you are using Java 1.8 or later.

Move all Blueprint files (including Templates and Schematics) to a different folder.  The
crash might be caused by an invalid blueprint that fails to parse.

Check the server log file for any error messages before the crash, and post them on the forum.

Q. I want to use this as part of a game

I think the wand is a little overpowered for that, but you do have the option to enable
or disable crafting of the wand in the cheshirecat.cfg file.  You can also pre-create a wand
that does something specific, and lock it so that it cannot be changed to a different
blueprint.  I might add a 'charges' option at some time, too.  This would allow you to have 
a wand that summons Zombies, for example, or that writes random graffiti on the wall.

Q. I want to include this in my Modpack

You can do this, provided that:
- You let me know via email at steve@steveshipway.org
- You include all relevant attributation (IE, you say who wrote it and where to get the latest version from)
- You do not charge people to obtain it in any way, including media costs.  Adfly downloads and the like are fine.
- I do not tell you that this permission is revoked. (only likely to happen if your modpack is in extreme bad taste)


WISHLIST
--------

- Sparkles on the screen as generation happens
- Proper server support using IMessages
- Synchronous generation in a separate thread, rather than pausing while build happens
- Support for conditional block options in template import
- GUI blueprint selector for wand, showing blueprint list, description and optional images
- Make wand optionally have a limited number of charges, ensure locked wand does not
  enable /bp command.
- Support for transparency in image files.