== TOGoS's Minecraft Map Generator ==

TOGoS's Minecraft Map Generator (TMCMG) is a Java application for
generating terrain data (chunk files) for Minecraft Alpha based on
user-defined terrain functions.  It includes a GUI for previewing
the generated terrain before exporting it, and can also be run from
the command-line.  It can also be used as a GenerateFS server and
generate chunks as needed to generate infinite terrain (see end of
this document for instructions for use with GenerateFS).



== GUI Notes ==
=== World Preview ===

This window shows side and top views of the terrain resulting from
interpreting the loaded script.  You can move around using the arrow
keys and zoom in and out using plus and minus.  For now this shows
only base terrain--no chunk-based objects such as trees or grass will
appear in the preview.  The number next to "MPP" near tht bottom
indicates Meters Per Pixel.

=== Export Chunks ===

This window pops up when you select Export Chunks under the File menu.
To select an output directory (this should be a directory directly
under 'saves/' for SP data), you must browse to that directory and
select a file directly within that directory, such as 'level.dat'.

The 4 boxes under the output directory selection are to give the
X and Z coordinates of the northeastern-most corner and the width and
height of the area to generate.  X, Z, width, and depth are all in terms
of chunks, which are 16 blocks (16 meters) on a side.

When you hit 'Generate' it will start generating new data for
those chunks and writing them into the chosen output directory.
WARNING: THIS WILL OVERWRITE ANY EXISTING TERRAIN/BUILDINGS/OBJECTS
IN THE AREA, so either back up your data before generating, or only generate
on maps that have nothing you want to keep.

There's an experimental job system for exporting chunks that can be
enabled at any time (even while an export is in progress) by checking
the 'Use job system' checkbox.  In the future this may be able to take
advantage of spare computers, but for now is limited to the number of
CPUs on your PC as returned by Runtime.getRuntime().availableProcessors().

== TOGoS Noise Language ==

TOGoS Noise Language (TNL) is the language for defining terrain
generation functions.  TNL files contain any number of named expression
definitions and one non-named expression that will be used when generating
terrain.  Expressions can refer to named expressions defined earlier using
their name.  See scripts/example.tnl for an example script using many
different predefined and user-defined functions.

=== Noise Functions ===

