GeoGen Documentation

Introduction

GeoGen (shortly GGen) is an open-source procedural heightmap generator. Scripting support is provided by Squirrel engine. GeoGen grants the scripts ability to generate the most various terrain shapes while keeping them simple and easy to read.

Contents

Using the console interface

The command line syntax for the geogen.exe is basically this:

geogen -i path_to_script -o path_to_output [options] [script_arguments]

Neither argument is really obligatory - GeoGen can be ran directly from Windows.

script_file indicates relative path to a Squirrel script file. output_file will be the place where the output bitmap is saved. If this file already exists, it will be overwritten.

script_arguments is a space-separated list of arguments in the order script requests them. If a script requests an argument value and you don't set it, default value proposed by the script is used. You can use "r" instead of any value to pick it randomly.

options can be used to adjust more advanced aspects of the generator. Complete list of options:

-i FILE, --input FILE
Input squirrel script to be executed.
-o FILE, --output FILE
Output file, the extension determines file type of the output (*.bmp for Windows Bitmap and *.shd for GeoGen Short Height Data are allowed). Set to "../temp/out.bmp" by default.
-d DIRECTORY, --output-directory DIRECTORY
Directory where secondary maps will be saved. Set to "../temp/" by default.
-v FILE, --overlay FILE
Overlay file to be mapped on the output. This file must be a Windows Bitmap file one pixel high and either 256 or 511 pixels wide.
-s SEED, --seed SEED
Pseudo-random generator seed. Maps generated with same seed, map script, arguments and generator version are always the same.
-a, --all-random
All unset script arguments are generated randomly.
-z, --ignore-zero
Height data range will be rescaled to fit the output file format including negative value. Zero level will probably not be preserved.
-n, --no-rescaling
The height data will not be rescaled at all. Might cause color overflows if the format's value range is lower than <-32787, 32787>.
-h, --split-range
Splits the value range of a file format, which doesn't support negative values, so lower half of the range covers negaive values and upper half covers positive values. Value "(max + 1) / 2" will be treated as zero.
-?, --help
Displays detailed usage help.
-x, --syntax-check
Will print OKAY if script is compilable or descibe the error found.
-p, --param-list
Lists the script's parameters in machine-readable format.
-e, --simple
Mode which allows all necessary data to be entered interactively. This mode is automatically activaded if no params were entered.
-m, --manual
Script arguments will be entered interactively.
-D, --disable-secondary-maps
All secondary maps will be immediately discarded, ReturnAs calls will be effectively skipped.
-V, --overlay-as-copy
Color files with overlays will be saved as copies.
-g SIZE, --grid SIZE
A grin with spacing SIZE will be painted onto output file along with chosen color overlay.

Script syntax

For Squirrel syntax, please refer to the language's official documentation.

Script API

Script layout

The first function script must contain is named "GetInfo" taking one string argument and also returning a string. This function will be repeatedly called by the API requesting various information. Typical content of this function is a switch statement responding to individual request strings.

function GetInfo(info_type){
	switch(info_type){
		case "name":
			return "Name of the map";
		case "description":
			return "Long and hopefully not boring description of the map";
		case "args":
			GGen_AddIntArg("width","Width","Width of the map.", 1024, 128, 20000, 1);
			GGen_AddIntArg("height","Height","Width of the map.", 1024, 128, 20000, 1);
			// some more arguments
			return 0;
	}
	return 0;
}

The script must also contain a function named "Generate" with body of the script logic. The function must return one GGen_Data_2D object.

A very simple function "generating" an empty heightmap (all zeroes) could look like this:

function Generate(){
	// load values of the arguments
	local width = GGen_GetArgValue("width");
	local height = GGen_GetArgValue("height");
	
	// Create a new 2D data array with given width and height filled with value 0
	return GGen_Data_2D(width, height, 0);
}

Standard library

GeoGen API utilizes the Math module from the Squirrel Standard Library, you can find reference of these functions in its documentation.

API Reference

See the API Reference for complete overview of all functions exposed by GeoGen to the scripts.

License

Copyright Matěj Zábský, 2009.

GeoGen is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 2 of the License, or (at your option) any later version.

GeoGen is distributed in the hope that it will be useful,but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with GeoGen. If not, see http://www.gnu.org/licenses/.