GGame Unix Textual Editor

by Gary Arndt

--------------------------------------------------------------------------------
What is this, why is it textual, and isn't there already an editor?

This is a secondary, lighter map editor for GGame.

The standard, full version of the editor currently runs only on Windows and is entirely separate.  Beyond a vast number of additional features, it uses full graphics like the game itself.

This light, textual version was written primarily to address a specific need, that being to edit map files on a cell phone, although a secondary purpose is to edit maps on Unix in general.  I started this project when I had a lot of time to spend on a cell phone and wanted to work on designing maps.  I suddenly realized that I could write a special, separate editor to do so for Unix that could run on a Linux emulator like iSH for Apple.  iSH currently only supports text (no graphics), so this version of the editor is also text-based (otherwise I would have instead ported the full version of the editor).  However, using colors and text styles makes it work reasonably despite the lack of graphics.


--------------------------------------------------------------------------------
What is iSH?  Can this be used without iSH?

iSH is an app for Apple cell phones.  Once you install it you have access to a version of Unix called Alpine Linux.  You may then install this program inside iSH and run it to edit maps to copy and use later on Windows in your GGame scenario or editing further in the full version of the editor.

This editor is a Unix program.  At this time, it has only been built and tested on Alpine Linux.  It should be possible to run it on any machine or app running Alpine Linux, but was tested using iSH on an Apple cell phone.


--------------------------------------------------------------------------------
Documentation

This file is the manual for this version of the editor.

A fundamental list of commands is available within the program by using the '?' key.

Some commands lead to a menu of options which provide information similar to using the '?' key.  For example, the options menu displays such a menu.

A list of command line options is available by using an option such as "-h", "-help", "--help", "/?", etc..  For example, "ggedit -h".  In case you are not familiar with command lines, it is worth mentioning that it will usually be necessary to scroll up to see the complete results.

Much more detailed information about editing maps and such can be found in the manual for the full, standard Windows version of the editor.  Be aware that some things differ, however, such as the keys used to activate commands and many features that are only available in that full editor.

Also, since this document still has a few minor things that are unfinished, that full editor's manual is a good reference to fill in the gaps.


--------------------------------------------------------------------------------
Basic use

Startup

- The program is named ggedit but different data dirs can be selected at startup by using the d[D] or dl[D] links that are preconfigured with the respective command line options (the later "dl" links more compatible when using a large font, 'l' for "large").  Further, these links can be edited to include additional command line options (for example, screen display size) or alter those that are already there.  This means the links effectively serve in place of a configuration file.  There is currently no command to change data ID so quit then restart if you need to do so.

- Although it should be clear from the startup text and help menu, it may be worth mentioning that the quit command is 'Q' (capitol, not lower case).

- Note that commands within the program are case-sensitive, meaning if a command is an upper case letter  then entering the lower case equivalent will NOT work, and visa versa.

- When the program first starts, the map is a default size and empty.  You may start editing a new map at this size, but it's more likely that you will want to first adjust the size using the options command resize choice ('o', 'r') or you may want to load an existing map by using the Load command ('L').  For example, if you started with data 2 via d2 or dl2, you could enter 'L' to load then type "s2-2" at the prompt to load that sample file (which happens to be scenario 2 map 2, the map you start on in scenario 2).


Font size

- The default font for iSH is very small and using at least a somewhat larger font size is highly recommended.  In the version of iSH that was used to develop this program, this was accomplished in the iSH settings menu.  The editor default size supports a larger font size, for example 21-point was used for much of the work.  That said, this was still somewhat small so the "dl" links were added and used with 32-point.  The disadvantages of a larger font size are showing less of the map at one time, and an additional disadvantage of the dl links are that the display excludes some of the summary info on the top line above the map.


Commands

- The built-in help mentioned earlier describes the commands available within the program.  Note that these commands often diverge significantly from those in the full version of the editor for Windows.  This is intentional due to the differences in a cell phone virtual keyboard, the small cell phone screen size, etc..


Position

- An aspect of the editor is the current position on the map.  This position is displayed at the exact center of the screen, just like in the game itself.  If the map prompt is on (the default), that center position will be highlighted in some manner, appearing differently than the tile in question would normally appear (often as inverse black and white).

