The Gemstone of Balance and Other Stories (GGame Engine)

by Gary Arndt


***************************************************************************
What is this?
***************************************************************************

This document is intended to provide notes on any critical topics such as critical bug fixes, provide any notable information about given release versions, explain the different documentation that is available, and cover any other topics that do not belong elsewhere.

Reading this document is not required to play the game, but it is recommended that you scan through the following summary of topics.

Critical topics:
- Bug fix: Exiting some dungeons goes to the wrong destination (in earlier versions).  This bug has been fixed and so reading this section is only important if you ran into this bug in an earlier version and have an existing save that you would like to transfer to this version.

Recommended topics:
- Documentation

Other topics:
- Release notes
- Transferring saves and save compatibility


***************************************************************************
Bug fix: Exiting some dungeons goes to the wrong destination
***************************************************************************

In an earlier version, did you enter a dungeon far north of Seaport, fall into a pit, and when you tried to exit the dungeon you instead appeared at the top of the pit?

Released versions prior to 230522 contained a bug that caused exiting some dungeons (those with map-based pits) to go to the wrong location.  This is now fixed.

That said, versions 230601 and later contain a related fix.  The problem is that an incorrect position could potentially have been included in saves that are in progress done from old versions (this is the case if your save is at a point where you have already entered one of these dungeons and have been unable to leave).

To solve this potential problem, a special option to fix saves that have the wrong location is now included.  The save itself is not directly modified, but rather the changes are made after such a save has been loaded (although if you use the default save rather than named saves, do not forget it is automatically saved over in a variety of situations such as many of the map changes, so you may want to back it up before proceeding).

Further details about the fix and when to use it are displayed when the option is selected (and it should be noted that it is possible to cancel the option if you decide not to proceed).

To access this option:
- Make sure the problematic save game is available in this version (making old saves available to use in a new version is explained in a separate section later in this document)
- Start the game and load the save game in question
- If you are not there already, move to a position near the exit of the dungeon and consider resaving the game in case you have to attempt a second step (detailed later) so you don't have to come back again but can simply reload
- Go to the options menu (F2)
- Select "Advanced options" (F2 again)
- Select "Bug fix options" ('B')
- Select "Remove invalid exit point" ("1")
- Read the text explaining the various details
- If you are ready to apply the fix, then select yes ('Y'), otherwise press any other key to cancel
- If it says there is another additional position, then you should probably try removing that as well ('Y')
- Try exiting the dungeon.  If it goes to a wrong location but one that is different from before, then reload and try removing only 1 position rather than 2.
- Once you are able to exit the dungeon, consider saving the game

Further notes about this option:
- The text with the option explains all of the important points of what you need to know to apply it, but is a general solution so does not addressing any specific situations
- One of the primary ways this bug can show up is in scenario 2 to enter the dungeon far north of Seaport (on the east coast on the west side of the mountains), fall into one or more map-based pits, escape from (exit) each of those pits, then try to exit the dungeon from the ladder on the top level.  By the time you reach that ladder, any additional exit maps are invalid and should be removed.
- I apologize for the inconvenience if you ran into this bug.  I've designed the game very carefully, but it is extremely complex and therefore bugs can sometimes appear.  This is one of the bugs that was not discovered in playtesting because it does not happen in most situations, another bug/limitation that had been covering it up was fixed, and that particular situation had not been tested in a while due to my having limited time to test the entire game after every minor change.

Further details:
- These are non-critical details, but may be helpful if you want or need further clarification
- Remember that this fixes the problem in an active game from an old save; the problem will not reappear since the actual source of the problem has been fixed in the newer versions.  (Of course, it WILL reappear if you reload the old save again; like any change when playing the game, it only applies to the active game session and any new saves done based on that session.)
- As mentioned above, if there are more than 1 additional exit positions it is very likely that they must all be removed.  However, this is not certain for all possible situations.  Therefore, if it goes to another (different) incorrect location after applying it then it may be necessary to try removing fewer positions.  Since only 2 additional positions ("additional" meaning those beyond the first position) were allowed in the older versions of the game, this would mean trying to remove only 1 of them rather than 2.  Remember that you should do this after reloading so that it is sometime before exiting the dungeon.
- As mentioned earlier, one of the primary ways this bug can show up is to enter the dungeon far north of Seaport, fall into one or more map-based pits, exit each of the pits, then try to exit the dungeon.  Every time you exit one of these pits it will introduce the bug and the exit from the dungeon will be set to go to the top of the pit rather than outside the dungeon.  However, if you exit the dungeon from 2-3 times it will go to the correct exit location.  If it does not after 2 times (and goes to the top of a different pit), then after 3 times it should definitely go to the correct exit location.  Of course, having to work your way back through part of the dungeon (potentially twice) is not correct so the better approach is to apply the bug fix to any save containing such incorrect exit points.
- The bug fix option described here removes the most recent exit point(s).  If 2 exit points are removed, then it removes the most recent exit point then the next most recent exit point.  While it should not be necessary to do so, as a last resort you can activate cheat/development mode (explained elsewhere) and view your current exit points using the "VA" option and look for the "Exit" line (the first number is the map ID).  The process for activating cheat mode is explained in the manual.  If you are in the dungeon north of Seaport, the only exit point that you want to remain after applying the fix is the one that goes to map 2.


