Skip to content

feat(editor): Item Options, the item's option links and the option preview - #179

Open
Mosch0512 wants to merge 31 commits into
mainfrom
feat/item-options-9a5
Open

Mosch0512 wants to merge 31 commits into
mainfrom
feat/item-options-9a5

Conversation

@Mosch0512

@Mosch0512 Mosch0512 commented Nov 16, 2026 •

Copy link
Copy Markdown
Owner

The fifth pull request of the item options design (docs/superpowers/specs/2026-11-04-item-options-design.md, 9a5, after 9a4 sven-n#1136): the editor gets a window for the option files (O18), Item Basics edits an item's option links, Item Tooltip previews the options as a server sends them, and the control API's tooltip takes the two fields it lacked. It goes on from 9a4's head, which sven-n#1136 merged into main; it changes nothing the game reads or shows.

What changes

  • Item Options (new item tool, Windows > Items), in three tabs:
    • Definitions: the definitions of Options/*.json with a search, a type filter, how many items link each and the highest level its value lists give. The picked definition's display names, server values and options (number, attribute, how it adds, a constant or one value per level, per terms, texts) are changed on a copy. New and Copy add a definition on the copy; Rename renames it in the rules and every item that links it; Remove works while no item and no rule links it (D26).
    • Highest level per list (new decision O36): the "general max option" setting, done per list. Marked definitions' value lists all end at one level with Fill levels of … marked, each going on by its own step (the difference of its last two values) or cut: the five damage and defense lists to 7 give [4, … 28] (+28 instead of +16 for an item whose option level is 7), the shields' [5, … 35], and the jewelry lists ([1, 2, 3] %, Season 6 jewelry has levels 1 to 3, the rest 1 to 4) change only when they are marked too. A single number for all lists would have given the rings +7 % or needed exceptions. Nothing changes in the game: a level above a list's end already shows the list's last value.
    • Rules: OptionRules.json in order, each rule with its definitions, its conditions and how many items take their list from it; New rule, Move up / down, Remove the rule, and the picked rule's definitions and conditions, with the item numbers and the excluded tags only the option rules have.
    • Texts: Tooltips/OptionTexts.json in the names grid.
    • Apply to the options checks the files as Save writes them (each written and read back; a fatal problem refuses the change, others are listed) and lists the items the change reaches before it applies it as one undo step: the items that link a changed definition, and the items that follow the rules and take another list. Save Items writes the definition files, OptionRules.json and OptionTexts.json.
  • Item Basics: a section Options with the item's links (type and English name, a click opens the definition in Item Options, x removes the link), a list to link another, and, when the list is not what the rules give, what they give and Use the rules.
  • Item Tooltip: the preview's Option checkbox (always level 1) becomes the option level 0 to 15 and, for a definition numbered by it (wings), the option type 0 to 3; Excellent (all six) becomes one checkbox per option of the item's excellent definition; a set gets its ancient bonus level 0 to 2.
  • Control API: tooltip takes option_type (with option) and ancient_bonus (with ancient), 0 to 15.
  • Data Checks: the option files' area opens Item Options; its name is now the window's, "Item Options".
  • Item Formulas' condition lists move to ItemRuleConditionWidgets (shared with the Rules tab), unchanged for the profile rules.
  • docs/item-data.md describes the window, the links and the preview; the design gets O36 and its section 11 the 0 to 15 option level.

Commits

  1. the item edits change, undo and save the option files (ItemOptionFiles, ValidateItemOptionFilesAsWritten, CItemDataHandler::SetOptions, the undo history's Options step)
  2. the rule condition fields are shared (refactor)
  3. Item Options
  4. Item Basics' option links
  5. Item Tooltip's option controls
  6. the control API fields
    7-21. review fixes, one commit each: Remove stops drawing the removed definition; the preview leaves out settings the item shows no control for, offers the six excellent bits on wings and takes option types up to the definition's highest number; the items' attackType picks of the ancient bonus definitions count as uses (no rename, the as-written check warns); the searches use the editor's text search; Save remembers the files it wrote; the text rows keep their ids; the link picker leaves out links that do nothing; rules and texts get the * mark; shared tool widgets, one file-grouping helper, a new definition's file from the data, cached per-frame work, the Rules tab split
    22-31. second review's fixes, one commit each: Apply waits for Revert when an undo or redo changed the option files under unapplied changes; the Texts tab shows whole names and their mark; an attackType pick needs type ancientBonus, as in the game; the six excellent bits only on wings and horns; a new ancient definition goes in Ancient.json; the link picker's note wraps; ExcellentByteMeansOther shared; the Tooltip's option controls in ItemPreviewOptions with tests, worked out once; the selected rule by item type

Checked

  • New tests: Save Items writes the option files only when changed, writes a file whose last definition went, and stops on a change only the reader refuses ("Options/Ancient.json"); the shipped files pass the as-written checks and a rule naming no definition fails them; a rename of a linked definition is undone and redone with the item's link; the undo step for the option files and its refusal when they changed past it; who links a definition, which items a change reaches (values, texts, not the display name, a rename), the item lists a rules change moves (a picked list stays), Fill levels (by the last step, a cut, a one-entry list, a constant) and a list written from a start level; the control API's two fields and their refusals; the Data Checks area opens Item Options.
  • Windows x64 Release (editor build), on 9a4's head dd1d363: every target builds without warnings. The full ctest run fails only the per-map file list test (on OptionRules.json, as on main, see feat(items): the ancient bonus in data sven-n/MuMain#1136) and the entries of one new test whose name had a ;, which splits a ctest name; after the rename, the 23 entries those touch pass, test_item_database (288 cases) and test_item_database_files (437) among them.
  • Linux (Ubuntu 24.04, GCC 13, editor build): each of the 6 commits builds, and test_item_database_files, test_item_database and rml_styling_regression_tests pass at each.
  • clang-format 21.1.8 on the changed lines passes. cppcheck 2.13 on the 40 changed files passes (CI runs 2.19).
  • Tried in the editor by hand before the review fixes.
  • Review fixes (on 6521bb8): Windows x64 Release builds every target without warnings; the full ctest fails only the per-map file list test (as on main) and bundled_font_assets, which timed out under the full run's load and passes alone. Linux and cppcheck for these commits come from this PR's CI.
  • Second review's fixes (on 2fc2a64): Windows x64 Release builds every target without warnings; the full ctest (4147) fails only the per-map file list test, as on main.

Item Options (9a5) changes the option definitions, rules and texts; this is
what it stands on:

- ItemOptionFiles: what the option files hold, comparable, and
  ItemOptionDatabase::GetFiles / a constructor from them.
- ValidateItemOptionFilesAsWritten: each file written and read back, so a
  problem only the reader finds stops a change too, then the checks across
  them.
- CItemDataHandler::SetOptions: the item database takes the files and the
  items' links resolve again; Save checks them as written and writes every
  definition file (also one whose last definition went), OptionRules.json
  and OptionTexts.json.
- The undo history's Options step and ItemEdits::SetOptions, with the items
  whose links the change renames as Slot steps of the same entry.
Item Formulas' condition lists and their description move to
ItemRuleConditionWidgets, so Item Options' Rules tab uses them too. They
gain the two conditions only the option rules have (shown only for them):
the item numbers ("0, 1, 41-49") and the tags an item must not have. Item
Formulas shows and edits the same as before.
A new item tool (design O18), in three tabs:

- Definitions: the list with a search, a type filter, how many items link
  each and the highest level its value lists give. The picked definition's
  display names, server values and options (number, attribute, how it adds,
  a constant or one value per level, terms, texts) are edited on a copy.
  New and Copy add one on the copy; Rename renames it in the rules and in
  every item that links it; Remove works while nothing links it (D26).
- Highest level per list (design O36, the "general max option" asked for):
  marked definitions' lists all end at one level with Fill levels, each by
  its own step, so the damage and defense lists go to +28 at once while the
  jewelry lists ([1, 2, 3] %) stay unless marked. Nothing changes in the
  game: a level above a list's end already shows its last value.
- Rules: the option rules with their conditions (also item numbers and
  excluded tags) and how many items take their list from each.
- Texts: OptionTexts.json in the names grid.

Apply to the options checks the files as Save writes them and lists the
items the change reaches before it applies it as one undo step: those that
link a changed definition and those that follow the rules and take another
list. The option files' Data Checks area opens the window. The texts are in
English and German; the Data Checks area's "Item options" is now the
window's name "Item Options".
A section Options under the prices: each definition the item links with its
type and English name (a click opens it in Item Options, x takes the link
out), a list to link another, and, when the list is not the one the option
rules give, what they give and Use the rules. A change is one undo step and
keeps the list in the order the game takes it in; a list that differs from
the rules stays so (FollowItemOptions), as before.
…option and the ancient bonus

The preview's Option checkbox (always level 1) becomes the additional
option's level 0 to 15 (off while the item links no option definition) and,
for a definition numbered by it (wings), its type 0 to 3. Excellent (all
six) becomes one checkbox per option of the item's excellent definition. A
set gets its ancient bonus level 0 to 2.
`option_type` (the option byte's high four bits, which wings number their
additional options by) needs `option`, `ancient_bonus` (the ancient byte's
bonus level) needs `ancient`; both are 0 to 15, as the bytes hold them, and
a bad_request without the field they need.
Remove applies the change at once when no item is reached, and Apply takes the copy again, so the rest of the frame drew a definition the copy no longer held.
…e item shows no control for

A type set on wings or an excellent bit set on another item stayed in the preview of the next item, whose option line then did not show.
…ithout an excellent definition

Wings link no excellent definition, but their own code reads the excellent byte; the old tool's Excellent checkbox set all six bits for them.
…e item's definition gives

The type stopped at 3, while a definition may number its options up to 15 (the control API takes that too), so higher numbers could not be previewed. The docs name both this and the excellent bits without a definition.
…ancient bonus definition

The items pick the four ancient bonus definitions by name, without links, so Item Options showed them unused and let them be removed or renamed, and neither Apply nor Save warned. The picks now count as uses and are reached by a change, those names cannot be renamed, and the as-written check reports a missing one.
Both searches passed each byte to std::tolower as a char, which is undefined for the bytes of a non-ASCII letter (the Debug runtime asserts on them).
The definition files were listed only when the data was read, so a file a save had added was not written again once its last definition went, and the definition came back at the next start.
The ids were the texts' places in name order, so a new text moved the ones after it: an edit in progress or a typed translation could land on another text.
It offered a second definition of a type the item links (only the first counts), the ancient types (the item sets give them) and excellent options on wings and horns. They are left out, with a note in the list.
…applied

The docs said a definition, rule or text with changes not applied is marked with *, but only the definitions were.
…list and colors

Item Formulas, Item Options and the option links of Item Basics each had their own copy; they live in ItemToolWidgets now. Item Options takes the add keys from the option reader and the definition lookup from ItemOptionFileChange.
…ir definitions

Load, Save, the as-written check and the writer each listed the files of the definitions and picked each file's definitions with their own loop.
… definitions of its type

The file names of the shipped definitions were written in the code; a new definition now goes in the file most definitions of its type are in, else in one named after the type.
… when the data changes

The unapplied-changes check compared all the option files several times a frame, the Used by list scanned the items every frame and the Rules tab matched every item against the rules every frame. The check runs once a frame, the list and the matches are kept until the item data, the picked definition or the rules change.
…r part

RenderRulesTab drew the table, the buttons and the picked rule in about 140 lines; the rule list, a row, the buttons and the picked rule have their own functions now.
…ged under

After an undo or redo of the option files, a copy with changes not applied still held the files from before it, so Apply wrote the undone change back (or undid the redone one). Apply now waits for Revert, with a note, and a change waiting for its confirmation is dropped when the files changed meanwhile.
…es and their mark

The names grid had room for 15 bytes of an id, so 16 of the 28 option text names were cut (increaseWizardryLevel20 and increaseWizardryPercent both read increaseWizardr) and the * after a changed one never showed. The grid has room for 63 bytes, the rows give their id column's width, and the mark goes first.
…tion of type ancientBonus

The game picks an item's ancient bonus by name and type (ItemOptionDatabase::FindAncientBonus), but Item Options matched the name only: a definition with one of the four names but another type got the attackType items as users, could not be removed or renamed, and every change of it listed those items.
…eans something else

The wings-or-horn test was written in the option checks and again in Item Basics' link picker; ExcellentByteMeansOther holds it for both.
…emPreviewOptions, with tests

Which controls an item shows and which option bytes the preview gives it were in Item Tooltip's anonymous namespace without a test. They are in ItemPreviewOptions now, and tests cover a Kris, an excellent definition with some numbers and wings.
… and horns

Every item without an excellent definition got them, potions and jewels too, and hovering one showed an empty tooltip. Only the items whose own code reads the excellent byte get them now, and a bit without an attribute shows no tooltip.
The controls (which resolve the item's links) were found twice a frame for the same item, for the controls and for the preview item. They are kept until another item is previewed or the item data changes.
…r ancient ones

The two ancient types share Ancient.json, but a new set option definition found no definition of its own type and went into a new AncientOption.json. The ancient types count as one now, and their fallback file is Ancient.json.
…width

The note about the links left out was one line of about 170 characters (more in German), which made the list wider than 1000 pixels.
…ule by its item type

The slots are in item type order, so the selection's type is the slot; the pointer difference to the slots' start is not needed.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant