Technical Specification: Character Level Up and Bonus Point System - wwestlake/Labyrinth GitHub Wiki

Technical Specification: Character Level Up and Bonus Point System

Overview

This document outlines the design and implementation of a character leveling and bonus point system for the Labyrinth game. The system uses a hybrid progression model for the experience points (XP) required to level up, with configurable settings stored in a CharacterConfig object within MongoDB. The bonus points system allocates a variable number of points per level-up, with random constraints, also configurable via the CharacterConfig.

1. CharacterConfig Object

1.1 Structure

The CharacterConfig object will be stored in MongoDB and contain the following fields:

  • LevelingConfig

    • BaseXP: The base amount of XP required for the first level.
    • XPIncreaseFactor: A multiplier that affects the increase in XP required for each subsequent level.
    • LevelingCurveType: The type of progression curve used (e.g., Linear, Exponential, Logarithmic, Hybrid).
    • HybridTransitionLevel: The level at which the curve transitions from one type to another (only used if LevelingCurveType is Hybrid).

  • BonusPointsConfig

    • BasePoints: The base number of bonus points awarded at each level-up.
    • MinRandomPoints: The minimum number of additional random points awarded.
    • MaxRandomPoints: The maximum number of additional random points awarded.
    • BonusPointsCap: An optional cap on the maximum number of points that can be assigned to a single stat over time.

1.2 Example Configuration

The CharacterConfig will include settings such as the base XP required for the first level, the factor by which XP requirements increase, the type of leveling curve (linear, exponential, logarithmic, or hybrid), and the level at which a hybrid curve transitions. Bonus point configuration will include the base number of points awarded per level, the range of additional random points, and an optional cap on how many points can be assigned to a single stat.

2. Leveling System

2.1 Hybrid Progression Model

The hybrid progression model combines linear, exponential, and logarithmic growth patterns to calculate the XP required for each level. The progression type will change based on the HybridTransitionLevel specified in the CharacterConfig.

  • Linear Progression: This is used for early levels where rapid progression is desired. The required XP increases linearly based on the level.

  • Exponential Progression: Applied after the transition level to significantly increase the difficulty of leveling up. The required XP increases exponentially as the level rises.

  • Logarithmic Progression: Used in very high levels to slow down the progression rate. The required XP increases logarithmically, making each level-up a significant achievement.

2.2 XP Calculation Workflow

  1. Fetch CharacterConfig: When a character is initialized or levels up, the system will retrieve the relevant configuration settings from the CharacterConfig stored in MongoDB.

  2. Determine Progression Type: The system will determine the progression curve to use (linear, exponential, or logarithmic) based on the character's current level and the HybridTransitionLevel.

  3. Calculate Required XP: The system will calculate the XP required for the next level using the appropriate formula based on the progression type.

  4. Reset XP After Level-Up: Once a character levels up, their XP will reset to zero, and the system will begin tracking XP towards the next level.

3. Bonus Points System

3.1 Variable Bonus Points Allocation

The bonus points system will allocate a variable number of points each time a character levels up. The total number of points awarded will consist of a base number plus an additional random number of points within a specified range.

  • Base Points: Each level-up grants a base number of bonus points as defined in the CharacterConfig.

  • Random Points: In addition to the base points, the system will add a random number of points, constrained by the MinRandomPoints and MaxRandomPoints values from the CharacterConfig.

  • Bonus Points Cap: If a BonusPointsCap is defined in the CharacterConfig, it will limit the total number of points that can be assigned to any single stat, ensuring balanced character development.

3.2 Points Allocation Workflow

  1. Calculate Total Bonus Points: Upon leveling up, the system will calculate the total bonus points available by summing the BasePoints with a randomly generated value within the defined range.

  2. Allocate Points: Players will allocate these points to their character’s stats, such as Strength or Intelligence. The system will enforce any caps on maximum stat values as specified in the CharacterConfig.

  3. Persist Stat Changes: The updated stats will be saved back to MongoDB, ensuring that the character's development is persisted across sessions.

4. Data Persistence and Retrieval

All configuration data will be stored in MongoDB under the CharacterConfig collection. This allows for easy updates and changes to the leveling and bonus point system without requiring code changes. Whenever a character is initialized or levels up, the system will retrieve the latest configuration from the database.

5. Extensibility and Future Enhancements

The design of the leveling and bonus point system is flexible, allowing for future enhancements. Potential extensions include:

  • Class-Specific Configurations: Different CharacterConfig settings for different character classes, allowing for unique progression and stat development paths.
  • Dynamic Difficulty Adjustments: Modifying the XPIncreaseFactor or BonusPointsConfig based on in-game events or player performance.
  • Advanced Stat Management: Incorporating more complex rules for stat improvement, such as diminishing returns or cross-stat dependencies.

The system is designed to be modular and scalable, supporting ongoing development and customization to meet the evolving needs of the game.