[ezequielzacca]

Summary

Step 1 of 6 of #815 (data-driven item tooltips, phase 8 of the data-driven items design). This step only adds the format and draws it; the next steps move the original items' texts into the data, add named placeholders filled from the item and its stats, and finally build the whole tooltip from data.

Adds an optional description list to the item data (src/bin/Data/Items/Group*.json): lines the item tooltip shows after the item's stats. Today every item text is a case in the tooltip code (ZzzInventory.cpp); with this, a new item brings its text as data.

For example, the Jewel of Bless's line ("It is used to increase your item level up to 6", today a case in the tooltip code) would read in its item data:

"description": [
  {
    "text": {
      "en": "It is used to increase your item level up to 6",
      "de": "Wird verwendet, um das Gegenstandslevel auf bis zu 6 zu erhöhen",
      "es": "Se utiliza para aumentar el nivel de tu objeto hasta 6.",
      "pt": "É usado para aumentar o nível do seu item até 6"
    }
  }
]

• text is written like name: a plain English text or the texts by language; an empty text ({"text": ""}) is a blank line.
• color is one of the tooltip colors by name (blue, yellow, red, …); white when left out.
• A long line wraps at about the width of the original tooltips' widest lines (measured with the tooltip's font), and in a text breaks the line there; each piece keeps the line's color.
• Read and written by the item JSON (left out when empty), kept by the bmd import, documented in docs/item-data.md.
• The tooltip draws the lines in the UI's language.

No shipped item uses it yet, and the original items keep their texts in the tooltip code, so nothing changes in game.

Screenshots

The Jewel of Bless's tooltip in the client built from main and from this branch, in both UI themes.

main

Legacy theme	Modern theme

This branch, no item data changed: the same tooltip.

Legacy theme	Modern theme

