https://github.com/bnacci/gamio
Gamio Level System and XP is a Laravel package that adds an experience (XP) and leveling system directly to the user model. It brings RPG-inspired progression mechanics to your application, boosting engagement in social platforms, apps, and other systems
https://github.com/bnacci/gamio
experince gamification laravel level-system levelup
Last synced: about 1 month ago
JSON representation
Gamio Level System and XP is a Laravel package that adds an experience (XP) and leveling system directly to the user model. It brings RPG-inspired progression mechanics to your application, boosting engagement in social platforms, apps, and other systems
- Host: GitHub
- URL: https://github.com/bnacci/gamio
- Owner: bnacci
- License: mit
- Created: 2025-09-29T13:43:53.000Z (8 months ago)
- Default Branch: main
- Last Pushed: 2025-09-29T13:45:08.000Z (8 months ago)
- Last Synced: 2026-03-28T00:42:39.752Z (about 2 months ago)
- Topics: experince, gamification, laravel, level-system, levelup
- Language: PHP
- Homepage: https://packagist.org/packages/bnacci/gamio
- Size: 19.5 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Gamio Level System and Xp
I spent a lot of time trying to find a simple package that would provide me with an effective level and xp system and according to what I was looking for, I tried using some (they are good, but not for me) so I decided to create my own and from that desire Gamio was born.
## Features
- Level and XP
- Badges
- Leaderboard
- User rank
## Installation
IInstall the package via Composer:
```sh
composer require bnacci/gamio
```
Publish the config file:
```sh
php artisan vendor:publish --provider="Bnacci\Gamio\Providers\GamioProvider" --tag="gamio-config"
```
Publish the migration files:
```sh
php artisan vendor:publish --provider="Bnacci\Gamio\Providers\GamioProvider" --tag="gamio-migrations"
```
Publish the view files:
```sh
php artisan vendor:publish --provider="Bnacci\Gamio\Providers\GamioProvider" --tag="gamio-views"
```
Then just add Leveable Trait (Bnacci\Gamio\Traits\Leveable) to User Model:
```php
*/
use HasFactory, Notifiable;
use Leveable; // Add this line to your model
/**
* The attributes that are mass assignable.
*
* @var list
*/
protected $fillable = [
'name',
'email',
'password',
];
/**
* The attributes that should be hidden for serialization.
*
* @var list
*/
protected $hidden = [
'password',
'remember_token',
];
/**
* Get the attributes that should be cast.
*
* @return array
*/
protected function casts(): array
{
return [
'email_verified_at' => 'datetime',
'password' => 'hashed',
];
}
}
```
## Migrations
Migrations
Gamio adds new columns to your users table (xp, level, coins, eligible).
Run the migrations:
```sh
php artisan migrate
```
## Configuration
The config file is located at config/gamio.php.
Here you can customize:
```php
100,
/**
* The user model to be used by the level system.
* This specifies the fully qualified class name of the model that will be used
* to manage users within the system. By default, it's set to the User model in the app.
*/
"user_model" => \App\Models\User::class,
/**
* The limit on how many users should be displayed in the leaderboard.
* This determines how many top users are shown in the leaderboard at a time.
* The default value is set to 10.
*/
"leaderboard_limit" => 10,
];
```
## Usage
You can now use the new methods on your User model.
Add xp to user:
```php
addXp(50);
echo $user->xp; // 50
echo $user->level; // 1 (The initial level is 1 and the maximum level depends on the configuration)
```
Make the user eligible to receive experience points:
```php
eligible(false); // default is true
```
Get user progress:
```php
addXp(300);
return $user->progress;
```
User progress return a json object like:
```json
{
"level": 3, // Current level
"xp": 36, // Current xp for current level
"next_level_xp": 172, // XP for the next level
"next_level": 10, // Next level
"progress": 20.93, // Current level progress
"max_level": false // If the user has the maximum level
}
```
Reset user progress:
```php
reset();
```
Get user rank:
```php
rank; // Return user rank or use @userRank directive
```
Get the leaderboard for all users using leaderboard() method or @leaderboard directive or accessing the /leaderboard route (publish the views to update the leaderboard view)
```php
badges;
```
Note: The level will be generated automatically based on the amount of XP, so there is no method to add levels.
## Badges
To create badges Gamio has an artisan command to make this easier for you, just run:
```sh
php artisan gamio:badge
What's badge name?:
> Gamio
What's level user gain this badge?:
> 10
Do you want to create this badge? (yes/no) [yes]:
> yes
```
The badge will be created in: \App\Gamio\Badges\GamioBadge.php
All badges will have the suffix "Badge" and when creating a new badge Gamio will create the file Badges/UserBadges.php:
```php
\App\Gamio\Badges\GamioBadge::class, // The created badge class
// ...other badges
];
}
}
```
The badge file will contain the following code:
```php