Character Configuration

Relevant source files

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

• src/config/characterData.js
• src/utils/CharacterConfigBuilder.js
• src/utils/CharacterDataAdapter.js
• src/entities/characters/base/CharacterBase.js
• src/utils/SaveSlotManager.js
• src/entities/characters/systems/LevelSystem.js
• src/systems/Tutorial.js

The Character Configuration system is a comprehensive framework that defines the attributes, abilities, and behaviors of all playable characters in the game. It serves as the single source of truth for character properties, ranging from visual assets and animations to physics, combat mechanics, and skill sets.

This system is primarily driven by a central data file, characterData.js, which contains raw static data for each character. This data is then processed and transformed by utility classes like CharacterDataAdapter and CharacterConfigBuilder into a structured format that game entities, such as CharacterBase, can consume. The system also integrates with persistence layers like SaveSlotManager to save and load dynamic character states, including health, mana, and progression managed by the LevelSystem.

Core Data Source: characterData.js

All static properties for playable characters are defined within the CharacterData object in src/config/characterData.js. This object acts as a database, mapping each character's type (e.g., monk, assassin, soul) to its detailed configuration.

Sources: src/config/characterData.js

Character Data Structure

Each character entry in CharacterData is an object containing several key properties that define its in-game representation and mechanics.

The diagram below illustrates the high-level structure for a single character entry.

Sources: src/config/characterData.js:2-23

The main properties are summarized in the table below:

Property	Description	Example from monk
sprite	Defines the visual assets for the character's sprite, including the spritesheet key, frame dimensions, and default scale.	{ key: 'monk', frameWidth: 288, frameHeight: 128, scale: 2.0 }
base	Specifies the character's default starting coordinates.	{ x: 100, y: 810 }
physics	Contains parameters for the physics engine, such as the collision box dimensions, movement speeds, and jump capabilities.	{ collisionBox: { ... }, walkSpeed: 200, runSpeed: 350, jumpPower: 300, maxJumps: 2 }
combat	Defines core combat mechanics, including the default attack hitbox and the time window for executing combos.	{ attackHitbox: { ... }, comboWindow: 450 }
skills	An object containing detailed configurations for each of the character's skills (e.g., attack, q_skill, e_skill).	See Skill Configuration section below.
animations	An array defining all of the character's animations, including the animation key, frame range, frame rate, and looping behavior.	[{ key: 'idle', frames: { start: 0, end: 5 }, frameRate: 8, repeat: -1 }, ...]

Sources: src/config/characterData.js:2-237

Skill Configuration

The skills object within each character's data is critical, as it defines the behavior of all their abilities. Each key in this object corresponds to a specific skill (e.g., attack, q_skill, s_skill).

A skill's configuration can include:

• type: The skill's category (e.g., instant, movement, channeling).
• icon: Path to the skill's UI icon.
• animation: The animation key to play when the skill is used.
• hitboxSequence: An array defining one or more hitboxes, their timing, damage, and effects. This is the modern approach for defining skill hits.
• cooldown: The time in milliseconds before the skill can be used again.
• cost: The resource cost (e.g., mana) to use the skill.
• invincible: A boolean indicating if the character is invincible during the skill's execution.

Sources: src/config/characterData.js:19-234

Data Processing and Consumption

The raw data from characterData.js is not used directly. Instead, it is processed by adapter and builder classes to create a standardized configuration object that the CharacterBase class and its subsystems can easily consume.

This diagram shows the general data flow from the raw data file to the instantiated character entity.

Sources: src/utils/CharacterDataAdapter.js:10, src/utils/CharacterConfigBuilder.js:4, src/entities/characters/base/CharacterBase.js:11

CharacterDataAdapter

The CharacterDataAdapter class is a modern utility for transforming the raw character data into a format compatible with the game's systems. Its primary method, buildConfig, creates a comprehensive configuration object.

Key responsibilities include:

• Transforming raw physics.collisionBox and combat.attackHitbox data into HitboxConfig objects.
• Converting skill data, including calculating animation durations to determine skill effect durations.
• Providing helper methods like getAnimationConfig and getSkillsData to isolate specific parts of the configuration.

