AutoDescription

[Alywena]

Hello,

Here is a presentation of the mod I am currently develloping: AutoDescription

In the Baldur's Gate series, terms used to describe the same effect differ from one item’s description to another. The items added by mods often have their own description template too, and all of this can prevent the player from having some very useful and practical reference points when reading a description.

The goal of this project is to standardize as much as possible, and in a completely automatic way, the technical part of the descriptions of the items.

This mod “reads” the game files, and "converts" the coded effects (opcodes) into readable description text for every item.

Eventually this one is designed to be installed after all others mods that modify or add items, potions... in order to enjoy clear, reliable and harmonized descriptions !

The method used by the mod also allows to detect bugs and errors in the coding of items, by comparing the generated description of the effects to the original text.
You’d be surprised how many there are, either in the vanilla game or the many existing mods. (Could be very useful to check any mod's items for bugs, and probably helpful for the EE Fixpack.)

The mod is originally developed for French, an English version is proposed, but it is not yet complete and the wording may not be appropriate. I encourage anyone to take a look at the mod, and would be very happy if some of you suggest modifications or improvements !

Here you can see the mod working on a vanilla BGEE and BG2EE version, without any mod : 

- BGEE diffs
- BG2EE diffs

Here you can find different examples of existing mods, and for each of them, on the right the original version and on the left the new one generated by "Autodescription".
Several mods have been and will be tested in order to handle as many cases as possible and to be as accurate as possible :

- Shade of the sword coast by @Lava: SotSC diffs
- Forgotten-Armament BG2EE and BGEE by @Morpheus : BGEE diffs and BG2EE diffs
- L'Interplan by @deratiseur : L'interplan diffs (Mod only in French, the statistics parts are translated into English by AutoDescription)

It’s interesting to note that this method could also allow some form of automatic translation for the description part of items and make the process of translating mods easier !

If you think that this idea could be helpful and wish to translate this mod to any other language, note that the lines are numerous but short, and that we can clarify some of their particularities with any potential translator.

The mod is still in development, for now :

- Full French, and most translated into English.
- Works for vanilla and EE.
- Can read files of a specific mod (the mod must be installed on your game).
- Provides a differential between the effects of the original description and the effective effects.
- Provides error and warning logs

Future goals :

- Completing spell support
- Improving the precision of descriptions
- Shorten descriptions ( Ex : Association of similar effects : Immunity, May memorize additional spells for several levels, ...)
- Integration of different languages (If some of you want to work on the translation).

If you want to try Autodescription, the mod features three components:

- Standardize item descriptions
- Standardize spell descriptions (Alpha)
- Standardize item descriptions of a mod (for this component, the installer prompts and asks for the name of the mod folder)

A "settings-default.ini" can be used to set your preferences :

alter_item_files = 1 (change in game description)
alter_item_files = 0 (only generate a DIff in docs folder, if you want to look at the possible / potential changes without altering anything in your game

You can also include items without_description or non_moveable for testing purposes. 

(Among other things included in settings-default.ini)

Here are the mod on github and the french forum page !

- AutoDescription on Github
- French Forum

If you have any questions or comments, don't hesitate !

[mickabouille]

Wow impressive.

I had thought that should be possible but probably impractical.

[jmerry]

Looking at your examples ...

It looks like a useful tool for modders, examining items to see if they actually do what's intended. But I wouldn't trust it to produce final descriptions. Even setting aside the parts that aren't fully translated, there are a lot of cases in which descriptions can be written in more than one style, and you might not prefer the one this tool generates. For example, here are the two descriptions for the abilities of "Amauna's Warm Smile" in your "Shades of the Sword Coast" example.

Lava original:

Spoiler

Equipped abilities:
- Protection from Blindness
- Wisdom during day: +2 
- Armor class during day: +1

Weight: 1

AutoDescription:

Spoiler

Equipped abilities: 
- Cure blindness
- Immunity to blindness
- During the day, in every round; Cast a spell
  - Armor Class of the wearer: +1 for 1 round
  - Increases the Wisdom of the wearer by 2 for 1 round

Weight: 0

I'll take the original description any time; we don't need to know how the bonus works in detail. But at the same time, the different weight in the AutoDescription version indicates a mismatch between the item and its original description that deserves a correction.

[mickabouille]

20 hours ago, jmerry said:

I'll take the original description any time

I actually prefer the second version. To each their own I guess.

[Endarire]

Thankee for releasing this.

[Alywena]

On 1/7/2023 at 10:53 PM, jmerry said:

Looking at your examples ...

It looks like a useful tool for modders, examining items to see if they actually do what's intended. But I wouldn't trust it to produce final descriptions. Even setting aside the parts that aren't fully translated, there are a lot of cases in which descriptions can be written in more than one style, and you might not prefer the one this tool generates. For example, here are the two descriptions for the abilities of "Amauna's Warm Smile" in your "Shades of the Sword Coast" example.

Lava original:

  Reveal hidden contents

Equipped abilities:
- Protection from Blindness
- Wisdom during day: +2 
- Armor class during day: +1

Weight: 1

AutoDescription:

  Reveal hidden contents

Equipped abilities: 
- Cure blindness
- Immunity to blindness
- During the day, in every round; Cast a spell
  - Armor Class of the wearer: +1 for 1 round
  - Increases the Wisdom of the wearer by 2 for 1 round

Weight: 0

I'll take the original description any time; we don't need to know how the bonus works in detail. But at the same time, the different weight in the AutoDescription version indicates a mismatch between the item and its original description that deserves a correction.

Thank you for your feedback, it has significantly improved the generation of this type of description.
The latest versions have focused on simplifying the generated descriptions and fixing bugs.
For the case you mention, this is now the generated result.

STATISTICS:

Equipped abilities:
- Protection from blindness
- During the day;
  - Armor Class: +1
  - Wisdom: +2

Weight: 0

The used style is only an example (and it was generated with translation from Deepl), I don't know the usage for English, but it is quite possible to adapt it to be as close as possible to the standards of your language.

[marchitek]

Neat idea. I have a feeling it will show its real potential with spells, where there is no clear distinction between "RP" description and "STATISTICS" description in unmodded game (putting aside those general information about school, casting time etc).

[MikeX]

This is quite amazing!

A suggestion:
Change current naming from Base Armor Class to Armor Class and Armor Class to Armor Class Bonus.
Switch sign of Armor Class Bonus by multiplying it with -1, then it's more intuitive (since lower numbers are better) to calculate the resulting armor class.

Example result (current), from a cursed item:

Equipped abilities: 
- Base Armor Class: 5
- Armor Class: -10 vs. missile attacks
- Armor Class: +2 vs. slashing attacks
- Armor Class: +1 vs. piercing attacks

armor class vs. missile attacks = 5 - (-10) = 5 + 10 = 15
armor class vs. slashing attacks = 5 - (+2) = 5 - 2 = 3
armor class vs. piercing attacks = 5 - (+1) = 5 - 1 = 4

Example result (suggestion), same item as above:

Equipped abilities: 
- Armor Class: 5
- Armor Class Bonus: +10 vs. missile attacks
- Armor Class Bonus: -2 vs. slashing attacks
- Armor Class Bonus: -1 vs. piercing attacks

or, even better and one line shorter:

Equipped abilities: 
- Armor Class: +15 vs. missile attacks
- Armor Class: +3 vs. slashing attacks
- Armor Class: +4 vs. piercing attacks

 

[jmerry]

Or, following the convention the game uses already in body armor descriptions:

Armor Class: 5 (3 vs. slashing, 4 vs. piercing, 15 vs. missile)

The order of the listings for AC versus types varies; the best rule I could spot based on a casual scan is that it runs best to worst. This convention would be used for anything that has both an AC-setting effect (flag 4) and AC effects for type modifiers (flags 0-3)

For items that don't have that AC-setting effect, the signs should be flipped to be consistent with vanilla descriptions. For example, a nonmagical large shield says "Armor Class: +1, an extra +1 vs missile effects". Small shields split that type modifier out onto a different line with that "No protection from missile attacks"; obviously, that should only be used when there's a net zero modifier.

[mickabouille]

38 minutes ago, MikeX said:

Switch sign of Armor Class Bonus by multiplying it with -1, then it's more intuitive (since lower numbers are better) to calculate the resulting armor class

I actually prefer having "3 point bonus to AC" rather than +3 or -3. Bonus means "better" and malus means "worse" in any case.

For absolute values, it's a bit more complicated...

Edited April 14, 2023 by mickabouille

[Alywena]

Thank you for your feedback.

I'm not very active on this forum, but I'll take all your comments into consideration!

Several versions have been released since my last message, and there have been a huge number of improvements, both to items and to spells. The latter have been given special treatment, and their descriptions can now be used in-game in most cases.

I'm not going to list all the changes, but rather provide you with links so that you can see the difference in descriptions between the last version I presented and the latest one.

Items
- Before: https://htmlpreview.github.io/?https://github.com/Selphira/AutoDescription/blob/0.9.25/docs/diff-bgee-en_us.html
- After: https://htmlpreview.github.io/?https://github.com/Selphira/AutoDescription/blob/master/docs/english-bgeesod-all-items-diff.html

For example PLAT05 to see the changes with AC

Spells
https://htmlpreview.github.io/?https://github.com/Selphira/AutoDescription/blob/master/docs/english-bgeesod-all-spells-diff.html

Note: The configuration that generates the "STATISTICS" section (add_statistics_section_to_spell_description)  is deactivated by default.

I was also able to detect bugs in the spells.

Spoiler

BHAAL1B: (BG2EE) The duration is +1 round every 2 levels, but at some point the spell goes from level 18 to 21 instead of level 20.

BHAAL3B: (BG2EE) Opcode 248, refers to a BH3B1(.eff) resource that doesn't exist (the .spl does exist though)

SPIN117: (BG2EE) Opcode 17 and 187, have 119 seconds instead of 120 like the rest

SPIN685: (BG2EE) Opcode 12, level 1 bypasses magic resistance

SPIN698: (BG2EE) Opcode 69, level 1 lasts 90 seconds instead of 60

SPPR701: (SOD and BG2EE) Opcode 201, level 1 with paramater2 == 3 has paramater1 equal to 9 instead of 7 like the others

SPWI318: (BG2EE) Level 1 is missing and should increase the duration by 3 rounds.

SPWI318: (SOD) The duration of some level 11 effects are 180 instead of 198

SPWI399: (SOD) The level 1 target is different from the others

SPWI606: (SOD) Opcode 31, parameter2 of level 19 and 20 are 0 and not 1 like the other levels

SPWI608: (SOD) Opcode 230, different resistance at level 18

SPWI620 ! (SOD) Opcode 165, level 19 duration equals 30 instead of 18

SPWI622 : The duration before level 12 is longer than from level 12 onwards

 

Edited July 9, 2023 by Alywena

[Endarire]

Thankee!

[Lurker]

@Alywena I've started to put some effort into the English translation. Neither English nor French are my native language, but Google translate is a thing, and since some of the previous text already seems a bit heavy-handed, the results shouldn't be completely terrible.

I'm not active on Github, and trying to generate a patch in unified diff format borks the character encoding, so I'd attach a gzip compressed version of the complete description.tra (based on the current release) here, if that's okay.

The side-by-side comparison in auto-generated html is really cool. I'm using mods that heavily tweak proficiencies and abilities, so item descriptions can become quite verbose.

 

Edited October 25, 2023 by Lurker
removed description.tra_english_0.9.29+2023-09-14.gz to save space

[Alywena]

Hello @Lurker

First of all, thank you for your interest in AutoDescription

Yes, you can attach a zip containing your translation, and I'll do the rest to integrate it into the mod.

It's true that some effects are still very verbose, but I'm still working on reducing the descriptions as much as possible. Almost every time there is an update, new description reductions are developed.

A small example with Skills & Abilities.
Before, this description was generated (sorry, the example is in French)

- À chaque round ; Si la force du porteur est supérieure ou égale à 18 ; 
  - Les effets ne se cumulent pas
  - Dégâts : +1 pendant 8 secondes
- À chaque round ; Si la force du porteur est supérieure ou égale à 19 ; 
  - Les effets ne se cumulent pas
  - Dégâts : +2 pendant 8 secondes
- À chaque round ; Si la force du porteur est supérieure ou égale à 20 ; 
  - Les effets ne se cumulent pas
  - Dégâts : +1 pendant 8 secondes
- À chaque round ; Si la force du porteur est supérieure ou égale à 22 ; 
  - Les effets ne se cumulent pas
  - Dégâts : +1 pendant 8 secondes
- À chaque round ; Si la force du porteur est supérieure ou égale à 24 ; 
  - Les effets ne se cumulent pas
  - Dégâts : +1 pendant 8 secondes
- À chaque round ; Si la force du porteur est supérieure ou égale à 25 ; 
  - Les effets ne se cumulent pas
  - Dégâts : +1 pendant 8 secondes

Now, this description is generated

- Si la force du porteur est supérieure ou égale à 18 ; Dégâts : +1 (non cumulable)
- Si la force du porteur est supérieure ou égale à 19 ; Dégâts : +2 (non cumulable)
- Si la force du porteur est supérieure ou égale à 20 ; Dégâts : +1 (non cumulable)
- Si la force du porteur est supérieure ou égale à 22 ; Dégâts : +1 (non cumulable)
- Si la force du porteur est supérieure ou égale à 24 ; Dégâts : +1 (non cumulable)
- Si la force du porteur est supérieure ou égale à 25 ; Dégâts : +1 (non cumulable)

It's not perfect yet, but it's better than before.

The most impressive improvements are in spells, where around 20 lines have been reduced to just one.

[Lurker]

2 hours ago, Alywena said:

A small example with Skills & Abilities.

That's the reason I spent last night with vim and Google translate as an advisor.

The strings that I changed I mostly picked from the *items-diff.html.

And as long as we can trust your mod to correctly interpret item files, it's a great way to finally get reliable item descriptions, or to identify errors without even running the game.

Btw, I sometimes noticed what seems like off-by-one errors when comparing the before and after of item descriptions. A repeating pattern is "15% chance [to something]", which often becomes "16 % chance [to something]"; off-by-one, and with an unaesthetic whitespace.

Obviously, I don't know if the item is wrong, or the generated description.

Edited September 9, 2023 by Lurker