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:
- The area with the final battle has been updated so that the battles there work more correctly
- The NPC in the desert town with some key information now clarifies some vital points with regards to the two separate subjects he addresses.  If you are having difficulty with anything in that area, try speaking to him again.
- There is now a significant series of new, additional hints to make it much more clear as to how to find a hidden location that is required to complete the main quest (SPOILER: the hidden mountains location).  If you already have a game in progress and are having any problems finding this location, refer to this section for more details.
- Ships sometimes seem to mysteriously disappear.  This is not a bug, but rather part of the game.  More specifically, this is due to dangers such as whirlpools.  A more feasible solution to avoid destruction of a ship has now been implemented.  Refer to this section for more details.
- Named saves now use just one single file rather than a directory (although the older approach is still also supported)
- 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.
- 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
- Unfinished features


***************************************************************************
Difficulty finding the hidden mountains location
***************************************************************************

WARNING: This section contains spoilers

Previous versions of the game DO contain some hints as to how to find the hidden mountains location required to complete the main quest.  However, it turns out that if you have explored in one particular order then the most clear of these hints will not yet be available (for logical reasons).  If you then dismiss this area as having already been explored and do not go back, you will never come across this hint which means that finding the hidden mountains location is likely to be extremely difficult.

This was a problem, not an intentional part of the scenario design, so a solution was needed.  The one that was selected was to add a significant series of new, additional hints to make it much more clear as to how to find the hidden location.

If you have been having any trouble finding the location, try going back to one of the hidden natural places spoken of by some of the NPC's.  If this does not tell you what you need to know, make sure that you have been to more than one of these locations.

Note that the original hints were not removed; the change is a series of new, additional hints.

As an aside, note that this solution also has the benefits of adding more significance to the other hidden natural locations and connecting them even more fully to the main plot.


***************************************************************************
Ships sometimes seem to mysteriously disappear
***************************************************************************

Did you leave your ship and come back later to find that it was gone?

This is actually not a bug, but rather the issue is that a whirlpool or storm destroyed the ship while you were gone.  This was an intentional part of the game design, but unfortunately it turns out that it made some areas too difficult (for example, when trying to explore the arctic region and having to leave a ship on the shore near several whirlpools).

Therefore, two changes have been made:
1: Magic has been added that can be used to protect unboarded vehicles from dangers such as whirlpools and storms
2: A message will be displayed (along with a sound) if an unboarded vehicle is destroyed even if you cannot see that vehicle

The magic consists of both a new spell and a new magic wand.  The spell can be bought from the arcane spell merchant and the wand can be bought from the shipwright or found as a part of random treasure.  In either case, the result is a magic barrier that is generated by casting onto an unboarded vehicle when standing adjacent to it.  The spell and item also include a message that explains how to dismiss the barrier.

The message helps by letting you know immediately if you may need to consider reloading from an older save.  Obviously, using the magic is the real solution, but this is intended to prevent losing any progress in the game should you forget to protect your ship.


***************************************************************************
Enhancement: Named saves now use just one single file rather than a directory
***************************************************************************

The first thing that should be mentioned right away is that the older approach is still also supported; existing named saves using the old format may still be loaded.

Anyway, named saves in older versions used a directory of files.  A significant enhancement has now been implemented that causes a save to instead be done as just one single file.  This file is called a "combined file" and includes the content of all the files that would previously have been separate in a directory.

Further, the main menu special options menu (F2) now includes tools to work with combined files (combine, uncombine, verify/compare, etc.).  For example, you can now convert old save games from the old directory-based format to the new single file format.

The purpose of the new format is to avoid various disadvantages of saves having many small, separate files (particularly when the number of files increases more and more as you get further and further into the game).  Some disadvantages include that they are harder to work with for purposes of backups, they can in some cases take up more file storage space, and in general they can be more cumbersome to manage outside of the game program.  For example, in the process of testing I do backups to an SD card, but the minimum size on that device is much higher than most of the individual files so the net total space used has been vastly higher than the actual sum of the actual file sizes.  Another example is that every time I have been running my backup tool there have been a huge number of files being processed.

All load options will check for both the old and new formats, so there is no problem loading saves done using the old format.

If for some reason you wish to go back to the old directory-based format for saving, this is still available by setting a configuration file (scenario1.dat) new option as "CFSAVE: 0".

One more point to be clear is that this enhancement only applies to NAMED save games, NOT the current/default save.


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


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


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

- The area with the final battle has been updated so that the AI works more correctly and the battles in that area are more balanced in general
- The NPC in the desert town with some key information now clarifies some vital points with regards to the two separate subjects he addresses.  If you are having difficulty with anything in that area, try speaking to him again.
- Significant playtesting has been continuing and it is clear that with the changes in this version, the scenario now works fairly well all the way to the end.  Addressing a series of moderate to minor issues discovered during playtesting and various enhancements will be planned for future versions.


Version 240131:

- Added a significant series of new, additional hints to make it much more clear as to how to find the hidden mountains location that is required to complete the main quest.  This is very important because the only significant hint that existed previously depends entirely on the order of exploration and therefore in some cases can make finding this location extremely difficult without the new series of hints.  If you are having any problems finding the location, try going back to one of the hidden natural places spoken of by some of the NPC's.
- Replaced a textual village on the S overland map with a real village (although not yet fully detailed)
- As usual, fixed a few minor bugs (such as some doors that should allow horses in Seaport not doing so)
- Significant playtesting has been continuing since version 230624 and all patches have been focused mainly on issues found during that process


Version 231008:

- Added an "Easter Egg" quest (to make some areas more interesting).  Good luck!  Note this is likely to only be available for new games; many games in progress will not be able to find this quest (saved areas don't pick up some of the necessary changes).  "Easter Eggs" are entirely optional, so this doesn't introduce a problem.


Version 230921:

- Implemented solutions to deal with whirlpools destroying ships (as detailed earlier)


Version 230909:

- A major enhancement for named saves using just one single file rather than a directory has been implemented (as detailed earlier)


Version 230825:

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

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
