Skip to content

Advanced Item Display

github-actions[bot] edited this page Sep 11, 2026 · 3 revisions

By enabling the "Advanced Item Display" configuration parameter, you can customize exactly how items are displayed. It is the only mechanism for customizing item names: with it disabled, items are named exactly as the game names them.

It also adds the item level, and the affix level where that differs, to an item's properties.

Where the rules are read from

The rules ship in BH.cfg, beside BH_settings.cfg. To keep more than one filter, put each as its own .cfg in a filters folder next to them, and choose between them with "Filter source" on the Filter tab of the settings window. A filter is named by its file name without the extension, so filters\Grail.cfg is offered as "Grail"; BH.cfg itself is "BH (default)". The choice is saved as Item Filter in BH_settings.cfg.

A chosen filter that cannot be read - the file is gone, or it holds no ItemDisplay rules - falls back to BH.cfg, and says so in game. The name is kept either way, so a filter that is missing today is still selected once it is back. .reload rereads both the settings and the filter, and picks up filters added to the folder since the game started.

To use Advanced Item Display, you will configure one or more rules in your filter. Each rule looks like this:

ItemDisplay[ ...CONDITIONS... ]: ACTIONS

The CONDITIONS specify a set of conditions an item must satisfy, and ACTIONS specify the actions taken when a matching item is found. The most basic type of action is to simply enter the name you want to see when viewing that item. If you leave the CONDITIONS empty, the rule will match all items. If you leave the ACTIONS empty, the rule will blank out the names of any matching items.

You will normally have multiple rules in your configuration file. The first rule that matches a given item is the one that will be used to display that item (with one exception, the %CONTINUE% action, described below).

The simplest rule has no conditions and no actions:

ItemDisplay[]:

This rule will match every item in the game, and will prevent the client from showing that item. (So when you hit the alt key, you will see nothing other than gold stacks.) Next is another simple rule that matches every item in the game, and gives them all the same name:

ItemDisplay[]: Wirt's Other Leg

Rules with No Actions

In version 0.1.4, items matching rules with no actions were still visible on the ground, but their names were changed to a single space. As of version 0.1.5, this is no longer true; these items are actually filtered out by the game client. As far as your game is concerned, the items do not exist. This is useful for reducing ground clutter from small gold stacks, junk items, etc. But be careful when using rules like this, as they can cause unexpected effects. For example, if you have a rule with no actions that matches health potions, they will effectively be invisible to you and you will not be able to see the potions on your own belt.

As of 1.9.9, an ignore rule is only created when the item name and description are not blank, there is no map action, and there is no %CONTINUE% statement. Essentially only blank lines can create ignore rules.

Additionally, blank item names are no longer generated. This could occasionally happen in previous releases when a name was set blank but the item was not completely filtered. To warn users that an item they see in game will be blocked by the packet filter, a [blocked] tag is added to the item. For example:

image

The blocked tag is only generated when the item has an ignore rule and not an explicit whitelist rule (could be any valid name or a map condition).

Item Codes

The simplest condition consists of an item code. An item code is the unique 3-letter code assigned to each type of item. You can find a full list of item codes here: http://bhfiles.com/files/Diablo%20II/ItemCodes.html.

EDIT: the bhfiles.com list contains some incorrect codes (e.g. gnarled staff is actually cst). A more correct (though less readable) list can be found here: https://github.com/dkuwahara/OmegaBot/blob/master/data/item_data.txt (the item code is the second column).

The item code for a scroll of town portal is "tsc". So to shorten the names of all town portal scrolls in the game to just "TP", you would put this line in BH.cfg:

ItemDisplay[tsc]: TP

To give all super healing potions (item code hp5) the name "Pan-Galactic Gargle Blaster", you would put this in BH.cfg:

ItemDisplay[hp5]: Pan-Galactic Gargle Blaster

Changing Colors

You can change the color of item text. To make your super healing potions appear with red text, do this:

ItemDisplay[hp5]: %RED%Pan-Galactic Gargle Blaster

The %RED% color will apply to everything that comes after it, until another color is encountered. To display the word "Blaster" in green text (with everything else still red), you would write:

ItemDisplay[hp5]: %RED%Pan-Galactic Gargle %GREEN%Blaster

These are the colors you can use:

  • %WHITE%
  • %RED%
  • %GREEN%
  • %BLUE%
  • %GOLD%
  • %GRAY%
  • %BLACK%
  • %TAN%
  • %ORANGE%
  • %YELLOW%
  • %PURPLE%

Short names for scrolls, potions and quivers are a common starting point. These rules abbreviate every one of them, colored by what it is:

