# 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.