DEV Community

Cover image for I got tired of rebuilding XP and badges for every project, so I made an open-source engine for it
Ronak
Ronak

Posted on

I got tired of rebuilding XP and badges for every project, so I made an open-source engine for it

So this started from a very simple problem.

I work on a few side projects of my own, and almost every time I wanted to add some fun to them. Some points when user completes something, a badge here and there, maybe a leaderboard. And every single time I was writing the same code again. XP table, levels logic, streak counting, "did this user already get this badge", all of it. After the fourth or fifth time I was honestly tired of it.

So I went online to find something ready made. And there are good tools out there, but almost everything was paid. Most of them charge you per user, so the more your app grows the more you pay. And your users data sits on their servers, not yours.

That's why I built Gami.Fied. It's an open-source gamification engine that you run on your own server.

Gami.Fied dashboard showing a weekly leaderboard

What it actually does

The idea is simple. Your app just tells Gami.Fied what happened, like "user finished a lesson" or "user placed an order". You set up rules in a dashboard which decide what that is worth. Then Gami.Fied keeps the score and gives out the rewards.

Things you get:

  • XP and levels
  • Streaks, daily or weekly, in each user's own time zone, with freezes so one missed day doesn't kill it
  • Badges that unlock by themselves, with tiers and secret ones
  • Challenges and journeys where finishing one opens the next
  • Leaderboards for day, week and month, plus leagues where people move up and down
  • Coins and a reward store where users can spend what they earned
  • Fun extras like mystery boxes (with odds shown to players, because it should be fair), a season pass, teams and friends

How it looks in code

From your server you send events:

import { Gami } from '@gami.fied/sdk';

const gami = new Gami({ baseUrl: 'http://localhost:3001', apiKey: 'your_api_key' });

await gami.events.track({
  userId: 'user_123',
  type: 'lesson_completed',
  properties: { score: 100 },
});
Enter fullscreen mode Exit fullscreen mode

That's it. The rules run in the background and the XP, badges and so on are given out.

To show progress to your users, there are ready-made React components:

<GamiProvider endUserToken={token} baseUrl="https://gami.example.com">
  <LevelProgress />
  <Leaderboard period="weekly" />
</GamiProvider>
Enter fullscreen mode Exit fullscreen mode

If you don't use React, there are plain HTML tags also, so it works with Vue, Svelte or a normal HTML page:

<gami-leaderboard period="weekly"></gami-leaderboard>
Enter fullscreen mode Exit fullscreen mode

One thing I was careful about: the browser never sees your API key. Your server makes a short-lived token for that one user, and it's read-only by default.

Running it

It's one Docker Compose file. API, a background worker, the dashboard, Postgres and Redis.

curl -LO https://github.com/gami-fied/gami.fied/releases/latest/download/docker-compose.yml
curl -LO https://github.com/gami-fied/gami.fied/releases/latest/download/env.example
cp env.example .env
docker compose up -d
Enter fullscreen mode Exit fullscreen mode

Fill in a few secrets in .env before starting and the dashboard is up on port 3000.

The license part

The server is AGPL-3.0. The SDK and the UI components are MIT, so you can use them in a closed-source app without any problem.

What's not great yet

I don't want to oversell it, so being honest here:

  • I haven't done a proper big load test yet. If you have a very large number of users, please test it first.
  • Push notifications are tested against test setups, not real Apple and Google accounts yet.
  • The one-click deploy files for Render, DigitalOcean and Coolify are there, but I haven't tried them on those platforms myself.

Try it

I would really like to know what you think. Especially if the API feels easy to use, and which of these features you would actually use and which ones feel like gimmicks. And if you find it useful, a star on GitHub helps a lot for a solo project like this 🙂

Top comments (0)