@design-ai/cli 4.55.0

package/knowledge/game-ui/korean-gaming-conventions.md

@@ -0,0 +1,312 @@
+<!-- hand-written -->
+---
+title: Korean gaming conventions (PC bang, mobile gacha, MMO, regulations)
+applies_to: [game-ui, korean, kr-market, gacha, mmo]
+version: 1.0.0
+last_updated: 2026-05
+stability: stable
+---
+
+# Korean gaming conventions
+
+Korean gaming has distinct UI conventions, regulatory requirements, monetization patterns, and cultural expectations. This file covers what's specific to the Korean game market.
+
+Read [`game-ui-fundamentals.md`](game-ui-fundamentals.md) first.
+
+## Market overview
+
+Korea is one of the world's most important game markets:
+- **Mobile gacha + MMORPG** dominate revenue.
+- **PC bang (PC방)** culture: PC cafés where games are played with hourly rates.
+- **High ARPU** — Korean players spend more per user than most markets.
+- **Whale-driven monetization** — top spenders fund most revenue.
+
+### Major Korean studios
+
+| Studio | Notable games |
+| --- | --- |
+| **NEXON** | 메이플스토리, FIFA Online, KartRider, 던전앤파이터, 서든어택 |
+| **NCSoft** | 리니지 / 리니지 M / 리니지 W, 길드워, 블레이드 & 소울, 아이온 |
+| **Smilegate** | 크로스파이어, 로스트아크, 에픽세븐 |
+| **Krafton** | 배틀그라운드 (PUBG), 칼리스토 프로토콜 |
+| **Pearl Abyss** | 검은사막, 도깨비 |
+| **Com2uS** | 서머너즈 워, 데스티니 차일드 |
+| **Netmarble** | 세븐나이츠, 리니지 2 레볼루션, 마블 콘테스트 오브 챔피언스 |
+| **Kakao Games** | 오딘:발할라 라이징, 우마무스메 (KR distribution) |
+
+## Regulatory framework
+
+### 게임산업진흥에관한법률 (Game Industry Promotion Act)
+
+Korea regulates games heavily. Key rules:
+
+#### 확률 표시 (probability disclosure)
+
+**Mandatory**: gacha / loot box / random reward systems must disclose drop rates.
+
+```
+[가챠 결과 화면 또는 상점 페이지]
+─────────────────────
+SSR 캐릭터: 1.5%
+SR 캐릭터: 8.5%
+R 캐릭터: 90%
+```
+
+Required:
+- All probabilities listed.
+- Updated after each balance change.
+- Accessible from store / gacha screen.
+- For ENHANCED guaranteed (pity / 천장 system): also disclosed.
+
+Failure = KFTC (공정거래위원회) fine. Several Korean gaming companies have been fined heavily for missing / incorrect disclosure (NEXON, Smilegate notable cases).
+
+#### 청소년이용시간제한 (Youth play-time restriction)
+
+Historically (now mostly relaxed but still relevant):
+- **Shutdown law (셧다운제)** — youth couldn't play between midnight and 6am. Repealed 2022 but historical context for older games.
+- **선택적 셧다운제** — parental control; family can set limits.
+- **확인 시스템** — game IDs link to real-name verification (실명인증 / 본인인증) — Korean games require this.
+
+#### 등급 분류 (Game ratings)
+
+Korean Game Rating Administration Committee (GRAC / 게임물관리위원회) rates all games:
+- **전체이용가** (All ages)
+- **12세 이용가** (12+)
+- **15세 이용가** (15+)
+- **청소년이용불가** (18+)
+
+Mobile / PC games released in Korea must have GRAC rating. Affects what content can be displayed.
+
+### 본인인증 (real-name verification)
+
+Korean games require player identity verification:
+- **PASS** (mobile carrier authentication)
+- **NICE / KCB** (credit bureau)
+- **휴대폰 본인인증** (mobile phone)
+
+For login screens / sign-up: typically deeper than Western games.
+
+See [`knowledge/i18n/korean-payments.md`](../i18n/korean-payments.md) for 본인인증 details.
+
+## PC bang (PC방) culture
+
+PC bangs are PC cafés — pay hourly to use a high-end PC. Critical to Korean PC gaming culture.
+
+### Implications for game UI
+
+- **PC bang exclusive content / bonuses** — many games have benefits when played from PC bang IP.
+- **Account login** is heavy (vs Western "press play to start").
+- **Auto-detection of PC bang** — server-side; UI shows PC bang badge / XP boost.
+- **Hourly session expectation** — long PvP / raid sessions; UI assumes 2-5 hour play windows.
+
+### Common Korean PC games
+
+- **롤 (League of Legends)** — Korea is LoL-dominant.
+- **오버워치 (Overwatch)** — major PC bang draw.
+- **배틀그라운드 (PUBG)** — Krafton's flagship.
+- **로스트아크 (Lost Ark)** — recent PC bang hit.
+- **메이플스토리** — long-running 2D MMORPG.
+
+## Mobile gaming conventions
+
+Mobile is the bigger market. Conventions:
+
+### Auto-battle (자동 전투)
+
+Most Korean mobile RPGs offer auto-play:
+- Toggle on; characters fight autonomously.
+- Player still earns rewards.
+- Reduces grind tedium.
+- 2x / 4x speed options.
+
+UI:
+- **Auto button** prominent (often bottom-right).
+- **Speed control** (1x, 2x, 4x).
+- **Pause auto** mid-battle for player intervention.
+
+Western games rarely have this; Korean / Asian mobile games default to it.
+
+### Daily login bonuses
+
+Visible in main menu:
+
+```
+일일 출석체크
+[Day 1 ✓] [Day 2 ✓] [Day 3 ▶ today] [Day 4 ▢] [Day 5 ▢]
+[Day 6 ▢] [Day 7 ▢ — 보상]
+```
+
+Player gets reward each day. Big reward at Day 7 / Day 30 / Day 100.
+
+### VIP / 출석
+
+Tiered loyalty:
+- **VIP 1-15 levels**.
+- Each level requires accumulated spending.
+- VIP perks: extra inventory, daily premium currency, exclusive cosmetics.
+
+Visible UI badge for VIP tier.
+
+### Battle pass / season pass
+
+Time-limited progress track:
+- **Free track** + **Premium track** (purchased).
+- Unlocks via gameplay.
+- Resets each season (1-3 months).
+
+Most major Korean mobile games have this 2024+.
+
+### Gacha (가챠)
+
+Random pulls for characters / items:
+
+```
+┌─────────────────────────────────┐
+│  [영웅 가챠]                       │
+│                                 │
+│  💎 1000 = 1회 뽑기                │
+│  💎 9000 = 10회 뽑기 (10% 할인)     │
+│                                 │
+│  최근 SSR 보장: 0/100 — 100회 후   │
+│  100% SSR 보장                   │
+│                                 │
+│  ▶ 확률 보기                       │   ← legally required link
+│                                 │
+│  [1회 뽑기]    [10회 뽑기]         │
+└─────────────────────────────────┘
+```
+
+Required:
+- Probability disclosure link.
+- Pity counter (천장 progress).
+- Currency cost.
+- Limited-time event indicator.
+
+### Whale signaling
+
+Korean mobile games signal whale status:
+- **Costume / mount** exclusive to high spenders.
+- **Server-wide announcement** ("[PlayerName] 님이 SSR 영웅 [Name]를 획득하셨습니다!").
+- **Leaderboards** prominent.
+- **Guild contributions** visible.
+
+UI design supports both whales (showing off) and free players (motivation to spend).
+
+## Korean MMO UI conventions
+
+Korean MMOs (Lineage, MapleStory, Lost Ark, BDO) share UI patterns:
+
+### Dense HUD
+
+- 5-7 hotbars visible.
+- Buff / debuff stacks of 10-20+.
+- Multiple chat tabs (general / guild / party / whisper / system).
+- Floating combat numbers always on.
+- Mini-map detailed with quest markers.
+
+Western players sometimes find "cluttered"; Korean players consider standard.
+
+### Heavy customization
+
+- Hundreds of HUD options.
+- UI scale per element.
+- Color theme presets.
+- Multiple keybind layouts.
+
+### Item labeling
+
+- **Tier color** (common / uncommon / rare / epic / legendary / mythic).
+- **+N enhancement** ("Iron Sword +12") — enhancement level visible everywhere.
+- **Soulbound / 귀속** marker — items locked to character.
+- **Tradable / 거래가능** marker.
+
+### PvP / siege UI
+
+Korean MMOs traditionally have heavy PvP. Siege UI:
+- **Castle / fortress timer**.
+- **Faction / guild standings**.
+- **Real-money bidding for siege participation** (some games).
+
+## Mobile gacha character UI
+
+Character roster screens show:
+
+```
+┌──────────────────────────────────┐
+│ [Tab filters: SSR / SR / Element]│
+│                                  │
+│ [Character card] [card] [card]   │
+│ [Character card] [card] [card]   │
+│ [Character card] [card] [card]   │
+│                                  │
+│ Selected:                        │
+│ ┌──────┐                         │
+│ │      │ Character name          │
+│ │ Img  │ Lv 60 / SSR             │
+│ │      │ HP 12,400 / ATK 1,820   │
+│ └──────┘ [Equip] [Level Up] [Awa]│
+└──────────────────────────────────┘
+```
+
+For each character:
+- **Star rating** (1★ - 6★).
+- **Element / class** icons.
+- **Awakening / 각성** stage (post-level-cap upgrades).
+- **Skill levels**.
+- **Equipped gear**.
+- **Affinity / 호감도** (relationship-style stat).
+
+Korean gacha trends to higher complexity than Western (more layered upgrade systems).
+
+## Cross-platform Korean games
+
+Many Korean games release on PC + mobile + console. UI must adapt:
+
+- **Account sync** across platforms.
+- **Cloud save** mandatory (mobile freed up but progress preserved).
+- **Cross-play** if supported.
+- **Cross-progression** (single character used everywhere).
+
+UI signals current platform (PC bang badge, mobile data warnings, controller prompts on console).
+
+## Korean game typography
+
+For Korean game UI:
+
+| Use | Font |
+| --- | --- |
+| Logo | Custom calligraphy or stylized brand font |
+| HUD numbers | Tabular numerals; condensed sans (Pretendard, NanumSquare) |
+| Body text | Pretendard, NanumSquare, NEXON Lv1 / Lv2 (NEXON's free game-friendly font) |
+| Display / titles | NEXON 두꺼비, 검은고딕, 본명조 |
+| Combat numbers | Bold sans, white / yellow with dark outline |
+
+NEXON Lv1 / Lv2 font: free, designed specifically for game UI, includes Latin + Hangul + numbers.
+
+## Audio in Korean games
+
+- **Korean voice acting** mandatory for major games (Western imports get full Korean dub).
+- **Voice options**: Korean / Japanese / English / Chinese (popular in MMOs).
+- **Voice sample** in character screen (preview).
+- **Cinematic dialogue** subtitled even if voice is Korean.
+
+## Don't
+
+- Don't ship a game in Korea without 본인인증. Required for most genres.
+- Don't skip 확률 표시 for gacha. KFTC fines + reputation damage.
+- Don't release without GRAC rating.
+- Don't apply Western mobile UI patterns to Korean players (less auto-battle, fewer login bonuses) — Korean players expect daily-login + auto-play.
+- Don't use Latin-only fonts for game UI in Korean. Pretendard / NanumSquare / NEXON Lv handle Hangul + Latin together.
+- Don't skip Korean voice acting for major releases. Players notice.
+- Don't ignore PC bang detection. Free XP boosts in PC bangs are competitive table stakes.
+- Don't treat all Korean players as one block. Mobile gacha audience differs from MMO audience differs from FPS audience.
+
+## Cross-reference
+
+- [`knowledge/game-ui/game-ui-fundamentals.md`](game-ui-fundamentals.md) — categories
+- [`knowledge/game-ui/hud-design.md`](hud-design.md) — HUD conventions
+- [`knowledge/game-ui/menu-systems.md`](menu-systems.md) — menus
+- [`knowledge/game-ui/game-accessibility.md`](game-accessibility.md) — a11y
+- [`knowledge/i18n/korean-payments.md`](../i18n/korean-payments.md) — 본인인증, payments
+- [`knowledge/i18n/korean-app-store-visual.md`](../i18n/korean-app-store-visual.md) — app store / store visuals
+- [`knowledge/i18n/korean-typography.md`](../i18n/korean-typography.md) — Korean fonts

package/knowledge/game-ui/menu-systems.md

@@ -0,0 +1,388 @@
+<!-- hand-written -->
+---
+title: Menu systems (main menu, pause, inventory, settings, store)
+applies_to: [game-ui, menus, navigation]
+version: 1.0.0
+last_updated: 2026-05
+stability: stable
+---
+
+# Menu systems
+
+Menus in games are full-screen interfaces players navigate to (not glanced at like HUD). Different rules: density, depth, visual hierarchy.
+
+Read [`game-ui-fundamentals.md`](game-ui-fundamentals.md) first.
+
+## Menu types
+
+| Menu | When |
+| --- | --- |
+| **Main menu** | Game launch; before play |
+| **Pause menu** | During gameplay; suspended state |
+| **Inventory** | Open via key; manage items |
+| **Character / stats** | Manage character build |
+| **Settings** | Audio / video / control / a11y options |
+| **Store** | Buy items / unlock content |
+| **Social / friends** | Online play |
+| **Leaderboards** | Compare with others |
+| **Achievements** | Unlocked progress |
+| **Tutorial / help** | Learn mechanics |
+
+Each has conventions players expect.
+
+## Main menu
+
+The first thing players see. Sets tone.
+
+### Common items
+
+```
+┌──────────────────────────┐
+│                          │
+│    [GAME LOGO]           │
+│                          │
+│                          │
+│      ▶ Continue          │   ← if save exists
+│        New Game          │
+│        Load Game         │
+│        Multiplayer       │   (if applicable)
+│        Store             │   (if applicable)
+│        Settings          │
+│        Credits           │
+│        Quit              │
+│                          │
+│                          │
+│  [news / version info]   │
+└──────────────────────────┘
+```
+
+### Hierarchy
+
+- **Continue / Play** is the most-used; top.
+- **New Game** is rare (most sessions resume); below.
+- **Settings** is necessary but not primary.
+- **Quit** at bottom (lowest priority on desktop / console; sometimes hidden on mobile).
+
+For mobile / always-online games: "Quit" is rarely shown (just close app); main menu often skipped entirely (auto-progress to lobby / character select).
+
+### Background
+
+- **Cinematic**: animated background, ambient music. Premium feel.
+- **Static**: single beautiful frame. Cheaper.
+- **Live render**: in-game character on idle animation.
+- **Procedural**: shifts each session.
+
+For Korean MMOs: often shows the player's character with all gear visible (motivates investment).
+
+## Pause menu
+
+```
+┌──────────────────────────┐
+│                          │
+│   PAUSED                 │
+│                          │
+│    Resume                │
+│    Restart               │
+│    Settings              │
+│    Quit to main menu     │
+│                          │
+└──────────────────────────┘
+```
+
+Or modern variant — show pause options + map / progress / inventory tabs:
+
+```
+┌──────────────────────────────────────┐
+│ [Resume] [Map] [Inventory] [Settings]│
+│                                      │
+│           [active tab content]       │
+│                                      │
+└──────────────────────────────────────┘
+```
+
+Pause menu rules:
+- **Pause is a single key** (Esc / Start / Menu button).
+- **Confirmation for destructive actions** (Quit → "Are you sure? Unsaved progress will be lost.")
+- **In multiplayer**: doesn't actually pause game; instead opens menu while game continues. Show this clearly.
+
+## Inventory
+
+The most-iterated game menu. Many design patterns:
+
+### Grid
+
+```
+┌─────────────────────────────┐
+│  [Item slot grid 8×6 ]      │
+│  [Tabs: Weapons | Armor | ] │
+└─────────────────────────────┘
+```
+
+Most common. Drag-and-drop on PC; tap on mobile.
+
+### List
+
+```
+┌─────────────────────────────┐
+│  ▶ [icon] Iron Sword  +5 ATK│
+│    [icon] Wooden Bow  +3 ATK│
+│    [icon] Leather Armor +2  │
+│  ...                        │
+└─────────────────────────────┘
+```
+
+For fewer items / mobile / simpler UX.
+
+### Tetris (Resident Evil 4 / Escape from Tarkov)
+
+Items have shapes; rotate / pack into limited grid. Adds gameplay; expensive UI.
+
+### Stacked panel (Korean MMO style)
+
+Multi-tab inventory:
+- Main bag (primary stash).
+- Crafting materials tab.
+- Quest items tab.
+- Consumables tab.
+- Currency tab.
+- Premium / paid items tab.
+
+Each tab is its own grid. Tab switching is fast; common Korean MMO UX.
+
+### Item detail
+
+Hover (PC) or tap (mobile) shows full item info:
+
+```
+┌──────────────────────┐
+│ [item icon, large]   │
+│                      │
+│ Iron Sword           │
+│ Common Weapon        │
+│                      │
+│ + 5 Attack           │
+│ + 1 Crit Chance      │
+│ Durability: 40/40    │
+│                      │
+│ "A simple iron blade │
+│  forged in ..."      │
+│                      │
+│ [Equip] [Drop] [Sell]│
+└──────────────────────┘
+```
+
+For comparison (equip new vs current): show side-by-side.
+
+### Inventory rules
+
+- **Sort options**: by type, by rarity, by recently acquired.
+- **Search / filter**: as inventory grows.
+- **Auto-equip / loadout**: save preset configurations.
+- **Stack** identical items (potions × 5).
+- **Limit stack size** (gameplay constraint, often 99 or 999).
+- **Highlight new items** (unviewed badge).
+
+For Korean MMOs: inventory is large (often 100+ slots). Sorting + filtering critical.
+
+## Settings menu
+
+Sections (common):
+
+| Section | Settings |
+| --- | --- |
+| **Video / Display** | Resolution, refresh, FOV, V-Sync, fullscreen mode, brightness, gamma |
+| **Audio** | Master volume, music, SFX, voice chat, dialogue, subtitle volume |
+| **Controls** | Remap keys / buttons, sensitivity, invert axis, deadzone |
+| **Gameplay** | Difficulty, HUD options, tutorial toggles, language |
+| **Network** | Region, NAT, ping limit |
+| **Accessibility** | Subtitles, color-blind, screen reader, motion reduction, contrast |
+| **Account** | Username, profile, link to social |
+| **Credits / About** | Game info, version, legal |
+
+### Settings UX
+
+- **Apply / Cancel**: changes preview but require confirm.
+- **Reset to defaults**: per-section button.
+- **Search**: large settings menus benefit from search ("subtitle" → finds it).
+- **Tooltips / explanations**: especially for technical settings (anti-aliasing levels).
+
+### Korean MMO settings
+
+Korean MMOs often have hundreds of settings:
+- HUD scale per element.
+- Combat number visibility.
+- Specific notification toggles.
+- Performance presets.
+- Multiple input mappings (PC + controller + mobile-controller hybrid).
+
+Search becomes essential.
+
+## Store / shop
+
+For games with monetization:
+
+```
+┌──────────────────────────────────────────┐
+│  [Tabs: Featured | Bundles | Cosmetics ] │
+│                                          │
+│  [Featured promotion banner]             │
+│                                          │
+│  [Item card] [Item card] [Item card]     │
+│  [Item card] [Item card] [Item card]     │
+│                                          │
+│  [Currency: 💎 1240]    [Buy gems]       │
+└──────────────────────────────────────────┘
+```
+
+Store UX:
+- **Hero promotion** at top.
+- **Currency balance** always visible.
+- **Buy currency** path always 1-2 taps from anywhere in store.
+- **Item card** shows: image, name, price (in real currency or premium currency).
+- **Limited time** banners with countdown.
+- **Confirmation** before purchase (especially expensive items).
+
+### Korean gacha store
+
+Korean mobile gacha specifics:
+- **확률 표시** (probability disclosure) — REQUIRED by 게임산업진흥에관한법률 (Game Industry Promotion Act).
+- **누적 보상** (pity / cumulative rewards) — UI showing how many more pulls until guaranteed item.
+- **이벤트 타이머** — limited-time banners with prominent countdown.
+- **첫 결제 보상** (first-purchase bonuses).
+- **VIP / 출석** — daily login + VIP tier rewards.
+
+See [`korean-gaming-conventions.md`](korean-gaming-conventions.md) for regulatory details.
+
+## Quest / mission menu
+
+```
+┌──────────────────────────────────────┐
+│ [Tabs: Active | Available | Done ]   │
+│                                      │
+│ ▶ Defeat the dragon                  │
+│   Talk to elder afterward            │
+│   ─────────────                       │
+│   Reward: 500 gold, Sword            │
+│   [Track] [Abandon]                   │
+│                                      │
+│   Find 5 rare herbs                  │
+│   3/5 collected                      │
+│ ...                                  │
+└──────────────────────────────────────┘
+```
+
+Tracking: one quest can be "tracked" — its waypoint and HUD reminder show.
+
+For story-heavy games: chronological / chapter-organized; player can replay completed.
+
+## Character / stats
+
+```
+┌──────────────────────────────────────┐
+│ [Character render]                   │
+│ Level 24                             │
+│ ───────────                           │
+│ HP    1450    INT  120               │
+│ MP    540     WIS  85                │
+│ STR   145     LUK  20                │
+│                                      │
+│ [Equipment slots]                    │
+│ Weapon: [Iron Sword]                 │
+│ Helmet: [empty]                      │
+│ ...                                  │
+│                                      │
+│ [Skill tree]                         │
+└──────────────────────────────────────┘
+```
+
+For RPGs / MMOs: very dense. Often multi-tab (Stats / Equipment / Skills / Talents / Loadouts).
+
+## Tutorial / help
+
+Modern games avoid traditional tutorial menus; integrate teaching into gameplay. But some still have:
+- **First-run tutorial** — initial sequence.
+- **Help / how-to-play** — reference accessed from main menu.
+- **Tooltips** — hover-triggered hints.
+- **Codex / journal** — lore + game systems explained.
+
+Allow skip.
+
+## Navigation patterns
+
+### PC mouse + keyboard
+
+- Click to navigate.
+- Tab / arrows for keyboard.
+- Esc to back / close.
+- Enter to confirm.
+
+### Console (controller)
+
+- D-pad / left stick to navigate.
+- A / X to confirm.
+- B / O to back / cancel.
+- Y / △ for context action (often).
+- Triggers / shoulders for tab switching.
+- Back button toggles overlay (map, inventory).
+
+Show button prompts at all times: bottom of screen "[A] Confirm [B] Back".
+
+### Mobile (touch)
+
+- Tap to select / activate.
+- Long-press for context menu.
+- Swipe between tabs.
+- Pinch to zoom (if applicable, like world maps).
+- Bottom-bar always thumb-reachable.
+
+## Transitions between menus
+
+Smooth transitions reduce jarring:
+- **Cross-fade** (200-300ms).
+- **Slide** (left / right for tab nav, up / down for hierarchy).
+- **Zoom** (entering submenu = zoom in).
+- **Stack** (modals over current screen, dim background).
+
+Don't transition longer than 400ms — feels slow when navigating quickly.
+
+## Modal interrupts
+
+Some events demand attention even outside menus:
+- **Achievement popup** — center of screen, dismissable.
+- **Reward unlock** — celebratory, dismissable after viewing.
+- **Login bonus** — daily, requires acknowledgment.
+- **Network disconnection** — full overlay until reconnected or accepted.
+- **Update available** — patch notes / download prompt.
+
+Allow dismissing; don't trap player.
+
+## Korean MMO menu density
+
+Korean MMOs tend to have many concurrent sub-windows on screen:
+
+```
+[chat]  [main game]  [quest list]
+        [inventory]      [skill]
+[mini-map]    [party]    [auction]
+```
+
+Players reposition / dock / hide. Customization is heavy. Western players can find this overwhelming; Korean players accept.
+
+## Don't
+
+- Don't make settings menus 200 items deep without search.
+- Don't put "Quit" before "Continue" in main menu.
+- Don't skip confirmation on destructive actions.
+- Don't disable "skip cinematic" — let players skip after first watch.
+- Don't make inventories that take 30 seconds to navigate.
+- Don't hide critical settings (subtitle toggle, color-blind) deep in menus.
+- Don't break the back button (Esc, B button) — should always work.
+- Don't auto-pop store on every launch.
+
+## Cross-reference
+
+- [`knowledge/game-ui/game-ui-fundamentals.md`](game-ui-fundamentals.md) — categories
+- [`knowledge/game-ui/hud-design.md`](hud-design.md) — HUD vs menu
+- [`knowledge/game-ui/korean-gaming-conventions.md`](korean-gaming-conventions.md) — KR market
+- [`knowledge/game-ui/game-accessibility.md`](game-accessibility.md) — settings / a11y
+- [`examples/component-game-menu.md`](../../examples/component-game-menu.md) — menu spec