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 by User Defined

Table of Contents

• 💻 API
  • Postman collection
  • Submit a new score
  • Get game scores
• 📦 Setup
  • MongoDB
  • NodeJS
• 🔧 Customization
  • ✅ Validators
    • Example validator
• 🚀 Ready To Go Clients
  • Godot 4 Client
  • Godot 3.5 Client
• 💡 Game Jam Advice
• 👨‍🔬 Future Goals

💻 API

Postman Collection

There is an up to date Postman collection included in this repo to help test!

You can see it here

And it's under the Release section!

Submit a new score

/games/submit - POST

Request Payload

{
    name: <player name>,
    score: <player score>,
    game: <game key>,
    metaData: { <optional game metadata> },
    validation: <optional validation string>
}

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/<game key> - 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> Number of results to return per page

page - <number> Page to return

📦 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.

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
  • 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
  • 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

🫙 Dockerized Setup

If you have Docker 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

🔧 Customization

✅ 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.

🚀 Ready To Go Clients

Godot 4 Client

Godot 3.5 Client

💡 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

You can optionally use the free hosted version of EasyLeaderboard by pointing your game at https://lb.userdefined.io.

👨‍🔬 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