- Movement can be accomplished using several methods.  The most fundamental is with the classic gaming keyboard "wasd" controls (meaning, classic for many other games, NOT actually GGame itself), meaning each of those keys for the given direction ('w' for north, 'd' for east, 's' for south, 'a' for west).  The arrow keys will do the same but are slightly more awkward in iSH.  That said, iSH DOES allow holding the arrow key control which means moving in the given direction repeatedly, a very useful way to move quickly.  The "jump" command allows going directly to a position such as a screen at a time, the center of the map, the edge of the map, or a corner of the map.

- The position is also a numeric x y coordinate.  This is shown at the top of the display.


Changing the map

- There are many commands for changing the map, but the most fundamental are those to set the tile at the current position.  The most simple of these commands ('x') will set the tile to the "empty tile", ID 0, meaning it is effectively an erase.

- Like current position, there is also a current edit tile.  A prerequisite step for many commands is to set the edit tile.  There are multiple commands for doing so such as the Get command ('g') to get the tile from the current position or the very direct but more cumbersome Set Tile command ('T') to enter the tile ID at a prompt.  The various next/previous commands change the tile at the current position and also set the edit tile to the result at the same time.

- Once the edit tile is set, the fundamental command to set that tile at the current position can be used (the RETURN key).  The most recent tile that was changed is tracked in order to allow for the reverse command (the BACKSPACE key).

- Of course, remember to save the map ('S') so any changes you made are not lost.

- If a section is marked with the Mark command ('m') then commands like the fundamental command to set the tile at the current position will apply to the entire marked section.  The mark and current positions together specify the upper left and lower right corners of a square.  That square is the section in question.  Which corner is the mark and which is the current doesn't matter.  The display will indicate at the top line info if there a marked position has been specified.  Using the Mark command again will change the mark position.  The Unmark command ('M') can be used if the mark is not needed after all.

- The info command ('i') displays a variety of information that can be particularly useful while editing.  This command is further detailed later in this document.

- There are a variety of other commands available to change the map such as a global fill, a global replace, and a section shift.  These are described in the help.  Also, some of them are further detailed later in this document.


Filenames

- Filenames and their path start from the directory of the program but there are mechanisms built in to make them easier to specify.  When loading, they may optionally be shortened to exclude some subdirectories that are automatically checked and the ".map" extension.  The subdirectories include "save" and "DATA[ID]".  For example, if you are using data dir 1 (the default) and there is a DATA1/24.map, then you only need to specify "24" to load that file.  When saving, if no path is specified then "save/" is automatically prepended.


Tilesets

- Built-in tilesets (DATA[ID]):
1: Ult2 base translated, extended with extra tiles used for scenarios 1 and 3
2: g1, the GGame 1 tileset used for scenario 2
3: Ult2 dungeon map editing tileset, extended with extra tiles used for scenarios 1 and 3
4: g1 dungeon map editing tileset used for scenario 2

- Each of these tilesets has at least one corresponding sample map in the respective data directory.

- You may add data directories of your own.  The easiest way to do this is to copy and modify an existing data directory and corresponding startup link.  It will of course need a unique ID, for example "DATA1000" and d1000.  Be sure and modify the content of the link so it points to the new data directory; it does not parse the link name but rather uses a command line option.


Display modes

- This editor defaults to an in-place display, automatically displaying when necessary, and displaying a map cursor, but a more simple approach can be used if you prefer.  These more simple modes of operation may be useful if something is not working correctly on your system for some reason.  The afore-mentioned features can be toggled on/off in the options menu.  Also, there are command line options to control these.


Command line options

- The built-in command line help mentioned earlier describes the command line options that are available.  Normally you will not need to use these directly, but it is important to mention that they exist in case you need them.  For example, there is an option to start with a specific data ID, there are options to set a specific screen size, and many more.

- Unlike the full version of the editor, there is currently no configuration file, but the command line options along with being used within links may serve in place of that.  The easiest way to do so is to edit the preconfigured links or to copy and modify those links.


--------------------------------------------------------------------------------
Command details

As mentioned earlier, the commands are listed within the program by using the '?' key.  That said, additional details about some of those commands are presented in this section.

i: Info

This displays some general information

The following abbreviations are used:
ET: Edit tile
PT: Previous edit tile used for the associated command (BACKSPACE)
CT: Current tile, meaning the one at the current position


f: Fill map

Fill the entire map with the edit tile.  This means the edit tile must be set to the tile to fill with prior to using this command.  A verify is done in case of accidental keypress.


E: Replace tile ("rEplace") 

Replace all instances of the tile at the current position with the edit tile.  This means the edit tile must be set to the tile to replace with prior to using this command.  A verify is done in case of accidental keypress.