ItemDisplay[tsc]: %GREEN%**%WHITE%TP
ItemDisplay[isc]: %GREEN%**%WHITE%ID
ItemDisplay[vps]: Stam
ItemDisplay[yps]: Anti
ItemDisplay[wms]: Thaw
ItemDisplay[gps]: Ranc
ItemDisplay[ops]: Oil
ItemDisplay[gpm]: Chok
ItemDisplay[opm]: Expl
ItemDisplay[gpl]: Stra
ItemDisplay[opl]: Fulm
ItemDisplay[hp1]: %RED%**%WHITE%Min Heal
ItemDisplay[hp2]: %RED%**%WHITE%Lt Heal
ItemDisplay[hp3]: %RED%**%WHITE%Heal
ItemDisplay[hp4]: %RED%**%WHITE%Gt Heal
ItemDisplay[hp5]: %RED%**%WHITE%Sup Heal
ItemDisplay[mp1]: %BLUE%**%WHITE%Min Mana
ItemDisplay[mp2]: %BLUE%**%WHITE%Lt Mana
ItemDisplay[mp3]: %BLUE%**%WHITE%Mana
ItemDisplay[mp4]: %BLUE%**%WHITE%Gt Mana
ItemDisplay[mp5]: %BLUE%**%WHITE%Sup Mana
ItemDisplay[rvs]: %PURPLE%**%WHITE%Rejuv
ItemDisplay[rvl]: %PURPLE%**%WHITE%Full
ItemDisplay[aqv]: Arrows
ItemDisplay[cqv]: Bolts
ItemDisplay[key]: Key

Socket counts, ethereality and rune numbers are shown only where a rule asks for them. These three add to a name rather than replacing it, so they stack with each other:

ItemDisplay[ETH]: Eth %NAME%%CONTINUE%
ItemDisplay[SOCK>0]: %NAME% (%SOCKETS%)%CONTINUE%
ItemDisplay[RUNE>0]: [%RUNENUM%]%NAME%%CONTINUE%

%CONTINUE% is what makes them stack: without it, the first rule to match an item is the only one applied and the rest are skipped, which is also why these three belong below the abbreviation rules rather than above them.

Adding to Existing Names

Sometimes it's nice to add onto an existing item name. To leave a super healing potion with the same name, but write it in red text, do this:

ItemDisplay[hp5]: %RED%%NAME%

To prepend "Ninja" to every item name in the game, use this rule:

ItemDisplay[]: Ninja %NAME%

You can append every item's vendor value to its name using the %PRICE% action, as shown here:

ItemDisplay[]: %NAME% ($%PRICE%)

To add item level to item names, do this:

ItemDisplay[]: %NAME% {L%ILVL%}

To show an item's item code, use the following rule:

ItemDisplay[]: %NAME% [%CODE%]

To add the number of sockets to item names, this would work:

ItemDisplay[]: %NAME% -%SOCKETS%-

%BASENAME% gives the item's base type name rather than its full name, which is useful for uniques and set items where the displayed name tells you nothing about what the item actually is:

ItemDisplay[UNI]: %NAME% (%BASENAME%)

That turns "Wizardspike" into "Wizardspike (Bone Knife)".

Logical Operators

Often you will want to match multiple conditions. This rule will match any item that satisfies both CONDITION1 and CONDITION2 (since no logical operators are given, the conditions are implicitly ANDed together):

ItemDisplay[CONDITON1 CONDITION2]: ...

For more complicated conditions, you can use the following logical operators:

  • AND
  • OR
  • ! (logical negation)

The previous rule is exactly equivalent to this one:

ItemDisplay[CONDITON1 AND CONDITION2]: ...

You can also use parentheses to group conditions. See below for examples of these logical operators.

Item Quality

Several conditions let you match items of certain quality:

  • INF: matches inferior items
  • SUP: matches superior items
  • MAG: matches magic items
  • RARE: matches rare items
  • SET: matches rare items
  • UNI: matches unique items
  • NMAG: matches nonmagical (white/gray) items
  • ETH: matches ethereal items
  • RW: matches runewords
  • CRAFT: matches crafted items

For example, to write all unique ethereal item names in purple, do this:

ItemDisplay[ETH UNI]: %PURPLE%%NAME%

Item Groups

Normal, Exceptional, Elite

  • NORM: matches normal items
  • EXC: matches exceptional items
  • ELT: matches elite items

Class Specific Items

There are conditions that refer to class specific items:

  • CL1 or DRU: druid pelts
  • CL2 or BAR: barbarian helms
  • CL3 or DIN: paladin shields
  • CL4 or NEC: necromancer heads
  • CL5 or SIN: assassin katars
  • CL6 or SOR: sorceress orbs
  • CL7 or ZON: amazon weapons

To display all ethereal paladin shields in purple, use this line:

ItemDisplay[ETH CL3]: %PURPLE%%NAME%

