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.
- Bug fix: Attribute increases (such as those given at particular locations) cause values such as AB, AC, DDB, or saving throws to decrease instead of increase (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
- Unfinished features


***************************************************************************
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 that save game
- 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.


***************************************************************************
Bug fix: Attribute increases cause AB, AC, DDB, or saving throws to decrease instead of increase
***************************************************************************

In an earlier version, did you go to a special location where it said that your attributes had increased but then discovered that your AB, AC, DDB, or saving throw values actually DECREASED?

Released versions prior to 230822 contained a bug that caused any attribute increase to decrease the related values (AB, etc.) by ignoring level (effectively assuming a level 0 character when making the increases to these values rather than any higher level).  This is now fixed.

That said, a related fix was also made at the same time.  The problem is that the incorrect, decreased values 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 had the attribute increase and your AB, AC, DDB, and/or saving throws are lower than before the attribute increase).

To solve this potential problem, a special option to fix (recalculate) values that have been decreased 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 that save game
- Go to the options menu (F2)
- Select "Advanced options" (F2 again)
- Select "Bug fix options" ('B')
- Select "Recalculate attribute-related values" ("2")
- Read the text explaining the various details
- If you still want to apply the fix (which will probably be the case), then select yes ('Y'), otherwise press any other key to cancel
- Check your AB, AC, DDB, and saving throws; they should now be correct (the same or higher than before the attribute increase)
- 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
- (WARNING: This note contains spoilers.)  One of the primary ways this bug can show up is in scenario 2 to go to the special position at the end of the south path on lowest (overhead) level of the lava dungeon, the special location in the desert, or the special location in the arctic.
- 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 the mechanism was implemented a long time ago and some changes had apparently been made since the last time it was playtested, it typically only happens very late in scenario 2 when a character is powerful enough to explore these difficult areas, and that particular situation had not been tested in a while due to my having limited time to test that far into the game on a regular basis.

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.)


***************************************************************************
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 usually 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


That said, a few specific notes follow:

Current version:

- Fixed a fairly severe bug where an ambush while in a ship or boat could sometimes result in land creatures that normally require a ship (such as pirates) to instead appear on the water.  The combat would not end without killing them since it is not possible to retreat from a ship-to-ship or boat-to-ship combat.  If you were a spellcaster, had area-effect spells, or had a long-range magic weapon, then you could kill the creatures from a distance in order to end the combat.  They were also able to attack adjacent positions as if they were the vehicle.  Ambushes from ship-based types were being generated because they are included on the general random encounter tables but were not being filtered out for ambushes.  This is now fixed.
- Fixed a notable bug where carrying weight at or close to max into the Planar Abode when the wand had only 1 charge remaining caused it to be dropped on the portal.  While a "Get" could later be used to retrieve it (then causing the portal to trigger), this was still incorrect and needed to be fixed.  The root problem was actually a more general one with any rechargable item and was therefore fixed for all of them.


Version 230822:

- Fixed a severe problem with attribute increases (as detailed earlier)
- Directly playtested through a significant portion of version 230624 (using a wizard character) finding a number of minor issues, 2 moderate issues, and 1 severe issue (attribute increases)


Version 230624:

A few but not all of the changes include:
- Fixed a particularly problematic bug where when there are a large number of creatures a few could be placed in bad starting positions on the foothills or ford combat maps.  This bug could cause a zoom combat not to end without using a missile weapon or spell to kill a trapped creature.
- Fixed a particularly problematic bug related to referencing memory incorrectly during a few conversation-based map transitions (the Seaport arena and theater merchants, and the ice gnome).  This bug could cause error messages related to NPC movement or a crash upon subsequent map transition.
- Just a few of various minor bug fixes include not allowing being aboard vehicles (such as horses) when watching an arena match and fixes/improvements related to getting wandering NPC's moved out of inn rooms being used


***************************************************************************
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.


***************************************************************************
Unfinished features
***************************************************************************

The following is a partial list of some features that are not yet complete.

General:
- The rogue class for scenario 2.  This class CAN be selected and played, but will be weaker than other characters since many of the advantages of the class are not yet implemented.
- Fine-tuning the game balance for scenario 2 (this does not mean that the balance is wrong, just that there are a few minor adjustments that would improve it)
- Scenarios 1 and 3 are unfinished in many ways.  Although they can be played from start to finish, they are both like very rough drafts.  In particular, the basic numeric values defined for both scenarios are still simply placeholders (things like HP's, attack values, etc.).
- A multi-character / party system; the game is currently single-player only.  A lot of the preliminary work for this feature is already complete (such as zoom-in combat and allies), but there is still significant work remaining.
- A single, combined file for save saved games; these currently consist of a directory of multiple files (this enhancement is largely complete, but there is still significant work remaining)

Scenario 2 locations:
- The content for the castle on the W continent is mostly unfinished, although the basic layout is done and there are already some NPC's there that are worth talking to such as the king
- The content for the keep near the swamp on the S continenent is mostly unfinished (although many things such as the layout are finished and it can be explored)
- There are still some details to finish for the desert dungeon (although it is largely complete, playable, and has very useful and important rewards, so best not to skip)
- There are some additional NPC conversations that need to be added to the desert town
