Character Switching

Relevant source files

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

• src/systems/CharacterSwitchManager.js
• src/systems/GameScene/CharacterSwitchHandler.js
• src/systems/GameScene/CharacterSelectOverlay.js
• src/scenes/GameScene.js
• src/utils/SaveSlotManager.js
• src/entities/characters/base/CharacterBase.js
• src/config/characterData.js

The Character Switching system allows the player to dynamically change their active character during gameplay. This feature is central to the game's mechanics, enabling players to leverage different character abilities. The system manages the state of each character, including their position, resources (health, mana), and skill cooldowns, ensuring a seamless transition.

The system is composed of several key components: a UI overlay for selection, a handler for the switching logic, a manager for in-session state, and a save manager for persistent data storage. The entire process is orchestrated within the main GameScene.

Core Components

The character switching functionality is distributed across several key classes, each with a distinct responsibility.

Class	File	Description
CharacterSwitchManager	src/systems/CharacterSwitchManager.js	Manages the in-session state of all available characters for the current map. It saves and loads character states like position and resources.
CharacterSwitchHandler	src/systems/GameScene/CharacterSwitchHandler.js	Orchestrates the entire switching process, from saving the current character's state to creating and restoring the new character.
CharacterSelectOverlay	src/systems/GameScene/CharacterSelectOverlay.js	A UI component that displays available characters and handles user input for selection.
GameScene	src/scenes/GameScene.js	The main scene that initializes and integrates all switching components. It handles user input to trigger the switch.
SaveSlotManager	src/utils/SaveSlotManager.js	Responsible for the persistent storage of character data, such as the current character type, resources, and skill cooldowns.
CharacterBase	src/entities/characters/base/CharacterBase.js	The base class for all characters, providing methods to save and load its own resources (saveResources, loadSavedResources).

This diagram illustrates the relationships between the main components of the character switching system.

User Interaction and UI

The character switching process is initiated by the player through a dedicated UI overlay.

Triggering the Overlay

• The player can press the **Backtick ()** key to toggle the CharacterSelectOverlay`.
• In UITestScene, holding the key for at least 300ms also shows the overlay.

Sources: src/scenes/GameScene.js:1229-1237, src/scenes/UITestScene.js:287-292

The Selection UI

Once visible, the CharacterSelectOverlay presents a horizontal list of available character icons.

• The player uses the Left and Right arrow keys to navigate between characters.
• A visual selector highlights the currently focused character.
• Pressing the Enter key confirms the selection and initiates the switch. In some contexts, releasing the Backtick key also confirms the selection.

Sources: src/scenes/GameScene.js:1239-1254, src/scenes/UITestScene.js:294-310

The following flowchart shows the user interaction flow for character selection.

State Management

To ensure a smooth transition, the system manages two types of state: a temporary in-session state and a persistent state saved to the game's save file.

In-Session State (CharacterSwitchManager)

The CharacterSwitchManager is responsible for caching the state of characters within the current map. This allows for quick restoration of a character's status when switching back to them in the same session.

• The state is stored in a Map called characterStates.
• The key for each state is a combination of the map key and character type: ${this.currentMapKey}_${this.currentCharacterType}.
• The saveCurrentCharacterState method captures a detailed snapshot of the character.

Sources: src/systems/CharacterSwitchManager.js:7-8, src/systems/CharacterSwitchManager.js:68-71, src/systems/CharacterSwitchManager.js:26-28

The following data is saved for each character in-session:

Property	Type	Description
type	string	The character's type (e.g., 'soul', 'monk').
mapKey	string	The map where the state was saved.
position	object	The character's {x, y} coordinates.
health	number	Current health.
mana	number	Current mana.
velocity	object	The character's physics body velocity {x, y}.
facingRight	boolean	The direction the character was facing.
isInvincible	boolean	The character's invincibility status.
skillCooldowns	object	A map of remaining cooldowns for each skill.
timestamp	number	The time the state was saved, used for calculating cooldown decay.

Sources: src/systems/CharacterSwitchManager.js:29-57

Persistent State (SaveSlotManager)

The SaveSlotManager handles writing character data to the player's save slot, ensuring that character progress is maintained between game sessions.

• updateCurrentCharacter(characterType): Updates the currentCharacter field in the save data. This determines which character is loaded when the game starts.
• saveCharacterResources(characterType, hp, mp, stats): Saves the health, mana, and combat stats (strength, defense, maxHealth, maxMana) for a specific character. This data is stored in a nested characters object in the save file.
• getCharacterResources(characterType): Retrieves the saved resources for a character.
• saveAllSkillCooldowns(characterType, cooldowns): Persists the end times of active skill cooldowns.

Sources: src/utils/SaveSlotManager.js:464-472, src/utils/SaveSlotManager.js:514-538, src/utils/SaveSlotManager.js:610-617

The Switching Process

The CharacterSwitchHandler class orchestrates the step-by-step process of swapping the player character. The process is designed to be atomic, preventing other actions while a switch is in progress via an isTransitioning flag.

This sequence diagram details the entire flow, from user input to the new character being ready for control.

Key Steps in the Process

1. Preparation (prepareSwitch): Before the old character is removed, its state is saved.

   • Persistent resources (HP, MP, stats) are saved via SaveSlotManager.
   • In-session state (position, velocity, etc.) is saved via CharacterSwitchManager.
   • Skill cooldowns are also persisted.
     Sources: src/systems/GameScene/CharacterSwitchHandler.js:23-44

2. Transition (performSwitch): This is the core of the switch.

   • An isTransitioning flag is set to true to lock the process.
   • The screen flashes to provide visual feedback.
   • The old player object is destroyed.
   • After a short delay, a new player object of the target type is created.
   • The new character's persistent resources (HP/MP) are loaded via loadSavedResources.
   • The in-session state (velocity, direction) captured from the old character is applied to the new one to maintain momentum.
   • The scene's camera and enemy manager are updated to target the new player.
   • A character-changed event is emitted to notify other systems (like the UI) of the change.
   • The isTransitioning flag is set to false.
     Sources: src/systems/GameScene/CharacterSwitchHandler.js:59-130

Conclusion

The Character Switching system is a well-structured feature that effectively decouples UI, state management, and the core switching logic. By using both in-session and persistent storage, it provides a responsive experience while ensuring player progress is not lost. The use of managers and handlers promotes modularity, making the system maintainable and extensible. The process is carefully orchestrated to save the state of the outgoing character before creating the new one, ensuring a seamless and state-aware transition.