GGame Editor

By Gary Arndt


The full version of this manual has not yet been completed.  However, some notes followed by a partially-completed version of the manual are included here.  Further, please use the F1 key within the application's editors for some fairly detailed help information.  The manual for the game itself is another good source of related information.


********************************************************************************
Notes
********************************************************************************

Here are a few important notes:

- This document is for the "version 2" editor that was originally designed around 2010 (and remains the current version as of this writing).  This does not mean that there aren't newer versions of this version 2 editor (minor versions), simply that version 2 is the newer overall main version being discussed here.

- The editor application is a distinct program from the game.  It is by no means needed to play the game, but rather is used for scenario design.  While the game program itself DOES include several tools helpful for scenario design, this separate editor program is a vital component for much of the work.

- This application is designed in a manner similar to the game.  It is expected that the user is familiar with navigating a file system, file manipulation (moving files, renaming files, etc.), editing files with a text editor, etc..  Further, the editor is designed to be compatible with older systems (to the point where it could even be ported to DOS, as with the game itself), to reflect the same style as the game itself, and to use the most efficient and precise UI approach possible, and so it is therefore almost entirely based on the keyboard.  That said, the editor does support drag and drop.  It is typical to supplement the use of the editor with a file explorer and text editor.  For example, it is often easiest to open files by dragging them from the file explorer into an open editor.  A file explorer is also extremely helpful for moving file, renaming files, selecting files to open with a text editor, etc..  A text editor is important for changes to the tileset file, for setting up command list files, editing other data need by the game engine, etc..

- This editor is used to edit graphical data, specifically maps and tile frames.  That said, the tile frame format is also used for other purposes such as referenced first-person images and special images that can be displayed at various points in the game.  The majority of the other scenario data types are specified as text files and therefore should be edited using a text editor (for example, the mapset, the tileset, scripts, effect specifications, encounter tables, character class definitions, first person vector graphics definitions, etc.).  There are additional tools available directly within the game engine to help with issues such as testing first-person vector graphics, testing sounds, and converting bitmaps.  These are available from the game engine main menu's hidden "special options" submenu which is accessed with the F2 key (the F2 menu in the GAME program, NOT the F2 menu in the editor program).  So to be clear, the editor application itself does NOT support the editing or creation of data beyond maps, tile frames, and tile frame graphics used for other purposes; that data is created/edited using the afore-mentioned methods.

- The editor consists of the map editor and the tile editor.  The "dual mode" editor allows working with both editors at the same time, and although they can interact in this mode, they are still distinct and separate parts of the application.

- Drag and drop only works within the editor modes, NOT within the main menu.

- Data should be placed under a data directory associated with an ID number.  The ID number selected in the main menu corresponds to this directory.  So the proper ID should be selected in the main menu prior to starting the desired editor mode.  Note that new data may be stored in any location (such as the "Save" directory), but it cannot be properly used until it has been moved to a data directory.  The data directories are named as "DATA[ID]", for example, "DATA1", "DATA2", etc..  The map editor and the game engine will always look for referenced data in these locations.  The map editor will load the tileset file and tile frame files from this data directory.  The game will load the same plus many other data files from the same location.

- Map files should normally be saved using the ".map" extension and tile frame files should use the ".til" extension.  Again, note that .til files ARE used for other purposes (as noted above).  Both map and tile files use the same file format, but the meaning of the data differs.  Map files refer to tile ID's and tile files refer to pixels.  In the later context, this is an uncompressed raster graphics format.  Although the file extensions are somewhat optional, there are operations that take them into consideration, particularly loading operations such as drag and drop.

- Although there are a huge number of files used by the game engine and that manual discusses some of those details, it is worth explaining here about some of the files types supported by the editor.  Map files are those that define the tiles used in a landscape and are created with the map editor.  So a map file of the overland may define which positions have tiles such as grassland, trees, mountains, water, etc..  Tile frame files define the graphics themselves.  So a grassland tile frame would hold the image of what that grassland tile actually looks like.  A tile frame is a single image, but a tile can hold more than a single frame for animation purposes.  A tile is defined in the tileset file and references the tile frames created with the editor.  The editor relies upon the tileset file to define the tiles, but it does not allow editing that information; this is done using a text editor.  So a map references tiles and is edited by the map editor.  A tile references tile frames and is edited by altering the tileset file with a text editor.  A tile frame holds graphics and is edited with the tile editor.

- Although the editor only operates on maps and tile frame graphics, it DOES have a very large number of options for doing so and is very powerful for that purpose.

- As noted previously, tile frame files are also used for raster images referenced by the first-person vector graphics system.  As a result, some of the tile editor options are most useful for this purpose, which amounts to options for working on larger, most complex graphical images with a wide variety of colors.  For example, a greyscale image that has been imported from a bitmap can be divided up, colorized, the pieces pasted back into a single image with multiple base colors, the intended use of the result perhaps being the image of a monster used in dungeons.

- Although the editor has options for creating a new tile and associated frames, it does NOT save the tile definition itself; this must be integrated into the tileset file manually using a text editor.  As for the frames, each frame created in this way must be individually selected and saved.

- Both the map and tile editors have the concept of different buffers.  This allows keeping multiple maps or multiple tiles in memory at the same time and is useful for a variety of purposes such as edited multiple maps in parallel.  For example, a dungeon with multiple levels and ladders that link them can be loaded at the same time in order to easily move between the map for each level, to view how the ladders are connected to each other, etc..  Note that some operations require the use of multiple buffers or at least are most useful when using them.  For example, the compare takes maps from 2 separate buffers and creates a comparison result in a 3rd buffer.

- The default data included with the editor install is not necessarily always synch'd with the latest data in the game.  While this is not essential to using the editor, it can cause problems in some cases (new tiles may not be available, altered tiles are not reflected correctly, etc.).  This can be resolved in one of two ways:

1: The easiest method is to copy the main editor files into the game directory.  This consists of the exe and dll file, the TEdit subdirectory, and the *.cfg files.  It may be best to use a copy of the game or at least to back up any game dir so it isn't accidentally corrupted when doing so (unless there's no changes to it, in which case the original install image can serve as the backup).

2: Another method is to copy the data from the game into the editor (probably best to first remove the old data from the editor after first backing it up, although files that do not overlap should be retained).  Be aware that the data directory ID numbering may sometimes differ between the game and the editor since some of the data does not apply in one context or the other, so verify it is the corresponding data before copying anything.  Refer to the old data in order to clarify what files to copy, but the most important files are the TILESET.dat file and the *.til files.  The map files may be helpful, but the editor does not reference them directly.  Files that do not overlap should be retained.  One of these is the RDGen.cfg file, which is needed for the random dungeon generator.  Also, the text file notes may be helpful.  It is not necessary to copy the many non-editor files from the game into these directories (for example, classes.dat, MAPSET.dat, script*.dat, etc.) since these are not used and would just take up unnecessary disk space and create clutter.  This will keep the editor distinct from the game and is the method I have to use to synch the data prior to a new build of the editor.

- Both drag and drop and the load command support not only the primary type for the given editor, but also command list files.  A command list file is a text file that consists of a variety of commands and is recognized by the extension ".ecl", which stands for "editor command list".  The purpose of these files is to avoid having to repeat the same actions each time the editor is restarted, such as when a dungeon consists of multiple levels and should all be loaded or maps use temp tiles or test tiles.  For example, if a dungeon is named "D1" (dungeon 1) and has 8 levels, you may want to create a file named "D1.ecl" that loads all 8 levels then jumps back to the first level.

Temp objects such as tiles and frames are a concept in the game where special mechanisms are used to create, load, and/or modify them dynamically rather than being included as part of the standard sets that are loaded normally.  Temp tiles/frames are normally created in the game using the scripting system which means that the tile editor does not have access to them.  There are ways to work around this such as using the unmodifed tile, using a placeholder tile, manually creating/loading a parallel tile, or forcing the use of an undefined tile ID (which shows up as a black and empty), but this is obviously not optimal.  The better approach is to use a command list to parallel the temp tiles/frames.  For example, in an arctic area using many temp tiles, you may want to create a file named "ArcticSetup.ecl" that defines the temp tiles/frames then change the cursor color to green so that it shows up over the white tiles.

