Skip to main content

I got tired of rewriting XP and badges code, so I built my own gamification engine

What I learned building Gami.Fied, an open source and self-hosted engine for XP, streaks, badges and leaderboards

Updated 5 min readMarkdown
Part of seriesBuilding Gami.Fied
I got tired of rewriting XP and badges code, so I built my own gamification engine

Every time I started a new side project, I ended up writing the same code again. Points table. Levels table. "Give badge when user does X". A leaderboard query. Then a streak counter that breaks because of time zones.

After the third or fourth time I thought, ok, this should be its own thing. I searched online and almost everything I found was a paid SaaS, and most of them charge you per user. For a side project that is a bad deal, because the moment people actually start using your app, your bill goes up.

So I built Gami.Fied. It is an open source gamification engine that you run on your own server. Your app sends it events, and it takes care of the XP, levels, badges, streaks, challenges and leaderboards.

In this post I want to share how it works and a few things I learned while building it.

The basic idea

Your app should not need to know anything about gamification. It just tells Gami.Fied what happened:

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

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

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

That's it from the app side. Then inside the dashboard you make rules like "a lesson_completed event gives 10 XP" or "if score is above 80, give 5 bonus XP". The rules run in the background, and they update levels, streaks, challenges and badges.

The good thing about this is when you want to change how many points something gives, you don't need to deploy your app again. You just change the rule.

The stack

Nothing very fancy, I picked things I know well:

  • Fastify for the API
  • PostgreSQL with Drizzle for the data
  • Redis with BullMQ for the background jobs
  • Next.js for the dashboard
  • Everything packed in Docker, so you can start it with one docker compose up

The code is a monorepo. Rules, leaderboards, rewards, challenges, notifications and webhooks each have their own package, which keeps things easy to test.

Things that were harder than I expected

1. Streaks and time zones

A daily streak sounds simple. Did the user do something today? Yes, then streak + 1.

But "today" depends on where the user lives. If I count days in server time, a user in India who does a lesson at 11 pm can lose the streak, because for the server it is already the next day. So the streak is counted in each player's own time zone. I also added freezes, so one missed day doesn't kill a 100 day streak. Trust me, people get very sad when that happens.

2. Two people buying the last item

Gami.Fied has a reward store where players can spend coins. When an item has stock of 1 and two people click buy at the same moment, both requests can see "1 left" and both succeed. Now you have sold something that you don't have.

The fix was to do the stock check and the update inside one database transaction with proper locking, so only one of them can win. Small bug, but the kind that only shows up in production.

3. Testing rules before they go live

The scariest moment is publishing a new rule and realising it gives 1000 XP instead of 10. So rules can be saved as a draft first, and you can test a rule against past events to see how much XP it would have given. If something still goes wrong, you can roll back to an older version.

4. Keeping secret keys out of the browser

Players want to see their own progress, so the frontend needs to call the API. But you can never put your API key in the browser. So your server creates a short lived token for one player, and the page uses that. By default these tokens are read only, so a player can see progress but can't change anything.

What it can do today

Right now it has:

  • XP, levels, badges (with tiers and secret badges)
  • Streaks with freezes and reminder emails
  • Challenges, including step by step ones and repeating ones
  • Leaderboards, leagues, teams and friends
  • Coins and a reward store
  • Mystery boxes, spin wheels and season passes
  • A dashboard to manage all of it, with an audit log and team roles
  • A TypeScript SDK, React components, and web components that work in any website

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

Try it

There is a live demo on the website, you don't need to sign up. It comes with example data and deletes itself after a day, so feel free to break things.

If you are building something with users and you have ever thought "it would be nice if this felt a bit more like a game", give it a try. And if something is confusing or broken, please open an issue. I read all of them.

Thanks for reading! A star on GitHub would honestly make my day ⭐

About the author

No comments yet. Be the first to comment.

Building Gami.Fied

Part 1 of 1

The story of building Gami.Fied, an open source and self-hosted gamification engine for XP, streaks, badges and leaderboards. I share what I built, what broke, what I learned, and the decisions behind it, one post at a time.