The Gibberlings Three Debugging Suite for BG2

In the course of BG2 Fixpack development,
several errors kept cropping up repeatedly--so much so that it became time-efficient
to write some automated checking tools. With some polish, these tools are now
ready to be released independently so that modders can use them to diagnose
issues in their own mods. This suite is not designed for players.

The Debugging Suite is designed to work with Baldur's Gate II with or without
the Throne of Bhaal expansion pack. Note that the suite doesn't actually alter
any game files and leaves no entry in the WeiDU log,
so that it can be used at any point in the install order, as many times as
needed. If there is interest for the Suite on other platforms (BG, IWD,
etc.) it can be developed. For the most part, the file formats are the same
so certain components may work on non-BG2 variants
of the Infinity Engine, though I may not be able to actively support them.

Area Checker

Output of this check can be found in G3_Debugging_Suite/debugger_area_checker.log.
This component scans all area files present for common errors, such as bad
indices, references to non-existent files, trap errors, etc. The following
checks are performed, and listed along with their generated error message:

Corrupt File: Area files must be at least 0x11c bytes in length to contain
all of the information below. If the file is below this size, none of the
following checks will be performed and the component will skip the area with
the message foo.are error: Corrupt file, below minimum file size.

Area Script: The suite will perform two checks here. If an area has a script
assigned, but the script doesn't exist, the message foo.are error: Area
Script assigned but nonexistant (foo.bcs). Now, if the area has no script
assigned but there's a script that matches it (i.e. if ar1000.are has no
area script assigned, but ar1000.bcs exists) then the message foo.are
error: Area Script exists but is unassigned (foo.bcs).

Offsets: The area files contain a series of offsets to tell the engine
where various information blocks within the file exist. These offsets are
expected to be in a particular order (though not required). As part of its
running checks, the tool will check the offset of each block in turn and
report incorrect offsets, based upon their expected order within the file.
The Map Note check in particular will generate a lot of messages, as BioWare
tended to consistently ignore the entry in areas without any map notes.

foo.are error: Actor offset is incorrect

foo.are error: Info Point offset is incorrect

foo.are error: Spawn Point offset is incorrect

foo.are error: Entrances offset is incorrect

foo.are error: Containers offset is incorrect

foo.are error: Items offset is incorrect

foo.are error: Ambients offset is incorrect

foo.are error: Variables offset is incorrect

foo.are error: Door offset is incorrect

foo.are error: Tiled Objects offset is incorrect

foo.are error: Vertices offset is incorrect

foo.are error: Animations offset is incorrect

foo.are error: Bitmap offset is incorrect

foo.are error: Songs offset is incorrect

foo.are error: Rest Spawn offset is incorrect

foo.are error: Map Notes offset is incorrect

Vertex Indices: Each area file has a list of points, used as vertices by
info points, containers, and doors. Each point in this list is supposed to
be used once; i.e. no door or info point should try and use a vertex that
has been used by another door. There should also be no unused points. As
such, the component will keep a running tally of the vertices and check them
against the indices used by doors and other area features to verify them.
If an error is found, one of the following messages is generated (note that
doors actually have four indices each):

foo.are error: Info Point #1 has vertex index error (should be
854)

foo.are error: Container #1 has vertex index error (should be
854)

foo.are error: Door #1 has vertex index error (should be 854)

Actor Resources: The component will run through the list of actors and
verify that the creature files exist. Scripts and dialogues can also be specified
in these blocks, so any custom dialogue or script noted here will also be
cheecked for existence. Creature file names beginning with RD are ignored,
as these are handled correctly by spawngrp.2da.

foo.are error: Actor #1 dialogue file does not exist (bar.dlg)

foo.are error: Actor #1 script does not exist (bar.bcs)

foo.are error: Actor #1 does not exist (bar.cre)

Info Points (Transitions): If the info point is actually a transition to
another area, the area is checked for existence and the component verifies
that the entrance point actually exists.

foo.are error: Info Point #1 has transition to non-existent area
(bar.are)

foo.are error: Info Point #1 has transition to non-existent entrance
point (bar.are, Exit0000)

Info Points (Traps): The component also checks for common trap errors.
If the info point is flagged as trapped, the component checks for the existence
of a trap script and whether the trap is already detected.

