Archived on 2026-10-24. The Godot rewrite is cancelled. Migration decisions and work checklists below are withdrawn. Original claims, code examples, file paths, and completion statements have not all been revalidated. Use the current documentation and issue register for maintenance decisions.

UI Flow Analysis

Purpose

The UI system covers startup splash, main menu navigation, character/stage/shop/achievement/collection/leaderboard views, gameplay HUD, pause/settings, reward cards, and game-over panels.

Current Unity Implementation

Main scripts:

Path	Script	Role
Assets/Script/App/Core/SplashUIController.cs	SplashUIController	Startup loading UI and main menu transition.
Assets/Script/App/UI/Controllers/MenuController.cs	MenuController	Generic page stack, back behavior, gate animation.
Assets/Script/App/UI/Shared/Page.cs	Page	Page-level UI behavior.
Assets/Script/App/Managers/MainMenuManager.cs	MainMenuManager	Main menu flow and start-game transition.
Assets/Script/App/UI/Views/*.cs	Views	Menu, shop, achievements, collection, leaderboard, joystick views.
Assets/Script/App/UI/Buttons/*.cs	Buttons	Stage, shop, collection, leaderboard button data/setup.
Assets/Script/Game/Managers/GameMenuManager.cs	GameMenuManager	Gameplay pause/settings page flow.
Assets/Script/Game/GameSystem/Rewards/RewardRoller.cs	RewardRoller	Reward card/chest animations and card creation.
Assets/Script/Game/GameSystem/Upgrades/UpgradeSelection.cs	UpgradeSelection	Reward card navigation/selection.
Assets/Script/Game/Managers/GameEndManager.cs	GameEndManager	Game-over UI references and buttons.
Assets/Script/Game/Entities/Player/Presentation/StatusPanel.cs	StatusPanel	Per-player HUD stats and resource bars.
Assets/Script/Game/Stage/DamagePopUp.cs	DamagePopUp	Floating damage text.
Assets/Script/Game/Utilities/Announcer.cs	Announcer	Special/miniboss/bonus announcements.

Key Data

• MenuController page stack and configured root/back callbacks.
• GameManager HUD refs: score text, level text, XP bar, player status panels.
• SpawnerEventManager HUD refs: timer bar, boss health, boss icon.
• RewardRoller reward UI refs: upgradeButton, upgradeButtonBorderParent, upgradeButtonUI, chest displays, particles.
• UpgradeSelection card markers, current selection indices, selection locks.
• GameEndManager game-over labels/stats/ability icons/buttons.
• UIResourcesConfig rarity colors/icons, gradients, damage popup prefab, damaged material.
• Localization uses Unity LocalizedString and localization tables.

Runtime Flow

App Startup and Main Menu

1. AppInitiator initializes services and save.
2. SplashUIController handles loading into main menu.
3. Main menu views/controllers use static managers for data:
4. AchievementManager
5. ShopManager
6. CollectionManager
7. LeaderboardManager
8. InputManager
9. MenuController manages page transitions and gate animations.
10. Start-game flow sets GameSession and loads stage scene.

Gameplay HUD

1. GameManager.StartUI() hides XP bar, timer bar, and player status panels.
2. OpenGate() starts game and later calls ShowUI().
3. ShowUI() tweens timer bar, XP bar, and status panel alpha/position.
4. GameManager.Update() updates level and XP bar.
5. StatusPanel.Update() shows player stats/resources and hides while paused.
6. DamagePopUp animates damage numbers and returns to pool.

Reward UI

1. RewardRoller.RollTheUpgradeTable() activates reward UI and spawns card buttons.
2. Chest or card particle animations play.
3. DisplayAnimation() scales cards in one by one using unscaled time.
4. Reward phase becomes Selecting.
5. UpgradeSelection lets each player navigate and lock a card.
6. ConfirmSelect() applies selected upgrades, destroys buttons, and resumes the game.

Pause / Settings

1. GameMenuManager.InitializeMenu() configures MenuController for gameplay.
2. Back button toggles settings if GameState.CanPause.
3. Opening settings calls GameManager.PauseGame().
4. Closing root settings sets GameManager.instance.isPaused = false.

Game Over

1. GameManager.GameOver() hides HUD and activates game-over panel.
2. It fills end stats, selected ability icons, score/currency/time/kill/level/stage/difficulty/nickname/title.
3. It submits leaderboard data and checks achievements.
4. It tweens panel into view and enables buttons.

Dependencies

• UI is tightly coupled to GameManager.instance, static managers, Save, GameSession, AudioResources, Game.Audio, DOTween, TextMeshPro, Unity Localization.
• Reward UI currently lives mostly inside RewardRoller, not RewardUIController.
• UIResourceProvider loads UIResources from Resources.

Problems / Risks

• Gameplay UI references are stored on GameManager.
• Reward rolling and reward UI animation are coupled.
• UpgradeSelection checks both pause state and reward phase; these can diverge.
• StatusPanel pulls data from player/modifier every frame instead of using signals.
• Game-over UI generation is embedded in GameManager.GameOver().
• Some app views instantiate UI lists directly and may need virtualization if lists grow.
• Localization keys are not centralized in docs yet.

Migration Notes for Godot

Preserve:

• Page stack/back behavior.
• Gate transition concept if still desired.
• Gameplay HUD reveal after gate open.
• Reward cards with one/two-player markers and lock-in behavior.
• Game-over stat contents.
• Rarity colors/icons and localized text.

Redesign:

UIRoot
- owns app/gameplay UI layers

PageRouter
- push/pop page stack

HUDController
- observes RunState, ScoreManager, PlayerStats

RewardUIController
- displays cards and emits selections

GameOverView
- consumes a GameOverSummary data object

FeedbackLayer
- damage popups, announcements, screen effects

Do not copy:

• UI references inside core gameplay controllers.
• Reward card animation inside reward roll logic.
• Per-frame UI polling where signal updates are enough.

Open Questions

• Which UI screens are needed for the first Godot milestone?
• Whether the current page-stack UX should be preserved exactly.
• Which localization tables should be converted first.
• Unknown / needs manual confirmation.