UI Architecture

Relevant source files

The following files were used as context for generating this wiki page:

• src/scenes/GameScene.js
• src/scenes/MainMenuScene.js
• src/scenes/IntroScene.js
• src/systems/Tutorial.js
• src/scenes/UITestScene.js
• src/utils/SaveSlotManager.js

The UI architecture in Souless is built upon the Phaser 3 scene system, employing a multi-scene approach to decouple user interface elements from the core game logic. The system uses dedicated scenes for different UI contexts, such as the main menu, narrative introductions, and the in-game heads-up display (HUD).

A key architectural pattern is the separation of the main gameplay scene (GameScene) from the primary in-game UI scene (UIScene). GameScene manages game logic and launches UIScene to run in parallel. Communication between these scenes is event-driven, with GameScene emitting events about player status changes, which UIScene then consumes to update the display. This ensures that UI elements are rendered independently of the game world's camera and state.

Scene-Based UI Management

The game leverages multiple Phaser scenes to manage different UI states and contexts. Each scene is responsible for a distinct part of the user experience.

Scene	Responsibility	Key Features
MainMenuScene	Main menu, new game, and load game functionality.	Displays save slots, calculates and shows completion percentage, handles navigation to start a new game or load an existing one.
IntroScene	Displays the narrative introduction at the start of a new game.	Features a typewriter-style dialogue system and triggers cinematic actions.
GameScene	Manages core gameplay and in-game contextual UI overlays.	Launches the persistent UIScene, manages the CharacterSelectOverlay, and instantiates the TutorialSystem.
UIScene	Renders the persistent in-game HUD. (Launched by GameScene)	Displays player stats (HP, MP), skill cooldowns, and experience bars. Listens for events from GameScene.
UITestScene	A development scene for testing UI components in isolation.	Used to develop and verify components like CharacterSelectOverlay and UISkillCooldown.

Sources: src/scenes/GameScene.js:149, src/scenes/MainMenuScene.js, src/scenes/IntroScene.js, src/scenes/UITestScene.js

The following diagram illustrates the typical scene flow for a user starting a new game.

Sources: src/scenes/MainMenuScene.js:460, src/scenes/IntroScene.js:283

GameScene and UIScene Interaction

GameScene is responsible for the core game logic, while UIScene handles the persistent HUD. GameScene launches UIScene to run in parallel and communicates with it via Phaser's event system. This decouples the UI from the game world.

Sources: src/scenes/GameScene.js:149, src/scenes/GameScene.js:1250-1251

Core UI Components

Main Menu and Save Slots

The MainMenuScene is the entry point for the player. It presents options for "NEW GAME", "LOAD GAME", and "EXIT". The "LOAD GAME" button is disabled if no save data exists.

When starting a new game or loading, the player is taken to a slot selection screen. This screen displays up to 3 save slots, each as an interactive card.

• Empty Slots: Display "EMPTY" and are clickable to start a new game in that slot.
• Used Slots: Display a summary of the saved game, including character level, current character, location, bosses defeated, and last save time. It also features a completion progress bar.

The scene uses SaveSlotManager to fetch all slot data and determine their status.

Sources: src/scenes/MainMenuScene.js:103, src/scenes/MainMenuScene.js:347, src/utils/SaveSlotManager.js:283

The completion percentage is calculated in calculateClearPercentage based on the number of bosses defeated (50% weight) and the average level of all characters (50% weight). A 100% clear is awarded immediately if the final_boss has been defeated.

Sources: src/scenes/MainMenuScene.js:121-161

Dialogue System

The IntroScene uses a dialogue system to present the game's opening narrative. The dialogue is structured as an array of objects, where each object contains the speaker's name and their line of text.

Property	Type	Description
speaker	string	The name of the character speaking (e.g., '내레이션', '고대 신').
text	string	The line of dialogue to be displayed.
action	string (optional)	An identifier for a cinematic action to trigger (e.g., 'change_to_dungeon', 'god_appear').

Sources: src/scenes/IntroScene.js:201-280

The showDialogue function displays the text with a typewriter effect using a timed event. The player can press SPACE to advance the dialogue or ESC to skip the entire intro.

Sources: src/scenes/IntroScene.js:292-313, src/scenes/IntroScene.js:336-345

Character Selection Overlay

In GameScene, players can switch characters by using an overlay UI. This UI is managed by the CharacterSelectOverlay class, which is instantiated in GameScene.

The overlay is triggered by pressing the backtick (`) key.

Sources: src/scenes/GameScene.js:1260-1285, src/scenes/UITestScene.js:268-297

The UI is created dynamically in UITestScene's createCharacterSelectContainer method, which can be seen as a reference implementation. It generates a series of icons based on the available CHARACTER_TYPES, complete with character images and names. A selector highlights the currently chosen character.

Sources: src/scenes/UITestScene.js:178-243

Tutorial System

When a new game is started, the GameScene for the other_cave map instantiates a TutorialSystem. This system guides the player through the basic controls.

The tutorial consists of a series of steps defined in an array within showStep. Each step is an object with a title, description, and duration.

Property	Type	Description
title	string	The title of the tutorial step (e.g., '🎮 움직임').
description	string	The instructional text for the player.
duration	number	Time in milliseconds before the tutorial automatically advances.
isLong	boolean	Optional flag to use a larger UI box for longer text.
isLast	boolean	Optional flag for the final step.

Sources: src/systems/Tutorial.js:81-131

The displayTutorialBox function creates a modal-like UI with a dark overlay, a styled box, title, description text, a progress bar, and a hint to press ENTER to skip to the next step. The tutorial automatically advances after the specified duration or can be manually advanced by the player.

Sources: src/systems/Tutorial.js:147-240

Summary

The UI architecture of Souless effectively separates concerns by using different scenes for different UI contexts. The MainMenuScene and IntroScene handle pre-game interactions, while the GameScene and UIScene work together to provide an event-driven in-game HUD. Reusable, component-like systems such as CharacterSelectOverlay and TutorialSystem are instantiated as needed within the appropriate scenes, creating a modular and maintainable structure for the game's user interface.