foo.are error: Info Point #1 is trapped with no trap script (bar.bcs)

foo.are error: Info Point #1 is trapped and detected

Spawn Points: The component will verify that all creatures listed exist.
Creature file names beginning with RD are ignored, as these are handled correctly
by spawngrp.2da.

foo.are error: Spawn Point #1 creature file does not exist (bar.cre)

Containers (Traps): Similar to the checks on info points, the component
will perform checks for the existence of the trap script and whether the
trap is detected if the container is flagged as trapped.

foo.are error: Container #1 is trapped and detected

foo.are error: Container #1 is trapped with no trap script (bar.bcs)

Item Indices: Like vertices, area files contain a list of items. Containrs
simpy refer to entries on the item list and, like vertices, each entry should
be used exactly once.

foo.are error: Containers #1 has an incorrect index

Items: Items are verified for existence; if not then the message foo.are
error: Item #1 does not exist (bar.itm) will be displayed. This component
does not account for the random treasure tables, so expect a few false
positives.

Ambients: Like items, the referenced sound files are checked for existence
and the message foo.are error: Ambient #1 does not exist (bar.wav) is
displayed upon failure of the check.

Doors (Sounds): Doors can use opening and closing sounds. If sounds are
listed, the resources are checked for existence with the message foo.are
error: Door #1 sound does not exist (bar.wav) displayed if the check
fails.

Doors (Traps): Like the container and info point trap checks, a trap script
and detection flag are checked if the door is flagged as trapped.

foo.are error: Door #1 is trapped and detected

foo.are error: Door #1 is trapped with no trap script (bar.bcs)

Doors (Keys): If a key is listed in a door, the key is checked for existence.
In addition, the door is checked to see if it is subject to being lockpicked.
The door is also checked to ensure it's actually locked.

foo.are error: Door #1 has non-existent key set (bar.itm)

foo.are error: Door #1 requires key (bar.itm) but the lock can
be picked

foo.are error: Door #1 requires key (bar.itm) but the door is
not locked

Animations: The component will check for both BAMs and VVCs for any animation
listed. If none are found, the message foo.are error: Animation #1 does
not exist (bar.bam or bar.vvc) is displayed.

Rest Spawns: The component will verify that all creatures listed exist.
Creature file names beginning with RD are ignored, as these are handled correctly
by spawngrp.2da.

foo.are error: Rest Spawn creature file does not exist (bar.cre)

Creature Checker

Output of this check can be found in G3_Debugging_Suite/debugger_creature_checker.log.
This component will check several potential issues in creature files. The
inventory is only given minimal treatement; please use the Creature Invenory
Checker component for in-depth inventory checks.

Invalid File: If the file is below the minimum file size required to have
a complete header, the component will generate the message foo.cre: Invalid,
below minimum size and move to the next creature file. None of the other
checks will be performed.

Offsets: The creature files contain a series of offsets to tell the engine
where various information blocks within the file exist. These offsets are
expected to be in a particular order (though not required). As part of its
running checks, the tool will check the offset of each block in turn and
report incorrect offsets, based upon their expected order within the file.

foo.cre error: Known Spells offset is incorrect

foo.cre error: Memorization Info offset is incorrect

foo.cre error: Memorized Spells offset is incorrect

foo.cre error: Effects offset is incorrect

foo.cre error: Item offset is incorrect

foo.cre error: Item Slot offset is incorrect

Name Check: Creatures have two name fields, name and apparent name. If
strings are set in both, the component will verify that they match. If not,
the message foo.cre: name fields do not match will be displayed.

Portraits: If portraits are specified for the creature, they are checked
for existence.

foo.cre error: Small Portrait does not exist (bar.bmp)

foo.cre error: Large Portrait does not exist (bar.bmp)

BG Proficiencies: If a creature has proficiencies from BG set in their
file, the message foo.cre: Has BG proficiencies set will be generated.
With all of the leftover creature files present in BG2, this component can
cause a number of false positives.

Sex/Gender: The component checks for conflicts between these two values.
As gender can have a broader range of values than sex, creatures with genders
other than male, female, both, or neither are not checked.

foo.cre: Gender and Sex do not match

Attribute Checks: The component will verify that the attributes of the
creature fall within the normal minimum of 3 and maximum of 25.

