Merge pull request 'fix(ui): keep deck popups above monster hp' (#33) from fix/deck-popup-layering into main

Reviewed-on: #33

RootDesk/MyDesk/SlayDeckController.codeblock

@@ -747,7 +747,7 @@
               "Name": "kind"
             }
           ],
-          "Code": "self.DeckInspectKind = kind\nif self.DeckAllOpen == true then\n\tself.DeckAllOpen = false\n\tlocal allHud = _EntityService:GetEntityByPath(\"/ui/DefaultGroup/DeckAllHud\")\n\tif allHud ~= nil then\n\t\tallHud.Enable = false\n\tend\nend\nfor i = 1, 4 do\n\tlocal monsterSlot = _EntityService:GetEntityByPath(\"/ui/DefaultGroup/CombatHud/MonsterSlot\" .. tostring(i))\n\tif monsterSlot ~= nil then\n\t\tmonsterSlot.Enable = false\n\tend\nend\nlocal pile = {}\nlocal title = \"\"\nif kind == \"discard\" then\n\tpile = self.DiscardPile or {}\n\ttitle = \"버린 덱\"\nelse\n\tpile = self.DrawPile or {}\n\ttitle = \"뽑을 덱\"\nend\nself:RenderDeckInspect(pile, title)\nlocal hud = _EntityService:GetEntityByPath(\"/ui/DefaultGroup/DeckInspectHud\")\nif hud ~= nil then\n\thud.Enable = true\nend",
+          "Code": "self.DeckInspectKind = kind\nif self.DeckAllOpen == true then\n\tself.DeckAllOpen = false\n\tlocal allHud = _EntityService:GetEntityByPath(\"/ui/DefaultGroup/DeckAllHud\")\n\tif allHud ~= nil then\n\t\tallHud.Enable = false\n\tend\nend\nlocal pile = {}\nlocal title = \"\"\nif kind == \"discard\" then\n\tpile = self.DiscardPile or {}\n\ttitle = \"버린 덱\"\nelse\n\tpile = self.DrawPile or {}\n\ttitle = \"뽑을 덱\"\nend\nself:RenderDeckInspect(pile, title)\nlocal hud = _EntityService:GetEntityByPath(\"/ui/DefaultGroup/DeckInspectHud\")\nif hud ~= nil then\n\thud.Enable = true\nend",
           "Scope": 2,
           "ExecSpace": 6,
           "Attributes": [],
@@ -762,7 +762,7 @@
             "Name": null
           },
           "Arguments": [],
-          "Code": "self.DeckInspectKind = \"\"\nlocal hud = _EntityService:GetEntityByPath(\"/ui/DefaultGroup/DeckInspectHud\")\nif hud ~= nil then\n\thud.Enable = false\nend\nfor i = 1, 4 do\n\tlocal monsterSlot = _EntityService:GetEntityByPath(\"/ui/DefaultGroup/CombatHud/MonsterSlot\" .. tostring(i))\n\tif monsterSlot ~= nil then\n\t\tmonsterSlot.Enable = true\n\tend\nend",
+          "Code": "self.DeckInspectKind = \"\"\nlocal hud = _EntityService:GetEntityByPath(\"/ui/DefaultGroup/DeckInspectHud\")\nif hud ~= nil then\n\thud.Enable = false\nend",
           "Scope": 2,
           "ExecSpace": 6,
           "Attributes": [],
@@ -837,7 +837,7 @@
             "Name": null
           },
           "Arguments": [],