This branch, with an example description (only in the screenshot's local item data, not in this PR): a blank line, a blue line that wraps to the tooltip's width, and a yellow line with a \n. The jewel's own line is still written by the tooltip code, after the description: the original items keep their texts in code for now, and moving them into the item data is step 2 of #815.

"description": [
  {"text": ""},
  {"text": "Drop it on an item in your inventory to raise the item's level by one, from +0 up to +6. The jewel is used up.", "color": "blue"},
  {"text": "A line break in the text\nstarts a new line", "color": "yellow"}
]

Legacy theme	Modern theme

Related issues

Step 1 of #815. Part of phase 8 (data-driven tooltips, D15) of the data-driven items design (#628).

Checklist

• I have read and followed docs/CODING_RULES.md.
• I have built the project locally (see docs/build/README.md). Windows x64 Release; all 977 tests pass, including the new An item's description is kept through write and read. Changed lines pass clang-format 21.1.8 as CI checks them.
• Changes are focused on one concern; the diff is as small as it reasonably can be.

[Mosch0512]

Verdict: changes requested for two items; the rest is non-blocking. The format is a good first step for #815. The description lines are LocalizedStrings like item names, as phase 8 of the items design asks; colors are names checked at load; and nothing changes in game. I also looked at the later steps (#816 to #836). They only add fields to ItemDescriptionLine, so data written for this step stays valid. The drawing code, though, is carried over almost unchanged to the end of the stack (WriteItemDescriptionLines in #836), so the two bugs below survive all 16 PRs unless they're fixed here.

Required

• A blank line inside a text ("a\n\nb", or a text that starts with \n) cuts off the rest of the tooltip (inline, ZzzInventory.cpp:3754).
• The 50-row check stops the description, but the rows after it are written without a check, so a long description writes past the end of TextList (inline, ZzzInventory.cpp:3752).

Non-blocking

• Description texts get none of the checks that item names get: English required, valid language codes, a warning for languages the game can't show (inline, ItemJsonFormat.cpp:409).
• The wrap measures the line again after every letter, every frame, through SDL_ttf's shared text cache (inline, ZzzInventory.cpp:3735).
• Rule 1 of the coding rules: the new block could be its own function (inline, ZzzInventory.cpp:3730).
• The wrap width is a tooltip value in the item data header (inline, ItemDefinition.h:96).
• The docs say the lines come "after its stats", but they come before durability, the requirements and the options (inline, item-data.md:84).
• No test covers turning a description into tooltip rows (inline, test_item_json.cpp:288).
• The color name table sits outside the file's anonymous namespace and is sized with a literal 14 (inline, ItemEnumNames.cpp:94).
• %.99ls (ZzzInventory.cpp:3754) hard-codes TextList's row width. "%.*ls" with std::size(TextList[0]) - 1 ties it to the array.
• The Dark Horse and the Dark Raven show no description outside shops. Their tooltip goes to giPetManager::RenderPetItemInfo and returns at ZzzInventory.cpp:1662, before the description is written. That line isn't in the diff, so there's no inline comment. Either draw the description there too, or mention the exception in the docs.
• The items design doesn't know about this yet. D15 and phase 8 plan the tooltips as JSON of their own, converted from the ItemTooltip* files. D22 keeps client-only display data out of the item files ("the item files keep what client and server share, and only those take part in the OpenMU exchange"). This PR puts client-only tooltip texts into the item files, as #815 plans. That split makes sense, especially with the shared texts and the layout in Data/Items/Tooltips/Tooltip.json later in the stack. But it should be written into D15, D22 and phase 8 in this PR, where the decision is made. Phase 7's exchange file then has to leave description out.
• The first commit's message still says a line longer than 99 characters gets a warning. The wrap commit removed that check.

Follow-up (the stack)

• All 16 PRs of #815 target main, so each diff holds every earlier step (#836 is +16,089/−12,674). On GitHub, a reviewer can't see one step's own change. Basing each PR on the previous step's branch would let each step be reviewed on its own.

What I checked: I read the diff, the code around it in RenderItemInfo, both tooltip renderers (RenderTipTextList and the RmlUi tooltip's BuildLines), WrapTextToWidth, the SDL_ttf measuring and the item data checks. I also read the items design, the roadmap and the later steps up to #836. I built WrapTextToWidth on its own with g++ and ran it on texts with blank lines. I didn't build the client or run the game. CI: no checks ran on this PR.

[Mosch0512]

Required. WrapTextToWidth returns an empty piece for a blank line inside a text. I ran it on a few texts:

• "Line one\n\nLine two" gives [Line one] [] [Line two]
• "\nLeading break" gives [] [Leading break]
• "One\n \nTwo" gives [One] [] [Two]

The empty piece is written here as L"". Both tooltip renderers treat an empty row as the end of the list: BuildLines (LegacyTextListTooltip.cpp:46) and RenderTipTextList (line 282). The height count at line 5156 stops there too. So everything after it is gone: the rest of the description, the jewel's own text, durability, requirements, options, the set and socket lines and the expiry date.

The docs say \n breaks the line, so \n\n is the natural way to leave a gap. No shipped text uses \n yet, also not in the later steps. So this shows up first with custom item data, or with the tooltip editor of step 6.

Writing L"\n" for an empty piece fixes it. The blank-line branch above then only has to produce one L"\n" piece, so both cases can share this loop.

[ezequielzacca]

Confirmed: WrapTextToWidth returns an empty piece for a blank line inside a text, and BuildLines, RenderTipTextList and the height count all stop at an empty row. Fixed in f62aa0c: a blank piece is written as the tooltip's own blank row ("\n"), the same way as a blank line, in one loop. Test: "A blank line inside a description text is a blank tooltip row, not the tooltip's end" ("a\n\nb", a leading "\n", a blank line). It fails on the old code (3 checks) and passes now.

[Mosch0512]

Required. This check stops the description at 50 rows, but the code after it adds rows without a check. Line 4730 writes L"\n" into TextList[TextNum] for every item. The jewel lines from line 3761, the options, RenderSetOptionListInItem, the socket lines and the expiry date follow. So when the description fills TextList, the next write goes to TextList[50], past the array into the globals next to it. ShowLegacyTextList then reads rows beyond 50 too.

A description that wraps to about 45 pieces is enough, for example in a server's own item files. Nothing limits its size at load: the first commit's ValidateDescription went away with the wrap commit.

A limit at load (an issue for a description with more than a set number of lines), or stopping here with room left for the rest of the tooltip, would fix it.

[ezequielzacca]

Confirmed: TextList is [50][100], and from line 4730 on nothing checks the bounds. Fixed in f62aa0c by giving the description rows of its own:

• TextList, TextListColor, TextBold and Size have MaxItemDescriptionRows (32) rows on top of the original 50 (MaxTextListRows).
• The description writes at most those 32, so it never takes the room the rest of the tooltip had before descriptions existed.
• Six files declared the arrays themselves with 50 rows. They use ZzzInventory.h's declarations now; MSVC's decorated names include the size, so a stale one fails to link rather than going unnoticed.

Later in the stack (#830) the description has a second part after the options; both parts share the 32 rows through a budget the caller holds. Test: "A description writes at most its own rows, leaving the tooltip's rows to the rest".

[Mosch0512]

Non-blocking. The docs say text "is written like name", but names get checks that description texts don't (items design, section 2 "Validation"; ValidateName and ValidateNameLocales):

• a missing English text is an error;
• a language code may only have letters, digits and -;
• a language the game has no UI texts for gets a warning.

Without these checks, {"text": {"de": "…"}}, or a typo like {"DE": "…"}, loads with no issue. In English the line then just disappears: Get returns the empty English text, WrapTextToWidth returns nothing, and not even a blank line is drawn. From step 2 on, many translated texts move into the data, so these checks pay off early. Missing description translations aren't counted anywhere either, unlike names in Item Translations, but that can come with the editor.

[ezequielzacca]

Agreed, done in f62aa0c. A description text gets the checks a name gets:

• the English text is required, except for a blank line;
• a language code has only letters, digits and -;
• a language the game has no texts in is a warning (with the names' check in ValidateNameLocales).

The same checks went into the later steps, where their texts appear: Tooltip.json's texts (#824), level values (#827) and name lines (#833). Every language in the shipped data is a UI language, so no new warnings. The missing-translation counts can come with the editor (step 6), as you say.

[Mosch0512]

Non-blocking. The tooltip is built every frame while an item is hovered. WrapTextToWidth calls this lambda after every letter, with the whole line so far. Each call goes through SdlTtfTextCache::Prepare: a linear search over up to 256 entries and, for a new string, TTF_CreateText with shaping. Every prefix is a new string, so a 150-letter description adds about 130 entries to a cache that all UI text shares. When that cache is full it is emptied completely, and every text on screen is created again.

Measuring only when a word ends would make this cheap. The language could also be picked at load, as SetDisplayLocale does for name; section 1 of the items design asks for "No hash maps or string lookups at runtime". Once placeholders come in step 3, the filled text depends on the item and the hero, so the wrap itself has to stay per tooltip. Cheap measuring is what matters.

This lambda is also the third copy of the same measure function, after MeasureInReferenceUnits (ChatCommandWindow.cpp:65) and the one in CustomMessageBox.cpp:47.

[ezequielzacca]

Confirmed: the line was measured after every letter, and each prefix was a new entry in the shared text cache. Fixed in 94af869:

• WrapTextToWidth measures a line once per word ending.
• It measures letter by letter only inside a word wider than a whole line.

I compared it with the old version on 200,000 random texts with characters of different widths:

• the lines are the same, except where the old version left a line wider than the limit (a word too wide for a line, after a break);
• the new one has about half the measure calls on that mix, and fewer on real text with longer words.

The language is still picked per line. With placeholders from step 3 on, the text is filled per tooltip anyway, as you note, so measuring was the costly part. The measure function stays separate from MeasureInReferenceUnits and the message box's: those measure in other units (reference units, the message box's font), the tooltip in its own font.

[Mosch0512]

Non-blocking. Rule 1 of docs/CODING_RULES.md: "When touching a large function, extract at least one logical block into its own function before you're done." RenderItemInfo is about 3,600 lines long, and this block is a natural WriteItemDescriptionLines(const ITEM&), which #821 extracts later anyway. Doing it here also makes building the rows testable (see the comment on the test).

[ezequielzacca]

Done in f62aa0c: the block is WriteItemDescriptionLines(definition, …, measure) in ZzzInventory.cpp, declared in ZzzInventory.h. It takes the item definition and the measure function, so the new tests check its rows directly. Later steps extend that function rather than the block (#830 merges its own extraction into it).

[Mosch0512]

Non-blocking. This is a tooltip layout value ("in the tooltip's text units") in the item data definition, and only ZzzInventory.cpp uses it. Rule 5 of docs/CODING_RULES.md keeps UI and data apart, so it fits better next to the tooltip code.

[ezequielzacca]

Moved in f62aa0c: ItemDescriptionWrapWidth is a constant of the tooltip code in ZzzInventory.cpp now, out of ItemDefinition.h.

[Mosch0512]

Non-blocking. "after its stats" is true for the jewels, but the block sits before durability, the requirements, the options and the set and socket lines. On a weapon, the description shows between the speed lines and durability. Saying where it goes avoids surprises, for example "after the damage, defense and speed lines, before durability and the requirements".

[ezequielzacca]

Fixed in 8b26e65: "after its damage, defense and speed lines and before its durability, requirements and options". The row also says the Dark Horse and Dark Raven show it only in shops, describes the checks and the 32-row limit, and that \n\n leaves a blank line.

[Mosch0512]

Non-blocking. This tests the file format well. Nothing tests how a description becomes tooltip rows: blank lines, \n, wrapping and the 50-row limit. A test of the extracted function, or of WrapTextToWidth with "a\n\nb", would have caught the blank-line bug.

[ezequielzacca]

Added tests/data/test_item_descriptions.cpp in f62aa0c. It's in test_item_database_files, which links Winmain.cpp, as the tooltip code needs. It tests:

• blank lines inside a text and at its start;
• wrapping to the width in the line's color;
• the row limit;
• the checks.

test_text_line_wrap gained cases for a blank line inside a text, measuring once per word, and a too-wide word after a break.

[Mosch0512]

Non-blocking. Every other name table is in the anonymous namespace above; this one is outside it and sized with a literal 14. A color added to ItemTextColor without a name gives no compile error. Such a color is then saved as a number, and reading the file refuses a number that has no name.

[ezequielzacca]

Fixed in f62aa0c:

• The table is in the anonymous namespace, sized by ItemTextColorCount (ItemTextColor::Count, as ItemRequirement does).
• A static_assert checks that every entry is set and in value order, so a color added without a name fails to compile.

[ezequielzacca]

Thanks for the thorough review. I checked each point against the code before changing anything, and they all held. The inline comments have the details; the rest:

• %.99ls: the row width comes from TextList now ("%.*ls" with std::size(TextList[0]) - 1), here and at the other rows the stack writes (layout lines in feat(items): the tooltip's stat lines come from a tooltip layout #824, the name rows in feat(items): the tooltip's item names come from the data (#815 step 5d-1) #833/feat(items): every item name comes from the item data (#815 step 5d-2) #834).
• Dark Horse and Dark Raven: documented rather than drawn. Their pet tooltip already writes their life line, which is what their description is later in the stack (the shared text @life), so drawing it there would show it twice.
• Items design: D15, D22, the field table, phase 7 and phase 8 now record the split: an item's own tooltip texts are client-only fields of its item file, and the exchange file leaves them out (8b26e65).
• The first commit's message still mentions the 99-character warning. Fixing it would mean rewriting the history of all 19 branches of the stack, so I left it; the later commits say what changed.
• Same kinds of problems later in the stack: fixed in the step that introduces them:
  • Tooltip.json's texts get the name checks, and a layout line never writes an empty row (feat(items): the tooltip's stat lines come from a tooltip layout #824);
  • level values get the checks (feat(items): the descriptions' repeated texts are written once #827);
  • both description parts share the row budget (feat(items): the item chain after the options comes from the data #830);
  • name lines get the checks, and an empty one keeps the standard name instead of leaving the tooltip's first row empty (feat(items): the tooltip's item names come from the data (#815 step 5d-1) #833).
• Current main: merged through the stack. feat(options): a Translate item names checkbox under the language #843's "Translate item names" makes the item database's display locale the item names' language. The stack read every tooltip text in that locale, so with the option off whole tooltips turned English. Now:
  • only names and name lines follow the option; descriptions, layout lines and level values follow the UI's language (c3da69c here, and the matching steps further up);
  • a test turns the option off with the UI in German and checks that the name is English and the stat lines German (feat(items): the tooltip's item names come from the data (#815 step 5d-1) #833);
  • in feat(items): every item name comes from the item data (#815 step 5d-2) #834, item names from the name lines no longer need a hero, since fix(helper): honor pickup modes and localized item names #840's pickup filters ask for names in tests without one;
  • fix(helper): honor pickup modes and localized item names #840's test of levels without a name of their own now checks the Box of Luck +4's data name, "Olive of love", instead.
• A flaky snapshot (test(items): every item's tooltip in a test, against recorded hashes #822 to fix(items): damage texts without a stray "of", and the Fruits' stat words #828): after the main merge, "Every item's tooltip is as recorded" failed in about half of its runs. The cause is the original client's code for the Weapon of Archangel (13/19), which exists at +0 to +2: at other levels, which the snapshot draws, the name row kept an earlier tooltip's text, and attack speed and the requirements were uninitialized locals. The snapshot had recorded stack contents. test(items): every item's tooltip in a test, against recorded hashes #822 now gives the item its own name and 0 there, and re-records its two entries; 20 of 20 runs pass (11 of 20 failed before). From feat(items): the second item chain's cases with values come from the data #829 on the item is data, so the problem ends there.
• Stacked PRs: GitHub only lets a PR from a fork target a branch of this repository, so each step can't be based on the previous step's branch. Instead, each PR's description now starts with a link to its own changes against the previous step.

Every branch builds, and its tests pass on Windows (MSVC), with no new clang-format issues on the changed lines.

[Mosch0512]

I pushed a small fix to this branch, b9a7430, so please pull before your next push.

WrapTextToWidth broke an indented line in front of a word too wide for the line, which left an empty line above the word. In the tooltip that's an extra blank half row, for example above the link in "Event info:\n https://forum.myserver.com/events/christmas-2026". Now the spaces go with the break, and blank lines written on purpose (\n\n) stay. A new case in test_text_line_wrap.cpp fails without the fix.

Every later step of the stack has the same TextLineWrap.cpp, so please carry it up the stack too.

[ezequielzacca]

Thanks! b9a7430 came into the whole stack with main (#817–#836 now merge main after #813 and #816 landed), so every step has the fixed TextLineWrap.cpp and the new line-wrap test.