The commands themselves include:

-- The standard data file commenting tokens: "/*", "*/", and "#"
-- Map [filename]: Loads the given map into the map editor.  It then increments to the next map buffer so any subsequent maps can be loaded without the need for an additional command to do so.
-- SetMBuffer [ID]: Switches to the given map editor buffer.  Useful after "Map" commands.
-- MENewTile [filename] [[ID]]: In the map editor creates a new tile with a single new frame then loads the given file into that frame.  If the optional ID field is not specified it defaults to 0, which means it uses the next available ID.
-- MELoadFrame [ID] [filename]: In the map editor loads an existing frame of the given ID with the given file.  Note that this will not create a new frame, only modify an existing frame.
-- MEEditFrame [ID] [[options]]: In the map editor modifies a frame of the given ID.  Options parallel a subset of those in game's scripting command to edit a frame.  Multiple options can be given on a single line including more than one instance of the same command.
--- -COPY [ID]: Copy the given frame (for example, "MEEditFrame 1 -COPY 2")
--- -MIRROR [type]: Mirror/rotate the given frame.  Types include R to rotate right, L to rotate left, F to flip 180 degrees, H to mirror across the horizontal axis, and V to mirror across the verticle axis.  For example, "MEEditFrame 1 L" would rotate it left.
--- -COLOR [R] [G] [B]: Set the draw color to the given color.  For example, "MEEditFrame 1 -COLOR 0 0 255" would set the draw color to blue.  Note that this accomplishes nothing without a subsequent command that uses it.  The draw color defaults to white (255 255 255).
--- -REPCOLOR [R] [G] [B]: Replace the given color with the current draw color
-- MECursorColor [R] [G] [B]: Set the map editor cursor to the given color
-- SetAutoSave [0|1]: Turns autosave on or off
-- SetAnimate [0|1]: Turns animation on or off

- There is an options submenu in the editor's main menu, not to be confused with the one in the game's main menu, which can also be accessed with the F2 key.  This menu includes the option to change the number of buffers available in the tile or map editor, something that must be done before they are started.


********************************************************************************
Partial manual
********************************************************************************

Here is the partially-completed manual:

Basic and misc. concepts

A few select concepts are described here either as prerequisites to other discussions in this manual or as misc. concepts that don't really belong in any other section.  That said, there are many other concepts that are explained elsewhere.  For example, details about the game itself are discussed in that separate manual, the game's manual also has many details about a variety of concepts used here, the definition of words like "pixel" can be looked up online, etc..

Further, it is expected that the user is familiar with navigating a file system, file manipulation (moving files, renaming files, etc.), editing files with a text editor, etc.; these concepts are not explained here.

The editor includes 3 main modes: the tile editor, the map editor, and "dual mode".  The later mode starts both editors at once and supports some limited interaction between them.  While dual mode is typically the most useful, being able to start the tile editor and map editor modes separately is important in some cases.

As with the game itself, the editor has a built-in quick help function that summarizes the available commands and a few other select subjects.  The traditional F1 key is used to display this information.  Note that the quick help differs between the map editor and tile editor and so the command should be used while the editor in question is active.  Further, the information may change slightly while in particular editing modes such as dual mode.

Also as with the game itself, there is a text display at the bottom of the screen and several keys can be used to interact with it.  Knowing how to scroll through the text display is VERY important since a lot of text is long enough that it cannot all be shown at once, the quick help information included.  The Page Up/Down keys allow scrolling a page at a time backwards and forwards through what has already been displayed.  The control key plus the up or down arrow key does the same except a single line at a time rather than a page.

The Escape key can be used to cancel in a prompt that requires a single key.  Entering no value (just pressing Enter) can be used to cancel in a prompt that requires typing a value.

Within a prompt the requires typing a value, the Escape key will erase any existing text.  Also, the Backspace key will function as expected for text.

The "I" (info) command can be used in either editor to display information about the current state of the editor and includes a wide variety of information about the current position, the state of standard and special operations, the current buffer and associated most recent file name (if any), etc..  Note that the most recent file name can be very useful in identifying the information in the current buffer (for example, a file named "D1L8.map" in the map editor may clarify that it is dungeon 1 level 8).

A tile or frame ID is a single numeric value from 0 to 65535.  The value 0 is reserved to indicate an "empty" tile or frame (if drawn, it is black).

A color consists of 3 separate values from 0 to 255.  The 3 colors are red, green, and blue.  0 means none and 255 means all.  In this document and in many places in the editor, the value is written as "[red] [green] [blue]", delimited by a space as indicated.  "0 0 0" is pure black.  "255 255 255" is pure white.  "255 0 0" is pure red.  Etc..  Combinations of various values form other colors.

All data files that are created/altered with a text editor should be saved as a pure (ascii) text format (a true ".txt" file).  A data file saved in another format will not function properly.  The best editors for doing so are those specifically intended for this purpose, not those that are intended for standard word processing.

A map defines the layout of multiple tiles.  A tile defines a number of things such as how many frames it has, what frames it has, the tile name, and various game-specific details such as terrain type.  A frame (or "tile frame") defines what a given frame of a tile looks like (for overhead maps that is done in the form of the colors of each pixel, meaning that it is a raster image).

The tile editor is used to edit raster tiles, those traditionally used for maps intended to be displayed in the game as overhead maps (such as those traditionally used for overland and towns).  First person graphics (such as those traditionally used for dungeons) and VERY different and therefore defined in VERY different manner, although they may reference raster images created with the tile editor (in fact, a number of features in the tile editor are specifically intended to help with creating these special frames).

As with the game itself, this program is designed to be a well-encapsulated one that does not tether itself to a single, particular location.  What this means is that the install directory can be moved around as needed, there can be more than one copy of the installation (including multiple versions), and ALL data is stored only within the install directory itself or in locations specifically designated by the user.

It is worth noting that more than one instance of the program can run at the same time, which can be very useful in some cases.  The only collision may be the autosave feature (and then only if it happens to be triggering at exactly the same time, which is highly unlikely) but that can be avoided by turning it off.


Starting the editor

Navigate to the directory where the editor was installed and launch the .exe file that is located there.  Alternatively, use any shortcut you have created to that .exe file.  Further, it is possible to launch the editor with a command-line option that references a configuration file to control some of the initial setup of the program such as the initial data ID.

When the application has started, the main menu is displayed.  It lists the current data ID, that value matching the ID used in the directory name of the scenario to be used in the editors.  If no special setup has been done, this will be set to 0, meaning no scenario has yet been selected.  In this case, starting the map editor will prompt for a data ID.  Alternatively, the "D" key can be used to enter the data ID.  The data ID refers to the the data directory containing the data in question and typically also corresponds to the scenario in question.  For example, if you want to start the map editor using the tileset in scenario 2, then enter "2".  That said, the data ID instead corresponds in many cases to a special data directory used for special purposes.  Each data directory installed by default contains a text file note that explains its particular purpose.

The standard, singular tile editor mode does not require a data ID.  That said, the map editor DOES require a valid data ID.  In the later case, a data directory that matches the ID in question and contains the appropriate data files must exist in the root of the install directory.  The install includes a number of such data directories by default.  For example, the data directory for scenario 2 is included.

Note that because the map editor requires a data ID, so does dual mode.

Whenever a data ID is selected, the respective configuration file (".cfg") is automatically loaded from the root of the install directory.  Optionally, the "C" key can be used to manually load a different configuration file, but it is not typically necessary and only supported for special purposes.

The desired editor mode can be started by using the keys presented in the menu.  Note that once an edit has been started, their respective options menu (F2) can be used to return to the main menu.

It is possible to exit the program from either the main menu or from any of the editor modes.  The editors allow doing so from their respective options menu, but also directly with the "Q" or "Control-Q" options (the later skips the save prompt).