-          "Code": "local inspectHud = _EntityService:GetEntityByPath(\"/ui/DefaultGroup/DeckInspectHud\")\nif inspectHud ~= nil then\n\tinspectHud.Enable = false\nend\nself.DeckInspectKind = \"\"\nself.DeckAllOpen = true\nfor i = 1, 4 do\n\tlocal monsterSlot = _EntityService:GetEntityByPath(\"/ui/DefaultGroup/CombatHud/MonsterSlot\" .. tostring(i))\n\tif monsterSlot ~= nil then\n\t\tmonsterSlot.Enable = false\n\tend\nend\nself:RenderAllDeck()\nlocal hud = _EntityService:GetEntityByPath(\"/ui/DefaultGroup/DeckAllHud\")\nif hud ~= nil then\n\thud.Enable = true\nend",
+          "Code": "local inspectHud = _EntityService:GetEntityByPath(\"/ui/DefaultGroup/DeckInspectHud\")\nif inspectHud ~= nil then\n\tinspectHud.Enable = false\nend\nself.DeckInspectKind = \"\"\nself.DeckAllOpen = true\nself:RenderAllDeck()\nlocal hud = _EntityService:GetEntityByPath(\"/ui/DefaultGroup/DeckAllHud\")\nif hud ~= nil then\n\thud.Enable = true\nend",
           "Scope": 2,
           "ExecSpace": 6,
           "Attributes": [],
@@ -852,7 +852,7 @@
             "Name": null
           },
           "Arguments": [],
-          "Code": "self.DeckAllOpen = false\nlocal hud = _EntityService:GetEntityByPath(\"/ui/DefaultGroup/DeckAllHud\")\nif hud ~= nil then\n\thud.Enable = false\nend\nfor i = 1, 4 do\n\tlocal monsterSlot = _EntityService:GetEntityByPath(\"/ui/DefaultGroup/CombatHud/MonsterSlot\" .. tostring(i))\n\tif monsterSlot ~= nil then\n\t\tmonsterSlot.Enable = true\n\tend\nend",
+          "Code": "self.DeckAllOpen = false\nlocal hud = _EntityService:GetEntityByPath(\"/ui/DefaultGroup/DeckAllHud\")\nif hud ~= nil then\n\thud.Enable = false\nend",
           "Scope": 2,
           "ExecSpace": 6,
           "Attributes": [],

docs/ui-generation-structure.md

@@ -0,0 +1,54 @@
+# UI Generation Structure
+
+## Current Rule
+
+Do not hand-edit `ui/DefaultGroup.ui` for SlayDeck UI changes. It is generated
+by `tools/deck/gen-slaydeck.mjs`.
+
+The `.ui` file is expected to stay large because MapleStory Worlds stores UI as
+one JSON entity list. The maintainable source is the generator, not the output.
+
+## Generated Sections
+
+`tools/deck/gen-slaydeck.mjs` centralizes generated UI roots in
+`GENERATED_UI_SECTIONS`:
+
+- `DeckHud`
+- `DeckInspectHud`
+- `DeckAllHud`
+- `CombatHud`
+- `RewardHud`
+- `MapHud`
+- `ShopHud`
+- `RestHud`
+- `MainMenu`
+- `CharacterSelectHud`
+
+When the generator runs, existing entities under those roots are removed and
+emitted again. Stock mobile controls are handled separately by
+`DISABLED_STOCK_CONTROLS`.
+
+## How To Change UI
+
+1. Edit the relevant section in `tools/deck/gen-slaydeck.mjs`.
+2. Add new top-level HUD roots to `GENERATED_UI_SECTIONS`.
+3. Emit section entities with `emit('SectionName', entities)`.
+4. Run `node tools/deck/gen-slaydeck.mjs`.
+5. Verify JSON parsing for generated files.
+
+`emit()` validates that a section only emits paths under its own root. This
+keeps accidental cross-section UI changes from silently landing in
+`DefaultGroup.ui`.
+
+## Next Refactor Target
+
+The next useful split is to move each large section builder into separate files,
+for example:
+
+- `tools/deck/ui/combat-hud.mjs`
+- `tools/deck/ui/shop-hud.mjs`
+- `tools/deck/ui/map-hud.mjs`
+- `tools/deck/ui/menu-hud.mjs`
+
+Keep shared helpers like `entity`, `transform`, `sprite`, `button`, and `text`
+in one shared UI helper module.

tools/deck/gen-slaydeck.mjs

