Hint Oracle Files

Hint Oracle description

The Hint Oracle is a tool found on the Chaos Strikes Back Utility disk. It looks in your saved game and gives you hints based on the location of your champions in the dungeon.
The Hint Oracle uses the data in the file HCSB.HTC to perform this task.
Each hint consists of a name and one or more pages. In the Hint Oracle, you have to click on the “Next” button to see the next page. In that way you can just read the hint part you need.

The goal of this page is to describe the format of .htc files.

The Hint Oracle hints file HCSB.HTC contains:

• A list of locations. Each location is defined by coordinates in the dungeon (Level, X, Y) and an associated hint number.
• A list of hint names.
• A list of hint contents. Each hint content contains all the pages for that hint.

Example:
If your party is located on level 05 at coordinates (25,07) and you run the Hint Oracle, the following hint will be available:

• Hint number: 195
• Hint name: PROVE YOU ARE WIZARD
• Page 426: You must cast a spell to please the guardian.
• Page 427: The spell you cast must be shown to the guardian.
• Page 428: Cast a ZOKATHRA spell.

In the HCSB.HTC file, a location is defined to associate the coordinates with the hint number : (05,25,07) / 195.
The hint number 195 is defined with its name and it contains 3 pages numbered 426 to 428.

The file format is exactly the same for Chaos Strikes Back for Atari ST and Amiga. It uses big endian format: the most significant byte of a word (2 bytes) is stored first.

You can convert files between .htc and .txt formats with the HTCConverter v1.0 that I wrote.

Notes

• In Chaos Strikes Back for Windows, the file name is HSCB.HCT instead of HCSB.HTC. HTCConverter will accept both extensions for input, but will only output .HTC files. You will have to change the extension if you want to use them with Chaos Strikes Back for Windows.
• The HCSB.HTC file is exactly the same on the Atari ST Utility Disk and on the Amiga English Release 1 Utility Disk. This file contains a few mistakes. Moreover, as the Amiga dungeon is slightly different from the Atari ST dungeon, some hints that were OK for the Atari ST version do not apply to the Amiga version. That is why FTL updated the hints file in the next Amiga Release.
• The HCSB.HTC file on the Amiga English Release 2 Utility Disk is not correct. In fact, that file was used as a test for the French and German translation of the game. FTL released the correct version in the English Release 3 Utility Disk.

Hint Oracle files

The following table lists all known Hint Oracle files:

Detailed file structure

Here is a detailed description of the contents of the HCSB.HTC file from Chaos Strikes Back for Amiga Utility Disk English Release 1.
This example is used to show the structure of an .HTC file. Offsets would be different in other files with arbitrary numbers of locations, hints and pages.

Notes:

• This file is 66172 bytes long.
• Although 4663 slots are available in the file to store locations, only 4648 are really used. Some slots near the end are filled with 00 bytes. If you place your party at (0,0,0) in the dungeon by hacking, the Hint Oracle will display several times the hint number 0 named “FULYA PIT”!
• 210 hints are defined
• 492 pages are defined

In this part of the document, each section of the file is entitled with the following information: Offset hexadecimal (offset decimal) Size of section in bytes - Description of section.
Below the title of each section are details about its content.

00000h (00000) 2 bytes - Unknown

2 bytes: 00 02 : Every hints file starts with these bytes. Their meaning is unknown.

00000h (00000) 2 bytes - Dungeon ID

2 bytes: 00 0D : This value is the dungeon ID of the dungeon that this hints file applies to. The same value is stored in the first word of the corresponding dungeon.dat file. In Chaos Strikes Back, the dungeon is supplied as a saved game and the dungeon ID has the same 00 0D value.

00000h (00000) 2 bytes - Unknown

2 bytes: 00 03 : Every hints file has these two bytes. Their meaning is unknown.

00006h (00006) 4 bytes - Header for the list of location records

2 bytes: 12 37 (4663) : Number of location records in the file.

2 bytes: 00 06 (6) : Size of each location record in bytes.

0000Ah (00010) 27978 bytes - List of location records

Each location record is defined by 6 bytes (4663 locations * 6 bytes = 27978 bytes).

1 byte: X coordinate. Value between 00 and 1F (00-31). (Level offset must not be included).

1 byte: Y coordinate. Value between 00 and 1F (00-31). (Level offset must not be included).

1 byte: Level number. Value between 00 and 0F (00-15). (The Chaos Strikes Back dungeon has 10 levels so only values between 00 and 09 are used.)

1 byte: Unused, always 00.

2 bytes: Hint number associated to the location.

Notes:

• If X or Y are greater than 31 or if the Level is greater than 15, then the corresponding hint will not be displayed as the party cannot be located at such coordinates in the dungeon.
• The only exception to the first rule is if BOTH the X and Y coordinates equal 255. In that case, the hint will be displayed no matter the location of the party on the level.
• It is not possible to use 255 for the level in order to make a hint appear on every level.

06D54h (27988) 4 bytes - Header for the list of hint records

