feat(items): item effects from the model files (phase 4c3)

[Mosch0512]

Phase 4c3 of the data-driven items (design doc D24, see docs/superpowers/specs/2026-09-25-data-driven-items-design.md): what item models do before they are drawn comes from the item model files instead of the type chain of RenderPartObjectEffect. Builds on phase 4c2 (sven-n#658). With it, phase 4c (glow, render styles, effects) is complete.

It also adds the plan beyond items: a new roadmap document for effects, skills, monsters and NPCs, and how their data is shared and edited.

What changes

• New "itemEffect" value in src/bin/Data/Items/Models/*.json (42 models have one). An item effect is what an item does every frame before it is drawn; the effect types of the planned effect catalogue (FX1, effectTypes) are what it creates instances of, so the two keep different names:

  { "number": 37, "file": "Data/Item/wing09.bmd", "textureFolders": ["Item"], ..., "itemEffect": "wingOfEternal" }

• Item effects Render/Items/ItemEffects (namespace Render::Items::ItemEffects, so it does not hide Render::Effects, the effect registry): 28 of the 29 item branches of the chain (42 items) become 27 named effects, the code moved unchanged. The Siege Potion and the Contract share one. An effect runs before the model is drawn and:
  • places sprites, particles and lightning on bones (Devil's Key and Invitation, Rena, the Wings of Darkness, the third-tier wings);
  • changes values of the drawing: a pulsing glow mesh (wingsOfDragon, staffOfKundun, divineSet, …), a mesh hidden by level (hiddenMeshByLevel, hideMesh1), or the level potions glow like (potion);
  • or draws the model itself (the Dark Lord scrolls, fruits, spirit, bloodBone, invisibilityCloak, firecracker, gmGift, meshesPerLevel).
• The shine below +3 of 10 items (the light scaled, then two shine passes) becomes values of their render style, which the drawing code applies. The seals (light 0.9), the Illusion Sorcerer Covenant and the Cursed Castle water have a style already; the Jewel of Harmony and the Moonstone Pendant get harmonyShine, which only shines (138 styles now).
• Socket seeds and spheres (the 39 items of the last branch) and zen need no effect: they get "glow": {"level": 0}, which is what their level checks did. The checks go.
• Stays in code: the effects of the event models of level variants (no model entries yet), in ApplyEventModelEffect in ZzzObject.cpp.
• Check: an item effect that does not exist is a warning when the models are opened, like an unknown render style. The model loader gets the checks of both look names from ZzzOpenData (LookNames), so the data layer does not call the drawing code. A test checks that the item effects of the shipped models exist.
• ItemModelTable (ItemModelTable.h): one value per item type, taken from the item model database after each build of it. The render styles and the effects both use it (the table code of 4c2 moves there).
• Effect step: ApplyPartObjectEffect runs the effect of the item's model entry, or for the event models theirs; RenderPartObjectEffect returns when it drew the model.
• MuEditor: a read-only "Looks" section above the item table. For the selected item it shows the model file, glow, render style and effect; each look lists the items that share it (in a box of fixed height), and clicking one selects it and scrolls the table to it, clearing the search when it hides the item. It only reads the model data, rebuilt when the selection, the model data or the items change (the item database counts its changes now). The labels are in Editor.en.resx only; other languages fall back to English, as for the bmd import and export.
• Removed: about 560 lines of the chain in ZzzObject.cpp, and the zen and seal/jewel checks of the plain drawing below +3.

Nothing changes while playing.

Plan beyond items (docs)

• New docs/superpowers/specs/2026-09-29-data-driven-content-roadmap-design.md:
  • D25 Looks in data: items (and later skills, monsters and NPCs) name their looks. What a named look is made of moves into data later, as building blocks.
  • D26 Shared definitions: defined once with a name and referenced by it. Editors show where a definition is used, warn with that list before a shared definition changes, and make copies for variants.
  • Bones: effects place things on bones, and looks store bones as numbers. Of the 778 item model files, 340 have readable biped names; the rest have export names like Bone01 or zx12, and in 396 files the bone called "BoneNN" is not bone NN.
  • The areas in order, each with its own design document when it starts: FX1 effect catalogue, item phase 13 (looks in data), SK1 skills, SK2 skill looks, MN monsters and NPCs, FX2 effect behavior as data, later map objects, buffs, pets and sounds.
  • Shared editor parts: the look editor with bone picking, the effect browser and the effect editor.
• Items design: new phase 13 "Looks in data" (depends on FX1); the cleanup is now phase 14; phase 6 and section 9 describe the look editor; 4c3 is described with its numbers.
• docs/item-data.md: explains itemEffect, the shine below +3 of the render styles, the glow level 0 of seeds, spheres and zen, the warning, and the Looks section of the item editor.

Verification

A temporary recorder (not part of this PR) marked every branch of the old chain and every drawing path after it (the plain drawing and the shine below +3, the level glow). It ran RenderPartObjectEffect for every model slot:

• on an item object (set up with ItemObjectAttribute, like the game's) and on a player object;
• at the levels 0, 3, 7, 9, 13, 14 and 15.

It recorded the branch of the chain, the level after it and the drawing path that follows, and did the same for the new code (the effects mapped to their first branch).

All 141,231 other records are the same. The only differences:

• 79 item slots on a player object: the new code does what it does on the item object, where the old checks looked at the object's item (o->Type). None of these items is drawn as a part of a character: weapons and wings are link objects with their own object, and potions, seeds, seals and scrolls are never on a character. The same holds for the look calls: the effect code, the inventory and the ground items draw with o->Type equal to the model.
• Zen: it reaches the drawing with level 0 from its glow level, where the old code kept its level and drew it plainly by its type. It is the plain drawing at every level either way.

The recording was made before the review moved the shine below +3 into the render styles. That move is checked by a test instead: each of the 10 items has the light factor and the two shine passes of its old branch, and the drawing code applies them in the old order (the light, the model, the passes).

Tests

• test_item_model_json.cpp: write/read of itemEffect (after renderStyle), errors for values that are not a name.
• test_item_model_problems.cpp: the warning for an item effect that does not exist.
• test_item_model_files.cpp:
  • the effects of the shipped models exist;
  • spot checks of the shipped effects (wings, Devil's items, potions, shared effects);
  • the shine below +3 of the 10 items, with the values of the old code, and none for other items;
  • the glow level 0 of seeds, spheres and zen;
  • ItemEffects::Apply changes the level of potions and the hidden mesh by level, returns "drawn" for effects that draw the model and "none" for other items and models;
  • ApplyPartObjectEffect: the item's effect first, the event model only when the item has none;
  • the effects follow a new build of the database.
• All 382 tests pass locally (Windows, Release, editor build). clang-format 21.1.8 and cppcheck 2.13 are clean; the changed files also compile with gcc (Linux, editor off).

Test plan

• Recording of old and new code compared
• The game builds and the data loads in the tests (889 models)
• In game: third-tier wings, Wings of Darkness, Devil's Key and Invitation, potions, the Dark Lord scrolls, seals and Jewel of Harmony below +3
• In MuEditor: the Looks section of the item editor

[Mosch0512]

Verdict: changes requested. (Posted as a comment: GitHub does not allow requesting changes on your own PR.)

Moving the chain itself looks right. I checked the effect of every model against the removed branches (all 52 match), each effect's Applied/Drawn against the old returns, and the glow level 0 of seeds, spheres and zen against the old level checks. Link objects, the inventory and ground items draw with o->Type == Type, so looking the effect up by Type instead of o->Type changes nothing in game.

Required:

1. Looks list: a click often does not select or show the item (search filter, scroll position).
2. An open Looks list squeezes the item table.
3. ApplyBloodBone: b instead of Models[o->Type].
4. ItemRenderStyles.cpp still includes <span> and <vector> (CODING_RULES rule 7).
5. ItemModelTable in its own file (rule 6).
6. The Looks section in the usage docs, "Editing items (MuEditor)" in docs/item-data.md (rule 11).

The other inline comments are non-blocking.

[Mosch0512]

Required. A click here often does not select or show the item:

• ItemEditorTable.cpp only handles the request when the item is in m_filteredItems. With a search active (search "seal", select Seal of Ascension, click Master Seal of Wealth under sealShine) or for an item without a name, the request is dropped and nothing happens.
• When the row is found, SetScrollY(GetTextLineHeightWithSpacing() * (row + 1)) assumes rows one text line high, but the rows are InputInt fields with frame and cell padding, about 4px taller each. For items of groups 12 to 14 (rows in the thousands) the table stops hundreds of rows short, so the selected row is off screen.

The description says clicking selects the item in the table. Suggestion: always set the selection (and say so, or clear the search, when the search hides the item), and scroll with clipper.IncludeItemByIndex(row) before Step() plus ImGui::SetScrollHereY() when that row is drawn.

[Mosch0512]

Required. The Looks section sits above the item table in the same window. The table scrolls (ScrollY) with an outer height of 0, which Dear ImGui aligns to the bottom of the window, so it only gets the height that is left. Opening a long list (the socketSeedSphere style is used by 30 items) shrinks the table down to 1px until the list is closed. Suggestion: draw the lists in a child or list box with a fixed height, or give the table a minimum height.

[Mosch0512]

Required. Models[o->Type] is how the old chain named the drawn model; the effect is now picked by Type, and b is &Models[Type]. When o->Type != Type (like the player object in your recorder), this sets and resets StreamMesh of another model, and the Blood Bone draws its bright pass without the stream mesh. b->StreamMesh, as in ApplyBillOfBalrog, fixes it.

[Mosch0512]

Required. With the table moved to ItemModelTable, this file no longer uses std::span or std::vector, but still includes <span> and <vector> (lines 12 and 14). CODING_RULES rule 7: "Keep includes minimal — only what the file actually uses."

[Mosch0512]

Required. CODING_RULES rule 6: "Each new class or significant struct/type gets its own file, named after the class." ItemModelTable is a class that two systems use (render styles and effects), so it would go into ItemModelTable.h; ItemModelLookup.h keeps the lookup functions.

[Mosch0512]

Non-blocking. RenderHarmonyShine and RenderSealShine only differ in the light factor (1 and 0.9), and ApplyDevilsKey and ApplyDevilsInvitation only in the bones (1, 2 and 9, 10). One function each, taking the factor or the bones, would do. It is moved code, so this can also wait for phase 13.

[Mosch0512]

Non-blocking. The empty if (Level == 1) {} comes from the old code; a switch with cases 2 and 3 says the same without it.

[Mosch0512]

Non-blocking. "+7 with any level": ApplyPotion only changes levels above 0, a +0 potion stays at 0 (your test checks that too). Maybe "+7 at every level above 0".

[Mosch0512]

Non-blocking. I count 81 items: 42 with an effect that runs before the drawing (52 models with an effect minus the 10 shines) and 39 socket seeds and spheres (12/60–65, 70–72, 100–129). The PR description says 80 too.

[Mosch0512]

Non-blocking. The tests call Effects::Apply directly; how RenderPartObjectEffect puts the pieces together is not tested (event models only when the item has no effect, the return after Drawn, the shine only below +3). If it is cheap, a small test of that order would keep it from breaking unnoticed.

[Mosch0512]

Verdict: ready to merge. (Posted as a comment: GitHub does not allow approving your own PR.)

Re-review of 121e0c4 and 2e118d8. All six required items of the first review are fixed:

1. Looks list: a click always selects the item and clears the search when it hides it; the table scrolls with clipper.IncludeItemByIndex and SetScrollHereY.
2. The lists are list boxes of at most 8 rows, and the table keeps a minimum height.
3. ApplyBloodBone uses b->StreamMesh.
4. ItemRenderStyles.cpp no longer includes <span> and <vector>.
5. ItemModelTable has its own ItemModelTable.h.
6. The Looks section is described under "Editing items (MuEditor)".

The non-blocking ones are fixed too: LookNames defaults to NoLookExists; the shine below +3 is now values of the render style (checked against the old code for all 10 items), so ItemEffects no longer calls back into ZzzObject.cpp; the rename to itemEffect / Render::Items::ItemEffects; the Looks cache; the switch in meshesPerLevel; both doc fixes (81 items, "+7 at every level above 0"); and the test of ApplyPartObjectEffect. Only ApplyDevilsKey / ApplyDevilsInvitation are still two copies, which is fine until phase 13.

Two new notes inline, both non-blocking.

[Mosch0512]

Non-blocking. The cache only follows the model database, but the names in the lists (GetLogName, the neutral name) come from g_ItemDatabase, which the editor changes without rebuilding the model database. After renaming an item, moving one with the Index column (OnItemsSwapped) or Import from bmd, an open list keeps the old names until another item is selected; after a move, clicking an entry selects whatever now has that item type. Resetting the cache on those edits (or also keying it on a change counter of the item database) would keep it current.

[Mosch0512]

Non-blocking. This constructor keeps the address of a const& parameter, while the textured one below takes a pointer. RenderStyles[] is const, not constexpr, so a later entry written as {"newShine", RenderPlainly, ShineBelowPlus3{...}} compiles and leaves shine pointing at a temporary that is gone after the initializer. Taking const ShineBelowPlus3* in both constructors, as the textured one does, makes the need for a named constant visible and keeps the two the same.