@@ -75,6 +75,32 @@ function luaDeckTable(deck) {
 
 const UI_FILE = 'ui/DefaultGroup.ui';
 const COMMON_FILE = 'Global/common.gamelogic';
+const UI_ROOT = '/ui/DefaultGroup';
+const GENERATED_UI_SECTIONS = [
+  'DeckHud',
+  'DeckInspectHud',
+  'DeckAllHud',
+  'CombatHud',
+  'RewardHud',
+  'MapHud',
+  'ShopHud',
+  'RestHud',
+  'MainMenu',
+  'CharacterSelectHud',
+];
+const UI_APPEND_ORDER = [
+  'DeckHud',
+  'CombatHud',
+  'RewardHud',
+  'MapHud',
+  'ShopHud',
+  'RestHud',
+  'DeckInspectHud',
+  'DeckAllHud',
+  'MainMenu',
+  'CharacterSelectHud',
+];
+const DISABLED_STOCK_CONTROLS = ['Button_Attack', 'Button_Jump', 'UIJoystick'];
 
 const TRANSPARENT = { r: 0, g: 0, b: 0, a: 0 };
 const DARK = { r: 0.08, g: 0.09, b: 0.11, a: 0.92 };
@@ -247,21 +273,28 @@ function scrollLayoutGroup({ cellSize, spacing, columns }) {
   };
 }
 