Selecting buffers

Both editors include the concept of multiple buffers.  This simply means that more than one map or more than one tile can be open at a time.  To switch between buffers, use the "[" and "]" keys to scroll backwards or forwards.  If a buffer has not yet been created, a prompt will ask for permission to create the new map or tile.  If the maximum number of buffers has been created, selecting a buffer lower than the buffer 0 or higher than the max buffer will "wrap around" to the max buffer or to buffer 0.

To jump directly to buffer 0, use the "\" key.

The new buffer's number and most recent filename (if any) will be displayed anytime it is changed.

The "I" (info) key can be used to display the current buffer number and most recent filename (if any) without changing it.

Note that the position is not changed when switching between buffers unless the size differs so that the position is invalid.  This allows doing things such as matching the placement of a ladder going down to the next level with the ladder going back up.

Also note that currently, changing the tile editor buffer in dual mode will lose any tile shared from the map editor and the above keys cannot be used to get back to it.  To do so, switch back to map editor and share it again with the Get command.


Changing position (movement)

Positions are designated as X and Y coordinates such as "0 0" to indicate the upper left-hand corner, "1 0" to indicate 1 position to the right of the upper left-hand corner, etc..

In the map editor, changing positions on the map is accomplished by using the arrow keys like in the game itself.  However, instead of showing the current position with the main character, a cursor is shown in the form of a box that outlines the position but does not overlap it so as not to obstruct the tile on the current position.  This can be toggled on and off using the "B" (toggle cursor (tile border)) command.  As with the game (under normal circumstances), the current position is always at the center of the screen, which is useful to remember when the cursor is off.

The tile editor actually has 3 separate sections.

In the tile editor's edit box, movement between positions is also accomplished by using the arrow keys, but moves a single pixel at a time.  Instead of a cursor, there is a horizontal and a verticle line on the side of the tile that points towards the current position.  Further, the current edit color is displayed at the current position even though it may not necessarily be the current color of that position.  The later is known as the "dot cursor" and can be toggled on and off using the "D" (toggle dot cursor) command.  Note that the position of the dot cursor may not be obvious if the color of the current position and/or the color of the surrounding pixels match the current edit color, in which case the line pointers become the only clear indication of the current position.

In the tile editor's color display, movement between the primary RGB colors is accomplished by using the left and right arrow keys.  The current color is marked with a box like that in the map editor.

In the tile editor's palette, movement is is accomplished by using the arrow keys.  The current color is marked with a box like that in the map editor.

If movement in any of these places the position beyond a border then the position "wraps around" to the min or max position.  For example, if the current position in the map editor is 0 5 and the max position is 49 49, then moving left by 1 position goes to 49 5.

The jump command can also be used in the map editor or the tile editor's edit box to change position by moving by more than one position at a time, which can be more efficient in many cases.  Once the jump command is selected, another option is required.  These options include the arrow keys to select a side (for example, left jumps to the left/west side where X is 0), the space bar to select the center, the home key to select the upper left-hand corner, and the end key to select the lower right-hand corner.  Note that the home and end keys can also be used without first selecting the jump command.  Also note that the home and end keys do work in the palette, but the jump command does not.  None of these work in the color display (and the home and end keys serve a different purpose).

All movement displays the new position's coordinates.

The space bar displays the same coordinate information given with movement but without actually moving.


Switching between sections

As noted, the tile editor has 3 separate section.  The edit box section is active by default and is typically where most of the work is done.  If another section is active, the method to switch to the edit box is with the "E" key.  The method to switch to the color display is with the "C" key and the method to switch to the palette is with the "P" key.

If dual mode is active, then the Tab key switches between the map editor and the tile editor.

Other than being able to switch to the tile editor when in dual mode, the map editor has only one section and therefore has no special keys to switch between sections.


Resizing

The default size (dimensions) of a map or a tile may not be that which is desired.

One easy way to resize is to load a map or tile of the correct size (loading is described in a separate section).

Another is with the "R" (resize) command.  Enter the requested width and height at the respective prompts and the map or tile will be resized.

If the size is smaller than any current data, this data will be cropped to the right and/or downward (depending on the if the width, height, or both are smaller).  If the size is larger than any current data, new positions will be added in the same manner with empty data (empty tile 0 on a map or black 0 0 0 on a tile).

Note that the sizes of buffers can differ.


Selecting the edit value in the map editor

In the map editor, one of the easiest ways to select the current edit value (the tile to place) is to use the adjacent "," and "." keys to scroll backwards or forwards through the available tiles.  Note that the "<" and ">" keys (the shift of the former keys) can be used to jump through these choices more quickly by skipping backwards or forwards by multiple tiles at once (this value is currently hardwired to 10).  Be aware that this not only selects the current edit tile, but also changes the tile of the current position.

Another easy method is to use the "Get" command, but this requires the value to have been placed at least once on the map.  To use this command, move to the position containing the desired edit tile and press the "G" (get) key.  The edit tile will now match the value of the given position.  Note that the Get command can be used in another buffer.  In a more general sense, the value "sticks", meaning that it can be retrieved through any series of actions (selected in another buffer, selected when a different file was loaded, etc.) and is not reset between them.

A more complicated method to select the current edit value is the option (F2) menu's "Set editor tile" option.  This is a method to enter the tile ID textually and has the advantage of doing so more directly without having to find the tile using one of the afore-mentioned methods.  It also allows for advanced techniques related to using a tile ID that has not yet been defined.


Selecting the edit value in the tile editor

In the tile editor, one of the easiest ways to select the current edit value (the color to place) is to press the "P" key to switch from the edit box to the palette.  Once in the palette, move to the desired color and press "Enter" to select it.  After doing so, press the "E" key to switch back to the edit box.

Another easy method is to use the "Get" command just like with the map editor.  As with the map editor, this requires the value to have been placed at least once on the tile and to use this command, move to the position containing the desired edit tile and press the "G" (get) key.  And like the map editor, the command can be used in another buffer and sticks.  Note that because the value sticks, it is possible leverage dual mode to get the value from a different tile (meaning, you can select a different tile in the map editor, get the color, then switch back to the one to change).

More complicated, advanced methods to select the current edit value include the option (F2) menu's "Set editor color" option or using the color display.

The former is a method to enter the color value textually.  This has the advantage of allowing any possible color, not just those available on the palette or already used.  As noted, this is done by selecting the value from the option menu.  It will then prompt for the 3 base colors that comprise and define the resulting color (as described earlier, this includes red, green, and blue).  After all 3 colors have been enterd, the new color will be selected.

Using the later method (the color display) is described separately.

Note that an advantage of using the palette or the Get command is to maintain consistency between the colors that are used.  This gives the tile frames a more consistent look, particularly when a lower resolution is being used.  That said, the advanced methods can help with selecting a new color to use in such a manner if one is needed.

Also note that all colors are defined and saved using each of the separate base colors; using the palette does not cause the result colors to be defined in a palette-based format (singular 8-bit color and such).


Changing the current value

In the map editor, the tile at the current position can be changed by using the Enter key.  In the tile editor, the pixel at the current position is changed in the same way.

Note that more than one tile or pixel can be changed at one time through several methods.  The most common method is using the mark command.  This sets a start and end position of a whole block of positions to set at the same time (a "block" meaning a rectangle from the starting position as a corner to the ending position as the opposite corner).  To do so, first change position to the starting position then select it with the "M" (mark) key.  Next, change position to the ending position then use the Enter key.  The entire block of positions will be altered at once.

For example, if the starting position is 3 3 and the ending position is 4 4, then the 4 positions set are 3 3, 4 3, 3 4, and 4 4.

Note that the Enter key normally changes only the single current position.  It will ONLY change multiple positions when the mark position has been set.  Once it has done so, the current marked position is unset and the functionality of the Enter key returns to normal (only the single current position).  The marked position may be manually unset with the Escape key, which is useful for situations such as if you change your mind.

