GOLD BOX COMPANION
==================
 
Version 2.01 (16-October-2015)


http://personal.inet.fi/koti/jhirvonen/gbc
joonas.hirvonen@pp.inet.fi



INTRODUCTION
============

In short, GBC is a tool to ease playing AD&D Gold Box games. For more introductionary features and screenshots, 
check out the home page. Basically GBC searches game/character/map data from DOSBox's memory.

Also check out SGE, Save Game Editor, located in the same folder as GBC. With SGE you can swap party members in/out, 
even increase party size to 8 (without NPCs) and edit inventories.



GENERAL TROUBLESHOOTING
=======================

If you have problems...
- Try to run GBC as an administrator.
- Try placing the files outside the "Program Files"-folder, instead to a folder like "C:\GBC".



STARTING DOSBOX AND A GAME
==========================

I won't give instructions here how to use DOSBox or start Gold Box games as there is plenty of information for that
already around the internet. 

You probably want to scale the DOSBox window to 2x or 3x depending on your display size and resolution.

It's best to have the game running before starting GBC. Also, if you create a party from scratch or add/remove characters,
I'd advice to save the game, restart DOSBox and the game and load the game. This ensures that the characters are found 
in correct order in the memory.



SEARCH WIZARD
=============

When you start GBC you'll see a search wizard. 

- Select a game and set the game folder. 
  ! For Unlimited Adventures, select the design subfolder you're playing. 
  ! The save game files have to be in the selected game folder or in SAVE-subfolder.
- Select the save game slot (A-J). GBC loads save game data.
- Click SEARCH and GBC searches for the character/map info.
  If all goes well, the search wizard is closed and the HUD screen is displayed on top of the DOSBox window.

In ADDRESS RANGE you need to put a memory address range for searching.

In WINDOW TITLE enter a part of DOSBox's window title. It doesn't have to be the whole title just enought that 
the window is recognized.

MAX GAP means the gap in bytes between character data records in memory. If the search wizards finds the character names
but values (hit points etc.) look odd, try decreasing this value and search again.

If SEARCH MAP is checked, search for map data and party location is also done and if succesful the map is shown in a
window.

Troubleshooting if search is not succesful:
- If first character was found but not all other party members, increase the max gap value.
- Save the game, click on the save slot and search again.
- In Death Knights of Krynn, spellbook information is not always directly after the character data in memory. So it must also 
  be searched for. If you have cast any spells, edited memorized spells etc. the spell data is changed from the save file
  version and can not be found. Again, save game, click on the save slot and then search.
- Enable debug-mode by pressing Control + D for more in-depth logging.
- Map is not found if you're in overland map. Search again when on a normal map.
- If party location is wrong, you should move the party to a location where the coordinates are not zero and change facing
  so that you're not facing north. It's easier to find the party location coordinates from memory if the coordinates are 
  14,8,4 (facing S) than 0,0,0 (facing N).

CLEAR EXPLORED clears all explored maps for the current game.

PASSWORDS displays a list of passwords for the game.

RANDOM NAMES creates a list of random male/female names if you have trouble of naming your characters.

HELP displays this help.



HUD
===

The HUD attaches itself on top of the DOSBox window. It shows character's name, XP bar and a health bar. The HUD might be 
little cramped if you don't scale the DOSBox window to at least 2x.

At the moment the XP bar doesn't take game or demihuman level limits into account.

Move mouse over the HUD to open up menu. Move mouse from the HUD to close it.

You can use custom combat icons by putting them into the corresponding game's data folder found under the GBC-folder. 
For example, for a character named Wulfgar, create two 24x24 bitmaps named "Wulfgar_1.bmp" and "Wulfgar_2.bmp".


MAP toggles map window on/off.

EXPLORE MAP / UNEXPLORE MAP reveals/unreveals the current map.

EDITOR opens character editor. Not usable in combat.

SETTINGS opens the settings-menu.

QUIT closes GBC.

JOURNALS opens the journal-menu where you can select journal entries or open cluebooks.

ENCAMP-FIX heals the characters. Not usable in combat.

STORE SPELLS stores currently memorized spells for all characters. The spells are automatically stored after a succesful
search for characters has been done. Not usable in combat.

RESTORE SPELLS restores memorized spells. Not usable in combat.

RACE HACK changes the race of all characters to human. This enabled demihumans to gain levels past racial level limits. 
Not usable in combat.

RESTORE RACES restores the race of the characters.

SEARCH WIZARD closes the HUD/map/editor-windows and goes back to the search wizard.



SETTINGS
========

ICONS toggles character combat icons in the HUD on/off.

XP-METER toggles the experience needed - meter in the HUD on/off.

TITLE HACK moves the HUD window on top of the DOSBox window so that the DOSBox window title is hidden.

DOCK MAP / DECREASE MAP / INCREASE MAP / RESTORE MAP changes / restores the map window docking and size.



JOURNALS
========

From here you can browse journal entries. The journal entry is opened on top of the DOSBox window. Click on it to close it.

Passwords opens the passwords list.

PDF cluebooks, manuals etc. can also be opened from here. The files has to be located in the corresponding game folder and named as:
Adventurers Journal.pdf
Cluebook.pdf
Manual.pdf

(These are the default names for the GOG.com releases but the files need to be copied/moved to the game folder.)



MAP
===

Map window attachment and size can be changed from the settings (see above). By right-clicking the map event numbers can
be toggled on/off. 

By Control + left click you can teleport around the map. By Control + right click you can set an event to a location.

Event viewing / setting not currently usable in FRUA.



EDITOR
======

Before doing any changes to characters, you should check out that all character data seem ok. If there's odd values in stats,
the search wizard hasn't probably found the right character locations.

REFRESH updates the character data from memory.

APPLY CHANGES or Control + S saves the changes.

To see applied changes taking effect visually in the game, update the game screen somehow by going into a menu or 
viewing character record sheet etc.

In the spellbook, 0 indicates that the character knows that spell. Any other number means that that many spells 
are memorized. The +/- buttons adjust memorized spells. L-button learns all suitable spells, C-button clears all memorized spells.



OTHER STUFF
===========

- Quickfight is automatically disabled after combat.

