Soul Absorb Mechanic

Relevant source files

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

• src/systems/SoulAbsorb.js
• src/scenes/GameScene.js
• src/entities/characters/playable/Soul.js
• src/config/characterData.js
• src/systems/GameScene/GameSceneInitializer.js

The SoulAbsorb system is a self-contained visual effect module responsible for rendering a "spirit" or "soul" that emerges from a specific point and travels towards a target entity, typically the player character. This mechanic provides visual feedback to the player, commonly used when an enemy is defeated and its soul is absorbed.

The system manages its own asset loading, animation creation, and the entire lifecycle of the spirit effect, from spawning to absorption. It is instantiated within the main GameScene and is designed to be triggered by game events, such as an enemy's death.

Sources: src/systems/SoulAbsorb.js, src/scenes/GameScene.js:28,127

Architecture and Components

The SoulAbsorb mechanic is encapsulated entirely within the SoulAbsorb class. It is initialized during the GameScene creation process and relies on Phaser's animation and tweening systems to function.

Sources: src/systems/SoulAbsorb.js:2, src/scenes/GameScene.js:127

Class Structure

The following diagram illustrates the relationship between GameScene and the SoulAbsorb class. GameScene creates and holds an instance of SoulAbsorb to trigger the effect when needed.

Asset and Animation Management

The system is responsible for its own assets. It defines static methods for preloading spritesheets and creating necessary animations, ensuring that all dependencies are met before the effect is used.

Asset Preloading

The preload static method loads the spirit spritesheet. This is called from GameScene.js within the loadCharacterAssets method.

Asset Key	Path	Frame Width	Frame Height
spirit	assets/effects/spirit.png	200px	200px

Sources: src/systems/SoulAbsorb.js:8-12, src/scenes/GameScene.js:112

Animation Creation

The createAnimations static method sets up the spirit_idle animation, which is a looping animation of the spirit effect. This is called from GameScene.create().

Animation Key	Frames	Frame Rate	Repeat
spirit_idle	spirit frames 0-21	22	-1 (infinite)

Sources: src/systems/SoulAbsorb.js:15-24, src/scenes/GameScene.js:126

Execution Flow

The core logic resides in the spawnAndAbsorb instance method. This method orchestrates the entire visual effect, from the spirit's appearance to its disappearance into the target.

Sources: src/systems/SoulAbsorb.js:27-56

spawnAndAbsorb Method

This method takes a starting position (x, y), a target object (e.g., the player character), and an optional onComplete callback.

The following sequence diagram shows the interaction between GameScene, SoulAbsorb, and Phaser's systems when the effect is triggered.

Internal Logic Flow

The internal process of the spawnAndAbsorb method can be broken down into the following steps:

1. A spirit sprite is created at the specified x and y coordinates.
2. The spirit_idle animation is played on the sprite.
3. The sprite waits at its initial position for 500 milliseconds.
4. A tween animation begins, moving the spirit towards the target's position over 400 milliseconds.
5. During the tween, the spirit's destination is continuously updated to track the target's current position.
6. The spirit's scale increases slightly, and its alpha fades to 0 as it approaches the target.
7. Once the tween is complete, the spirit sprite is destroyed.
8. If an onComplete callback was provided, it is executed.

This flow is visualized in the diagram below.

Integration

The SoulAbsorb system is integrated into the GameScene as a standard scene system.

1. Preload & Create: SoulAbsorb.preload() and SoulAbsorb.createAnimations() are called during the scene's preload and create phases, respectively.
2. Instantiation: An instance of SoulAbsorb is created and stored in this.soulAbsorb within the GameScene.create() method.

// src/scenes/GameScene.js

// ... in preload()
this.loadCharacterAssets(); // This method calls SoulAbsorb.preload(this)

// ... in create()
SoulAbsorb.createAnimations(this);
this.soulAbsorb = new SoulAbsorb(this);

Sources: src/scenes/GameScene.js:112,126-127

While the provided files show the initialization, the exact trigger for this.soulAbsorb.spawnAndAbsorb() (e.g., upon an enemy's death) is not present in the analyzed GameScene.js context. It is logically expected to be called within an enemy death event handler, likely before or during experience gain processing (onExpGained).

Sources: src/scenes/GameScene.js:338

Summary

The SoulAbsorb class provides a clean, reusable, and visually appealing effect for the soul absorption mechanic. By encapsulating its own asset loading, animation, and tweening logic, it decouples the visual effect from the core gameplay systems like combat or experience management. Its integration into GameScene is straightforward, allowing it to be easily triggered by any relevant game event to provide immediate feedback to the player.