TuDee - Online Help

This help is the same as the help file distributed with TuDee.

Disclaimer of warranty
The source code examples are supplied "AS IS". Gojo Entertainment disclaims all warranties, expressed or implied, including, without limitation, the warranties of merchantability and of fitness for any purpose.
Gojo Entertainment assumes no liability for direct, indirect, incidental, special, exemplary, or consequential damages, which may result from the use of this source code, even if advised of the possibility of such damage.

Contents

1) Introduction
2) Acknowledgements
3) Project Overview
4) Tile Sets
5) Maps
6) Layers
7) Entities
8) Paths
9) Custom Variables
10) Keyboard and Mouse Controls
11) What Does That Mean?
12) Exporter Basics
13) Exporter Example
14) How to...
15) Technical

A warm welcome to TuDee's help file!

What is TuDee?

TuDee is a tile based map editor, primarily aimed at 2D games. It has a user-friendly interface, and is based on common concepts for building maps. Maps are also known as levels or stages in a game. Although TuDee is primarily aimed at 2D tile based games, it is flexible enough to use for various projects (e.g. it can be used as a spline placement tool for a 3D game's A.I. paths, or building levels for a puzzle game).

TuDee has a very flexible exporter, which works on a DLL basis. This means that you can program your own DLL to read data from a TuDee project. TuDee has a default text file exporter, and the provided sample code can be used as the starting point for your own DLL exporter.

What are Tiles?

Tiles are small images that are used to build a map with. (Maps are also referred to as levels or stages.) All the tiles for the map are stored on a single image (referred to as the tile image in the rest of the help file).

Each map has at least one layer, which is basically a grid. The tiles are placed on the map's grid. Tiles can be repeated on the grid. The grid stores the indices for the tiles. These indices refer to the tile's position in the tile image.

Here is an example of a tile set:

Here is an example of a map, using the above tile set:

Related Topics:
Tile Sets

A great Thank You to all of the following:

Tester and Consultant
Herman Tulleken

Luma
http://www.luma.co.za/
A creative and inspirational company.

tinyxml
tinyxml was used for loading XML files.
http://www.sourceforge.net/projects/tinyxml
tinyxml version 2.5.3
Original code (2.0 and earlier):
Copyright (C) 2000-2006 Lee Thomason (www.grinninglizard.com)

libpng
libpng was used for loading png files.
http://www.libpng.org/
libpng version 1.2.22 - October 13, 2007
Copyright (C) 1998-2007 Glenn Randers-Pehrson
(Version 0.96 Copyright (C) 1996, 1997 Andreas Dilger)
(Version 0.88 Copyright (C) 1995, 1996 Guy Eric Schalnat, Group 42, Inc.)
A complete list of libpng's contributing authors can be found at:
http://www.libpng.org/

zlib
zlib was used for loading png files.
http://www.gzip.org/zlib/
zlib version 1.2.3
(C) 1995-2005 Jean-loup Gailly and Mark Adler
"zlib1.dll" version 1.2.3.0 is used and can be downloaded from:
http://www.zlib.org/

Inno Setup
Inno Setup was used to create the installation file.
http://www.innosetup.com/
Inno Setup version 5.1.12
Copyright (C) 1997-2007 Jordan Russell. All rights reserved.
http://www.jrsoftware.org/

Overview

TuDee projects can be saved and loaded in its native binary format (.tdp), or in XML format. The binary files save and load faster than the XML files. Binary files are also smaller than XML files.
XML files are text files, therefore you can easily load these into your own program with the use of an XML parser.

Each TuDee project consists of the following elements:
1) Tile Sets
2) Maps
3) Layers
4) Entities
5) Paths
6) Mosaics

1) Tile Sets
A tile set is an image that contains the tiles. It also has various properties which describe the tiles in the image.
For example: the width and height of the tiles, the position of the first top-left tile in the image, and if there are any spaces between the tiles.
Note: The tile set stores a path to the image, it does not make a copy of the image.

2) Maps
A map consists of layers, on which tiles, entities and paths can be placed.
Each map uses only 1 tile set. The map also has additional properties (such as a name).

3) Layers
A layer is a grid which can hold tiles, entities and paths.
Each layer also has additional properties (such as a name, scrolling speed, background colour, opacity).

4) Entities
Entities are objects which can be placed on a layer. These include objects such as sprites, power-ups, triggers, etc.