I (cap i): Find tile ("fInd")

Find the next instance of the edit tile on the map by going to it if found.  This means the edit tile must be set to the tile to find prior to using this command.


H: Shift section (sHift)

Shift the marked section by a given X and Y amount and replacing positions underneath with the edit tile.  This means the mark position must be set to the start position and the edit tile must be set to the tile to replace with prior to using this command.


[More text NYI]


--------------------------------------------------------------------------------
Additional details

Tileset synchronization

- While the textual versions of the built-in tilesets reflect the respective real tilesets on the given program version date, they may become out of synch with any future changes to the real tilesets; please feel free to update them with any changes, as needed.  Such changes are most likely to consist of a new tile, maybe a few new tiles, that would need to be correspondingly added.  Be sure and back any such changes up if you switch to a newer version of this program, although that is likely to then include corresponding tileset updates.  Note that while this issue is technically true of any of the built-in tilesets, the g1 (DATA2, scenario 2) tileset happens to be one that is more likely to have such changes.  To be clear, this does NOT effect any maps that you create or modify using the existing tilesets; no existing ID's of base map tiles will be removed.


New tiles and editing tiles

- The options to add a new tile and to edit a tile ('T') are both temporary, meaning the changes can not be saved, persisting only for as long as the program is running.  To make permanent changes, the tileset file itself must be modified directly.  The purpose of the temporary commands is to support using tiles that have not yet been designed or at least not fully integrated, or to support changes that are not intended to be permanent such as for the temp tiles mechanism, or to try out changes to the textual tiles real-time before integrating them into the textual tileset.

- The afore-mentioned options are marked as "temp" for those reasons (the results being temporary), NOT the options themselves being removed at some point or anything like that

- When a new textual tile is created using that option, it is entirely blank so you will most likely then want to afterwards use the edit option

- Some of the prompts require a color specification.  These use the same syntax as the tileset file, therefore refer to that topic for the list.


Tileset file

- The syntax of the textual tileset file is detailed here for if any changes to the standard tileset are not yet correspondingly updated here and so you do so yourself or for the sake of custom scenarios

- The tileset file is per scenario and thus located in the respective DATA[ID] subdirectory.  It is specific to this editor and, while it parallels the real tileset file used in the full Windows version of the editor and the game itself, is entirely separate and distinct.  It defines the list of tiles and how they should appear.  Note that unlike the real tileset file, this textual tileset file does NOT reference an external .til file but rather defines the visual details of each tile directly.  Use the built-in textual tileset files as examples.

- The first actual setting that should be defined, and only defined once, is "TS [count]" where count is the number of tile buffers to allocate.  This needs to be high enough to contain both the total number of tiles defined directly in the file plus any additional that may be added temporarily using those internal options.

- T [ID] [char] [[name]]: Defines a tile with the given ID, textual character (the "char" field), and optionally a name.  The name must be in double quotes and may optionally contain spaces.  If the character is a backslash character then it invokes special behavior where a number for the ascii character may be used (for example, "\32" to specify a space) or else use another backslash to define an actual backslash character ("\\").  Note that while the backslash notation opens up the potential to use special characters, only those that can be displayed should be used.

- FC [color] or BG [color]: Foreground or background color

- The following color specifications are used both in the textual version of the tileset file and at the tile edit color promps.

0 (zero): Default
R: Red
G: Green
B: Blue
WH: White
BL: Black
GR: Grey
LGR: Light grey
DGR: Dark grey
BR: Brown
OR: Orange
YE: Yellow
PU: Purple
PI: Pink
LB: Light blue
LG: Light green

- Styles can be used via "BO" for bold and/or "ITL" for italics


[more potential subjects NYI]

Some additional subjects in this section for me to potentially address at some point:
- Consider maybe more details about subjects discussed earlier
- Consider maybe at least 1 step-by-step tutorial
- More TBD


--------------------------------------------------------------------------------
Unfinished

- More work on this doc
- More work on the install guide
- Thoroughly test that all modes behave optimally with respect to messages and any refresh, fix any problems
- Investigate the problem when using bold and max optimal height with refresh flickering (does the total height used by the char perhaps become slightly larger and thus provoke scrolling?)
- Finish implementation of defined default tile
- Try to save and restore the overwritten console text (like vi seems able to do)
- Other misc. tasks listed in comments in the source code

Maybe:
- Change data dir without restarting
- More command line options parallel to other existing internal options
- Other optional tasks listed in comments in the source code