To clarify, the marked position and the position where the Enter key are used form a rectangle by specifying the upper right-hand corner and the lower left-hand corner.  It does not matter which one is which; it simply needs the two positions.  If the two positions are the same, it simply places the single position.  If the X but not the Y or visa versa are the same, it places the values like a verticle or horizontal line.

Note that the marked position in the tile editor is shown visually with red pointer lines.  The current marked position can be displayed numerically using the "I" (info) command.

While the Enter key sets the edit value, the Delete key sets the empty value (meaning set the empty tile 0 in the map editor or black 0 0 0 in the tile editor).  Similarly, the Backspace key functions as an "undo", meaning it sets the most recent value that was changed.  Either key can be used instead of Enter not only to place a single tile but also to set a marked block of tiles.

Every value on the map or tile can be changed at once by using the "F" (fill) command.  Once this command is selected, a menu asks which value to use, including the current tile (meaning the standard edit tile), erase (meaning fill with the empty tile 0 in the map editor or black 0 0 0 in the tile editor), or specify the value with a numeric value.

Values can also be changed through special operations such as copy and paste in either editor.  The tile editor includes the advanced flood fill option to fill only to positions that are marked by a delimiting color.


Interacting with animation

The map editor will animate the tile in the same way as the game itself.  However, there are various situations that require interation with this animation.

Note that the tile editor is really a tile FRAME editor, although multiple frames CAN be edited in conjunction with each other by placing each in a different buffer.

In dual mode the tile that is selected with the Get command can be edited with the tile editor, but since it is actually just a frame that is edited, the frame that is selected depends on the animation.  While the appropriate frame can be selected with the Get command by timing it at just the right moment during animation, it is often better (especially with fast animation) to use a more precise alternative method.

Animation can be turned on and off in the map editor by using the "A" (toggle animation) command.  The animation frame position can be scrolled backwards or forwards using the "-" and "=" keys.  Further, the "_" key can be used to jump to the first animation frame position (position 0).  An important use of these commands is to select the exact frame needed for the Get command.

The current animation position can be checked with the "I" (info) command.

Note that the animation frame position of a given tile does NOT necessarily or typically match the overall frame position being discussed with respect to those commands since each given tile may differ in their number of frames.  For example, say a given tile of water contains 2 frame, a given tile of an energy field contains 4 frames, and a given tile of the PC and some monster each contain 1 frame.  If the overall animation frame is at position 2 (the 3rd position given that these are base 0), this does mean that the tile of water or the PC or the monster are at tile position 2; they do not even have that many frames.  Further, there is yet a 3rd number involved, that being the frame ID.  The frame ID is nothing more than an identifier; it is totally distinct from both the overall frame position and the frame position within a given tile.

That said, it is not necessary to fully understand the previous explanation before using those commands.  In fact, the best way to understand how this all works is to experiment with them.

Another important point with respect to animation is that it is the tile that defines which animation frames that are in that tile.  The map editor is used to edit maps and the tile editor is used to edit tile FRAMES, but the tiles themselves are NOT defined within the editor.  Each tile is defined textually in the tileset data file, a separate and distinct activity that is NOT done within the editor and is explained elsewhere.  That said, the "new tile" option in the map editor can be used to temporarily create a tile.  However, that mechanism is intended for temporary purposes and therefore limited in many ways and the result cannot be saved.


The tile editor color display

The tile editor has 3 modes.  The edit box is where most of the operations that are discussed in the other sections are done.  Selecting colors from the palette is discussed as part of the more basic operation of selecting an edit color (changing the current edit value in the tile editor).

A third mode is the color display.  This serves both as a way to display the current color and as an advanced method to select a color.

Remember from earlier that any color is defined by 3 base colors, those being red, green, and blue.  The top box in the color display shows the resulting combination of these base colors while the 3 boxes underneath that show the base colors themselves (in the above order from left to right).

The first purpose of the color display that was mentioned (showing the current color) is done automatically when any method to select a color is used.  All 4 boxes will automatically change to match the selection.

Selecting a color directly requires a bit more explanation.

First of all, it is worth mentioning that this is a good way to select a very specific color and to be shown the results right away as the values are being incrementally adjusted.  This is not the case with the other methods described earlier.  While choosing a color by entering the numbers directly also works, the results are not shown until the value is set.  Choosing a color using the palette restricts the color to only the colors that are included, which is an advantage in many cases (to maintain consistency), but is not always what is needed.  Getting an existing color that has already been used from the tile is often very restrictive.

It was mentioned earlier that to activate the color display mode, use the "C" (color display) command.  Remember that to switch back to the edit box, use the "E" (edit box) command (or "P" for the palette).  When the color display is active, it displays a box cursor around only the current selection base color position.  The left and right arrow keys are used to move between these (and it wraps around between the last/blue and first/red).

Changing one of them also changes the resulting combination color.  To change one of them, first make sure the the base color to change is the one currently selected and then use the "," and "." keys to increase or decrease the value from 0 to 255 (going up or down from the max 255 or min 0 value wraps back around to the min or max value).  The "<" and ">" keys will change the value by 16 rather than by 1 (since 16 is an even and typical increment for a color given the total value of 256 and that 16 * 16 = 256).  As described earlier, remember that 0 provides none of the given base color and 255 provides all of the given base color.  This means that 255 255 255 is pure white, 0 0 0 is pure black,  255 0 0 is pure red, etc..  As soon as any change is made, this becomes the new edit color.  When the changes are satisfactory, go back to the edit box to use it.


Loading and saving

A file can only be loaded or saved once an editor mode has been selected.  For maps, make sure that the selected data ID matches the tileset that was used to create the file or it will be displayed incorrectly.

One of the easiest methods to load a file is to drag it from a file manager into the program.  This works in both editors.  In dual mode, it is best to make sure that the appropriate editor is activated before doing so.  That said, it will attempt to match the file extension to the appropriate editor and activate it automatically (for example, if the map editor is activated and a file with a ".til" extension is used, it will activate the tile editor and load it as a tile).

Another method to load a file into either editor is by using the "L" (load) command, which will prompt for the file name.  A path may be included in the name to load if from another location (for example, "DATA2\2.til").

Files can be saved from either editor with the "S" (save) command, which will prompt for the file name.  Files are saved by default in the "Save" subdirectory, but a path may be included in the name to place it elsewhere.

Note that only a single file is saved at one time.  This means that if multiple files are loaded into multiple editors and/or buffers, then each must be saved individually.

If you wish to cancel the load or save when entering a file name then enter no text (an empty line).  As usual with entering text, remember that the escape key deletes all current text, the backspace key can be used, etc..

Both editors will remember the most recently used name and pre-enter it for both loading and saving.  Each buffer remembers the name separately.  If you want to use the current name, simply press Enter.  If you want to change it, backspace to the position where it differs and enter the changes.  If you want to delete the name to start fresh with an empty name, press Escape then enter the new name.  If you want to cancel, press Escape to make the line empty then press Enter.

Files are normally loaded one at a time, but there is a special method to load more than one at a time, that being through the use of a command list (".ecl") file (that said, the loading commands are not the only supported commands).  A command file can be loaded in either editor by dragging or with the "L" command.

A "quick save" option is available in both editors with the F3 key.  This will save the file into the Save directory using a default name.  While this will overwrite any previous instance of the file, the name differs for each editor and a suffix is appended to the filename corresponding to the current buffer.  The base name for a quick save file is "qsave".

There is also an autosave feature in both editors.  This will save the current state of the file in each buffer of each editor every few minutes in case something unexpected happens.  The filename works just like that of the quick save, but instead uses the base name "asave".  This can be toggled off and on in the options (F2) menu.


Duel mode details

Most of the details about dual mode are integrated into the sections discussing specific operations and commands.  However, there are a few more details that are worth noting.

The tile editor serves two main purposes in dual mode.

The first and most obvious is to take any tile that has been selected with the map editor and edit it directly.  This has a number of advantages, just one of which being that the results are immediately obvious in the context of a map.

The second is that it is much more clear which tile has been selected with the map editor since it shows up in the tile editor.

