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.

Introduction
Contents
Using the console interface
Script syntax
Script API
License

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);
}

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

GeoGen Documentation

Introduction

Contents

Using the console interface

Script syntax

Script API

Script layout

Standard library

API Reference

License