5) Paths
Paths can be straight lines or Bezier curves. Click and drag a point to make it a Bezier curve.

6) Mosaics
A mosaic is a group of tiles that form an image. Mosaics are created by selecting tiles on a layer, and converting it to a mosaic. It works similar to copying and pasting tiles on a layer.

A tile set consists of an image that contain tiles, and various properties that describe the
tiles in the image.

Each tile set has the following properties:

Tile Set Name
A text string describing the tile set. The name does not have to be unique.

User ID
An ID for the tile set, supplied by the user. This ID is not used internally by TuDee. This can be used by the user to uniquely identify each tile set. The tile set's ID can be read with a custom exporter DLL.

Custom Variables
Each tile set has its own custom variables. Each custom variable is a text string.

Image
The name and path of the image to use for the tile set. The image must contain all the tiles for the tile set. The tiles can be laid out in a single row, or in multiple rows. The tiles must all be the same size (i.e. have the same dimensions).
Note: The TuDee project only saves the file name and path of the image, it does not keep an internal copy of the image.

Tile Dimensions
The dimensions of each tile in the image. This is measured in pixels.

Position of First Tile
This is the top-left position of the first tile in the image. This is measured in pixels.

Space Between Tiles
This specifies if there are spaces between the tiles, vertical and/or horizontal. This is measured in pixels.

Transparent Colour
A single colour in the image can be replaced with a transparent colour when the image is drawn. This can be turned on or off with the check box. The transparent colour can be selected by clicking on the image's preview, or by clicking on the colour button (which will bring up a colour dialog).

Code Example:
The following code can be used to find a tile's position on a tile set image:

A map consists out of one or more layers, on which tiles, entities and paths can be placed.
Each map uses only one tile set.

Each map has the following properties:

Map Name
A text string describing the map. The name does not have to be unique.

User ID
An ID for the map, supplied by the user. This ID is not used internally by TuDee. This can be used by the user to uniquely identify each map. The map's ID can be read with a custom exporter DLL.

Tile Set
The tile set used by the map. Each map uses only one tile set.

Export Map
A check box that indicates if the map must be exported. This value is not used internally by TuDee. Programmers can read this value during the export to determine if the map must be exported.

Custom Variables
Each map has its own custom variables. Each custom variable is a text string.

Related Topics:
Layers

A layer is a grid on which objects are placed (e.g. tiles, entities, paths).
Layers can help you to organise a map better. For example, you might have four layers:
1) a background layer
2) a layer for decorative objects
3) a layer for placing moving objects
4) a layer for placing triggers

Each layer has the following properties:

Layer Name
A text string describing the layer. The name does not have to be unique.

User ID
An ID for the layer, supplied by the user. This ID is not used internally by TuDee. This can be used by the user to uniquely identify each layer. The layer's ID can be read with a custom exporter DLL.

Main Layer
A check box that indicates if the layer is a main layer. This value is not used internally by TuDee. It can be used, for example, to indicate if the layer contains collision, sprites, etc.

Dimensions
The layer's width and height. This value is measured in tiles (i.e. grid blocks).

Wrap
There are two wrap check boxes, one for horizontal wrap and one for vertical wrap. These indicate if the layer wraps (repeats). If this is checked then the layer will be drawn and repeated beyond its specified width/height.

Custom Variables
Each layer has its own custom variables. Each custom variable is a text string.

Position
The layer's position relative to the world origin. The world's origin is located at the coordinates 0, 0 (X and Y coordinates, or horizontal and vertical coordinates). The layer's position is measured in tiles (i.e. grid blocks).

Background Colour
The layer can have a background colour, which will be drawn behind all the objects on the layer. This can be turned on or off with the check box.

Background Image
The layer can have a background image, which will be drawn behind all the objects on the layer. This can be turned on or off with the check box. The image will not be stretched to fit the layer dimensions.
Note: The TuDee project only saves the file name and path of the image, it does not keep an internal copy of the image.

Scroll Speed
The layer's horizontal and vertical scroll speed can be specified (float values, e.g. 1.3). These values are not used internally by TuDee, but it can be read during export.

Opacity
This specifies the layer's opacity level (i.e. transparency). The range is 0 to 255. A value of 0 is completely transparent and a value of 255 is completely solid.

Related Topics:
Maps

Entities are objects which can be placed on a layer. These include objects such as sprites, power-ups, triggers, etc.