***************************************************************************
Documentation
***************************************************************************

Beyond this file, other documentation currently includes:

- install.txt (the install instructions): This provides the install instructions for the game and peripheral programs along with some details about related issues

- manual.txt (the game manual): This provides the primary instructions for the game along with many peripheral details.  It is strongly suggested that you read at least the first few pages of this document (but it is by no means necessary to read it all).

- hints.txt (a hints document for scenario 2): Reading this is entirely optional and not recommended unless you need it (although you may want to scan the introduction to better understand what is available in it).  Use this if you have any problems playing the game where you would need hints / a clue book / etc..

- version.txt (version information): Viewing this is entirely optional and only useful if you need to know the version of the install.  It is just an extremely short note containing nothing more than the current version designations.


***************************************************************************
Release notes
***************************************************************************

Most releases contain a very large number of changes everywhere from those that are very minor to those that are very significant.  However, the only specific points for particular release versions that are currently addressed in this document are things like critical bug fixes.  This is due to not having enough time to document so many changes.

That said, the changes between versions typically include things such as:

- New scenario content or adjustments to scenario content.  At this point, such work has been almost entirely on scenario 2.  One example of new content was completing the arctic dungeon (which was an extremely lengthy project), another was adding several new spells (along with a related NPC cleric option), but there many, many more.  Similarly, one example of adjusted content was a variety of work to improve the balance of several dungeons that contain rooms, another was reducing the difficulty of random encounters at the beginning of the game, but there were many, many more.

- Fixes for minor or moderate bugs

- Improvements and enhancements to the engine.  An example of an improvement to the engine was making sure the creature name is specified during attacks, another was improving the way other verbosity modes behave, but there were many, many more.  An example of an enhancement was adding and enhancing various script commands to support some new scenario 2 content (new or adjusted content often drives such enhancements), another making it so creatures in dungeon rooms can also decide to do a group retreat, another a new mechanism to more simply define changes to a dungeon room depending on the entrance (to support work in adjusting related dungeon balance), another functionality to support a new spell (removing beneficial enchantments), but there were many, many more.

- Updates to documentation


***************************************************************************
Transferring saves and save compatibility
***************************************************************************

There are 2 issues addressed in this section.  The first is transferring saves from one version to another and the second is the overall issue of compatibility.

Saves are not currently checked in any way to determine if they belong to the current version or even the current scenario; you are allowed to load any game in any context even if it does not end up working properly.  (This may change in the future, but if so the change would most likely be to issue a warning that such a game may not be compatible and to potentially provide an import option.)

To transfer a save from one game to another, simply copy or move the save from the old version's save directory to the new version's save directory.  Alternatively, you can include the path to the save in the old version when you load from the new version, but this is likely to be rather cumbersome.

For example, say you had a save game named "87" that you wanted to transfer from "C:\Games\GGame2.230308" to "C:\Games\GGame2.230522".

This would mean that you would copy "87" from "C:\Games\GGame2.230308\Save\87" to "C:\Games\GGame2.230522\Save\87".

You can also move the game rather than copying it, but a copy has the advantage of providing a backup in case something goes wrong and allowing the old version to still be used for any comparision purposes.

You may notice that the name of the install directories used in the examples above have been customized with a ".[version]" suffix.  It should be clarified at this point that this game is designed in a way that makes it so that you CAN rename the install directory name as needed in order to have multiple versions (which is different from many programs which only allow one version to be installed at a time).

Anyway, the public versions released so far are likely compatible with older versions.  This has been tested with scenario 2 saves that are not far into the game but not tested nearly as well with those that are much further into the game.  However, the game does attempt to resolve inconsistencies between an older save and a newer version whenever possible (often by loading it anyway but potentially issuing warnings and/or potentially applying corrections when such corrections are obvious).  An example of such an inconsistency is when a given map has changed significantly in a newer version and an older save game is saved against the older version of that map.

Another point is about the default save.  The default save is the one that is used when you use options like 'Q'.  It has no name that you provide yourself, but you will see it in the "Save" directory as "Default" with a suffix for the corresponding scenario ID (for example, "Save\Default2" for scenario 2).  Automatic saves such as the ones done during many map transitions always use this, which means it will be saved over quite often.  Therefore, if you are using only this method of saving rather than named saves, it is recommended that you do not simply move this save but rather copy it so that you still have the original as a backup within the previous version of the game.

Another point is that while you are likely to be able to use most saves in a newer version, it is far less likely that a save from a newer version will work in an older version.

Loading a save in a scenario other than the one it was saved in is not recommended.  An exception would be if a 3rd party designer specifically designs multiple scenarios that allow this (for example, creates a sequel that will accept a save from the previous scenario).  None of the currently-included scenarios support this, however; they are all mutually-exclusive.  Loading a save in the wrong scenario is allowed, but will typically result in a number of errors.  For example, consider that map 2 in scenario 2 is entirely different from map 2 in scenario 1 and the saved information about it will therefore be totally invalid if it had been saved in the other.
