Tooltips Guide

March 27, 2018 ยท View on GitHub

Updated 2017-12-05

< KV

Tooltips are used in the Dota 2 user interface to communicate information about units, abilities, debuffs, almost everything.

General Information

Tooltips are important for communicating information about the game to the players. They can be translated into multiple languages. Tooltips are compiled by a script, or by hand, into a file called "addon_language.txt". By default, OAA authors create tooltips in English and translators use those files to make tooltips in these additional languages using Transifex translation software.

Nearly all of the data for the English tooltips has already been generated by hand, however much of the data is in need of updating, correction, and other housekeeping. Authors should create/modify the individual files and run "node scripts\generate-translations.js" to compile the main English tooltip file (addon_english.txt) for testing.

Once tested, this file should not be committed to Github along with the rest of the files as it would generate conflicts if another author also edited the main file and attempted to merge it as well. To ensure you do not commit such changes you should undo any changes before committing-all, or commit all files but the main file.

Directories

The main English tooltip file (addon_english.txt) is located in ".../game/resource/". The individual English tooltip files (ex. tooltip_item_dagon.txt) are located in ".../game/resource/English/". The individual tooltips are divided into subfolders: ability, modifier, & npc.

Ability Sub-folder

The Ability sub-folder is where tooltips for Hero and unit abilities are located. These are the dialog boxes that appear when you mouse-over on a hero or unit's base abilities (ex. Berserker's Call).

Modifier Sub-folder

The Modifier sub-folder is where tooltips for buffs & debuffs are located. These are the dialog boxes that appear when you mouse-over on a buff or debuff (ex. if a unit is affected by Battle Hunger).

NPC Sub-folder

The NPC sub-folder is where tooltips for units are located. These are primarily used for the names of heroes, creeps, summons, and other units.

Coded Information

Some of the information in Tooltips is coded and should not be translated. Many of the default codes are listed here: https://developer.valvesoftware.com/wiki/Dota_2_Tooltip_Formatting

Key Value Pairs

Within most tooltip files you will find Keys with the prefix "DOTA_Tooltip_type_subtype_name_suffix". These are raw-value names taking various suffixes (ex. Description, duration, etc.)

  • Type/subtype - Indicates whethere this tooltip is a modifier, item, ability, etc.

  • Name - The name of the item, ability, etc.

  • Suffixes

    • Default - Default suffixes include "Description, Note, and Lore.
    • Custom - These are taken from the "AbilitySpecial" Values found in the item or abilty's corresponding "npc_name" file.

Descriptions

Descriptions which contain coded information use % as their delimiter (separating text from code). For example a Description might read "Active - Gives the hero %strength_bonus% strength." The coded part of the preceding example is taken from the item or ability's npc_item or npc_ability file. located in ".../game/scripts/npc/items/" and ".../game/scripts/npc/abilities" respectively.

Descriptions can also contain line breaks, shown as "\n".

Syntax and Organization

The content of the individual English tooltip files is organized into pairs of strings enclosed in quotation marks.

Ability

The individual Ability tooltip files in OAA are divided into item abilities and unit abilities folders. Each individual Ability tooltip file contains the data for either a single unit/item ability or set of cloned items (ex. Furion's force of nature, Dagon or all 5 abyssal blades).

Modifier

The individual Modifier tooltip files in OAA are also divided into item modifiers and unit modifiers folders. Each individual Modifier tooltip file contains the data for either a single item/ability or set of cloned items (ex. decay debuff, Shiva's Guard debuff.)

NPC

Each individual NPC tooltip file in OAA contains multiple units. The different files are: npc_bosses, npc_buildings, npc_creeps, npc_item_summons, and npc_unit_summons.

  • The first string of each pair in an NPC tooltip file is the raw-data value, or internal name, given to the unit (ex. npc_dota_hero_axe).

  • The second string of each pair in an NPC tooltip file is the name that should appear to players in the user interface (ex. Axe).

Testing Tooltip Changes

  1. Play Dota 2
  2. Press console shortcut key
  3. Type 'dota_launch_custom_game oaa oaa', press 'Enter'
  4. Play and identify broke shit.
  5. Disconnect from lobby when done. You don't need to close Dota 2
  6. Make your individual KeyValue changes. Commit your KeyValue changes in git.
  7. Populate changes to addon_english.txt by running node scripts/generate-translations.js using cmd-prompt in the oaa directory.
  8. Hop back into dota 2 and dota_launch_custom_game oaa oaa and test changes.
  9. Do not commit or upload addon_english.txt remove any/all changes to this file before committing by doing git checkout -- game/resource/addon_english.txt.
  10. Repeat 2-10 as necessary.

Summary

Tooltips are fairly easy to learn, but properly creating the text requires a very high attention to detail and great communication skills. Changes to any file or set of files should be done completely at once to save the translators from having to re-translate files multiple times. Authors should maintain intimate knowledge of the designs of items and abilities so that their tooltips will be accurate. Descriptions should be succinct and clear, based on a complete understanding of how the item/ability/unit works.

Authors should also be prepared to maintain their own set of files, uploading their work independently using a Git client: https://github.com/OpenAngelArena/oaa/blob/master/docs/github-for-noobs.md