Weapon Groups

  • WP1 or AXE: axes
  • WP2 or MACE: maces
  • WP3 or SWORD: swords
  • WP4 or DAGGER: daggers
  • WP5 or THROWING: throwing weapons
  • WP6 or JAV: javelins
  • WP7 or SPEAR: spears
  • WP8 or POLEARM: polearms
  • WP9 or BOW: bows
  • WP10 or XBOX: crossbows
  • WP11 or STAFF: staves
  • WP12 or WAND: wands
  • WP13 or SCEPTER: scepters
  • WEAPON: any weapon

Armor Groups

  • EQ1 or HELM: helms
  • EQ2 or CHEST: body armor
  • EQ3 or SHIELD: shields
  • EQ4 or GLOVES: gloves
  • EQ5 or BOOTS: boots
  • EQ6 or BELT: belts
  • EQ7 or CIRC: circlets
  • ARMOR: any armor

To display ethereal elite polearms capable of 4+ sockets in purple, use this line in BH.cfg:

ItemDisplay[WP8 ETH ELT NMAG (SOCK=0 OR SOCK>3) !7o7]: %PURPLE%%NAME%

The exclamation point prevents matching item code 7o7 (ogre axe), which can only have 3 sockets.

Sockets

You can match items with a certain number of sockets. To display all items with more than 4 sockets in green:

ItemDisplay[SOCK>4]: %GREEN%%NAME%

For conditions like SOCK that compare with a number, you can use <, >, or =.

Filled sockets (as of BH 1.9.11f)

SOCK counts the total number of sockets in an item, whether or not anything has been put in them. USEDSOCK counts only the sockets that have something inserted (a gem, rune, or jewel). The two together let you distinguish an empty base from a partially filled one from a completed runeword.

To find four socket bases that are still empty and worth using for Spirit:

ItemDisplay[SOCK=4 USEDSOCK=0 !RW]: %NAME%%MAP%

To find items someone has already started filling, so you don't vendor them by accident:

ItemDisplay[USEDSOCK>0 !RW]: %ORANGE%%NAME%

The matching %USEDSOCKETS% variable prints the count, in the same way %SOCKETS% prints the total:

ItemDisplay[SOCK>0]: %NAME% [%USEDSOCKETS%/%SOCKETS%]

Note that a completed runeword still reports its sockets as used, so pair USEDSOCK with !RW when you want socketed-but-unfinished items only.

Runes, Gems, and Gold

The "RUNE" condition can be used to match different types of runes based on the rune number. To display runes Lem and higher in purple "20 - Lem" format:

ItemDisplay[RUNE>19]: %PURPLE%%RUNENUM% - %RUNENAME%

The "GEM" condition will match based on gem quality (1=chipped, 5=perfect). To display all flawless and perfect gems in purple:

ItemDisplay[GEM>3]: %PURPLE%%NAME%

The "GEMTYPE" condition will match on the type of the gem, based on this list: gem types. To match all perfect diamonds:

ItemDisplay[GEM=5 GEMTYPE=2]: ...

To block the game from showing any gold stacks smaller than 1000:

ItemDisplay[GOLD<1000]:

Unlike other conditions, GOLD can only be used to filter out small stacks. It cannot currently be used to change the color or show stacks of certain sizes on the map.

Skills

It is possible to match bonuses to all skills, bonuses to class skills, bonuses to particular skill trees, and bonuses to individual skills.

All Skills

To match all items with +2 or more to all skills:

ItemDisplay[ALLSK>1]: ...

Class Skills

Find the number of the class from this page: class list; next, append that number to "CLSK". This will match grand matron bows with +2/+3 to amazon skills (class number 0 from the list):

ItemDisplay[amc CLSK0>1]: ...

Skill Tabs