foo.cre: Attributes fall outside min/max

Scripts: The component will check for the existence of the creatures's
scripts, if they are assigned.

foo.cre error: Script does not exist (bar.bcs)

Dialogue File: The component will check for the existence of the dialogue
file, if one is assigned. This component will generate a number of false
positives, as BioWare assigned many creatures dialogue files that do not
exist.

foo.cre error: Dialogue does not exist (bar.dlg)

Known Spells: Each spell listed as known in the creature file has three
paramaters, all of which are checked. The spell resource itself is checked
for existence and the other two parameters (spel level and spell type) are
verified against the spell files.

foo.cre error: bar.spl in Known Spells section does not exist

foo.cre error: bar.spl level in Known Spells section does not
match spell file

foo.cre error: bar.spl type in Known Spells section does not
match spell file

Memorization Info: The memorization information lists how many spells can
be memorized at every level and which spells are actually memorized. As the
block is a fixed length--it always contains information for 9 levels of mage
spells, 7 levels of cleric spells, and one for innate spells--the length
is checked. The spells are listed in an index system, so the indices are
validated to ensure each spell is listed exactly once.

foo.cre error: Memorization Info length is incorrect

foo.cre error: Memorization Info index is incorrect

Memorized Spells: The listed spells are checked for existence.

foo.cre error: bar.spl in Memorized Spells section does not exist

Items: The listed items are checked for existence.

foo.cre error: Item does not exist (bar.itm)

Creature Inventory Checker

Output of this check can be found in G3_Debugging_Suite/debugger_creature_inventory_checker.log.
Originally available separately, this has been rolled into the Suite.

Invalid File: If the file is below the minimum file size required to have
a complete header, the component will generate the message foo.cre: Invalid,
below minimum size and move to the next creature file. None of the other
checks will be performed.

Ammo/Launcher Checks: These errors are all caused by a similar issue: the
creature has a launcher in its weapon slot, but lacks the requisite ammunition
in the quiver slots. Alternatively, the creature has ammo but no launcher
for it.

foo.cre: Bow with no arrow

foo.cre: Sling with no bullets

foo.cre: Crossbow with no bolts

foo.cre: Arrows with no bow

foo.cre: Bullets with no sling

foo.cre: Bolts with no crossbow

Items in Incorrect Slots: All of these errors are caused by having an invalid
item equipped. For example, if a creature has an item not of the type armor
(2) in its armor slot, this error will be reported. Many of the rings and
amulet errors will be spurious, as BioWare tended to use these slots for
special items that give creature immunities and other special abilities for
their creature type. As many of these items are not flagged with proper item
types you will see a number of false positives.

foo.cre: Invalid Helm

foo.cre: Invalid Armor

foo.cre: Invalid Amulet

foo.cre: Invalid Ring

foo.cre: Invalid Cloak

foo.cre: Invalid Gloves

Invalid Weapon: You will see the error message foo.cre: Invalid Weapon if
the creature has an item in its weapon slot that does not have a melee (1),
ranged (2), or launcher (4) ability. Originally, this was only a check against
item type, but there were a number of spurious errors resported as many of
the creature paws (such as b1-8.itm) are of the type Miscellaneous (0).

Invalid Offhand Item: The message foo.cre: Invalid offhand is
caused by having an item in the offhand/shield slot that is not a one-handed
weapon or a shield. The offhand weapon must be melee-only (ranged weapons
are not allowed offhand) and not flagged as two-handed.

Invalid Quiver: The message foo.cre: Invalid quiver is generated
by an item in the quiver slot that is not arrows, bullets, or bolts.

Invalid Weapon Equipped: The utility will perform a compare against the
equipped weapon value and the weapon slots. This error is reported if there
is 1) a valid weapon available and 2) either no weapon selected
or the selected slot has no valid weapon. So if a creature has weapon slot
1 set as equipped but has no weapons at all, this error will not be
generated as condition #1 is not satisfied.

foo.cre: Invalid weapon equipped

Two-Handed Weapon and Offhand Item: The message foo.cre: Two-handed
weapon and offhand item is triggered by one of the weapons in the
weapon slots being flagged as two-handed while the offhand/shield slot
is filled. This would cause a hard crash in BG2 if
such a creature were encountered.