Since the two editors are separate implementations, interaction between them is handled very specially.  As a result, there are some limitations such as the need to carefully switch between them before using one or the other.  The best way to tell which editor is currently active is to look at the textual prompt since it specifically displays the name of the active editor.

The commands and even the quick help (F1) information is completely separate and can only be accessed while the editor in question is active.

Also, it is worth reiterating that the data between the editors (and within each buffer) is completely separate and therefore must be saved separately.

The tile selected within the map editor is a special buffer that is separate from the normal tile editor buffers (some limitations related to this are discussed in the section about setting the edit tile).  Whenever a command in the map editor changes this, it updates the tile editor with the change.  Correspondingly, whenever a command in the tile editor changes the data in that tile, it tells the map editor to visually refresh with those changes.  Any error messages indicating problems with this process will refer to this as "sharing" the tile (cancelling some operations and such has sometimes revealed situations that are not yet handled properly, minor bugs that need to be fixed but do not cause any real harm otherwise).

Remember that the tile editor can be started separately from the main menu.  This is particularly useful when a tile is very large, such as one used as a referenced tile in vector graphics.  Further, there is sometime no map involved, again such as a referenced tile in vector graphics.  For example, a variety of referenced tiles in the vector graphics of scenario 2 (various wall images, various creature images, etc.) are very large and would be difficult to work with in the limited space available to the tile editor in dual mode, plus they are not used directly on any maps so that the map editor in dual mode would not be used and would just take up much-needed space on the screen.


Visual interaction commands

These are commands that help with visually interacting with the editors.  Some commands that fall into this category (such as those related to toggling cursors off and on, interacting with animation, etc.) are noted in other, more specific sections.

The tile editor can work on tiles of many different sizes, which means that it very important to be able to zoom in and out.  This capability is available with the "-" and "=" keys.

The border for the tile editor can be toggled off and on with the "B" (toggle tile border) command.

Some maps may have a large amount of a given color in them, making the map editor tile border cursor difficult or impossible to see.  The color of the border can be changed with the "Control-B" command, which will cycle through various colors and then back to the original color.

There may be some cases where it is convenient to refresh the screen.  This can be done in either editor with the traditional F5 key.


Copy and paste

In either editor, a copy and paste operation can be used to copy a marked section from one position to another.  This also works between different buffers.

To do so, go to the first position and mark it using the "M" (mark) command (as described above in "Changing the current value", but do NOT do more than that such as using the Enter key on the second position).  Next, go to the second position (opposite corner of the block).  Press the "Control-C" (copy) command to copy the section.

If desired, the "I" (info) command can optionally be used to display positional information about the marked section.

Go to the upper left-hand corner of the position for which to paste the section and use the "Control-V" (paste) command.  The tiles to the right and downward from that corner will be changed to match those of the marked section.  Put another way, the selected rectangle is pasted starting at its upper left-hand corner.

Note that once a marked section has been pasted, it is NOT automatically unselected.  Another copy will alter the marked section or the Escape key can be used to clear it.

An unmarked copy and paste (a single position) is not supported because this can be accomplished using the "G" (get) command followed by the Enter command (as described above).


Shifting a section

An entire block of tiles in the map editor or a block of pixels in the tile editor can be shifted with the "Control-S" (shift) command.  What this does is move the data in the given block of positions by a given X and Y distance.  It overwrites anything that is underneath their new positions and fills any previous positions that are open with empty data (tile 0 or black).

To do this, first mark a position with the "M" (mark) command (as described above).  Then go to the second position (opposite corner of the block) and use the shift command (analogous to using other commands that require a marked position).  It will then prompt for the X and then the Y distance.  This is the number of positions to shift the given block of data.  After entering this information, the data will be shifted.

For example, entering "1" for X and "0" for Y will shift the block 1 position to the right, "0" for X and "1" for Y will shift the block 1 position downward, "1" for X and "1" for Y will shift the block 1 position to the right and 1 position downward, etc..

As usual, the operation can be cancelled by entering no data (just Enter) at any prompt.


Replacing all instances of a value

It is possible to replace all instances of a tile in the map editor or a color in the tile editor.  To do so, first set the current edit tile or pixel (as described earlier).  Move to a position with the value to be replaced and then use the "Control-R" (replace) command.  Because this is a rather delicate operation, it will indicate what it will do and prompt you to be sure that this is what you want done.  Answer "Y" (yes) and all instances of that value will be replaced (not just the one at the current position).

For example, say you have a map with grass tiles and you want to replace them all with desert tiles.  First set the edit tile to the desert tile.  Then go to a position with one of the grass tiles and use the Replace command.  All instances of the grass tile will be replaced with the desert tile.


Mirror/rotate

Both editors support the mirror/rotate operation, which alters the entire map or tile by rescanning it into another order.  The end result is one of several forms of mirroring or rotation such as rotating right, mirroring across the horizontal axis, etc..

To do this, use the "Control-M" (mirror/rotate) command then choose the desired option from the submenu that appears.  The entire map or tile will be altered as specified.

For example, you may want to rotate the image of a tile that points to the north to the east, perhaps to create a version that faces that direction.  In the tile editor, the mirror option followed by "rotate right" could be used to accomplish this.


Transparency copy and templates

Both editors support a transparency copy operation.  This means that it takes all the data from one buffer and copies it onto data from another buffer.  What makes this operation useful is that it skips empty data (tile 0 in the map editor or black 0 0 0 in the tile editor).  The purpose of this is to overlay data from one map or tile onto another.

To do this, load one buffer with the map or tile that serves as the overlay and another with the data to be modified, meaning the one which will have the overlayed data placed upon it.  Put another way, the former is the source and the later is the destination.

The next step is to go to the destination buffer if that is not already the case.

Next, if the editor is the tile editor then go to the position relative to the placement of the data.  For example, if the source will be placed exactly over the entire destination, then go to position 0 0 (remember, an easy way to do so is with the Home key).  If the source should be offset onto the destination, then change the position to match the upper left-hand corner of where the data should be applied.  For example, position 1 0 would cause it to be shifted 1 position to the right.

If the editor is the map editor, the current position is ignored; the placement always begins at 0 0.  It is therefore not necessary to change the position.

Next, go to the options (F2) menu.  Select the transparency copy option and it will prompt for the buffer index number of the source.  Enter that value (for example, buffer 0 if it is in the first buffer) and it will modify the current buffer (the destination) with the data from the given buffer (the source).

There are multiple uses for this command.

A major use in the map editor is to take a map template and overlay it onto another map.  For example, if there are two levels in a town, then in theory the second level would have to duplicate some of the information from the first map if there were any "open" positions showing the first map underneath (for example, the street outside a second-story window).  Instead of doing so, the map of the second story can be drawn to exclude any redundant information so that the empty tiles are used on those positions.  This second story template map would then be applied over the first story map to create a result map for the second story (this map would be the one used in the game but never modified directly).  So the end result would be 3 different maps: the first story map (created by hand and used directly in the game), the second story template map (created by hand but NOT used directly in the game), and the second story result map (created with this command and used directly in the game).  The name of the first story map may be something like "FrielL1.map", the name of the second story template map may be something like "FrielL2Template.map", and the name of the second story result map may be something like "FrielL2.map".  The operation to create FrielL2.map would be to apply FrielL2Template.map onto FrielL1.map and save it as the FrielL2.map.

That said, the game actually has a built-in mechanism to apply templates automatically during the loading process.  This actually works in the same way as what is described here, but done automatically as specified in the mapset data file.  Doing this manually with the editor is an older method before that mechanism in the game was implemented, but it is still often useful for various purposes.

Note that the process of applying templates can be "stacked", meaning they can be applied in sequence to accumulate information from more than a single template.  For example, if a town map had 3 levels (ground, second, and third), then the second level template could be applied to the ground level map to create the result map for the second level (as usual) but then the third level template could be applied in turn to that result to create the result map for the third level.  While this may not be necessary if all of the third level differences completely overlapped the second level, that may not necesarily be the case (for example, when the buildings are not all the same height).