Sources: src/utils/CharacterDataAdapter.js

CharacterConfigBuilder

The CharacterConfigBuilder is an alternative or possibly older class that also processes characterData.js. Its static build method constructs a configuration object for a given character type. A notable feature of this builder is its logic for calculating a skill's duration based on the frame count and frame rate of its associated animation.

// src/utils/CharacterConfigBuilder.js:15-18
const animData = data.animations.find((anim) => anim.key === animKey);
const frameRate = animData?.frameRate || 10;
const frameCount = animData ? animData.frames.end - animData.frames.start + 1 : 0;
const duration = frameCount > 0 ? (frameCount / frameRate) * 1000 : 400;

Sources: src/utils/CharacterConfigBuilder.js:4-59

Integration with CharacterBase

The processed configuration object is passed to the constructor of CharacterBase, the foundational class for all playable characters. CharacterBase uses this configuration to initialize itself and its various subsystems.

The following class diagram shows the relationship between CharacterBase and the systems it initializes using the configuration data.

Sources: src/entities/characters/base/CharacterBase.js:132-159

Upon initialization, CharacterBase performs these key actions:

1. Sprite Creation: Creates the character's physics-enabled sprite using the spriteKey and spriteScale from the config.
2. System Initialization: The initSystems() method instantiates AnimationManager, StateMachine, AttackSystem, and MovementController, passing relevant configuration details to each.
3. Physics Setup: The setupPhysics() method applies the collisionBox dimensions and offset from the config to the sprite's physics body.

Sources: src/entities/characters/base/CharacterBase.js:77-99

Character State Persistence

While characterData.js defines the static, initial state of a character, their dynamic state (e.g., current health, mana, stats, location) is managed and persisted by SaveSlotManager. This ensures that a character's progress is saved between game sessions.

Key Persistence Methods

SaveSlotManager provides several asynchronous methods to save and retrieve character-specific data.

Method	Description
saveCharacterResources(charType, hp, mp, stats)	Saves the current health, mana, and full stat block for a specific character.
getCharacterResources(charType)	Retrieves the saved health, mana, and stats for a character.
saveCharacterStats(charType, stats)	Saves only the stat block (strength, defense, maxHealth, maxMana) for a character.
getCharacterStats(charType)	Retrieves only the saved stat block for a character.
updateCurrentCharacter(charType)	Updates and saves which character is currently active.
savePosition(mapKey, x, y, charType)	Saves the character's current location.

Sources: src/utils/SaveSlotManager.js:410-502

Save State Flow

The following sequence diagram illustrates how a character's resources are saved during gameplay.

Sources: src/scenes/GameScene.js:1310-1318, src/utils/SaveSlotManager.js:428-454, src/entities/characters/base/CharacterBase.js:56-69

Character Progression

Character progression, such as leveling up and unlocking skills, is managed by the LevelSystem. This system tracks experience points on a per-character basis.

• Character-Specific Levels: The LevelSystem maintains a Map called characterLevels to store the level, current XP, and XP to the next level for each character type.
• Skill Unlocks: Skills are unlocked based on character level. For example, the tutorial states that skills unlock at levels 10, 20, 30, and 40.
• Persistence: The LevelSystem uses SaveSlotManager to persist its data, ensuring that character levels and experience are saved. It serializes its state, including the characterLevels map, into a plain object for storage.

Sources: src/entities/characters/systems/LevelSystem.js:10-30, 203-222, src/systems/Tutorial.js:105-111

Summary

The Character Configuration system is a well-defined, data-driven architecture. It effectively decouples character data (characterData.js) from game logic (CharacterBase and its subsystems). This separation allows for easy modification and addition of new characters by simply defining their properties in the central data file. The use of adapters ensures that this raw data is transformed into a consistent, usable format. Finally, the integration with SaveSlotManager and LevelSystem provides a robust mechanism for persisting dynamic state and handling character progression, making it a cornerstone of the game's design.