Unequipped Items: The component is also looking for items that were possibly
meant to be assigned. As such, it performs a check in a creature inventory
for armor, shields, helms, etc. to see if an item could be equipped rather
than left in inventory.

foo.cre: Possible equippable item in inventory

Item Checker

Output of this check can be found in G3_Debugging_Suite/debugger_item_checker.log.
This component performs basic checks against item files.

Invalid File: If the file is below the minimum file size required to have
a complete header, the component will generate the message foo.itm: Invalid,
below minimum size and move to the next creature file. None of the other
checks will be performed.

Offsets: Abilities traditionally start at 0x72, the end of the fixed item
information block, and effects begin immediately after the abilities. The
component will check both of these offsets for proper ordering and values.

foo.itm: Abilities do not start at the proper offset

foo.itm: Effects do not start at the proper offset

Effect Indices: All effects, whether global or via ability, are contained
in a list. Each effect shold be used exactly once--this is ensured by an
indexing system in the abilities. If these indices are incorrect, the message foo.itm:
Ability #1 has an index error will be generated.

Abilities: Ability types (melee, magical, etc.) are checked against whether
they appear in the weapon slots or item slots. If they're in the wrong place,
the error message foo.itm error: Ability #1 appears in wrong place is
displayed. The component also checks for extraneous default (0) headers with
the message foo.itm error: Ability #1 is extraneous Default(0) type.

Effects on Abilities: Three rudimentary checks are performed on the effects
attached to abilities. If the effect is designed to be permanent, the duration
should be zero. Unknown timing modes are reported. Also, the durations of
limited effects are compared against one another to identify potential errors.
In this last check, effects with durations of less than one round are ignored
as many abilities include playing graphics or sounds for a few seconds.

Global Effects (aka Equipping
Effects): The global effects are supposed to be more rigid as they are supposed
to affect the wearer while the item is equipped. As such, they should target
self, have a timing mode of instant/while equipped (2), should be applied
100% of the time, and should not be subject to dispel magic.

Enchantment/Magical: The component checks for agreement between the magical
flag and the enchantment level. If an item has non-zero enchantment and is
not flagged as magical, the message foo.itm: Disagreement between enchantment
and magical flag will be displayed.

Icons: If specified, the three icons (inventory, ground, and carried) are
checked for existence. The icons for the various abilities are also checked.

foo.itm error: Icon does not exist (bar.bam)

foo.itm error: Ground Icon does not exist (bar.bam)

foo.itm error: Carried Icon does not exist (bar.bam)

foo.itm error: Ability #1 icon does not exist (bar.bam)

Spell Checker

Output of this check can be found in G3_Debugging_Suite/debugger_spell_checker.log.
This component performs basic checks against spell files.

Invalid File: If the file is below the minimum file size required to have
a complete header, the component will generate the message foo.spl: Invalid,
below minimum size and move to the next creature file. None of the other
checks will be performed.

Innate Level: If a spell is of the type innate, it can potentially crash
the game when used in a HaveSpell() trigger and its level is not set to one.
This component will issue the warning foo.spl warning: Innate spells
should be spell level one in these cases.

Offsets: Abilities traditionally start at 0x72, the end of the fixed spell
information block, and effects begin immediately after the abilities. The
component will check both of these offsets for proper ordering and values.

foo.spl: Abilities do not start at the proper offset

foo.spl: Effects do not start at the proper offset

Effect Indices: All effects, whether global or via ability, are contained
in a list. Each effect should be used exactly once--this is ensured by an
indexing system in the abilities. If these indices are incorrect, the message foo.spl:
Ability #1 has an index error will be generated.

Abilities: Spell type is checked against the ability type to determine
whether they appear in the innate slots or spell slots. If they're in the
wrong place, the error message foo.spl error: Ability #1 appears in wrong
place is displayed. The component also checks for extraneous default
(0) headers with the message foo.spl error: Ability #1 is extraneous
Default(0) type.

Effects on Abilities: Three rudimentary checks are performed on the effects
attached to abilities. If the effect is designed to be permanent, the duration
should be zero. Unknown timing modes are reported. Also, the durations of
limited effects are compared against one another to identify potential errors.
In this last check, effects with durations of less than one round are ignored
as many abilities include playing graphics or sounds for a few seconds.