A major use for the tile editor is to take a complex image with different components and apply them together.  For example, a greyscale image may be imported from bitmap and then cut into different pieces in order to separately apply global color gradient changes to those pieces with the command to adjust all colors (colorizing the greyscale).  Once these changes are completed, then this command allows those pieces to be reassembled.  While the other aspects of this particular example are not described here (importing from bitmap, cutting the image into pieces, and using the command to adjust all colors), the process for reassembling them is as follows: First open one of the images of the pieces as the destination.  Then use the transparency copy option (the source) of each of the other pieces to begin adding them onto this result.  When all of the pieces have been assembled, save the result.  This works the same way as with the map templates described above.  Note that for this to work, a critical aspect in the process of "cutting the image into pieces" includes making sure the parts that are not intended to be applied have been set to the empty black 0 0 0 transparency color; template source data MUST include this empty data in order to function as such.


Searching for a tile in the map editor

It is sometimes useful to be able to search for a particular tile in a map.  For example, if a secret door has exactly the same image as a wall and you're not sure if you placed it properly or not, a search can be used to find each instance of it.  Or if you use the "compare map" command, then it is very useful to search for the results.

Note that there is currently no parallel functionality to find a pixel in the tile editor.

To find a tile, first set the edit tile to the tile to be found using one of the methods already described elsewhere.  Next go to the position on which to start the search.  Note that positions are searched first in the X direction, then in the Y direction.  To search everything on the entire map, start at the upper left-hand corner (a quick way to do so is with the Home key).  Use the "Control-F" (find) command and it will jump to the first result.  Use it again and it will jump to the next result.  If there are no results (or no remaining results) the text output will indicate that is the case.


Comparing maps in the map editor

It is sometimes useful to compare two maps and determine the differences between them.  For example, if you have saved two versions of a given map and can't remember what was changed, this will show the differences between them.

The results are shown as a third result map that contains the overlapping data and any differences in the form of a specified tile.  For example, say that you want to show the differences as the tile used for the main character since the main character would of course normally never appear directly in the map.  The resulting comparison map would then match the map as usual except where there were differences.  On those position that differed between the two maps, the main character tile would appear instead.

To use this command, first open the two maps in two different buffers then go to a third buffer that will hold the results.  Next set the edit tile to the tile to show the differences (such as the main character tile).  Select "compare maps" in the options (F2) menu.  At the prompts, enter the numbers of the buffers holding the maps to be compared.  For example, if the first map is in buffer 0 and the second in buffer 1, then enter "0" at the first prompt and "1" at the second prompt.  The result comparison map will then be generated.

A good way to scan for the tile marking the difference is to subsequently use the Find command.  And the prerequisite of selecting the tile to find will have conveniently already been done for the comparison operation.


Creating a new tile or loading a frame in the map editor

The map editor depends on tiles as defined in the data directory.  However, a few special options exist to avoid having to change the files in those data directories simply to temporarily test something.

Remember that tiles are NOT the same as tile frames.  A given tile references one or more frames and defines other information such as the name of the tile.  The tile editor is used to change tile frames, but does not deal with actual tiles.  Maps reference tiles, so therefore the map editor requires tiles in order to display those maps.  Tiles are defined in the tileset data, which are normally changed with the data in the data directory, not with this program.  For example, the tileset file is changed with a text editor and corresponding new tile frame files must be reside in that directory.

However, the options (F2) menu includes an option to TEMPORARILY create a new tile (with no corresponding save) and another to load a frame.  Some examples of where this is useful include when a map is being designed and one or more new standard tiles or temp tiles may potentially be needed.  This option can be used to try out such tiles with the map in question without modifying the data files.

To clarify, the term "temp tile" used in these examples does not refer to the fact that these special options are temporary (no save available and such), but in this case refers to a special concept in the game of a tile that is NOT part of the standard tileset, but rather loaded only when it is needed using special mechanisms (which currently are only implemented as scripting commands, at least as of the time of this writing).  The game's temp tile system allows the use of special-case tiles without concern for having to include a lot of abnormal tiles in with the permanent tiles, since that means they use up more memory and may be messy.  Further, this allows dynamically altering a given tile or tile frame.  It is a very powerful, flexible system.  However, it means that the map editor must somehow also define such a tile.

Note that an editor command list file may also include commands to create a new tile (this system is described elsewhere).

To create a new tile in the map editor, select that option from the options (F2) menu.

[More NYI]


The random dungeon generator

The map editor includes a random dungeon level generator.  This generates a single map (one level at a time) and is likely to require more than a single step to complete various details, but does complete the majority of the work.  Dungeon maps generated in this way have a very particular appearance and will not match the style that may be desired in many cases.  For example, many dungeons in the included scenarios follow a particular design style that is not followed by those generated with this tool.  One of those style approaches is to maximize space, meaning many of them avoid any adjacent walls that use more than 1 position in both directions.  This tool does not do so.  Because of this and the fairly arbitrary twists and turns of the passageways, the results tend to have a feel more along the lines of natural caverns.

To invoke this tool, first go to the position on which the ladder up (or other specified analogous tile) will be placed.  Next use the "D" (random dungeon generator) command.  A submenu will appear with several available option.  The "D" option will generate a complete dungeon level except for any ladder down (or analogous tile) to any next level or any other details.  Note that if you don't like the results, the command can be used more than once until a satisfactory result is produced.  Afterwards, additional hallways can be added from the selected current position using the respective submenu option.

Note that this tools uses a dedicated configuration file located in the respective data directory named "RDGen.cfg".  If changes are made to this file, there is a submenu option that can be used to reload it with the new values.  This file does not have to be changed since the installation includes a default copy of the file in each applicable data directory, but there may be cases where doing so is helpful.

Like all such textual data, the config file should be altered with a text editor.  The options in this file include:

- Standard comments: "#", and the "/*" / "*/" pair as supported in most of the game and editor data files
- TILE-OPEN: The ID of the tile to be placed in open positions (the place where you can walk such as the empty tile or a floor tile or something of that nature)
- TILE-WALL: The ID of the tile to use as the walls in closed positions
- TILE-UP: The ID of the tile to use for any ladder up or analogous tile
- GRANULARITY: This is a percentage in floating point format, for example "1.0" means 100%.  It specifies the percentage of the total map size used to determine how many random elements to generate.  The best way to really understand what this means is to experiment with the value.

As always (meaning with all data files), be sure and back up the original version of the file before making any modifications.


Adjust all colors in the editor

This is an advanced mechanism to apply color gradient changes, which changes all colors in the current tile frame.  It is most useful in an advanced image with a range of colors (including shades of grey in greyscale images).  The purpose is to do things like colorize a greyscale image, change the base color, lighten or darken all colors, etc..  For example, the hand-drawn greyscale dungeon images of several creatures were imported and then colorized using this command (after having been split in separate pieces in order to change the pieces in different ways).  Another example is how image-based dungeon walls such as those in scenario 2 can be modified using this command to produce a version that has an arctic look (although in that case it is done dynamically in the game with a parallel scripting command, but this tool WAS used to determine the values to use there in the first place).

Note that this is totally different from REPLACING all colors, a much more simple operation which is described in an earlier section.

Before using this command, first keep in mind that the best way to understand what will happen is to experiment with the setting (reloading the unmodifed image as needed; do NOT save over the original file).  It may take a number of attempts to find what looks the best and the command may even have to be used several times in a row to do different things to the colors.  When something starts to look good, it is best to write down what was done (the values that were used) so that the operation can be duplicated again or it is more clear what to modify for the next attempt.

It is also important to understand what the values mean and how they are applied.  First of all, the values entered in the command are modifiers to the exiting base color values; they will be added to the existing values.  Both positive and negative values can be used.  The values of EVERY color in the image are increased or decreased by these values.  If a given value hits the max or min (255 or 0), it stops at that point.

