maplecontest/docs/ui-generation-structure.md

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.