2 bytes: 00 D2 (210) : Number of hint records in the file.

2 bytes: 00 1A (26) : Size of each hint record in bytes.

06D58h (27992) 5460 bytes - List of hint records

Each hint record is defined by 26 bytes (210 hints * 26 bytes = 5460 bytes).

22 bytes: Hint name, up to 21 characters, terminated with a 00 byte. Allowed characters: A-Z and space. Padded with 00 bytes. The first 00 marks the end of the name. Some hints have some characters after the first 00 byte. These characters are ignored by the Hint Oracle.

2 bytes: Index of the first page of the hint.

2 bytes: Number of pages in the hint.

082ACh (33452) 2 bytes - Header for the list of hint content lengths

2 bytes: 01 EC (492) : Total number of pages for all hints.

082AEh (33454) 984 bytes - List of hint content lengths

This section contains 2 bytes per hint page (492 pages * 2 bytes = 984 bytes).

The 2 bytes of the first page of a hint represent the length in bytes of the compressed hint content (which includes all the hint pages).
The 2 bytes for the subsequent pages of the hint are always 00 00.

As a consequence, the sum of all the 2 bytes values from this section equals 31734, which is the size of the Hints contents section of the file.

08686h (34438) 31734 bytes - Hints contents

This section contains a sequence of variable-length compressed hint contents. The length of each compressed content is defined in the previous section of the file.

Each hint content is compressed using the LZW algorithm (see below).

After decompression, each hint content is a string containing the text of all the pages of the hint. Each page is ended by a 00 byte.
Each page can contain up to 12 lines of around 30 characters maximum.
The ASCII character number 2Fh (slash) is used as carriage return. The Atari ST and Amiga English Release 1 versions of the hint Oracle do not display characters above 7Fh. The Amiga English Release 3 version displays these characters for multilanguage support. The Atari ST and Amiga English Release 1 versions of the hint Oracle display the ASCII character number 96h as a space. The Amiga English Release 3 version displays the character correctly.

1027Bh (66171) 0 bytes - End of file

The LZW algorithm

The hints contents are compressed with the LZW (Lempel, Ziv and Welch) dictionary compression algorithm.
If you want to learn more about this algorithm, you should read the LZW Data Compression article by Mark Nelson, published in Dr. Dobbs’s Journal in 1989. This is the article I used to understand and then implement the algorithm in my HTCConverter.vbs script.

The things to know about the use of this algorithm by the Hint Oracle are:

• The uncompressed characters are standard 8 bits ASCII characters. Thus, the initial dictionary is filled with 256 entries for each ASCII character (codes 0-255).
• The code 256 is never used in the compressed data of the .HTC files released by FTL. I suppose this code would tell the decoder to flush the dictionary, as suggested in Mark Nelson’s article, but this is yet to be tested. As a consequence, codes for strings start at 257.
• The codes used in the compressed data are of variable length. While the dictionary has less than 512 entries, the codes are 9 bits long (2^9=512). Once the dictionary has 513 or more entries, the algorithm switches to use 10 bits codes (thus allowing the use of 512 more codes for a total of 1024 codes). The dictionary cannot contain more than 1024 codes, so 10 bits is the maximum size for a code (2^10=1024). The Hint Oracle cannot manage codes of 11 bits or more.
• To decode data: read each byte in the source file, and append it to the left of the previously read data. Each time you have at least 9 bits (or later 10 bits) available, you can remove them: they form one code. You can output the string corresponding to this code. The 9 least significant bits form the first code. The next 9 bits form the next code, etc…
  When the dictionary has more than 512 entries, 10 bits codes are read in exactly the same way.
  When there is no more bytes to read from the file, if there are just enough bits left to form a code, then output its corresponding string. Otherwise, the few bits left can be ignored.
  Example: In the Chaos Strikes Back for Atari ST hints file, the first four bytes of the first compressed hint content (offset 08686h) are: 54 D0 A4 99.
  Now let us read these bytes in order and append each new byte to the left of the previously read data. We obtain: 99 A4 D0 54.

• In binary representation:
     99       A4       D0       54
  10011001 10100100 11010000 01010100       These are the decoded
       ^        ^^        ^^        ^       strings (we only have
       |        ||        ||        |       single     characters
  -----|--------||--------||--------|   +-- because  the  first 3
  etc.. 3rd 9bit  2nd 9bit  1st 9bit    |   codes are lesser than
          code      code      code      |   256). The hint starts
          "i"       "h"       "T"    <---   with the word "This".
  

Special Thanks

I wish to thank Paul R. Stevens, the man who ported Chaos Strikes Back to Windows. His source code and the Hint Oracle dump feature of Chaos Strikes Back for Windows were very useful to produce this document.

History of this document

Version 1.2 - May 22, 2009: Added list of known hint files.
Version 1.1 - September 10, 2008: Added explanation of the dungeon ID value at the beginning of the file.
Version 1.0 - August 31, 2002: First release