While understanding what to do with the command can be very complex, actually using the command is relatively simple.  First, use the "A" (adjust all colors) command.  It will then prompt for a value of each base value.  Enter a positive or negative value (the former is the default while the later requires a minus sign prefix).  After all 3 values have been entered, it will then ask for the type of change, that being whether to add or multiply by the given values.  After entering the desired type, the colors in the image will be altered as specified.

A simple example for experimenting with this is to do the following: start the stand-alone tile editor, load the scenario 2 dungeon wall image (currently named "VWall.til" as of the time of this writing), then adjust with red 16, green 0, blue 0, "A" (add).  This will give the wall a slight red look.  After reloading, do the same again but instead use red 0 and green 16 to give it a slight green look.  The same can be done with blue, but 16 isn't much in that case so try 32 (that said, it turns out a bit more purple than blue).

Another example is to use one of the above examples but subtract instead of adding (such as using red -16 to reverse the change back to the original state or using red -16 after reloading to take some red out of the image, thus leaving it with more green and blue).

A trick that is helpful in some cases is intentionally using the fact it stops at the min or max, particularly when using the command multiple times in a row to achieve the desired end results.  That way, colors that are already at the min or max remain so but colors that are not yet at that given boundary can still be altered.


Editing tiles used for other purposes

As noted previously, tile frames may be used for other purposes.  Two major uses are frames referenced from vector graphics and images that are displayed directly for special purposes in the game (such as when victory has been achieved or when a special item is used).  That said, the later is typically displayed by a command in an associated script, so actually any game feature that uses a script could theoretically display an image directly, not just victory or item use (for example, the image of an NPC could be displayed when you talk to them, an image could be diplayed via a trigger when you step onto a particular position, etc.).

While the features available in the tile editor are the same regardless of the data in question, since these tiles tend to be very large and contain a large number of different colors there are particular features and techniques available that help when dealing with such tiles.

[This section is incomplete with the intent to finish it later.  However, the basic text here should at least provide the basic premise and enough information to look for those features.  They include things such as importing bitmaps (a tool within the game engine), starting the tile editor in the singular mode rather than dual mode, zooming in and out, outlining with a limiting color and then using the flood fill command, using the command to adjust all colors when changing the base color of gradients or to colorize greyscale images, cutting and pasting colorized graphics with different base colors together from separate buffers, and using continuous draw mode to help draw the afore-mentioned limiting color for the flood fill command.]


Tile editor palette

The purpose of the palette is to select a color.  While this was discussed earlier, there are a few details that still require further explanation.  These are mainly related to what makes the palette appear with the given choices.

The palette is set up through one of two methods.  The first, most useful, and the one used in most of the default data is an external text file that sets each value explicitly.  The second is a hardwired (built-in) palette that is used by default when no file has been defined.  

While the built-in palette attempts to include a wide range of choices, the palettes that are defined explicitly with a file are usually much more useful because they can include choices that were made very carefully and limit those choices to give the tiles constructed with them a more consistent look.

A palette file is not required to define all the possible positions.  Those that are not defined automatically are filled with black 0 0 0 (unless another default is set).

A palette file can be loaded using "load palette" from the options (F2) menu.  If no directory is specified, the default directory "TEdit" is used.  All the palette files used in the default data are located there.  Not placing the palette file in the data directories allows the stand-alone mode for the tile editor to remain independent from the data directories and for the palettes to be shared in any case.  It is suggested to locate any new palette files in this same directory, but this is not required.

While a palette file can be loaded using the afore-mentioned option, it can be set persistently for a given data directory using the respective "PALETTE" configuration file setting (editor configuration file details are described elsewhere).

The palette file itself is a textual file and therefore created or altered with a text editor.  It includes the following options:

- Single-line comments: "#" as supported in most of the game and editor data files
- LIST [[list size]] [[entry size]]: The list size is how many entries there are and the entry size is how many values there are per entry.  There are defaults for both of these and therefore the entire setting is optional (unlike many other such initial sizing settings in other data file types).  The default list size is the max size of the palette (currently 256 as of the time of this writing) and the default entry size is the number of values required to represent a color (while the value should always be set to 3 given the current implementation of the editor (1 for each base color: red, green, and blue), allowing other values leaves room for any future enhancement to support other color definition types.  For example, 32-bit color includes an alpha channel value and 8-bit color references an internal palette).
- [entry] [values]: Define the values for a given position.  The entry number is the position in the palette from left to right, then top to bottom.  Having to define the entry number allows setting values in specific positions (skipping any given positions) rather than them having to be defined sequentially in order for the position to be implied as such.  Note that the entry number is base 0.  The values are the base color values such as "0 0 0" for black, "255 255 255" for white, etc..
- DEFAULT [values]: Define a default other than black 0 0 0.  The values work exactly like those for a standard entry.

The best way to understand how a palette file works is to look at the default palette files as examples.

Remember to back up any file before making any changes (for example, copy the file then add a "-orig" to the name).


Editor configuration file

Various setup options are available in the editor configuration file.  To clarify, there is more than one type of configuration file used by the editor and others used by the game.  This section discusses the program's primary configuration file.  Others are described elsewhere.

The editor will read the config file in four cases.  The first is when the program starts normally and the file "editor-0.cfg" is defined.  The second is when the program starts and a specific config file is defined as a command-line option to the main program exe file (optional but can be convenient).  The third is whenever the data ID is changed in the main menu.  And the fourth is by using the "read config file" main menu option.

Changing the data ID and using the "read config file" option are described in detail in another section.  That said, changing the data ID requires some more explanation.

Specifically, when the data ID is changed the program will attempt to read the file "editor-[DATA ID].cfg".  For example, the file for data ID 1 is named "editor-1.cfg".

While how to use command-line options is a generic subject and therefore not explained here, there are some details that require more explanation.  First of all, the value of the option is simply the file name of the config file (be sure and include the file extension).  Secondly, the option is most useful when used with a shortcut or batch file (again, setting these up are generic subjects).

The config file is textual and therefore should be altered with a text editor.  Be sure and back up the file before making any changes.

One particularly important subject is how to create a new config file when creating a new data directory.  The easiest way to do so is by copying then modifying an existing config file.  Be sure that the new name matches the new data ID.  Also be sure and change all of the existing settings that do not match the characteristics of the data in the new directory such as "DATASET", "TESIZE", etc..

There are a very large number of options available in the config file.  Refer to the existing config files as examples.

Note that all of these settings have a default and are therefore optional, although it can be important to set some of them explicitly.  For example, DATASET must be set when it may be loaded through some methods that do not already know the data ID.  But there is a default number of text buffers, so it is not necessary to use that setting under normal circumstances.

Also note that it is possible to define just one field when more than one is required, often X and Y.  When defining just X, simply set only one parameter.  When defining just Y, use an invalid value (typically something less than 0 such as -1) as a placeholder for X.  The field that is not set will continue to use the default.
 
Options include:

