The Gemstone of Balance and Other Stories (GGame Engine)

by Gary Arndt


***************************************************************************
About this document
***************************************************************************

I have tried to write these instructions in a way that is clear to both experienced and less experienced users.  Therefore, some of what I explain here will be obvious to many users; the clarifications and such are there simply to try to cover the subject for anyone who may not know.

I have attempted to cover the subject starting with the most basic information first then gradually getting into more and more detailed information.  Therefore, many users will not need to read more than the first few paragraphs of "Installing the game" and a brief look at "Starting and playing the game" and "Uninstalling the game", while others may benefit from also reading the various later details in "Installing the game" and the later sections.

That said, note that there is a "Troubleshooting" section at the very end of this document.


***************************************************************************
Installing the game
***************************************************************************

Unlike many programs, this is designed using an install method where there is no need for an installer.  Some operating systems and antivirus tools that are designed in a questionable manner may complain about this method; while it is always crucial to scan any downloads for viruses and respond accordingly, it may be necessary to skip any extraneous warnings to allow the program to be unzipped and run.

The game is packaged into a zip file.  Simply unzip the complete content into any directory you wish.  For example, if you had previously created "C:\Games", then you could unzip to that directory where it would create "C:\Games\GGame2").  The startup files are located in the root of the unzipped directory.

Note that most simple unzip tools will by default include all files and directories and preserve the directory structure.  However, if you use an unzip tool with any special options then please make certain that they are configured correctly to do so.  You need to end up with the GGame directory containing multiple files (such as "manual.txt" and others) and multiple subdirectories (such as "DATA1" and others with many files inside most of them).  If you end up with only a single file or subdirectory, if all of the files are together rather than inside various subdirectories, or if there are no files inside directories such as "DATA1", then the unzip process has not done this correctly and the game will not run properly.