-function displayOrderFor(path, displayOrder) {
+function popupLayerFor(path) {
-  if (path.startsWith('/ui/DefaultGroup/DeckAllHud')) return 2000 + displayOrder;
+  if (path.startsWith('/ui/DefaultGroup/DeckAllHud')) return { root: '/ui/DefaultGroup/DeckAllHud', base: 4000 };
-  if (path.startsWith('/ui/DefaultGroup/DeckInspectHud')) return 1900 + displayOrder;
+  if (path.startsWith('/ui/DefaultGroup/DeckInspectHud')) return { root: '/ui/DefaultGroup/DeckInspectHud', base: 3000 };
-  return displayOrder;
-}
-
-function sortingOrderFor(path) {
-  if (path.startsWith('/ui/DefaultGroup/DeckAllHud')) return 2000;
-  if (path.startsWith('/ui/DefaultGroup/DeckInspectHud')) return 1900;
   return null;
 }
 
+function uiOrderFor(path, displayOrder) {
+  const popup = popupLayerFor(path);
+  if (popup != null) {
+    const relative = path.slice(popup.root.length).split('/').filter(Boolean);
+    return popup.base + relative.length * 100 + displayOrder;
+  }
+  return displayOrder;
+}
+
+function displayOrderFor(path, displayOrder) {
+  return uiOrderFor(path, displayOrder);
+}
+
 function applySortingOverride(path, components, displayOrder) {
-  const baseOrder = sortingOrderFor(path);
+  if (popupLayerFor(path) == null) return components;
-  if (baseOrder == null) return components;
+  const order = uiOrderFor(path, displayOrder);
   return components.map((component) => {
     if (component['@type'] !== 'MOD.Core.SpriteGUIRendererComponent' && component['@type'] !== 'MOD.Core.TextComponent') {
       return component;
@@ -270,7 +303,7 @@ function applySortingOverride(path, components, displayOrder) {
       ...component,
       OverrideSorting: true,
       SortingLayer: 'UI',
-      OrderInLayer: baseOrder + displayOrder,
+      OrderInLayer: order,
     };
   });
 }
@@ -307,13 +340,46 @@ function entity({ id, path, modelId, entryId, componentNames, components, displa
   };
 }
 
+function uiPath(...parts) {
+  return [UI_ROOT, ...parts].join('/');
+}
+
+function sectionRoot(section) {
+  return uiPath(section);
+}
+
+function isGeneratedUiEntity(e) {
+  return GENERATED_UI_SECTIONS.some((section) => e.path.startsWith(sectionRoot(section)));
+}
+
+function appendUiSection(ui, section, entities) {
+  if (!GENERATED_UI_SECTIONS.includes(section)) {
+    throw new Error(`[gen-slaydeck] unknown generated UI section: ${section}`);
+  }
+  const root = sectionRoot(section);
+  for (const e of entities) {
+    if (!e.path.startsWith(root)) {
+      throw new Error(`[gen-slaydeck] ${section} section emitted unexpected path: ${e.path}`);
+    }
+  }
+  ui.ContentProto.Entities.push(...entities);
+}
+
 function upsertUi() {
   const ui = JSON.parse(readFileSync(UI_FILE, 'utf8'));
   const E = ui.ContentProto.Entities;
-  ui.ContentProto.Entities = E.filter((e) => !e.path.startsWith('/ui/DefaultGroup/DeckHud') && !e.path.startsWith('/ui/DefaultGroup/DeckInspectHud') && !e.path.startsWith('/ui/DefaultGroup/DeckAllHud') && !e.path.startsWith('/ui/DefaultGroup/CombatHud') && !e.path.startsWith('/ui/DefaultGroup/RewardHud') && !e.path.startsWith('/ui/DefaultGroup/MapHud') && !e.path.startsWith('/ui/DefaultGroup/ShopHud') && !e.path.startsWith('/ui/DefaultGroup/RestHud') && !e.path.startsWith('/ui/DefaultGroup/MainMenu') && !e.path.startsWith('/ui/DefaultGroup/CharacterSelectHud'));
+  ui.ContentProto.Entities = E.filter((e) => !isGeneratedUiEntity(e));
 
   const byPath = new Map(ui.ContentProto.Entities.map((e) => [e.path, e]));
-  for (const path of ['/ui/DefaultGroup/Button_Attack', '/ui/DefaultGroup/Button_Jump', '/ui/DefaultGroup/UIJoystick']) {
+  const uiSections = new Map();
+  const emit = (section, entities) => {
+    if (uiSections.has(section)) {
+      throw new Error(`[gen-slaydeck] duplicate generated UI section: ${section}`);
+    }
+    uiSections.set(section, entities);
+  };
+
+  for (const path of DISABLED_STOCK_CONTROLS.map((name) => uiPath(name))) {
     const e = byPath.get(path);
     if (e != null) {
       e.jsonString.enable = false;
@@ -495,7 +561,7 @@ function upsertUi() {
     ],
   }));
 
-  ui.ContentProto.Entities.push(...hud);
+  emit('DeckHud', hud);
 
   const inspect = [];
   const inspectHud = entity({
@@ -617,7 +683,7 @@ function upsertUi() {
       }));
     }
   }
-  ui.ContentProto.Entities.push(...inspect);
+  emit('DeckInspectHud', inspect);
 
   const allDeck = [];
   const allHud = entity({
@@ -739,7 +805,7 @@ function upsertUi() {
       }));
     }
   }
-  ui.ContentProto.Entities.push(...allDeck);
+  emit('DeckAllHud', allDeck);
 
   const PANEL_BG = { r: 0.08, g: 0.09, b: 0.11, a: 0.78 };
   const combat = [];
@@ -899,7 +965,7 @@ function upsertUi() {
   });
   result.jsonString.enable = false;
   combat.push(result);
-  ui.ContentProto.Entities.push(...combat);
+  emit('CombatHud', combat);
 
   const reward = [];
   const rewardHud = entity({
@@ -980,7 +1046,7 @@ function upsertUi() {
       text({ value: '건너뛰기', fontSize: 26, bold: true, color: GOLD, alignment: 4 }),
     ],
   }));
-  ui.ContentProto.Entities.push(...reward);
+  emit('RewardHud', reward);
 
   const TYPE_KO = { combat: '전투', elite: '엘리트', boss: '보스', shop: '상점', rest: '휴식' };
   const map = [];
@@ -1042,7 +1108,7 @@ function upsertUi() {
       ],
     }));
   }