There are two types of entities: parent entities and child entities.
The parent entities contain common data used by the child entities. Child entities are placed on a layer, and are copies of the parent entities. If you change a parent entity's properties then it will affect all the child entities of the parent entity.

Each Parent entity has the following properties:

Entity Name
A text string describing the entity. The name does not have to be unique.

User ID
An ID for the entity, supplied by the user. This ID is not used internally by TuDee. This can be used by the user to uniquely identify each entity. The entity's ID can be read with a custom exporter DLL.

Image
The file name and path of the image to use for the entity (e.g. a single frame image of a sprite).
Note: The TuDee project only saves the file name and path of the image, it does not keep an internal copy of the image.

Trigger
The trigger check box indicates if the entity is a trigger. Trigger entities do not need an image. The trigger will be drawn as a rectangle or a circle when no image is provided. The image will be scaled to the value of the trigger's radius, or width and height.

Rectangle Trigger
The Rectangle trigger radio button indicates if the trigger is a rectangle. The user can specify the rectangle's width and height (see child entities below).
Note: The rectangle trigger is drawn from the entity's top-left position.

Circle Trigger
The Circle trigger radio button indicates if the trigger is a circle. The user can specify the circle's radius (see child entities below).
Note: The circle trigger is drawn from the entity's top-left position.

Default Rectangle Trigger Size
The default width and height of the rectangle trigger (if the entity is a rectangle trigger). These values are used when placing child entities on the layer. The size is measured in pixels.

Default Circle Trigger Radius
The default radius of the circle trigger (if the entity is a circle trigger). This value is used when placing child entities on the layer. The radius is measured in pixels.

Custom Variables
Each parent entity has its own custom variables. Each custom variable is a text string.

Each Child entity has the following properties:

Position
The entity's position on the layer. This is measured in pixels. The position is relative to the layer. The entity's layer and world position can be read during export.

Flip
The entity can be flipped horizontally and vertically.

Rotate
The entity can be rotated clockwise by 90 degrees.

Circle Radius
The radius of the circle trigger (if the entity is a circle trigger). This is measured in pixels.

Rectangle Width/Height
The width and height of the rectangle trigger (if the entity is a rectangle trigger). The width and height are measured in pixels.

Custom Variables
Each child entity has its own custom variables. Each custom variable is an integer value (short integer with a range of -32768 to 32767).

Paths can be straight lines or Bezier curves. Click and drag a point to make it a Bezier curve.
The Bezier curve's control points can be edited, added or deleted at any time. Each point in the path has its own properties. These properties can be edited with the Selected Points dialog.

Each path point has the following properties:

Position
The point's position on the layer. This is measured in pixels. The position is relative to the layer. The point's layer and world position can be read during export.

Custom Variables
Each path point has its own custom variables. Each custom variable is an integer value (short integer with a range of -32768 to 32767).

Editing Paths With the Mouse

Left-click: Adds a new point.
Left-click and drag: Adds a new point with control points (Bezier curve).
Double left-click: End the path, places the final point.
Right-click: End the path, does not place another point.

Related Topics:
Mouse Controls

Custom variables are user-defined variables for all the objects in a project.
The user specifies a description for each custom variable. Descriptions are global, it is used by all the objects of a particular type (e.g. all the maps use the same custom variable descriptions).

There are two types of custom variables: text strings and short integers.
The text strings are an array of char data, terminated with a null character. Each char has a value range of 0 to 255.
Short integers have a value range of -32768 to 32767.

Custom variables can also be used as bit values. In this case the variable is used and displayed as 16-bits. Each variable can then be used as 16 variables, each with a value of 0 or 1.
The descriptions for the bit variables are created by breaking the variable's description into groups of 3 characters per bit variable.
Example:
The variable description “OneTwoThrForFivSixSvnEgtNinTenElvTwlThtFrtFftSxt” will be broken into the following 16 descriptions (one for each bit value):
“One”, “Two”, “Thr”, “For”, “Fiv”, “Six”, “Svn”, “Egt”, “Nin”, “Ten”, “Elv”, “Twl”, “Tht”, “Frt”, “Fft”, “Sxt”.

Here is the list of keyboard shortcut keys:

Here is the list of mouse controls (functions are dependant on the edit mode):

The following list describes elements in the user interface.

1) Camera Position
The position of the viewport camera is displayed in the top-right corner, above the viewport. The camera position is measured in grid blocks and is relative to the world origin (0, 0).

