https://github.com/adrenallen/easyleaderboard
Easy to setup and highly customizable leaderboard with built-in score validation system.
https://github.com/adrenallen/easyleaderboard
game-development godot godotengine leaderboard
Last synced: 3 months ago
JSON representation
Easy to setup and highly customizable leaderboard with built-in score validation system.
- Host: GitHub
- URL: https://github.com/adrenallen/easyleaderboard
- Owner: adrenallen
- License: mit
- Created: 2022-08-28T23:43:35.000Z (about 3 years ago)
- Default Branch: main
- Last Pushed: 2022-09-11T22:42:49.000Z (about 3 years ago)
- Last Synced: 2025-04-01T09:47:24.859Z (6 months ago)
- Topics: game-development, godot, godotengine, leaderboard
- Language: JavaScript
- Homepage:
- Size: 287 KB
- Stars: 15
- Watchers: 1
- Forks: 3
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# EasyLeaderboard
#### **Add a leaderboard to your game in under 10 minutes!**
🏃 Ready to go game clients make adding a leaderboard quick and easy
🕵️ Extendable score validation system to protect against cheaters
👨💻 Open source and easily setup for custom implementations
💸 Optional free-hosting provided at [https://lb.userdefined.io](https://lb.userdefined.io) by [User Defined](https://userdefined.io)
## Table of Contents
- [:computer: API](#computer-api)
* [Postman collection](#postman-collection)
* [Submit a new score](#submit-a-new-score)
* [Get game scores](#get-game-scores)
- [:package: Setup](#package-setup)
* [MongoDB](#mongodb)
* [NodeJS](#nodejs)
- [:wrench: Customization](#wrench-customization)
* [:white_check_mark: Validators](#white_check_mark-validators)
+ [Example validator](#example-validator)
- [:rocket: Ready To Go Clients](#rocket-ready-to-go-clients)
* [Godot 4 Client](#godot-4-client)
* [Godot 3.5 Client](#godot-35-client)
- [:bulb: Game Jam Advice](#bulb-game-jam-advice)
- [:man_scientist: Future Goals](#man_scientist-future-goals)
## :computer: API
### Postman Collection
There is an up to date Postman collection included in this repo to help test!
[You can see it here](EasyLeaderboard.postman_collection.json)
[And it's under the Release section!](https://github.com/adrenallen/EasyLeaderboard/releases)
---
### Submit a new score
`/games/submit` - `POST`
Request Payload
```
{
name: ,
score: ,
game: ,
metaData: { },
validation:
}
```
Response
```
{
"score": {
"game": "easy-leaderboard-example",
"name": "Player Name",
"score": 12,
"metaData": "{test: \"test\"}",
"date": "2022-09-10T00:25:41.068Z"
},
"scoresGreater": 20,
"scoresLesser": 5
}
```
_NOTE: Using a game key that ends with `-basic-validation` will cause that game to automatically use the basic hash check for payload tampering._
---
### Get game scores
`/games/` - `GET`
Response
```
[
{
"game": "easy-leaderboard-example",
"name": "Garrett",
"score": 1003,
"metaData": "{\"metaData\":\"yo\"}",
"date": "2022-09-02T01:42:53.376Z"
},
{
"game": "easy-leaderboard-example",
"name": "Garrett",
"score": 123,
"metaData": "{\"metaData\":\"yo\"}",
"date": "2022-09-02T01:31:41.070Z"
}
]
```
Optional query params
`asc` - `true` Sorts by ascending order if true else defaults to descending by score
`pagesize` - `` Number of results to return per page
`page` - `` Page to return
---
## :package: Setup
There are two requirements to run EasyLeaderboard.
### MongoDB
The recommended way to quickly get an instance of MongoDB running is to use the free tier of MongoDB Cloud. [You can find more about that here.](https://www.mongodb.com/docs/drivers/node/current/quick-start/)
### NodeJS
To run the application itself, you will need to make a copy of `.env.example` and name it `.env`. Fill out the details in the file with your configuration settings. The app can be started via `npm start`.
To make the application reachable and always online, you will want to host it somewhere. Here are a few suggestions.
- [Digital Ocean App Platform](https://docs.digitalocean.com/products/app-platform/quickstart/sample-apps/node/)
- You can fork this repo, then use the Digital Ocean app platform to quickly host the app. Instead of using the `.env` mentioned earlier, you will use the Digital Ocean environment variable settings for the app.
- [Repl.it](https://replit.com/languages/nodejs)
- Repl.it has an always-on tier of subscription. You can fork this repo and Replit can easily import it so you can edit it live. You may also be able to modify the app to use [Replit's key/value DB by using the code from this Replit that adds a layer of abstraction](https://github.com/adrenallen/replit-db-orm)
## 🫙 Dockerized Setup
If you have [Docker](https://www.docker.com/) installed, you can simply run the `docker compose up -d` command to run the whole project in a containerized environment.
Even though this setup is best-suited for local development, it can be used in production too on your own server (VPS, AWS, Digital Ocean...).
You can also use `docker compose --profile=admin-panel up -d` to run a local admin panel for your mongo database.
Docker will use the same .env file used by the Node web server to resolve internal variables. In this way the containers are highly customizable together with the web server itself.
```
# example configuration of .env in development
MONGO_USERNAME=root
MONGO_PASSWORD=example
MONGO_HOST=mongo
MONGO_PORT=27017
MONGO_DB=mygame
PORT=6999
```
## :wrench: Customization
### :white_check_mark: Validators
Validators are custom scripts which can be run to validate a submitted score before it is saved.
Validators are defined under the `/validators` folder. You can make a copy of `/validators/example.js` and fill in your own game's key.
Fill out the `validateScore` function with logic to validate scores that are submitted!
Your app will need to be rebooted for changes to take effect.
#### Example validator
Validates the score by checking if the validation value is equal to the score + 9. You can get creative using the submission metadata to playback game events or check for other anomalies in submissions to make cheating more difficult.
```
module.exports = {
games: ["my-game-key"],
validateScore(game, name, score, metaData, validation){
return validation == score + 9;
},
};
```
_Note: You can define more than one validator for a given game, and they will all be run to validate a score. If any fail, then the submission will be rejected._
## :rocket: Ready To Go Clients
### [Godot 4 Client](https://github.com/adrenallen/EasyLeaderboard-Godot)
### [Godot 3.5 Client](https://github.com/adrenallen/EasyLeaderboard-Godot/tree/godot3.5)
## :bulb: Game Jam Advice
For game jams, you likely will not need more than basic validation.
By using a game key ending with `-basic-validation`, all scores will automatically be checked for payload tampering via a validation hash. This is easily circumvented by anyone that _really_ tries to cheat, but for the sake of quick/short games it will generally suffice to prevent spoofed scores.
If your game can't use a client above, you can [see how basic validation works here](validators/generic_hash.js)
You can optionally use the free hosted version of EasyLeaderboard by pointing your game at [https://lb.userdefined.io](https://lb.userdefined.io).
## :man_scientist: Future Goals
- [ ] Human readable HTML leaderboards for maximum easy mode setup 😏
- [ ] Landing page clean-up
- [ ] Repl.it DB support
- [ ] Firebase support
- [ ] SQLite support
- [ ] Discord integration