-  ui.ContentProto.Entities.push(...map);
+  emit('MapHud', map);
 
   const shop = [];
   const shopHud = entity({
@@ -1176,7 +1242,7 @@ function upsertUi() {
       text({ value: '나가기', fontSize: 26, bold: true, color: GOLD, alignment: 4 }),
     ],
   }));
-  ui.ContentProto.Entities.push(...shop);
+  emit('ShopHud', shop);
 
   const rest = [];
   const restHud = entity({
@@ -1233,7 +1299,7 @@ function upsertUi() {
       text({ value: '나가기', fontSize: 26, bold: true, color: GOLD, alignment: 4 }),
     ],
   }));
-  ui.ContentProto.Entities.push(...rest);
+  emit('RestHud', rest);
 
   const menu = [];
   menu.push(entity({
@@ -1466,7 +1532,16 @@ function upsertUi() {
     ],
   }));
   select[0].jsonString.enable = false;
-  ui.ContentProto.Entities.push(...menu, ...select);
+  emit('MainMenu', menu);
+  emit('CharacterSelectHud', select);
+
+  for (const section of UI_APPEND_ORDER) {
+    const entities = uiSections.get(section);
+    if (entities == null) {
+      throw new Error(`[gen-slaydeck] missing generated UI section: ${section}`);
+    }
+    appendUiSection(ui, section, entities);
+  }
 
   JSON.parse(JSON.stringify(ui));
   writeFileSync(UI_FILE, JSON.stringify(ui, null, 2), 'utf8');
@@ -1908,12 +1983,6 @@ if self.DeckAllOpen == true then
 		allHud.Enable = false
 	end
 end
-for i = 1, 4 do
-\tlocal monsterSlot = _EntityService:GetEntityByPath("/ui/DefaultGroup/CombatHud/MonsterSlot" .. tostring(i))
-\tif monsterSlot ~= nil then
-\t\tmonsterSlot.Enable = false
-\tend
-end
 local pile = {}
 local title = ""
 if kind == "discard" then
@@ -1932,12 +2001,6 @@ end`, [{ Type: 'string', DefaultValue: null, SyncDirection: 0, Attributes: [], N
 local hud = _EntityService:GetEntityByPath("/ui/DefaultGroup/DeckInspectHud")
 if hud ~= nil then
 	hud.Enable = false
-end
-for i = 1, 4 do
-\tlocal monsterSlot = _EntityService:GetEntityByPath("/ui/DefaultGroup/CombatHud/MonsterSlot" .. tostring(i))
-\tif monsterSlot ~= nil then
-\t\tmonsterSlot.Enable = true
-\tend
 end`),
     method('RenderDeckInspect', `local count = 0
 if pile ~= nil then
@@ -1997,12 +2060,6 @@ if inspectHud ~= nil then
 end
 self.DeckInspectKind = ""
 self.DeckAllOpen = true
-for i = 1, 4 do
-\tlocal monsterSlot = _EntityService:GetEntityByPath("/ui/DefaultGroup/CombatHud/MonsterSlot" .. tostring(i))
-\tif monsterSlot ~= nil then
-\t\tmonsterSlot.Enable = false
-\tend
-end
 self:RenderAllDeck()
 local hud = _EntityService:GetEntityByPath("/ui/DefaultGroup/DeckAllHud")
 if hud ~= nil then
@@ -2012,12 +2069,6 @@ end`),
 local hud = _EntityService:GetEntityByPath("/ui/DefaultGroup/DeckAllHud")
 if hud ~= nil then
 	hud.Enable = false
-end
-for i = 1, 4 do
-\tlocal monsterSlot = _EntityService:GetEntityByPath("/ui/DefaultGroup/CombatHud/MonsterSlot" .. tostring(i))
-\tif monsterSlot ~= nil then
-\t\tmonsterSlot.Enable = true
-\tend
 end`),
     method('RenderAllDeck', `local pile = self.RunDeck or {}
 local count = #pile