Leveling and Progression
Relevant source files
The following files were used as context for generating this wiki page:The leveling and progression system in Souless is a core mechanic that governs player and character growth. It features a dual-track system, separating a global "Total Level" from individual "Character Levels". Gaining experience points (EXP) contributes to both tracks simultaneously.
This system is central to the game's progression, as leveling up grants direct stat bonuses, unlocks new skills for specific characters, and serves as a condition for accessing new areas through portals. The entire system is managed by the LevelSystem class, with its state persisted through the SaveSlotManager and visualized in the game via the UIScene and UIExpBar.
Core Architecture: The LevelSystem Class
The LevelSystem class is the heart of the progression system, managing all experience and level calculations for both the total account and individual characters. It is instantiated within the GameScene.
Sources: src/entities/characters/systems/LevelSystem.js, src/scenes/GameScene.js:295
Class Structure
The diagram below illustrates the key properties and methods of the LevelSystem class.
This diagram shows the main components of the LevelSystem class, which manages both total and character-specific progression.
Sources: src/entities/characters/systems/LevelSystem.js:3-20
Key Properties
| Property | Type | Description |
|---|---|---|
level | number | The current Total Level. |
experience | number | The current EXP towards the next Total Level. |
experienceToNext | number | The EXP required to reach the next Total Level. |
totalExperience | number | The cumulative EXP gained for the Total Level. |
characterLevels | Map<string, object> | A map storing the level, experience, and experienceToNext for each character type. |
LEVEL_CURVE | object | A pre-calculated object mapping each level to the EXP required to reach it. |
Sources: src/entities/characters/systems/LevelSystem.js:7-17
Experience Curve
The experience required for the next level follows a defined curve. The base requirement is 100 EXP. For most levels, the requirement increases by 10% (* 1.1). Every 10th level acts as a milestone, where the requirement increases by a more significant 50% (* 1.5).
// src/entities/characters/systems/LevelSystem.js:23-34
buildLevelCurve() {
const curve = { 1: 100 };
let required = 100;
for (let lvl = 2; lvl <= 100; lvl++) {
if ((lvl - 1) % 10 === 0) {
required = Math.floor(required * 1.5);
} else {
required = Math.floor(required * 1.1);
}
curve[lvl] = required;
}
return curve;
}
Sources: src/entities/characters/systems/LevelSystem.js:23-34
Dual Leveling System
The game uses two distinct but related leveling tracks. When a character gains EXP, it is applied to both the Total Level and that specific character's level.
Sources: src/scenes/GameScene.js:380-386
Total Level
This represents the player's overall progression in a save slot.
- Purpose: Unlocks stat bonuses and serves as a condition for certain portals.
- Management: Handled by
level,experience, andtotalExperienceproperties inLevelSystem. - Level-Up Bonus: When the Total Level increases, the current player character receives permanent stat boosts.
Sources: src/entities/characters/systems/LevelSystem.js:7-10, src/scenes/GameScene.js:424-442
Character Level
This tracks the progression of each individual character type (e.g., 'soul', 'assassin', 'monk').
- Purpose: Primarily used to unlock character-specific skills.
- Management: Handled by the
characterLevelsMap inLevelSystem. Each character has its own level, current EXP, and EXP-to-next. - Initialization: If a character has no level data, it is initialized at Level 1.
Sources: src/entities/characters/systems/LevelSystem.js:13, src/entities/characters/systems/LevelSystem.js:37-45
Data Flow and Persistence
Experience Gain Flow
When an enemy is defeated, it triggers an experience gain event. This sets off a chain of updates across the LevelSystem, UIScene, and SaveSlotManager.
The sequence diagram below shows the process from gaining EXP to updating the UI and saving the data.
This diagram shows the flow of events when a character gains experience.
Sources: src/scenes/GameScene.js:375-418, src/scenes/UIScene.js:160-177, src/entities/characters/systems/LevelSystem.js:82-113
Save Data Structure
The leveling progression is stored within the main save data object, managed by SaveSlotManager. The levelSystem object is serialized and saved, which includes both the total level and the map of character-specific levels.
The relationship between the save slot and the leveling data is as follows:
This ER diagram shows how leveling data is structured within a save slot.
Sources: src/utils/SaveSlotManager.js:37-51, src/entities/characters/systems/LevelSystem.js:255-268
The levelSystem object in the save file contains the following fields:
| Field | Type | Description | Source |
|---|---|---|---|
level | number | The current Total Level. | LevelSystem.js:262 |
experience | number | Current EXP for the Total Level. | LevelSystem.js:263 |
experienceToNext | number | EXP needed for the next Total Level. | LevelSystem.js:264 |
totalExperience | number | Cumulative total EXP. | LevelSystem.js:265 |
characterLevels | object | An object where keys are character types and values are their level data. | LevelSystem.js:266 |
UI Representation
The UIScene is responsible for displaying all progression information. It uses UIExpBar to render two separate experience bars at the top of the screen: one for the Total Level and one for the current character's level.
- Total Level Bar: Colored yellow/orange, displays
Total Lv.X | EXP / Next. - Character Level Bar: Colored blue, displays
CHARACTER Lv.X | EXP / Next.
These bars are updated in response to events emitted from the GameScene, such as exp-gained and character-level-up.
Sources: src/ui/UIExpBar.js, src/scenes/UIScene.js:16-33
Progression Unlocks
Leveling up provides tangible benefits that are crucial for game progression.
Stat Bonuses
Each time the Total Level increases, the currently controlled player character receives a permanent stat bonus. The bonuses are larger for milestone levels (every 10th level).
| Stat | Standard Bonus (per level) | Milestone Bonus (every 10 levels) |
|---|---|---|
maxHealth | +5% | +10% |
maxMana | +3% | +10% |
strength | +0.1 | +0.5 |
defense | +0.1 | +0.5 |
Sources: src/scenes/GameScene.js:427-442
Skill Unlocks
New skills for playable characters (excluding 'soul') are unlocked based on the Character Level.
| Level | Skill Unlocked |
|---|---|
| 10 | Q Skill |
| 20 | W Skill |
| 30 | E Skill |
| 40 | R Skill |
Sources: src/systems/Tutorial.js:98-103, src/scenes/UIScene.js:133-141
Portal Unlocks
Certain portals require a minimum level to be unlocked, acting as progression gates.
| Portal ID | Unlock Type | Requirement | Source Map |
|---|---|---|---|
temple_4_to_dark | Total Level | Level 60 | temple_4 |
dark_to_final_map | Character Levels & Boss | Level 40 (all characters) & Defeat 'semi_boss' | dark |
final_map_to_snow | Character Levels | Level 50 (all characters) | final_map |
Sources: src/systems/PortalConditionManager.js:84-110
Conclusion
The Leveling and Progression system is a robust, dual-track framework that ties player effort directly to power and accessibility. The separation of a global Total Level and specific Character Levels allows for both overall account progression and focused development of individual characters. This system effectively drives the gameplay loop by rewarding players with stat increases, new abilities, and access to later stages of the game, making it a fundamental pillar of the Souless experience.