If you are unfamiliar with zip files, please refer to any general instructions on the subject for details.  Most newer operating systems include built-in zip tools.  If you are unfamiliar with creating directories and navigating the file system of your machine, again please refer to any general instructions.  I have included some brief information on both of these subjects in later sections of this document.  An internet search may be a reasonable source of further information (just don't look at information that appears to overcomplicate the subject, since the basics are not all that complicated, or information that tries to get you to download some additional program, since the unzip tools are usually built into the operating system).

It is a good idea to save any install package in case you want to reinstall a program.

If you download the zip file, be aware that some browsers may be configured to try to immediately unzip the file.  I would suggest NOT doing so, but instead saving the intact zip file to some location you can find again such as the desktop.  That said, if you do let the browser immediately unzip it, be sure that it does so correctly (as noted above) and to the location where you want it installed or at least to where you can find it in order to move the install directory later to where you want it installed.

I have heard that unfortunately a few systems can sometimes be misconfigured to try to lock their own users out of some directories.  If this happens (for example, you are unable to create a directory like "C:\Games" or write to it because you don't have write permissions for "C:\"), please either attempt to open permissions to write to the directory in question or install the game to a directory to which you do have permissions (perhaps something like the desktop).  While opening permissions is beyond the scope of this document, it is worth mentioning to be careful doing so and that further information may be available in your operating system manual or via an internet search.  That said, if you are unfamiliar with these concepts then it is probably better to just install to another directory where you do have permissions.

Lastly, note that this program does NOT do anything else related to installing.  It does NOT download anything additional from the internet.  It does NOT do any automatic updates.  Running the game does NOT cause it to take any subsequent install steps.  It does NOT intentionally add any settings to the registry ("intentionally" meaning that the operating system may add some information about the program for peripheral purposes).


***************************************************************************
Starting and playing the game
***************************************************************************

Please refer to the manual.txt file located in the root of the install directory.


***************************************************************************
Uninstalling the game
***************************************************************************

Since this game uses an install method that does not create a mess of files and registry settings and such, there is no need for an uninstaller; simply delete the unzipped directory (such as C:\Games\GGame2).  Further, there are no files created anywhere else on the machine; all original and save files are appropriately contained within the install directory.

Do be careful not to delete anything else (for example, if the game is installed as "C:\Games\GGame2", then do not accidentally delete "C:\Games").

Again, note that deleting the game's install directory will also cause all save games to be deleted.  Therefore, if you wish to preserve your save games, then you will need to move the "Save" directory elsewhere before doing so.

Similarly, you may also want to move or copy any other customizations you may have made such as a keymap file, changes to a configuration file, custom scenario files, etc..


***************************************************************************
Zip files
***************************************************************************

If you are unfamiliar with zip files, here is some brief information.

A zip file is typically used to store and transfer a group of files within a single file for convenience and because it is compressed so that it most often uses less space.  A zip file may contain multiple files, directories, and a complete directory structure (as it does for this game).  There are many types of compressed files, but this program uses zip, one of the most common and therefore built into many newer systems.

A method to unzip a zip file on many systems is as follows:
- Navigate to the zip file
- Right-click on it to open the context menu
- Choose the "Extract All" option and follow the prompts
- When it asks which directory to use, this is where the install directory structure will be placed.  You may wish to choose something like "C:\Games", "C:\Programs", maybe the desktop, etc..  "C:\Program Files" is probably not the best choice for a variety of reasons, but may potentially work.


***************************************************************************
Navigation and the file system
***************************************************************************

If you are unfamiliar with navigation and the file system, here is some brief information.

File management is crucial knowledge for any computer.

Navigation is the process of locating a given file or directory so that it may be selected and manipulated.

On operating systems like Windows, this is typically done using the built-in file explorer, which is probably the single most important program on the system.  Please refer to any general instructions (such as your operating system manual or online information) if you are unfamiliar with this program.  Note that the file explorer may appear in a variety of forms; any form is appropriate as long as you can navigate the file system, select files and directories, create new directories, etc..

On many versions of Windows, the dual-pane tree/content form, which I believe is the most clean and useful version, can be started with the hotkey "Win-E" (although some additional configuration is usually necessary the first time it is used to put this program into a clean and useful layout).  However, many users typically use the "My Computer" link (shortcut).

In this particular case, you should use it to navigate the file system to any given file or directory, to optionally create any new directory you wish to install to, to unzip the zip file that you downloaded, and to start the program.  You can also use it to help manage save games, to uninstall the program, to create links (shortcuts), and for many other purposes.

This is entirely optional, but to elaborate on what I consider the most useful configuration for the file explorer:
- Two panes, left and right
- The left pane shows the directory tree
- The right pane shows the content
- The content pane is set to "details" so that it shows a concise list of files and subdirectories
- The content is set to show the name, size, file type, and date modified

That said, many users prefer a single window, icons instead of lists, or file content previews, all of which seem to be the default configuration on many system.


***************************************************************************
A step-by-step install example
***************************************************************************

This is a step-by-step example of how one could decide to install the game given particular circumstances.  These instructions are an example because they may only work on some particular systems and make assumptions about the results the user wants (such as which directory to install to).

- The zip file is named "GGame.zip" and located at "C:\Downloads"
- Press the "Win-E" hotkey to open the file explorer
- Navigate to "C:\"
- Create a new directory named "Games".  One way of doing this is to right-click in the file pane (which will be on the right if the explorer is configured in the dual-pane tree/content manner), select "New", then select "Folder".
- Now the "C:\Games" directory should exist
- Navigate to "C:\Downloads"
- Right-click on "GGame.zip" and select "Extract All..."
- The "Extraction Wizard" window appears
- Press the "Next" button to move past the "Welcome" screen
- In the "Files will be extracted to" text box type "C:\Games"
- Press the "Next" button and wait until the wizard is finished extracting the files.  There are a lot of files (although most are extremely small), so this may take a while.
- When the wizard is finished, uncheck the show checkbox, close it, and go back to the file explorer
- The file explorer should still be at "C:\Games" but now contain a "GGame2" directory.  In other words, now the "C:\Games\GGame2" directory should exist.  If it does not, something went wrong.
- Navigate into the GGame2 directory
- Verify that some files such as "manual.txt" exist and some directories such as "DATA1" exist.  If they do not, something went wrong.
- The game can now be run by double-clicking on a startup file such as "GGameS2[etc].bat"
- Test doing so and make sure the main menu appears
- Press the "Q" key to quit
- Open the manual.txt file

Optionally to create a shortcut to the directory:
- Navigate to "C:\Games"
- Right-click and drag the "GGame2" directory onto the desktop
- A context menu should appear
- Choose "Create Shortcut Here"
- The game folder can now be opened with that shortcut
- As before, the game can now be run by double-clicking on a startup file

Optionally to create a shortcut to a scenario:
- Right-click and drag a batch file such as "GGameS2[etc].bat" onto the desktop
- A context menu should appear
- Choose "Create Shortcut Here"
- The game can now be run with that shortcut
- Test doing so and make sure the main menu appears


***************************************************************************
About this install method
***************************************************************************

Many programs use installers and so many users are used to this approach.  While installers can sometimes be useful when they are implemented correctly, they all too often tend to encourage an unclean install where a given program's files are located in a wide variety of locations all over the machine, it makes a mess in the system registry, it prevents the user from understanding what is actually on their machine, it adds unnecessary programs that run everytime the machine runs, it prevents a user from having the option to maintain their own links, it prevents multiple installs, etc..  In other words, they all too often create a general mess, which requires a special uninstaller to attempt to clean it up (some of which do not actually complete the job correctly).

The install method for this game does not use an installer, which keeps things simple and clean.  It has the following advantages:
- It keeps the results of an installation very clean and simple, as it should be
- It discourages the problems listed above
- All files and related data is contained within a single directory
- It makes it clear to the user what is actually installed on their machine
- Multiple versions of the same program may be installed
- The user may freely create and modify data, links, etc.
- It is clean and easy to uninstall (simply delete the directory)

The disadvantages are:
- It may take very slightly longer
- Some systems and antivirus tools and such that are designed in a questionable manner may issue warnings and/or lock users out of directories they should have access to
- The user must understand how to use their file explorer (which is not really a bad thing)
- The user must understand how to manually unzip a zip file (again, not really a bad thing)
- The user must either navigate to the install directory each time they want to use the program (which used to be the standard approach on older systems), or they must manually create any links (which gives them more control over their own machine, so not really such a bad thing)

In any case, this is the main reason I have opted to use this install method rather than writing an installer.  While a carefully-implemented installer may add a very small amount of convenience (walk the user through the navigation/copy process and automatically add some links), and I may even consider it as a low-priority enhancement in the future, in general it does not seem particularly worthwhile and I would prefer to instead encourage this install method.


***************************************************************************
Installing other related programs and packages
***************************************************************************

These overall install instructions are written specifically for the game itself.  However, there are some other related programs or other packages that you may also want to install.

To be clear, all other programs and packages are optional; the game consists of a single self-contained program.

The process of installing other related programs and packages is largely the same as it is with the game.


If a program is a completely different one such as the editor, it should typically have a different root directory name.  For example, you may place both at "C:\Games" so that the game ends up as "C:\Games\GGame2" and the editor as "C:\Games\GGame2-Editor".


If a package is a patch and includes a special install document, follow those instructions.  If it does not include any special install document and has only one file or a very few files, then replace the original copy/copies of the included file(s) with the new one(s) following this process:

- Rename the old file(s) so that they have a different name such as "[file]-orig[[.extension]]" (for example, "app.dll" would be renamed to "app-orig.dll").  You could instead delete it, but it is probably better to rename it in case you have to restore the original file for one reason or another.

- Copy the file from the patch's zip file to the same location as the original.  You should now have a copy of the file named with "-orig" and one without (for example, "app.dll" and "app-orig.dll").


If the package is for a plugin, the file must be placed in a directory of your choice that is then defined as the path of the PLUGIN configuration setting that points to the file in question.  For example, if you created "C:\Games\GGame2\plugins" and placed "plugin-ping.dll" there, then the setting should be "PLUGIN: plugins\plugin-ping.dll".


***************************************************************************
Troubleshooting
***************************************************************************

The following issues have come up during testing.


You are unable to enter text in some situations, such as at prompts

There appears to be an error on some systems when either some other programs are running or the system has somehow become in a bad state.  Rebooting and not starting other programs seems to resolve the issue.


Text is displaying wrong or shifting around

This is a font error on some systems.  An enhancement was made to the game to automatically try other fonts if the primary default font is detected as having been damaged.  More specifically, the game first attempts to use the standard fixed-width system font.  If that font appears to be damaged, it tries several other fixed-width fonts until one that is undamaged is detected.

If you do not like the font that ends up getting used or even simply want to change the primary default font in any case, it is possible to manually select a particular font.  Refer to the manual for details.  That said, it is worth noting here that it that the font in question MUST be fixed-width; variable-width fonts are NOT supported.

Correcting the system font error itself is beyond the scope of this document (and NOT necessary for the game to work), but online research seems to indicate that it is possible (the problem seems to be that the essential fixed-width system font "Fixedsys" can be overrided by an incorrect font and thus made unavailable).  However, it is NOT suggested to do so unless you are certain you understand what you are doing and are VERY careful doing so (back things up before making changes, etc.).  Further, as noted above, the game has the ability to use alternate fonts, so it is NOT necessary to change your system in order for the game to work.
