Heditor Manual v1.0



Chapter Summary
Chapter 1: What is HEditor An overview of what hed will do for you.
Chapter 2: Setting Up Your Map The steps involved in setting things up whenever you want to edit a map.
Chapter 3: Loading and Saving How to load and save...and what can go wrong.
Chapter 4: The Tile Menu The options available under the Tile menu.
Chapter 5: The File Menu The options available under the File menu.
Chapter 6: The Reset Menu The options available under the Reset menu.
Chapter 7: The Preferences Menu The options available under the Preferences menu.
Chapter 8: The Help Menu The options available under the Help menu.
Chapter 9: Preferences How to use preferences.
Chapter 10: The Keyboard The keyboard commands.
Chapter 11: The Mouse The mouse controls.
Chapter 12: The Command Line What parameters there are to HEditor.
Apendix A: General Tips Some tips for stress-less map making.
Apendix B: Fortelling the Future Some possible future directions.
Apendix C: Some Screen Shots Some miscellaneous screen shots.

Chapter 1: What is HEditor

An overview of what hed will do for you.

HEditor is designed to allow you to create and edit terrain and object maps out of H3D files. You can set the attributes of each tile in the map through an easy to use and dynamic menuing system. All the tile menus are built from user-defined files, so they are dynamic from map to map. What this means for you is clear cut definitions of what each tile, obstacle, and bit represent.

HEditor does not currently allow you to modify any of the H3D files. If you make a change in an H3D file and want to see that in your currently running HEditor, you can reload all of the H3D files.

Currently, the maps created are always 100x100. Due to time constraints, it was not feasible to implement a dynamic load and save process for maps.


Chapter 2: Setting Up Your Map

The steps involved in setting things up whenever you want to edit a map.

To set up each map you want to create, you will most likely need to modify several of HEditor's menu files. These files are:

Each of these files sets up one of the "Tile" sub menus with choices tailored to your taste and available H3D files. These same files will be used to understand the map file generated by HEditor. This is an important and somewhat confusing issue. I wholeheartedly suggest you make a directory with the name of the map your are creating and store the .hed* files for that map in there as well as the map itself. Because HEditor generically creates maps, the .hed* files are vital to reproducing the results you desire when you are ready to read the map into your program and display it. Otherwise, you will have extreme problems. Trust me.

Beware! Once you save a map file, you cannot reorder the .hed* files unless you intentionally do so. For instance, if "Forest" was the first terrain tile and "Water" second, then you saved, then you added "Forest 2" after "Forest"...anything that was previously "Water" will now be "Forest 2". This is the same for all three files. So, if you make more tiles after you have saved the map, you must add them at the end of the .hed* files.

.hed_terrains is the menu file for "Tile | Terrain Tile". It is made up of lines with the format:

<Filename> <Short Description>
These tell HEditor the filename of an H3D file and the description of that file so it can properly build your Tile menu.

.hed_obstacles is the menu file for "Tile | Obstacle Tile". It is made up of lines with the format:

<Filename> <Short Description>
These tell HEditor the filename of an H3D file and the description of that file so it can properly build your Tile menu.

.hed_bits is the menu file for "Tile | Bits". It is made up of lines with the format:

<Short Description>
Note the different format. You do not specify a filename for defining the bits. What are bits? Bits are the bits (I know, defining the word with the word...but you should know this stuff by now) for the bitvector of attributes for each tile in the map. You will probably want to think these through before making them (be sure you understand their purpose).

Terrains and Obstacles have a maximum number of 255 each. This means you can have 255 terrain H3D files and 255 obstacle H3D files. It does not mean you MUST have that many. You are only allotted 32 bits due to the size of an unsigned long, but this should be plenty given the purpose of this bitvector.


Chapter 3: Loading and Saving

How to load and save...and what can go wrong.

Loading and Saving are very easy to do. From the "File" menu, you can select one or the other. You must be careful when you are loading a file as it will overwrite (without prompting you) the current map you have loaded in memory. This can be a dangerous thing as you can lose changes you have made. Saving can be equally dangerous because it will overwrite (without prompting) the filename you specify on disk. This means you should be absolutely sure you want to really save the map as what you're saving it as.

Other than overwrite issues, any errors you get should be pretty easy to decipher as they'll be the error strings from C (Permission denied, etc).


Chapter 4: The Tile Menu

The options available under the Tile menu.

The Tile menu is dynamically constructed from the files talked about in Chapter 2. The submenus will always show what the settings are for the current tile. The "Terrain Tile", "Terrain Orientation", "Obstacle Tile", and "Obstacle Orientation" menus allow only one item to be selected at once. The "Bits" menu allows for either "None" or any combination of the other items (if you have any). Also, on the "Bits" menu, selecting an item which is already on, will toggle it off and selecting "None" will turn off all bit settings.

Tile

The "Terrain Tile" menu allows you to set the H3D file you want to have displayed in the current map location. You can then rotate it using the "Terrain Orientation" menu, if you so desire.