Find the number of the skill tab here: skill tabs; then append it to "TABSK". So to match all items with +1 or more to warcries (#34 from that list):

ItemDisplay[TABSK34>0]: ...

Individual Skills

Look up the number of the skill on this page: skills list. For example, Battle Orders is skill number 149. So to display barbarian helms capable of 3os with +3 to BO in purple:

ItemDisplay[CL2 ((ILVL>25 SOCK=0) OR SOCK=3) NMAG SK149>2]: %PURPLE%%NAME%

Other Conditions

Other miscellaneous conditions:

  • ILVL: matches against the item level
  • QLVL: matches against the item quality level
  • ALVL: matches against the item affix level
  • CLVL: matches against you character current level
  • DIFF: matches against the games current difficulty
  • ED: matches % effective defense/damage (depending on item type)
  • RES: matches resist all
  • FRES: matches fire resist
  • CRES: matches cold resist
  • LRES: matches lightning resist
  • PRES: matches poison resist
  • FCR: matches faster cast rate
  • FHR: matches faster hit recovery
  • FBR: matches faster block rate
  • FOOLS: matches against the Fools mod
  • LVLREQ: matches against the items level requirement
  • ARPER: matches against attack rating based on char level
  • MFIND: matches magic find
  • GFIND: matches gold find
  • STR: matches +STR items
  • DEX: matches +DEX items
  • FRW: matches faster run walk rate
  • MINDMG: matches +MIN damage items
  • MAXDMG: matches +MAX damage items
  • DTM: matches damage to mana
  • MAEK: matches mana after each kill
  • REPLIFE: matches replenish life
  • REPQUANT: matches repair quantity
  • REPAIR: matches repair durability
  • ID: matches items that have been identified
  • DEF: matches total defense
  • LIFE: matches +HP items
  • MANA: matches +MANA items
  • IAS: matches increased attack speed
  • CRAFTALVL: matches the resulting affix level of the item if it were to be crafted by the character you are playing
  • AREAID: matches the id of the area the item is lying in (see Area ids and area levels)
  • AREALVL: matches the monster level of that area for the current difficulty (see Area ids and area levels)
  • USEDSOCK: matches the number of sockets that have been filled (see Filled sockets)
  • XP: matches when the character you are playing is an expansion character
  • CLASSIC: matches when the character you are playing is a classic character
  • AMAZON, SORCERESS, NECROMANCER, PALADIN, BARBARIAN, DRUID, ASSASSIN: match when the character you are playing is of that class

XP and CLASSIC take no operator or number; they are used on their own. They describe your own character, not whoever is holding the item, and let a single config behave differently on classic and expansion characters:

ItemDisplay[CLASSIC gcv]: %NAME%%MAP%
ItemDisplay[XP gcv]:

The class names work the same way, and likewise refer to the class you are playing rather than any class restriction on the item itself, so one config can be shared between characters of different classes. This hides keys only while playing an assassin:

ItemDisplay[key ASSASSIN]:

They combine with !, AND and OR like any other condition, e.g. ItemDisplay[key !ASSASSIN]: hides keys on every class except the assassin, and ItemDisplay[cm1 (SORCERESS OR NECROMANCER)]: %NAME%%MAP% marks small charms only on those two classes.

Area Ids and Area Levels

Two item filter codes describe the area an item is lying in. Both only ever match items on the ground, so a rule using them never applies to inventory, stash, cube, belt or equipped items. Match results are cached per item, so an item you pick up keeps the match it had on the ground until something about the item itself changes.

Code Meaning
AREAID Id of the area the item is lying in, as listed below.
AREALVL Monster level of that area for the current difficulty, as listed below.

Both support the usual comparison operators, for example:

ItemDisplay[AREALVL>83]: %NAME%
ItemDisplay[AREAID=108]: %NAME%

Area names are the names the game displays.

Area levels are the expansion values; classic characters use the classic monster levels of the same area. Towns and other areas without monsters have an area level of 0.

Id Hex Act Area Normal Nightmare Hell
1 0x01 1 Rogue Encampment 0 0 0
2 0x02 1 Blood Moor 1 36 67
3 0x03 1 Cold Plains 2 36 68
4 0x04 1 Stony Field 4 37 68
5 0x05 1 Dark Wood 5 38 68
6 0x06 1 Black Marsh 6 38 69
7 0x07 1 Tamoe Highland 8 39 69
8 0x08 1 Den of Evil 1 36 79
9 0x09 1 Cave Level 1 2 36 77
10 0x0A 1 Underground Passage Level 1 4 37 69
11 0x0B 1 Hole Level 1 5 38 80
12 0x0C 1 Pit Level 1 7 39 85
13 0x0D 1 Cave Level 2 2 37 78
14 0x0E 1 Underground Passage Level 2 4 38 83
15 0x0F 1 Hole Level 2 5 39 81
16 0x10 1 Pit Level 2 7 40 85
17 0x11 1 Burial Grounds 3 36 80
18 0x12 1 Crypt 3 37 83
19 0x13 1 Mausoleum 3 37 85
20 0x14 1 Forgotten Tower 0 0 0
21 0x15 1 Tower Cellar Level 1 7 38 75
22 0x16 1 Tower Cellar Level 2 7 39 76
23 0x17 1 Tower Cellar Level 3 7 40 77
24 0x18 1 Tower Cellar Level 4 7 41 78
25 0x19 1 Tower Cellar Level 5 7 42 79
26 0x1A 1 Monastery Gate 8 40 70
27 0x1B 1 Outer Cloister 9 40 70
28 0x1C 1 Barracks 9 40 70
29 0x1D 1 Jail Level 1 10 41 71
30 0x1E 1 Jail Level 2 10 41 71
31 0x1F 1 Jail Level 3 10 41 71
32 0x20 1 Inner Cloister 10 41 72
33 0x21 1 Cathedral 11 42 72
34 0x22 1 Catacombs Level 1 11 42 72
35 0x23 1 Catacombs Level 2 11 42 73
36 0x24 1 Catacombs Level 3 12 43 73
37 0x25 1 Catacombs Level 4 12 43 73
38 0x26 1 Tristram 6 39 76
39 0x27 1 The Secret Cow Level 28 64 81
40 0x28 2 Lut Gholein 0 0 0
41 0x29 2 Rocky Waste 14 43 75
42 0x2A 2 Dry Hills 15 44 76
43 0x2B 2 Far Oasis 16 45 76
44 0x2C 2 Lost City 17 46 77
45 0x2D 2 Valley of Snakes 18 46 77
46 0x2E 2 Canyon of the Magi 16 48 79
47 0x2F 2 Sewers Level 1 13 43 74
48 0x30 2 Sewers Level 2 13 43 74
49 0x31 2 Sewers Level 3 14 44 75
50 0x32 2 Harem Level 1 0 0 0
51 0x33 2 Harem Level 2 13 47 78
52 0x34 2 Palace Cellar Level 1 13 47 78
53 0x35 2 Palace Cellar Level 2 13 47 78
54 0x36 2 Palace Cellar Level 3 13 48 78
55 0x37 2 Stony Tomb Level 1 12 44 78
56 0x38 2 Halls of the Dead Level 1 12 44 79
57 0x39 2 Halls of the Dead Level 2 13 45 81
58 0x3A 2 Claw Viper Temple Level 1 14 47 82
59 0x3B 2 Stony Tomb Level 2 12 44 79
60 0x3C 2 Halls of the Dead Level 3 13 45 82
61 0x3D 2 Claw Viper Temple Level 2 14 47 83
62 0x3E 2 Maggot Lair Level 1 17 45 84
63 0x3F 2 Maggot Lair Level 2 17 45 84
64 0x40 2 Maggot Lair Level 3 17 46 85
65 0x41 2 Ancient Tunnels 17 46 85
66 0x42 2 Tal Rasha's Tomb 17 49 80
67 0x43 2 Tal Rasha's Tomb 17 49 80
68 0x44 2 Tal Rasha's Tomb 17 49 80
69 0x45 2 Tal Rasha's Tomb 17 49 80
70 0x46 2 Tal Rasha's Tomb 17 49 80
71 0x47 2 Tal Rasha's Tomb 17 49 80
72 0x48 2 Tal Rasha's Tomb 17 49 80
73 0x49 2 Tal Rasha's Chamber 17 49 80
74 0x4A 2 Arcane Sanctuary 14 48 79
75 0x4B 3 Kurast Docks 0 0 0
76 0x4C 3 Spider Forest 21 49 79
77 0x4D 3 Great Marsh 21 50 80
78 0x4E 3 Flayer Jungle 22 50 80
79 0x4F 3 Lower Kurast 22 52 80
80 0x50 3 Kurast Bazaar 22 52 81
81 0x51 3 Upper Kurast 23 52 81
82 0x52 3 Kurast Causeway 24 53 81
83 0x53 3 Travincal 24 54 82
84 0x54 3 Arachnid Lair 21 50 79
85 0x55 3 Spider Cavern 21 50 79
86 0x56 3 Swampy Pit Level 1 21 51 80
87 0x57 3 Swampy Pit Level 2 21 51 81
88 0x58 3 Flayer Dungeon Level 1 22 51 81
89 0x59 3 Flayer Dungeon Level 2 22 51 82
90 0x5A 3 Swampy Pit Level 3 21 51 82
91 0x5B 3 Flayer Dungeon Level 3 22 51 83
92 0x5C 3 Sewers Level 1 23 52 84
93 0x5D 3 Sewers Level 2 24 53 85
94 0x5E 3 Ruined Temple 23 53 84
95 0x5F 3 Disused Fane 23 53 84
96 0x60 3 Forgotten Reliquary 23 53 84
97 0x61 3 Forgotten Temple 24 54 85
98 0x62 3 Ruined Fane 24 54 85
99 0x63 3 Disused Reliquary 24 54 85
100 0x64 3 Durance of Hate Level 1 25 55 83
101 0x65 3 Durance of Hate Level 2 25 55 83
102 0x66 3 Durance of Hate Level 3 25 55 83
103 0x67 4 The Pandemonium Fortress 0 0 0
104 0x68 4 Outer Steppes 26 56 82
105 0x69 4 Plains of Despair 26 56 83
106 0x6A 4 City of the Damned 27 57 84
107 0x6B 4 River of Flame 27 57 85
108 0x6C 4 The Chaos Sanctuary 28 58 85
109 0x6D 5 Harrogath 0 0 0
110 0x6E 5 Bloody Foothills 24 58 80
111 0x6F 5 Frigid Highlands 25 59 81
112 0x70 5 Arreat Plateau 26 60 81
113 0x71 5 Crystalline Passage 29 61 82
114 0x72 5 Frozen River 29 61 83
115 0x73 5 Glacial Trail 29 61 83
116 0x74 5 Drifter Cavern 29 61 84
117 0x75 5 Frozen Tundra 27 60 81
118 0x76 5 The Ancients' Way 29 62 82
119 0x77 5 Icy Cellar 29 62 83
120 0x78 5 Arreat Summit 37 68 87
121 0x79 5 Nihlathak's Temple 32 63 83
122 0x7A 5 Halls of Anguish 33 63 83
123 0x7B 5 Halls of Pain 34 64 84
124 0x7C 5 Halls of Vaught 36 64 84
125 0x7D 5 Abaddon 39 60 81
126 0x7E 5 Pit of Acheron 39 61 82
127 0x7F 5 Infernal Pit 39 62 83
128 0x80 5 Worldstone Keep Level 1 39 65 85
129 0x81 5 Worldstone Keep Level 2 40 65 85
130 0x82 5 Worldstone Keep Level 3 42 66 85
131 0x83 5 Throne of Destruction 43 66 85
132 0x84 5 The Worldstone Chamber 43 66 85
133 0x85 5 Matron's Den 50 75 83
134 0x86 5 Forgotten Sands 50 75 83
135 0x87 5 Furnace of Pain 50 75 83
136 0x88 5 Tristram 50 75 83

Marking Items on the Map

You can mark any matching item on the map with a square by putting %MAP% anywhere in the action for the rule. This will put all mage plates on the map as a white square without changing the name:

ItemDisplay[xtp]: %NAME%%MAP%

This square will be white because a color was not specified; if a color is used before the %MAP% action, then that will be used as the square color. For example, this marks mage plates with blue squares:

ItemDisplay[xtp]: %NAME%%BLUE%%MAP%

Item Descriptions (as of BH 1.9.9)

Item descriptions allow users to add custom descriptions to items. For example, we can set a line describing how to make a Hoto runeword with an eligible flail (below).

Item descriptions are added using curly braces {}. The above description was created with the following line.

ItemDisplay[NMAG !RW (fla OR 9fl OR 7fl) SOCK=4]: {%WHITE%Heart of the Oak: %ORANGE%KoVexPulThul}

It is also valid to set the description in the same line as the item name or item MAP actions. For example:

ItemDisplay[NMAG !RW (fla OR 9fl OR 7fl) SOCK=4]: %NAME%%MAP%{%WHITE%Heart of the Oak: %ORANGE%KoVexPulThul}

Descriptions are processed separately from name and map actions, so a line with only a description will not set an ignore rule. For example, the following would still result in the item being visible in game.

ItemDisplay[NMAG !RW (fla OR 9fl OR 7fl) SOCK=4]: {%WHITE%Heart of the Oak: %ORANGE%KoVexPulThul}
ItemDisplay[NMAG !RW (fla OR 9fl OR 7fl) SOCK=4]: %NAME%

Descriptions do not white list items. So an item with only a description can still be hidden. For example:

ItemDisplay[NMAG !RW (fla OR 9fl OR 7fl) SOCK=4]: {%WHITE%Heart of the Oak: %ORANGE%KoVexPulThul}
ItemDisplay[NMAG !RW (fla OR 9fl OR 7fl) SOCK=4]:

Descriptions support any keywords that the normal item name does with the exception of %CONTINUE%. The %CONTINUE% keyword is not valid inside curly braces, but it can still be used outside curly braces to further modify descriptions. For example:

ItemDisplay[NMAG !RW (fla OR 9fl OR 7fl) SOCK=4]: {%WHITE%Heart of the Oak: %ORANGE%KoVexPulThul}%CONTINUE%
ItemDisplay[NMAG !RW ETH fla SOCK=4]: {%NAME% (best base)}

Above, the description will be "Heart of the Oak: KoVexPulThul (best base)" for an eth 4 socket flail. The %NAME% keyword becomes a replacement token for the description up to that point.

Native ilvl display (as of BH 1.9.9)

The item level is now displayed within the item properties. Similarly, affix level is shown for magic, rare, and crafted quality items. Affix level is only shown if it is different than item level. Both are shown whenever "Advanced Item Display" is on. Below shows some rare gloves with item level and affix level display.

image

In-game item filter modes (as of BH 1.9.9)

The in-game menu supports four options for "Filter Level": None, Minimal, Moderate, and Aggressive. It is up to the BH.cfg to set the behavior for the filter modes. There is a new keyword FILTLVL to support these modes. The modes described previously correspond to FILTLVL 0, 1, 2, and 3, respectively.

Here's an example of what can be done using the "Filter Level":

image

The skull cap is blocked when the filter level is set to moderate but not when it is set to None. This is because of the FILTLVL>0 condition in the blocking line.

In-game configurable ping levels (as of BH 1.9.9)

The "Ping Tiers" setting allows the user to control which lines in the config will ping and be drawn on the map. There is a new keyword, TIER-x that supports this. For example:

image

image

Above we set the skull cap as a TIER-2 item. This means that "Ping Tiers" must be set to 2 or more in game in order for this item to ping. The TIER-x command impacts only the map-box and notification. It does not impact the item name. All items with an explicit name or a map condition are whitelisted regardless of the "Ping Tiers" setting in game. In this context "whitelist" means that the named- or mapped-item will always show in-game, even if the config had another line that tried to block the item.

For example, in the following situation, the skull cap would be displayed in game regardless of "Ping Tiers", but it will only notify and map when "Ping Tiers" is set to 2 or more.

ItemDisplay[!RW NMAG skp]: %NAME%%MAP%%TIER-2%
ItemDisplay[!RW NMAG skp]:

If no TIER level is specified, it defaults to TIER-0. This is essentially an unconditional map + notification.

Craft affix level condition and display (as of BH 1.9.9)

There is a new keyword CRAFTALVL that evaluates to the affix level of an item if it were to be crafted by the character you are playing. For example, the below displays the new affix level as part of the item description.

 // Magic Amulets [VERBOSE]
 ItemDisplay[MAG amu]: %NAME%{%WHITE%Caster: %ORANGE%Ral %PURPLE%O%WHITE%Perfect %BLUE%Jewel %WHITE%(%CRAFTALVL%)}

image

The keyword can also be used as part of the filter condition. For example:

 // Magic Amulets [VERBOSE]
 ItemDisplay[MAG amu CRAFTALVL>89]: %NAME%%MAP%

Rule order decides what is hidden

A hide rule is a rule with a blank action. Whether it hides an item depends on where it sits in BH.cfg relative to the rules that name or map the same item: the earlier rule wins. So a single catch-all near the top hides a whole category, and the rules further down that would have named it do not bring it back:

// near the top of BH.cfg
ItemDisplay[FILTLVL=3 RARE BELT]:

// ... hundreds of lines later
ItemDisplay[RARE]: %NAME%

Exceptions go above the hide rule rather than below it.

An exception has to be a rule that stops

Only a rule that settles what an item is called protects it from a hide rule. A rule ending in %CONTINUE% is saying it is not the final word - it decorates the item and passes it on - so it does not count as an exception, wherever it sits:

ItemDisplay[ETH]: %DARK_GREEN%Eth %NAME%%CONTINUE%   // decorates, does not protect
ItemDisplay[ETH RARE BELT]: %NAME%                   // protects

This is what makes broad hide rules usable at all. A config typically has a few %CONTINUE% rules matching enormous numbers of items purely to colour them, and if those counted as exceptions almost nothing could ever be hidden.

⚠️ A broad rule high in the file is destructive

A hide rule suppresses every naming rule below it that matches the same item. The failure mode is severe and silent - items simply stop existing as far as the game client is concerned, with no error and nothing in the log to tell you which line did it.

The extreme case is a bare catch-all:

ItemDisplay[]:

At the top of the file, that hides every item in the game, ignoring all of the hundreds of rules beneath it. Your entire config appears to have stopped working. The same line at the bottom of the file is the harmless idiom it has always been.

So:

  • A rule you wrote as a fallback will behave as a veto if it sits above the rules it was meant to fall back to. Move fallbacks to the bottom.
  • The shipped config places its hide rules at the bottom. If you are unsure about your own, re-read it top to bottom before trusting it.
  • The broader a hide rule's conditions, the higher the cost of putting it early. Prefer conditions that are as narrow as the intent (FILTLVL=3 RARE BELT rather than RARE or nothing at all).
  • Hidden items are filtered out at the packet level, so as far as your client is concerned they never dropped. There is nothing to reveal in game and no in-game way to tell a hidden drop from one that did not happen. If items seem to be missing, bisect your config.

Excluding items from the run tracker

The run tracker records the items that dropped during each run. Adding %NOTRACK% to a rule's action keeps matching items out of that record while leaving them displayed normally in game:

ItemDisplay[tsc]: %NAME%%NOTRACK%

This is useful for items you map or ping for convenience but don't want cluttering your drop history. Items that drop in town are never tracked.

Example Configuration

Here is a sample configuration file containing some basic rules that display certain items in purple. Ethereality, sockets, and item level are added to the item name. Inferior items are filtered out. Runes over lem are shown on the map.

//Item Display Configuration
ItemDisplay[tsc]: %GREEN%**%WHITE%TP
ItemDisplay[isc]: %GREEN%**%WHITE%ID
ItemDisplay[vps]: Stam
ItemDisplay[yps]: Anti
ItemDisplay[wms]: Thaw
ItemDisplay[gps]:
ItemDisplay[ops]:
ItemDisplay[gpm]:
ItemDisplay[opm]:
ItemDisplay[gpl]:
ItemDisplay[opl]:
ItemDisplay[hp1]: %RED%**%WHITE%Min Heal
ItemDisplay[hp2]: %RED%**%WHITE%Lt Heal
ItemDisplay[hp3]: %RED%**%WHITE%Heal
ItemDisplay[hp4]: %RED%**%WHITE%Gt Heal
ItemDisplay[hp5]: %RED%**%WHITE%Sup Heal
ItemDisplay[mp1]: %BLUE%**%WHITE%Min Mana
ItemDisplay[mp2]: %BLUE%**%WHITE%Lt Mana
ItemDisplay[mp3]: %BLUE%**%WHITE%Mana
ItemDisplay[mp4]: %BLUE%**%WHITE%Gt Mana
ItemDisplay[mp5]: %BLUE%**%WHITE%Sup Mana
ItemDisplay[rvs]: %PURPLE%**%WHITE%Rejuv
ItemDisplay[rvl]: %PURPLE%**%WHITE%Full
ItemDisplay[aqv]: Arrows
ItemDisplay[cqv]: Bolts
ItemDisplay[key]: Key
ItemDisplay[tes]: Andy*Duriel Essence
ItemDisplay[ceh]: Mephisto Essence
ItemDisplay[bet]: Diablo Essence
ItemDisplay[fed]: Baal Essence

// Ignore all inferior items
ItemDisplay[INF]:

// Runes and gems
ItemDisplay[RUNE<20]: %RUNENUM% - %RUNENAME%
ItemDisplay[RUNE>19]: %PURPLE%%RUNENUM% - %RUNENAME%%MAP%
ItemDisplay[GEM>3]: %PURPLE%%NAME%

// Add ethereality, sockets, ilvl to the name
ItemDisplay[ETH]: Eth %NAME%%CONTINUE%
ItemDisplay[SOCK>0]: %NAME% (%SOCKETS%)%CONTINUE%
ItemDisplay[]: %NAME% L%ILVL%%CONTINUE%

// Polearms
ItemDisplay[WP8 ETH ELT NMAG (SOCK=0 OR SOCK>3) !7o7]: %PURPLE%%NAME%

// Body armor
ItemDisplay[EQ2 ELT ETH NMAG !SUP SOCK=0]: %PURPLE%%NAME%
ItemDisplay[uui !ETH NMAG !SOCK=1 !SOCK=2 DEF>450]: %PURPLE%%NAME%
ItemDisplay[utp !ETH NMAG !SOCK=1 !SOCK=2 DEF>505]: %PURPLE%%NAME%
ItemDisplay[xtp !ETH NMAG !SOCK=1 !SOCK=2 DEF>254]: %PURPLE%%NAME%
ItemDisplay[xtp !ETH NMAG ED>13]: %PURPLE%%NAME%

// Paladin shields
ItemDisplay[CL3 ELT ETH NMAG RES>29 SOCK=0]: %PURPLE%%NAME%
ItemDisplay[CL3 ELT !ETH NMAG RES>39 !SOCK=1 !SOCK=2]: %PURPLE%%NAME%

// Barb helms with +3 BO
ItemDisplay[CL2 ((ILVL>25 SOCK=0) OR SOCK=3) NMAG SK149>2]: %PURPLE%%NAME%

// Druid pelts with +3 tornado
ItemDisplay[CL1 ((ILVL>25 SOCK=0) OR SOCK=3) NMAG SK245>2]: %PURPLE%%NAME%

// Wands with BS/BS capable of 2os
ItemDisplay[WP12 !wnd !9wn !ywn NMAG !SOCK=1 SK84>1 SK93>1]: %PURPLE%%NAME%

// Leaf/memory bases
ItemDisplay[WP11 NMAG (SOCK=0 OR SOCK=2) SK52>2]: %PURPLE%%NAME%
ItemDisplay[WP11 NMAG (SOCK=0 OR SOCK=4) SK58>2]: %PURPLE%%NAME%

// Grand matron bows
ItemDisplay[amc ((SOCK=0 !SUP) OR SOCK=4) NMAG CLSK0=3]: %PURPLE%%NAME%

// Monarch shields
ItemDisplay[uit (SOCK=0 OR SOCK=4) NMAG DEF>145]: %PURPLE%%NAME%

More Information

See the BH 1.9.9 Pre-Release Notes for detailed changes on this release.

Clone this wiki locally