- Standard comments: "#", and the "/*" / "*/" pair as supported in most of the game and editor data files.  Note that "#/*" will disable the "/*" and that "*/" does nothing if there is no "/*" preceding it, this being useful when wanting to quickly disable or re-enable a block of text without retyping the "/*" / "*/" pair.
- INCLUDE [filename]: Process the settings in the given file.  This is limited to one file at a time (included files may not include other files).
- DATASET [ID]: This must match the data ID.  Although this may seem redundant in that it is defined in the filename and so is known when it is loaded by changing the data ID, other methods of loading the file do NOT necessarily know this value (and do not try to extract it from the filename).
- PALETTE [filename]: A palette file to load automatically
- TEBUFFERS [value]: The number of buffers available in the tile editor
- MEBUFFERS [value]: The number of buffers available in the map editor
- ANIMATE [[0]] [value]: The value is the animation speed in ms.  The optional first parameter turns animation off.
- AUTOSAVE [[0]] [value]: The value is the autosave frequency in ms.  The optional first parameter turns autosave off.
- FSDRAW [0|1]: Toggles full screen draw mode off or on, a draw method which is faster on some machines.  The default is off.  Note that it is less well-supported and well-tested than the standard draw mode (draw each tile separately).
- SCALE [value]: Each pixel is scaled up by this multiplier.  Low-resolution tilesets will tend to need a higher value while high-resolution tilesets will tend to need a lower value.  Further, the available screen resolution (such as 640x480 vs. 1024x768) may well also lead to the need for higher or lower values.
- EDMARGIN [left] [right] [top]: Offset the position of the tile edit by the given margin in pixels.
- TEPOS [X] [Y]: The position in pixels of the tile editor in stand-alone mode starting at the upper left-hand corner.
- DTEPOS [X] [Y]:  The position in pixels of the tile editor in dual mode starting at the upper left-hand corner.
- TESIZE [X] [Y]: The default size of a tile in pixels used by the tile editor
- TEZOOM [value]: The default zoom scale value for the tile editor in stand-alone mode
- DTEZOOM [value]: The default zoom scale value for the tile editor in dual mode (the "D" stands for "dual" NOT "default")
- MEPOS [X] [Y]: The position in pixels of the map editor starting at the upper left-hand corner.
- MESSIZE [X] [Y]: The screen size in tiles for the stand-alone map editor.  Note that this is the SCREEN size, NOT the map size.
- DMESSIZE [X] [Y]: The screen size in tiles for the dual mode map editor (the "D" stands for "dual" NOT "default").  Note that this is the SCREEN size, NOT the map size.
- WINDOWMODE [FULL|WINDOW]: "FULL" indicates to display using full screen mode rather than a window, while "WINDOW" is already the default so not typically necessary.
- WINDOWSIZE [X] [Y]: The size of the application window in pixels (if using a window rather than full screen)
- RELWINDOWSIZE [X] [Y]: This is a percentage in floating point format, for example "1.0" means 100%.  It specifies the percentage of the screen width or height used to determine the size of the window.  The best way to really understand what this means is to experiment with the value.  Note that it is an alternative to specifying the value directly with the WINDOWSIZE setting, not something that should be used at the same time.
- FSSIZE [X] [Y]: The full screen text display size.  This is the number of characters that can be used in either direction (or effectively the number of lines for Y) in any full screen display (such as the main menu).  It is normally determined automatically, but setting it manually can be helpful in some cases.
- FSFONTSIZE [value]: The full screen text display font size, which is used for any full screen display (such as the main menu).  This is normally determined automatically, but setting it manually can be helpful in some cases.  Note that the size in this context is a scale factor of the base size of the font.
- FSBUFFERS [value]: The full screen text display number of buffers.  This is the number of lines of text available in any full screen display (such as the main menu).  It should at a minimum match the total number of lines possible on the screen.  Increasing the value increases how far back it is possible to scroll, which may be helpful in some cases.
- TDPOS [X] [Y]: The position in pixels of the text display area starting at the upper left-hand corner.  The text display area is the one for most standard text at the bottom of the screen (such as that used once an editor has been selected).  This is normally determined automatically, but setting it manually can be helpful in some cases.
- TDSIZE [X] [Y]: This is the parallel setting to FSSIZE for the text display area (standard text at the bottom of the screen).
- TDFONTSIZE [value]: This is the parallel setting to FSFONTSIZE for the text display area (standard text at the bottom of the screen).
- TDBUFFERS [value]: This is the parallel setting to FSBUFFERS for the text display area (standard text at the bottom of the screen).
- FONT [name] [size] [weight]: This allows defining a specific font (the font is normally determined automatically).  Note that it is VERY important to remember that the only supported fonts are those with a fixed width; variable width fonts are NOT supported.  The size in this case refers to the point size of the font rather than the scale.  Weight is a value indicating how bold it is.  Note that most fonts only support very particular values for the size and weight and may round to the nearest supported value.
- FONTGCW: "Get character width".  This specifies that because the given font has an invalid character width reported by the system, additional analysis must be done to get the correct width.  This only works AFTER the "FONT" setting.
- FONTFIXED: The specifies that because the given font has an invalid fixed width specification reported by the system, it should simply be considered fixed width.  In other words, it turns off (overrides) the automatic detection of whether a font is fixed width and prevents the program from going to a default value instead.  This only works AFTER the "FONT" setting.


Separate game tools

The game itself has a special hidden menu with several tools that were cleaner to implement as part of that program rather than as part of this program even though several of them are highly related to the use of this program.

The tools of most interest in this context are a tool to import a bitmap (convert it to the ".til" format) and a tool to test vector graphics (which is related when the vector graphics reference a ".til" image since that is created/altered with the tile editor).  There are also several unrelated tools that will not be addressed here (for example, one to test sounds).

To use any of these tools, start the game itself.  Once the main menu is displayed, invoke the hidden special options menu with the F2 key and then select the desired tool from that menu.

The bitmap conversion tool will show a prompt and request the filename.  Enter the filename, and (as noted there) do NOT include the extension (which must be ".bmp") since it is already implied and typing it wastes time and effort (particularly when you have many files to convert).  You can (and probably need to) include a full path.  For example, the source may be "C:\Temp\CatTest" to convert CatTest.bmp.  The resulting image will be displayed at the top of the screen and a ".til" version of the file will be placed in the same directory as the source bitmap file.  More files may be converted in the same session.  Press Enter with no file to exit.

The other tools such as the vector frame display tool are accessed in the same manner.  While most are not described in this document since they are for the most part outside the scope of working with maps and tiles, here are a few notes for the vector frame display tool since it is distantly related:

- Before starting the tool, select the scenario in question.
- The available options are displayed by the tool (such as using Escape to exit), but most of the details of what it does are controlled by editing the associated configuration file (currently named "VFDisplay.cfg" as of the time of this writing) and vector frame file (currently named "VFSet.dat" as of the time of this writing).
- A given vector frame may reference a standard tile using an entity command such as "IMAGE" (for example, "IMAGE VOrc.til").  These referenced images are what can be created and changed with the tile editor.  As with all tiles, these referenced files need to be located in the given scenario's respective data directory.
- The game itself does NOT use this tool's configuration file (these are only test settings) but it DOES use the vector frame file, that being what the tool is primarily intended to test.
- These text files and the vector system itself are in no way directly supported in this editor program.  The only related feature consists of any referenced ".til" files.


Editing data files

As already noted, this program is intended only for editing maps and tile frames.  The game contains a vast number of other types of data, but all of that other data is defined textually and can be created or modified with a text editor.  The details for dealing with those files is not included in this manual (a good source of information is in the game's manual).

One important note related to all this is that it is important to reiterate that a tile and a tile FRAME are two different things and that the tile editor is actually used to edit the later (tile frames) NOT tiles.  Tiles are defined in one of the afore-mentioned textual data files and therefore require the use of a text editor; doing so is NOT supported within this program (except in a temporary, limited manner with a special command to create a new tile that is described elsewhere).

Some other examples of other data types that are NOT supported within this editor and require the use of a text editor include scripts that defined complex conversations with NPC's, the vector graphics used for first-person (the graphics traditionally used for dungeons) (with the exception of any referenced raster tile frames, which ARE supported here), the file that defines various game effects (damage types and such), files used to define triggers at given positions, the files that define what is on a given map and how that map behaves (not just the base tiles but rather the creatures and such that are on it, if it is dark or not, the scale related to things like food usage, etc.), and the particularly central file containing the basic definitions of every creature type, vehicle type, location type, item type, and NPC type in the game ("object definitions").  And there are many dozens more types.  NONE of these are supported within this program.  This editor is intended for those things that cannot be done textually, specifically the binary data used for maps and tile frames.


More information

There are a few features that have not yet been described in this manual (or that deserve futher explanation).  Again, use the F1 key to display a summary of the various commands that are available (and don't forget there are more commands available under the F2 options menus).  Most of the commands are fairly intuitive when used in conjunction with the information that has already been documented (for example, some commands require a marked position as a prerequisite, a process that HAS been documented).  And yet again, another important source of information is the game's manual.

[Some of what are probably the next-most important topics to document: Various remaining advanced options (if any) and various remaining F2 menu options and related subjects (if any)]