Terrain Orientation

The "Obstacle Tile" menu allows you to set the H3D file you want to have displayed on top of the terrain in the current map location. You can then rotate it using the "Obstacle Orientation" menu, if you so desire.

Obstacle Orientation

The "Bits" menu allows you to set the attributes of the current map location. This is a powerful tool as you can add special effects to your environment based on the interaction of its inhabitants. For instance, you might want to have different speeds of mobility based on the type of terrain the object your moving is on. Or a trigger which raises and lowers a bridge, perhaps.

Bits


Chapter 5: The File Menu

The options available under the File menu.

The File menu gives you the options of Loading a map file, Reloading the current map file (useful when you have changed an H3D file), Saving the current map file, and Reloading the Configuration files (.hed*).

File


Chapter 6: The Reset Menu

The options available under the Reset menu.

The Reset menu lets your reset Rotation, Zoom, Pan, Light, or All of the above to the default values (same as when you start up HEditor).

Reset


Chapter 7: The Preferences Menu

The options available under the Preferences menu.

The preferences in HEditor pertain to modifying how things are displayed to you. They do not affect the map or H3D files in any way. See each section below for a brief description of each preference. See Chapter 9 for more information.

Preferences

You can set the background color of the OpenGL canvas to Black, Gray, or White.

Background

You can turn the grid on or off.

Grid State

You can set each color component to 1 or 0 (giving your primary and secondary color choices) for the grid color.

Grid Color

Scale is a percentage value which tells HEditor how many tiles to draw on the screen at once. It does not "glScale" anything.

Scale

The last preference option is the ability to save the preferences as they currently are set in your system. These will be loaded as the default the next time you run HEditor.


Chapter 8: The Help Menu

The options available under the Help menu.

The Help menu gives a very brief synopsis of the various options available in HEditor. There is help for the program in general and for preferences.

Help


Chapter 9: Preferences

How to use preferences.

To get a default listing of all the preferences, use the command "hed -d". This will save the file ".heditor" in your home directory. You are free to edit it as you see fit, but only certain answers are valid. You will see warning/error messages when you start up HEditor if you have incorrectly set something.

The preferences currently available are:

Grid
On | Off
GridRedComponent
1 | 0
GridGreenComponent
1 | 0
GridBlueComponent
1 | 0
GridSize
50 | 100 | 150 | 200
NumVerticalGrids
1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10
BackgroundColor
black | gray | white
DisplayScale
25 | 50 | 75 | 100 | 150 | 200


Chapter 10: The Keyboard

The keyboard commands.

Keyboard:
        Movement (keypad or main keyboard):
                7 8 9           u i o
                 \|/             \|/
                4-+-6           j-+-l
                 /|\             /|\
                1 2 3           m , .

        Hotkeys:
                ~ - Copies to clipboard         ` - Copies from clipboard
                h - Print This Text             p - Preferences Help
                <ESC> - Exit


Chapter 11: The Mouse

The mouse controls.

Left Mouse Button:
        No Modifier: 
                Rotate Camera
        Control: 
                Rotate Light
        Shift: 
                Pan Camera

Middle Mouse Button:
        No Modifier: 
                Zoom Camera

Right Mouse Button:
        No Modifier:
                Menu System


Chapter 12: The Command Line

What parameters there are to HEditor.

usage: hed [-v] [map_filename]


Chapter 13: Terrains and Obstacles Windows

How these windows work.

The Terrains and Obstacles windows were added to make developing your maps easier when initially setting things up. Whenever you are on a tile, the same terrain and/or obstacle tile gets "boxed" in the Terrains and Obstacles windows. If you click with the left mouse button on a different tile, it will select that (either the terrain or obstacle depending on the window) as the current terrain or obstacle tile. Clicking in the lower left hand "empty" area will select "None".

If the title of either window has "[Make Bigger]" in it, that means your window is to small to display all of the terrains or obstacles you have defined. Resize the window to your liking. You can arrange the windows however you wish and they will rebuild correctly.

Appendix A: General Tips

Some tips for stress-less map making.

Save Often. This program is stable, but there are unknown variables which can always cause problems.

Copying a tile to another tile is a fast way to build up your map. If you have large areas of tiles (like a forest or a lake), it's easy to fill in that space using the clipboard in HEditor. First move to the tile you want to duplicate (this means everything, bits, terrain, obstacles, and orientations) and press the "~" (tilda) key. This copys the current map location to memory. You should receive a message on stdout telling you it has been copied. Then proceed to where you want the tile to appear and press the "`" key. Why choose these keys? Because they're out of the way of "accidentally" hitting them.


Appendix B: Fortelling the Future

Some possible future directions.

Too tired right now.


Appendix C: Some Screen Shots

Some miscellaneous screen shots.

To avoid unnecessarily long load times of this documentation, the screen shots are in a different location.