pymcworldgen
Alpha 2
========

This package is a pipelined minecraft world generator written in Python. This is a pre-release to help stir up discussion with other modders who have made terrain generators before or are currently developing terrain generation mods.

What's new in Alpha 2:
========
- LandmarkGenerator class, for placing a large number of landmarks easily.
- Beginning of the unit testing code, which means more bugs will get caught, sooner. You can run them yourself with 'runtests.py'

License:
========
    Free as in free speech, AND as in free beer! I provide this to all yalls, free of charge, just as long as you credit me if you use this source in other places.

Installation:
========

This mod depends on:
    Python 2.6: http://www.python.org/download/releases/2.6.6/ 
    numpy: http://numpy.scipy.org/
    pymclevel: https://github.com/codewarrior0/pymclevel
    pylab/scipy: http://www.scipy.org/PyLab (for saving graphs of heightmap data)
    c10t: http://www.minecraftforum.net/viewtopic.php?f=25&t=33803 (for taking a quick snapshot of the world)

    you can download these dependencies manually, or use the script 'get-dependencies.sh' if you're a linux user (who uses aptitude.)

Usage:
========
    Standalone Map Generation:
    python mcworldgen.py

    Test map will be saved to ./renders

    It just generates a random 16 x 16 map as 'testmap' and creates a c10t rendering of the map (given that c10t exists.)
	
Pipelined World Generation Design
========

	The terrain generators in pymcworldgen are built as an demand-driven image processing pipeline: Filters pass 
	2D arrays of heightmap data and 3D arrays of minecraft block ID's between eachother. Each stage refines the
	requested chunk further and further, until the final chunk is passed to either pymclevel or to Minecraft, where
	it can be saved as part of the map.
	
	There are several types of layers and filters, defined by what sort of data they output:
	
	Layer and Filter: output chunk block ID data (a chunk-sized 3D array of integers)
	LayersMask2d and MaskFilter2d: output chunk heightmap data (a chunk-sized 2d array of float values from 0.0 to 1.0)
	LayerMask3D, MaskFilter3D (not implemented yet): output chunk density data (a chunk-sized 3D array of float values from 0.0 to 1.0)
	
	Filters in pymcworldgen are demand-driven: this means that data is requested at the output of a filter, 
	and pulled forward from each of the filter's inputs. For instance, if we have a pipeline set up as follows:
	
	Layer --> TopSoilFilter --> WaterLevelFilter
	
	We activate the pipeline by requesting a chunk's worth of data from the last filter in the pipeline, WaterLevelFilter.
	We call WaterLevelFilter.getChunk(), which in turn will call TopsoilFilter.getChunk(), and eventually call Layer.getChunk(),
	recursively. Layer.getChunk() will return a 3D array of integers to the context of TopsoilFilter.getChunk(), and in turn
	TopsoilFilter.getChunk() will return its own chunk data to WaterLevelFilter.getChunk(). 
	
	Setting up your own filter is easy: create each filter, and pass in its inputs as constructor arguments:
	>> from layer import *
	>> pipeline = Layer()                         # in this example, pipeline always points to the last filter in the pipeline...
	>> pipeline = TopSoilFilter(pipeline)         # ... and is updated every time we add another pipeline stage.
    >> pipeline = WaterLevelFilter(pipeline)	
    >> mapchunk = pipeline.getChunk( 0, 0 )       # you can now pass 'mapchunk' to pymclevel and save it as a level.
	
	For more examples of how to set up filter pipelines, refer to mcworldgen.py
	
Credits:
========
Chrisknyfe (main developer)
lahwran (ideas & discussion)