https://github.com/widgrensit/asobi
Game backend platform built on Nova/OTP
https://github.com/widgrensit/asobi
asobi beam erlang game-backend gamedev leaderboards lua luerl matchmaking multiplayer nova otp realtime websocket
Last synced: 3 days ago
JSON representation
Game backend platform built on Nova/OTP
- Host: GitHub
- URL: https://github.com/widgrensit/asobi
- Owner: widgrensit
- License: apache-2.0
- Created: 2026-03-28T10:31:53.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2026-04-20T17:50:36.000Z (8 days ago)
- Last Synced: 2026-04-20T19:38:07.740Z (8 days ago)
- Topics: asobi, beam, erlang, game-backend, gamedev, leaderboards, lua, luerl, matchmaking, multiplayer, nova, otp, realtime, websocket
- Language: Erlang
- Size: 644 KB
- Stars: 10
- Watchers: 1
- Forks: 0
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Security: SECURITY.md
Awesome Lists containing this project
README
asobi
Multiplayer game backend on Erlang/OTP. Hot-reloadable, Apache-2.
Docs •
Live demo •
Discord •
Issues
Edit a Lua file. Save. Live match updates. No restart. Try it.
---
## Who it's for
Solo devs and small teams building **indie 2D multiplayer**. If you're on
Godot, Defold, LÖVE, Phaser, or Flame+Flutter, asobi ships the backend
pieces you'd otherwise rebuild from scratch: matches, matchmaker, chat,
leaderboards, economy, voting, phases, worlds, presence, inventory.
Not the right fit for twitch-latency AAA shooters — WebSocket/TCP has a
floor around 4ms. Great for turn-based, casual, MMO zone, roguelike,
co-op, party, and social games.
## Try it in 60 seconds
```bash
git clone https://github.com/widgrensit/asobi
cd asobi/examples/hotreload-demo && docker compose up
```
Open , then edit `lua/match.lua` and save — the
running match updates live. No restart, no reconnect, no kicked players.
## Two ways to use asobi
**Write your game in Lua** — use the [**asobi_lua**](https://github.com/widgrensit/asobi_lua)
Docker runtime. One container, hot-reloadable Lua match scripts, batteries
included. No Erlang required. **This is what most people want.**
**Write your game in Erlang** — depend on this library directly. You get the
same match supervisor, matchmaker, leaderboards, economy, world server, and
voting primitives, implemented as OTP behaviours you compose with the rest of
your release.
```erlang
%% rebar.config
{deps, [
{asobi, "~> 0.1"}
]}.
```
## Features
- **`asobi_match`** — behaviour for per-match logic, backed by a supervised `gen_server` with ETS state backup on crash.
- **`asobi_matchmaker`** — pluggable strategies (`fill`, `skill_based`); your own via the `asobi_matchmaker_strategy` behaviour.
- **`asobi_world_server`** — persistent worlds with lazy zones, spatial grid indexing, terrain chunk serving, adaptive tick rates.
- **`asobi_vote_server`** — plurality, ranked choice, approval, weighted. Fixed / ready-up / hybrid / adaptive windows. Spectator voting, veto tokens, majority-tyranny mitigations.
- **`asobi_phase`, `asobi_season_manager`, `asobi_timer`** — phase engine, season lifecycles, five timer primitives.
- **Rate limiting** via `seki` (sliding window, per route group), **sessions** cached in ETS, **presence** via `pg`, **chat / social / economy / inventory / storage / tournaments / notifications** as Nova controllers.
- **Client SDKs** for Godot, Defold, Unity, Unreal, JS/TS, Dart, Flame — [see below](#client-sdks).
## Benchmarks
Single node, 8 cores, same-machine client. See [guides/benchmarks.md](guides/benchmarks.md) for full numbers.
| | Peak |
|---|---|
| WebSocket throughput | **83,000 msg/sec** @ 3,500 concurrent connections |
| RTT p50 / p99 | 4.4 ms / 6.5 ms |
| REST reads (matches / friends / wallets) | 7–14 ms p50 |
| Memory per connection | ~15 KB |
Not a twitch-FPS backend — WebSocket/TCP has a latency floor. Excellent for
turn-based, casual, MMO zone, roguelike, co-op, and party games. Pair with a
UDP relay if you need sub-3ms physics.
## Client SDKs
| Engine | Package | Docs | Example |
|---|---|---|---|
| **Godot 4.x** (GDScript) | [asobi-godot](https://github.com/widgrensit/asobi-godot) | [Guide](https://asobi.dev/godot) | [Demo](https://github.com/widgrensit/asobi-godot-demo) |
| **Defold** (Lua) | [asobi-defold](https://github.com/widgrensit/asobi-defold) | [Guide](https://asobi.dev/defold) | [Demo](https://github.com/widgrensit/asobi-defold-demo) |
| **LÖVE** (Lua) | _asobi-love — ships May 2026_ | — | — |
| **Phaser** (TypeScript) | _asobi-phaser — ships May 2026_ | — | — |
| **Unity 2021.3+** (C#) | [asobi-unity](https://github.com/widgrensit/asobi-unity) | [Guide](https://asobi.dev/unity) | [Demo](https://github.com/widgrensit/asobi-unity-demo) |
| **Unreal Engine 5** (C++) | [asobi-unreal](https://github.com/widgrensit/asobi-unreal) | — | — |
| **TypeScript / JS** (Browser + Node) | [asobi-js](https://github.com/widgrensit/asobi-js) | — | — |
| **Dart / Flutter** | [asobi-dart](https://github.com/widgrensit/asobi-dart) | [Guide](https://asobi.dev/dart) | — |
| **Flame** (Flutter) | [flame_asobi](https://github.com/widgrensit/flame_asobi) | — | [Demo](https://github.com/widgrensit/asobi-flame-demo) |
## Documentation
- [**Getting started**](guides/getting-started.md) — stand up a local asobi node from Erlang
- [**Architecture**](guides/architecture.md) — supervision tree, modules, design
- [**REST API**](guides/rest-api.md) · [**WebSocket protocol**](guides/websocket-protocol.md)
- [**Matchmaking**](guides/matchmaking.md) · [**Voting**](guides/voting.md) · [**World server**](guides/world-server.md) · [**Large worlds**](guides/large-worlds.md)
- [**Economy**](guides/economy.md) · [**Authentication**](guides/authentication.md) · [**IAP**](guides/iap.md)
- [**Lua scripting**](guides/lua-scripting.md) · [**Lua bots**](guides/lua-bots.md)
- [**Configuration**](guides/configuration.md) · [**Clustering**](guides/clustering.md) · [**Performance tuning**](guides/performance-tuning.md)
- [**Benchmarks**](guides/benchmarks.md) · [**Comparison vs Nakama / Colyseus / SpacetimeDB**](guides/comparison.md)
- [**HexDocs**](https://hexdocs.pm/asobi) — full API reference
## Migrating?
- [**from Hathora**](guides/migrate-from-hathora.md) — Hathora shuts down 2026-05-05.
- [**from PlayFab**](guides/migrate-from-playfab.md)
- [**from Nakama self-host**](guides/migrate-from-nakama.md)
## Related projects
- [**asobi_lua**](https://github.com/widgrensit/asobi_lua) — Lua scripting runtime + Docker image (`ghcr.io/widgrensit/asobi_lua`)
- [**asobi-cli**](https://github.com/widgrensit/asobi-cli) — deploy, manage, and scaffold games
- [**asobi_admin**](https://github.com/widgrensit/asobi_admin) — admin dashboard
- Client SDKs: [asobi-godot](https://github.com/widgrensit/asobi-godot) · [asobi-defold](https://github.com/widgrensit/asobi-defold) · [asobi-unity](https://github.com/widgrensit/asobi-unity) · [asobi-unreal](https://github.com/widgrensit/asobi-unreal) · [asobi-js](https://github.com/widgrensit/asobi-js) · [asobi-dart](https://github.com/widgrensit/asobi-dart) · [flame_asobi](https://github.com/widgrensit/flame_asobi)
## Stability
> [!NOTE]
> asobi is pre-1.0. The API is stabilising; expect minor breaking changes
> until 1.0. We will never relicense — see [guides/exit.md](guides/exit.md)
> for the "if asobi disappears tomorrow" runbook.
## Run it yourself, or use the cloud
asobi is Apache-2 and self-hostable. One Docker container runs the full
stack — see [`docker-compose.example.yml`](docker-compose.example.yml) for
a production-shaped setup with Postgres.
Don't want to operate it? [**asobi.dev/cloud**](https://asobi.dev/cloud)
is the managed version — €9/mo Indie tier, EU-sovereign, same open-source
core. If we ever pivot, you still have the code — see
[guides/exit.md](guides/exit.md).
## FAQ
**Does asobi replace Nakama / Colyseus / PlayFab?**
For the indie-2D multiplayer slot, yes. For AAA shooters needing
per-match dedicated UDP servers, no — pair asobi with a UDP relay.
**Can I write my game logic in something other than Lua?**
Yes. Depend on asobi as an Erlang library and write match code in Erlang,
or call the REST/WebSocket API from any language. Lua is the easy mode.
**Does it scale across machines?**
asobi is single-node by design — one BEAM node handles tens of thousands
of connections. Shard at the app level (game-per-node, region-per-node),
don't try to cluster a single match across hosts.
**What happens if asobi disappears?**
Apache-2, single-binary deploy, Postgres backing store. Nothing in your
stack is load-bearing on us. See [guides/exit.md](guides/exit.md).
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md) for the build setup, pre-push
checklist, and test matrix. Security issues: see [SECURITY.md](SECURITY.md).
## License
Apache-2.0. See [LICENSE](LICENSE).