The art of the well-written bug report

[CamDawg]

In the interest of easily turning our work into bug reports (and hopefully fixes) for Beamdog, having well-written bug reports is critical. A good bug report contains the following elements:

1. What is currently happening
2. What should be happening
3. Steps to reproduce the bug
4. If available, a fix

Along the way we include other relevant information (like which game it affects) and files such as screenshots or save games to help QA understand or reproduce the issue.

Let's start with the Yoshimo banter bug as an example:

Quote

[BG2] Yoshimo Should Have Follow-Up Banters with the PC

Yoshimo has a series of three banters where he gets to know the PC. However, because the first banter never sets a timer the second and third banters never fire. The third banter depends on how forthcoming you are in the second banter. A little more information is available in this initial bug report on WM.

1. Load the attached save game.
2. Prompt the first Yoshimo banter by making its timer expire with C:SetGlobal("YoshimoTalksPC","GLOBAL",1). This banter begins with "Tell me, how did you get into adventuring?". Answer all of his questions and be as forthcomng as you can.
3. After the banter, check the second timer with C:GetGlobal("YoshimoTalksPC2","GLOBAL"). This currently will return a message that this global does not exist; it should instead return a numeric value.
4. Make a quick save.
5. Prompt the second banter by making its timer expire with C:SetGlobal("YoshimoTalksPC2","GLOBAL",1). This banter begins with "Tell me, where did you spend your childhood?". Do not answer any of Yoshimo's questions and get out of the banter as quickly as possible.
6. Check the variable for the next talk by putting your cursor over Yoshimo and using C:GetGlobal("YoshimoTalksPC2","GLOBAL") and C:GetGlobal("PCYosh","LOCALS"). The former should be a large number (not one) and the latter should be set to 1.
7. Test that the third banter should not fire by making its timer expire with C:SetGlobal("YoshimoTalksPC2","GLOBAL",1).
8. Reload the quick save from step 4.
9. Prompt the second banter by making its timer expire with C:SetGlobal("YoshimoTalksPC2","GLOBAL",1). This banter begins with "Tell me, where did you spend your childhood?". This time answer all of Yoshimo's questions and reveal your parentage.
10. Check the variable for the next talk by putting your cursor over Yoshimo and using C:GetGlobal("YoshimoTalksPC2","GLOBAL") and C:GetGlobal("PCYosh","LOCALS"). The former should be a large number (not one) and the latter should be set to 2.
11. Prompt the third banter by making its timer expire with C:SetGlobal("YoshimoTalksPC2","GLOBAL",1). This banter begins with "I have pondered what you have said about Bhaal."

Currently this string of events ends at step three, as the timer for the second banter is never set. There are two bugs to be fixed and checked: the first banter needs to set the timer (checked in step three) and Yoshimo should initiate the third banter depending on how you answered his questions in the second (checked in steps 7 and 11). 

In this case, I'd attach a save game made right after I escaped CI and had the Irenicus-Cowled Wizard-Imoen cutscene. Alternatively the first step could be "start a new SoA game, grab some Godbows and go through the opening dungeon, pick up Yoshimo, escape, and watch the cutscene"; we don't have to provide save games for every report.

In this case, since we have a fix we can include it

Quote

To fix, we set the timer in the first banter with .d code:

// add timer to prompt second banter
ADD_TRANS_ACTION bysohim BEGIN 11 END BEGIN END ~SetGlobalTimer("YoshimoTalksPC2","GLOBAL",FIVE_DAYS)~

And we extend his script with

//add script prompt for third banter
EXTEND_BOTTOM ~yoshimo.bcs~ ~files/baf/yoshimo_banter.baf~

And we'd attach the second file, yoshimo_banter.baf.

Now, not everything can be seen easily in-game such as the probability bug. Rather than have some poor tester run around and do a few thousand swings with an axe to get a statistically valid result, we can direct to Near Infinity instead:

Quote

[BG, BG2, IWD] Probabilities are systematically off by 1%

All effects on items and spells have d100 percentile probabilities assigned. The majority of these effects are written under the assumption that the engine rolls 1-100 to determine if these effects occur, however, the engine actually rolls 0-99. In most cases this doesn't make a difference as the default values are 0-100, but for effects that are supposed to only occur on x% of hits or castings it means the functional percentage is actually (x+1)%.

1. Open up IWDEE in Near Infinity and scroll to the item u1ham3a, the Corrosive Hammer +2.
2. Note that the description says it has a 30% chance of dealing 1d4 acid damage.
3. Open up the melee header and then the damage (12) effect. Note that Probability 1 = 30 and Probability 2 = 0.

Because these values are inclusive and 0 is a valid roll, this is actually a 31% chance for the damage to occur. These values should be 29 and 0 for a true 30% chance. You can verify similar issues in BGEE (check the Stupefier, blun41) and BG2EE (check Celestial Fury, sw1h51).

Note that this should not be fixed in code to roll 1-100 instead of 0-99, as most mods assume this behavior.

In this case, the fix is massive and I'd likely include a tpa for each game, along with listing some files to spot check.

Engine bugs should still follow the same guidelines. We won't have a fix, but we may have pseudo-code from Bubb that explains the issue or screenshots or whatever to support the problem.

Quote

[BG, BG2, IWD, PsT] Pausing immediately after a spell is cast causes issues with probability, saves

Normally when a spell is cast, a single probability and saving throw is used for every effect in the spell. However, if the game is paused right when the spell is cast--notably by enabling 'Spell Cast' in Options > Gameplay > Auto-Pause--then every effect can get independent rolls for saving throws and probabilities. (While Auto-Pause on Spell Cast is the easiest way to reproduce this, note that this bug can be tripped with a manual pause at the wrong moment.) This is a longstanding bug from the original engine.

1. Start a new HoW game with the default party
2. Skip the movie and mash 1 to get through Hjollder's dialogue
3. Go to the game options and verify that 'Spell Cast' is selected in Options > Gameplay > Auto-Pause
4. Make a quick save
5. Have Baern cast Sunscorch on Gorris by pressing 2, f7, f5, 1
6. Reload and repeat step five as needed

Sunscorch has four effects which depend on a save: target being blinded, target receiving the blind portrait icon, target having the string 'Blinded' appear in the combat feedback, and target getting half- or full-damage from the spell. Note that Gorris may have multiple "Save vs. Spell" messages in the combat feedback even though there should only be one saving throw rolled. Sometimes he'll get the Blinded icon but not actually be blinded because he made one save but not another. See the attached screenshot where the target has a Blind portrait icon and 'Blinded' in the combat feedback, but is not actually blinded.

This is a code-level issue and, as mentioned above, this also affects the d100 probability rolls in addition to saving throw rolls. In the old BG2 Fixpack, Friends was supposed to last 1 round/level of the caster plus 1d4 rounds, so we set up four effects that added 6 charisma with different durations, all with a 25% chance to occur. This happened, which is multiple, supposed-to-be-exclusive effects firing.

In this case I'd attach the screenshot from this post as a demonstration.

Some notes specific to bug reports for the EE Fixpack

Bug reports will likely come from players actually playing the game, which may be modded. This is fine, but we do need to know what mods may be affecting any bug you report. We can then verify if it's a bug in the unmodded game and come up with repro steps from there.

And no, we don't expect players to provide fixes.