2) Cursor Position
The cursor's position is displayed beneath the camera position, in the top-right corner. The cursor's position is measured in pixels and it is relative to the current selected layer.

3) Locked Map/Layer
A red border around the viewport indicates that the current map or layer is locked for editing.

4) Hidden Layer
A yellow border around the viewport indicates that the current layer is hidden.

5) World Origin
The world origin is displayed in the viewport as a cross with arrows at the end of its arms.

6) Number of Objects Beneath the Cursor
A number next to the cursor indicates the number of objects beneath the cursor. This is the number of entities, paths or path points beneath the cursor. This can be turned on/off via the View menu.

7) Missing Entity Image
A red question mark with a green background is drawn when the entity's image is missing or the image failed to load.

8) Flashing Red Rectangle
A flashing red rectangle appears when you try to place entities on top of each other. You can enable/disable placing entities on top of each other via the Preferences dialog.

9) Postfixes “(faster)” and “(slower)”
Options that contain the words “(faster)” and “(slower)” affect TuDee's drawing speed. The “(faster)” options make drawing faster, and the “(slower)” options make drawing slower.

10) Tile Sets Dialog
Square brackets next to the tile set's name:
[L] – Indicates that the tile set is locked.

11) Maps Dialog
Square brackets next to the map's name:
[T:xxx] – “xxx” is the name of the tile set which the map uses.
[L] – Indicates that the map is locked.
[E] – Indicates that the map must be included for exporting.

12) Layers Dialog
Square brackets next to the layer's name:
[M] – Indicates if the layer is a main layer.
[L] – Indicates that the layer is locked.
[H] – Indicates that the layer is hidden.

13) Parent Entities Dialog
Square brackets next to the entity's name:
[L] – Indicates that the entity is locked.
[T] – Indicates that the entity is a trigger.

TuDee's exporter works on a DLL basis. This means that programmers can write their own exporters for TuDee.
You select a DLL to use when you export a project. TuDee loads the DLL and calls the function StartExport in the DLL to start the export. The DLL is unloaded when the export is complete. Programmers must make sure to free all memory that was allocated in the DLL.

The DLL reads data from TuDee's project via function pointers. A range of useful #defines have been created to make exporting easier. These defines call the relevant functions within TuDee to read data.

The exporter DLL must have the following two functions. These functions must be declared in the EXPORTS section of the DLL's module-definition file (.def):

ULONG QueryExporterDLLVersion(void)
TuDee calls the function QueryExporterDLLVersion to get the DLL's version.

UCHAR StartExport(tTdExportFuncsPtrs *pTdFuncs)
TuDee calls the function StartExport to start the exporter. The various #defines in “TdExport.h” can be used in StartExport to read data from the TuDee project.

The exporter DLLs can be copied into the “Exporters” directory, which is located in the directory where TuDee is installed. A list of all the DLLs in the “Exporters” directory is displayed during export, and you can choose one of these DLLs to use. You also have an option to browse for a DLL not located in the “Exporters” directory.

TuDee has a default text file exporter (TextFile.dll). This is a DLL that exports the project to a text file. The source code for this exporter is available, so that it can be used as a starting point for writing an exporter DLL.

Related Topics:
Exporter Example

Below is an example of code for an exporter DLL. For a more detailed example, have a look at the “ExportExample.cpp” file, which is installed with TuDee in the “Include” directory.

You need to create a DLL and export the following two functions from your DLL.
These functions must be declared in the EXPORTS section of the DLL's module-definition file (.def):

QueryExporterDLLVersion
StartExport

The following code is an example of how to implement the two functions in a .cpp file, and how to export all the tile sets to a text file:

Related Topics:
Exporter Basics

This section describes how to perform various functions and tasks in TuDee.

Start a New Project
1) From the File menu, select New.

Insert a Tile Set
1) From the Insert menu, select Tile Set.

Insert a Map
1) First insert a tile set, which will be used by the map.
2) From the Insert menu, select Map.

Insert a Layer
1) First insert a tile set and a map.
2) Select the map to which you want to add the layer.
3) From the Insert menu, select Layer.

Insert a Parent Entity
1) From the Insert menu, select Entity.

Place a Child Entity
1) First insert a tile set and a map.
2) Insert a layer on the map.
3) Select the map and layer on which you want to place the entity.
4) Select the entity from the list on the Entities dialog.
5) Select the Entities edit mode.
6) Select the Placement tool.
7) Place the entity on the layer in the viewport.