Since function definitions in TNL do not explicitly give their
parameters, using name( parameters ) syntax to indicate composition
of functions rather than their final application (in OOP terms this
can be thought of as creating an object graph by calling constructors
without calling methods on the resulting objects (in fact that is
what's happening behind the scenes)), the following definitions use
square[ brackets ] to denote that final application.  Where
no constructor arguments are needed, parentheses in TNL are optional.
e.g. you may write 'perlin()' or just 'perlin', since the Perlin
noise function's constructor takes no arguments.  Words in <angle
brackets> denote placeholders for expressions.

+, -, *, / (expr1,expr2,...)[x,y,z] -> value
  - add, subtract, multiply, and divide outputs of at least 2
    functions.  These can be written using infix notation, where
    standard precedence rules apply.  e.g.  the following 3
    expressions are equivalent:
    
      a - b + c * d / e
      a - (b + ((c * d) / e)) 
      -( a, +(b, /( *(c, d), e)))

perlin()[x,y,z] -> value
  - A function for generating smooth noise closely based on Ken Perlin's
    Improved 3D noise function.  The range of this function is -1 to +1
    and output is 0 at integer coordinates, so for example to create
    rolling hills using a single perlin noise function you should multiply
    the output by half the desired height between hilltops and valley floor
    and divide the inputs by the desired average distance between hills
  - e.g.  scale-in( 0.05, 0.05, 0.05, perlin ) * 8
    would result in hills about 20 meters apart and 16 meters from top to
    base.
  - See http://en.wikipedia.org/wiki/Perlin_noise

simplex()[x,y,z] -> value
  - Very similar to perlin noise, but based on a triangular grid, so in
    theory is somewhat faster and has less noticable directional artifacts.
  - The implementation used by TMCMG seems to have lower average amplitude
    than perlin noise, so you may want to multiply the output more to get
    a similar effect.
  - See http://en.wikipedia.org/wiki/Simplex_noise

translate-in( <xt>, <yt>, <zt>, <expr> )[x,y,z] -> value
  - fast input translation; xt, yt, and zt must all be constant
  - equivalent to <expr>[ x + <xt>, y + <yt>, z + <zt> ]

scale-in( <xs>, <ys>, <zs>, <expr> )[x,y,z] -> value
  - fast input scaling; xs, ys, and zs must all be constant
  - equivalent to <expr>[ x * <xs>, y * <ys>, z * <zs> ]

xf( <xt>, <yt>, <zt>, <expr> )[x,y,z] -> value
  - arbitrarily transform inputs to expr
  - equivalent to <expr>[ <xt>[x,y,z], <yt>[x,y,z], <zt>[x,y,z] ]

ridge( <min>, <max>, <expr> )[x,y,z] -> value
  - transforms the output of <expr> by folding it back and forth
    between <min> and <max> (which may be [x,y,z]->v expressions
    themselves) until it lies between <min> and <max>.  e.g.
    
      ridge( 2, 4, -1 )[?,?,?] = 3
    
    (to calculate by hand, 2 - -1 = 3, 2 + 3 = 5, 5 - 4 = 1, and
    4 - 1 = 3).

min( <expr1>, <expr2>, ... )[x,y,z] -> value
  - returns the lowest value returned by any of the component
    expressions at each input point. 

max( <expr1>, <expr2>, ... )[x,y,z] -> value
  - returns the highest value returned by any of the component
    expressions at each input point. 

fractal( <iter>, <hscale>, <vscale>, <ihscale>, <ivscale>,
    <ztrans>, <expr> )[x,y,z] -> value
  - Scales inputs to and outputs from <expr> over multiple iterations,
    summing the results.
  - All parameters except <expr> must be constant
  - iter = number of iterations
  - hscale = horizontal scale (inputs will be divided by this) on
    first iteration
  - vscale = vertical scale (output will be multiplied by this) on
    first iteration
  - ihscale = how much to multiply hscale between iterations
  - ivscale = how much to multiply vscale between iterations
  - ztrans = how much to translate z for each iteration

cache( <expression> )[x,y,z] -> value
  - Caches the result of the wrapped expression to speed up processing
    when that expression is evaluated multiple times for the exact
    same input.
  - Should not alter the output at all, but will improve performance
    in some cases.
  - Ideally the compiler would be able to figure out what expressions
    are used multiple times for the same inputs and automaticall insert
    these, but that hasn't been implemented, yet.

=== Other Functions ===

To define a world in Minecraft, you need more than a simple
[x,y,z] -> value function!  You also need to define what materials
go where, how to distribute objects such as trees, and what other
post-processing steps to perform on chunks before they are saved.

Here is a description of some of the functions that help accomplish
that:

layered-terrain( <layer1>, <layer2>, ...,
    <processor1>, <processor2>, ... )
  - defines a world generator that generates terrain based on a list
    of ground material layers and chunk processors.
  - when layers of material overlap, later layers' materials override
    those of earlier layers.  For instance if the first layer at a given
    point on the map is water (material) from 0 (floor) to 64 (ceiling),
    and the second layer is bedrock from 0 to 1, the bedrock will
    replace the water in the bottommost block at that point.

layer( <material-id>, <floor-height>, <ceiling-height> )
  - define a material layer for use with layered-terrain
  - material-id is a constant integer representing the material to be
    placed.  This can be a named material in the 'materials'
    namespace, such as 'materials.sand' (without the quotes).
  - floor-height and ceiling-height can be [x,y,z] -> value functions
    that give the height at any x, z position on the map.  x,z map
    coordinates become the x and y inputs - the z input to the
    height function will always be zero.

=== Chunk post-processors ===

These are applied to chunks after all material layers:

grassifier
  - adds grass to the topmost block if it is dirt

winterizer( winterness-function )
  - if topmost block is water, turns it to ice, otherwise adds a layer of
    snow above it wherever winterness-function returns > 0

lighter
  - attempts (it's currently not completely correct) to initialize
    proper light values throughout the chunk based on shadows, water,
    etc.  It is recommended that you include this as the last component
    to layered-terrain.

flag-populated
  - sets the 'terrain populated' flag on chunks so that Minecraft does
    not try to add veins and calculate lighting itself.  Note that
    Minecraft does a MUCH better job of calculating lighting than TMCMG
    does, so you may want to leave this out unless you are very
    particular about where ores (and ash, and maybe some other stuff)
    get placed.

tree-populator( <tree-type>, <density-function> )
  - places trees at pseudo-random locations in chunks, with their
    placement being more likely where <density-function> returns
    higher values.
  - density-function = [x,y,z]->v expression giving trees per square
    meter.  As with layer height functions, the x and y inputs
    to the function come from world x and z, and the z input will
    always be zero.  The return value is interpreted as number of
    trees the populator will *attempt* to place--it may fail to place
    some if they would be put on a surface other than dirt or if
    there are obstacles that prevent them from fitting.
  - for now, <tree-type> is limited to the constants:
    tree-types.round
    tree-types.pine

    
== Using with GeneratorFS ==

If you are running minecraft on Linux you can use TMCMG as a GenerateFS
server and generate new chunks on-the-fly.  At this point there are probably
a lot of bugs and performance issues, but you can try it.

On Ubuntu (possibly other Debian-based distros), make sure you have the
FUSE dependencies:

  sudo apt-get install libfuse-dev pkg-config

Check out the GenerateFS source from github:

  git clone git://github.com/TOGoS/GenerateFS.git

Enter the GenerateFS directory and 'make test' to make sure it works.

  cd GenerateFS
  make test

(While it's compiling you may see a few warnings like:
src/fusetest.c:146: warning: initialization from incompatible pointer type
I haven't figured out what's up with those, but it doesn't seem to cause
any problems).

Choose a directory on the server where minecraft is running to store
generated terrain data OUTSIDE OF minecraft's saves directory/the directory
Minecraft stores level data in, for example let's say
  /home/ted/World1-backing-data.
Create that directory with mkdir if it does not exist.

Run genfs (unless you copy it to your a directory on your command path you
will have to write out the whole thing, such as
/home/ted/programs/GenerateFS/build/genfs), giving the world directory
(such as World1) as an argument.  The world directory should be *empty*
before you run this command, as its contents will be mapped to the fake
filesystem.

  genfs -f /home/ted/minecraft-server/World1

-f means to run the filesystem in the foreground.  This isn't required but
makes it easy to kill the process in case it starts misbehaving.

You can also specify --server-host=<host> and --server-port=<port>, but
for this example we'll use the default 127.0.0.1, port 23823.

In another console, run the TMCMG server...

  java -cp TMCMG.jar togos.minecraft.mapgen.server.ChunkServer -data-root /home/ted/World1-backing-data -gfs-port 23823 DIM-0=example.tnl

DIM-0=example.tnl tells it to use the terrain function defined by example.tnl
for the overland world.  DIM-1=somescript.tnl should allow you to define
one for the Neath but I haven't tested that yet...

Now run minecraft or minecraft_server and try loading up that world!




== Contact ==

If it doesn't work, e-mail bug reports and complaints to

  togos zero zero at gee male daught com.