Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/nabeghe/levex-php
A simlpe leveling and experience (XP) system designed for PHP.
https://github.com/nabeghe/levex-php
Last synced: 13 days ago
JSON representation
A simlpe leveling and experience (XP) system designed for PHP.
- Host: GitHub
- URL: https://github.com/nabeghe/levex-php
- Owner: nabeghe
- License: mit
- Created: 2024-10-14T18:04:10.000Z (about 1 month ago)
- Default Branch: master
- Last Pushed: 2024-10-14T18:06:13.000Z (about 1 month ago)
- Last Synced: 2024-10-14T19:08:17.908Z (about 1 month ago)
- Language: PHP
- Size: 10.7 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
# Levex (Level + Experience)
> A simple leveling and XP System for PHP, Just Like in Online Games.
Building a leveling system that showcases a user's level based on their experience points might seem like a daunting
task.
But fear not! Levex simplifies this process with just a few straightforward methods.
You can effortlessly implement this functionality without diving into complex calculations.
Enjoy a seamless experience as you elevate your users’ journey!
## 🫡 Usage
### 🚀 Installation
You can install the package via composer:
```bash
composer require nabeghe/levex
```
### Instance
#### Default Instance
Retrieve a singleton instance with default options:
```php
use Nabeghe\Levex\Levex;
$levex = Levex::instance();
```
#### Custom Instance
Retrieve a custom instance with custom options:
```php
use Nabeghe\Levex\Levex;
$options = ['baseLevelXp' => 50];
$levex = new Levex($options);
```
Options are related to class fields:
| Name | Description |
|-----------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `baseLevelXp` | XP required to reach level 1. Default `100`. |
| `levelLogBase` | Logarithmic base in calculating the level by XP. Default `3`. |
| `priceXpRate` | XP rate per unit of price. For example, if the rate is 10, every 10 units of a specified price will equal 1 XP. Default `1`. |
| `godLevelSymbols` | Symbols that indicate a level associated with the creator or God, rather than a regular level. Default `['∞']`. |
| `negativeLevelIsGod` | Indicates whether a negative level should be considered as the god/creator or not. Default `true`. |
| `levelNamesHandler` | A callable that acts as a replacement for the determineLevelName method and takes the same input. If determineLevelName returns null, the main method will be executed. Used to customize the name/title of levels. Default `null`. |
### Global Configuration
use kyeword `const` or function `define`.
| Name | Description |
|-------------------------------|-----------------------------------------|
| `LEVEX_BASE_LEVEL_XP` | related to `$levex->baseLevelXp` |
| `LEVEX_LEVEL_LOG_BASE` | related to `$levex->levelLogBase` |
| `LEVEX_PRICE_XP_RATE` | related to `$levex->priceXpRate` |
| `LEVEX_GOD_LEVEL_SYMBOLS` | related to `$levex->godLevelSymbols` |
| `LEVEX_NEGATIVE_LEVEL_IS_GOD` | related to `$levex->negativeLevelIsGod` |
### Methods
#### `calcLevel(int $xp): int`
Calculates which level corresponds to a given XP.
#### `calcRequiredXpToLevel(int $level): int`
Calculates the minimum XP required to reach a specified level.
#### `calcRemainingXpToLevel(int $level, $currentXP, &levelXP = null): int`
Calculates how much XP is remaining to reach a specific level.
**Notice:** The $levelXP is output of the calcRequiredXpToLevel()
#### `calcRemainingPercentToLevel(int $level, int $currentXP, int &$leftXP = 0): float|int`
Calculates how many percent of progress reamining to reaching a specific level.
**Notice:** The $levelXP is output of the remaining XP to reach the desired level.
#### `calcPassedPercentToLevel(int $level, int $currentXP, int &$leftXP = 0): float|int`
Calculates how many percent of progress has been made towards reaching a specific level.
**Notice:** The $levelXP is output of the remaining XP to reach the desired level.
#### `calcXpByPrice($price, ?float $rate = null): int`
Calculates how much XP can be earned from a given price.
Notice: The $rate is XP rate per unit of price.
For example, if the rate is 10, every 10 units of a specified price will equal 1 XP.
Default is option 'priceXpRate'.
#### `checkGodLevel($level): bool`
Checks whether the level is specific to the god or not.
#### `determineLevelName($level): string`
Retrives the name/title of a level.
## 📖 License
Copyright (c) 2024 Hadi Akbarzadeh
Licensed under the MIT license, see [LICENSE.md](LICENSE.md) for details.