Place a Path
1) First insert a tile set and a map.
2) Insert a layer on the map.
3) Select the map and layer on which you want to place the path.
4) Select the Paths edit mode.
5) Select the Placement tool.
6) Left-click on the layer in the viewport to place the path's first point.
7) Left-click to add more points.
8) (Left-click and drag to add control points to create a Bezier curve.)
9) Right-click or double-left-click to end the path.

Pick a Tile from a Layer
1) Select the layer from which to pick a tile.
2) Make sure the Tiles edit mode is selected.
3) Right-click on the tile in the layer.

Pick an Entity from a Layer
1) Select the layer from which to pick a tile.
2) Make sure the Entities edit mode is selected.
3) Right-click on the entity in the layer.

Add Points to an Existing Path
1) Make sure the Paths edit mode is selected.
2) Select the path with the Selection tool.
3) Click the Edit Path Points button.
4) Select the Placement tool.
5) Left-click on the path to add new points.
6) (Left-click and drag to add control points to create a Bezier curve.)

Scale/Resize a Path
1) Make sure the Paths edit mode is selected.
2) Select the path with the Selection tool.
3) From the Paths menu, select Scale or Individual – Scale.
4) Enter the scale percentage value in the dialog and press Ok.

Rotate a Path
1) Make sure the Paths edit mode is selected.
2) Select the path with the Selection tool.
3) From the Select menu, select Rotate or Individual – Rotate.
4) Enter the angle of rotation in the dialog and press Ok.

Split a Path's Segment
1) Select two or more consecutive points on a path.
2) From the Paths menu, select Split Segment(s).

Convert a Straight Path's Points to Bezier Points
1) Select the points on the path.
2) On the Paths menu, select Generate Control Points.

Quickly Select a Tile on the Tiles Dialog
1) Press Crtl + Arrow key to move the selected tile.

Export a Project
1) From the File menu, select Export....
2) Type in the name of the output file.
3) Select a custom exporter DLL.
4) Click Start Export.

Change the Grid's Appearance
1) From the File menu, select Preferences.
2) On the Preferences dialog, select the Grid type.

Sort Drawing Entities from Left/Right and Top/Bottom
1) On the View menu, select Sort When Drawing Entities (significantly slower).

This section describes various technical aspects of TuDee.

Minimum Specifications

Software rendering version of TuDee
Operating System: Windows 2000
Memory: 256 MB RAM (the required memory size is dependant on the project size)
Processor: 2.0 GHz
Graphics: VGA 256 colours, 800x600 screen resolution
Hard drive: 5 MB hard drive space

OpenGL rendering version of TuDee (TuDee GL)
Operating System: Windows 2000
Memory: 256 MB RAM (the required memory size is dependant on the project size)
Processor: 2.0 GHz
Graphics: VGA 256 colours, 800x600 screen resolution, 64 MB (the required memory size is dependant on the sizes of the images in the project)
OpenGL version: 1.1
Hard drive: 5 MB hard drive space

Auto Backups

TuDee makes automatic backups of a project while the project is open. This feature can be turned on or off via the Preferences dialog. The backup interval times can also be changed via the Preferences dialog. The interval times are specified in minutes and have a range of 1 to 120 minutes. The backup interval times indicate how often a backup is made.
The backup files are saved in TuDee's binary format (.tdp), instead of XML format, because the binary files save faster than XML files. The binary files can be opened and saved to XML format.
The backup files are saved to the directory “Autoback”, which is created in the directory where TuDee is installed. The maximum number of backup files can be set via the Preferences dialog, and has a range of 5 to 100. The oldest backup files are deleted when the maximum number of backup files have been exceeded in the backup directory.
Backup files names are created with the date and time in the format “Year-Month-Day_Hour-Min-Sec.tdp” (e.g. “2007-07-15_02-10-12.tdp”).
TuDee only starts making backups of a project after the project has been saved for the first time.

Supported Image Types

The following image types are supported for tile sets, parent entities and layer backgrounds:
1) Bitmaps (.BMP). 32-bit, 24-bit, 8-bit, 4-bit and 1-bit.
2) Targas (.TGA). 32-bit and 24-bit (uncompressed).
3) Portable Network Graphics (.PNG). 64-bit, 32-bit, 24-bit, 8-bit, 4-bit and 1-bit.

Drag and Drop Files

Project files can be dragged and dropped into TuDee.