furic / leaderboards
RESTful API serving the leaderboards and reporting the scores to your client app.
Fund package maintenance!
Patreon
Tidelift
furic
paypal.me/furic
Requires
- php: ^7.2
- furic/game-essentials: ^1.0
- laravel/framework: ~5.8||~6.0||~7.0||~8.0
README
Leaderboards management for Laravel 5.*. This package is developed while working for a leaderboard solution in Sweaty Chair Studio, serving leaderboards to players. This contains RESTful API for reading the leaderboard in daily, weekly, monthly or all-time period, reporting players' scores to server, as well as getting reward for top ranks.
There are two type of leaderboard:
- Highscore: The standard leaderboard, each player has ONE highest score within the period.
- Score-sum: The leaderboard that summing up all scores reported by each player, e.g. seasonal event for collecting the most in-game items within the period.
The web console is in the TODO list. Meanwhile, you will need to setup the leaderboards in the database manually.
Table of Contents
Installation
Install this package via Composer:
$ composer require furic/leaderboards
If you are using Laravel 5.5 or later, then installation is done. Otherwise follow the next steps.
Open config/app.php and follow steps below:
Find the providers array and add our service provider.
'providers' => [ // ... Furic\Leaderboards\LeaderboardsServiceProvider::class ],
Configuration
To create table for redeem codes in database run:
$ php artisan migrate
Usage
Leaderboards Table
| Name | Type | Not Null |
|-----------------|-----------|----------|
| id | integer | ✓ |
| game_id | integer | ✓ |
| timescope | tinyint | ✓ |
| sum_score | boolean | ✓ |
Leaderboard settings, you would need to set up this mannually.
- Game ID: Which game this leaderboard belongs to.
- Timescope: The repeating period of the leaderboard: 0: all time, 1 - daily, 2 - weekly, 3 - monthly.
- Sum Score: Should we sum the scores for this leaderboard, set to true only if this is a "Score-sum Leaderboard".
Leaderboard Timescopes Table
| Name | Type | Not Null |
|-----------------|-----------|----------|
| id | integer | ✓ |
| leaderboard_id | integer | ✓ |
| start_at | date | ✓ |
| end_at | date | ✓ |
| previous_id | integer | |
Leaderboard Timescopes are the entries for each leaderboard period, for example, a daily leaderboard will have one entry per day. Each entry is created automatically when the first player report score in a new period.
- Leaderboard ID: Which leaderboard this leaderboard timescope belongs to.
- Start At: The date that this leaderboard timescope start.
- End At: The date that this leaderboard timescope end.
- Previous ID: The previous leaderboard timescope ID, used to give the ranking reward of last period.
Leaderboard Scores Table
| Name | Type | Not Null |
|--------------------------|-----------|----------|
| id | integer | ✓ |
| leaderboard_timescope_id | integer | ✓ |
| player_id | integer | ✓ |
| score_sum | integer | ✓ |
| highscore | integer | ✓ |
Leaderboard Scores are the score entries of the players within the leaderboard timescope period. Each entry is created automatically when the player report score.
- Leaderboard Timescope ID: Which leaderboard time scope this leaderboard score belongs to.
- Player ID: Which player this leaderboard score belongs to.
- Score Sum: The score sum of this leaderboard score, used for score-sum leaderboard only.
- Highscore: The highscore of this leaderboard score, used for highscore leaderboard only.
Leaderboard Rewards Table
| Name | Type | Not Null |
|-----------------|-----------|----------|
| id | integer | ✓ |
| leaderboard_id | integer | ✓ |
| score_sum | integer | |
| score_sum_rank | integer | |
| highscore_rank | integer | |
| type | tinyint | ✓ |
| amount | integer | ✓ |
| item_id | integer | |
Leaderboard Rewards are the rewards for players achriving given rank or score sum, optional only if you have rewards for leaderboard and you would need to set up this mannually.
- Leaderboard ID: Which leaderboard this leaderboard reward belongs to.
- Score Sum: The score sum required for this reward, for example, 100 coins for collecting 5 candies in game.
- Score Sum Rank: The score sum rank required for this reward, for example, 100 coins for 5 most collected players.
- Highscore Rank: The highscore rank required for this reward, for example, 100 coins for 5 top score players.
- Type: The reward item type.
- Amount: The reward item amount.
- Item ID: The reward item ID, optional. Notes: Only one number would be set within Score Sum, Score Sum Rank and Highscore Rank; the rest two should be null. The lower ranks would ignore the higher ranks, for example entries of 5 rank and 10 rank, the 10 rank entry would ignore the first 5 rank and only giving reward for rank 5~10.
Leaderboard Player Rewards Table
| Name | Type | Not Null |
|--------------------------|-----------|----------|
| id | integer | ✓ |
| leaderboard_timescope_id | integer | ✓ |
| player_id | integer | ✓ |
| score_sum | integer | ✓ |
| score_sum_rank | integer | ✓ |
| highscore_rank | integer | ✓ |
Leaderboard Player Rewards are the reward entries for each player. Each entry is created automatically when the player obtain a reward.
- Leaderboard Timescope ID: Which leaderboard time scope this leaderboard player reward belongs to.
- Player ID: Which player this leaderboard player reward belongs to.
- Score Sum: The score sum that the player achived, used for score-sum leaderboard only.
- Score Sum Rank: The score sum ranking that the player achived, used for score-sum leaderboard only.
- Highscore: The highscore that the player achived, used for highscore leaderboard only.
API URLs
GET <server url>/api/leaderboards
Returns a JSON array containing all valid leaderboards, for debug purpose only.
GET <server url>/api/leaderboards/{id}
Returns a JSON data containing the leaderboards with given ID, for debug purpose only.
GET <server url>/api/leaderboards/{id}/current
Returns a JSON data containing the current leaderboard timescope and reward info.
GET <server url>/api/leaderboards/{id}/score-sums
Returns a JSON array containing all score-sum entries around the player's score-sum entry.
GET <server url>/api/leaderboards/{id}/highscores
Returns a JSON array containing all highscore entries around the player's highscore entry.
GET <server url>/api/leaderboards/{id}/rewards
Returns a JSON data containing all rewards the player can be obtained in current (score-sum) and previous (rank) leaderboard timescope period.
POST <server url>/api/leaderboards/{id}/score
Reports a score of the player and creates the relevant database entries.
POST <server url>/api/leaderboards/{id}/reward
Reports a reward obtain of the player and creates the relevant database entries.
API Document can be found here.
Unity Client Repo
You can simply import this repo in Unity to communicate with your Laravel server with this package:
<to be added>
TODO
- Create the web console to add/edit leaderboards and upload images.
- Add admin login for web console.
- Add tests and factories.
Alternative Solutions
Before you start running and developing your Laravel server, you should always consider other leaderboard solutions first:
- (Mobile only) App Game Center and Google Play Games leaderboards: highly recommendated for mobile games but not cross-platform and the control such as removing hacker scores is limited.
- dreamlo: A free cross-platform leaderboard service, also limited control.
- GameSparks/Playfab Full game server services including leaderboards, great for mid-core games but require good javascript and daabase knowledge.
License
laravel-leaderboards is licensed under a MIT License.