https://github.com/widgrensit/asobi-godot
Godot 4.x client SDK for Asobi game backend
https://github.com/widgrensit/asobi-godot
asobi client-sdk game-backend gamedev gdscript godot godot-engine godot4 multiplayer sdk
Last synced: about 2 months ago
JSON representation
Godot 4.x client SDK for Asobi game backend
- Host: GitHub
- URL: https://github.com/widgrensit/asobi-godot
- Owner: widgrensit
- License: other
- Created: 2026-03-29T11:58:55.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-04-23T19:28:20.000Z (about 2 months ago)
- Last Synced: 2026-04-23T21:26:15.183Z (about 2 months ago)
- Topics: asobi, client-sdk, game-backend, gamedev, gdscript, godot, godot-engine, godot4, multiplayer, sdk
- Language: GDScript
- Size: 26.4 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# asobi-godot
Godot 4.x client SDK for the [Asobi](https://github.com/widgrensit/asobi) game backend. Tested on Godot 4.4 LTS and Godot 4.5.
## Installation
1. Copy `addons/asobi/` from this repo into your project's `addons/` folder, **or** clone as a git submodule:
```bash
git submodule add https://github.com/widgrensit/asobi-godot.git vendor/asobi-godot
ln -s ../vendor/asobi-godot/addons/asobi addons/asobi
```
For a tagged release (recommended):
```bash
git submodule add -b v0.4.0 https://github.com/widgrensit/asobi-godot.git vendor/asobi-godot
```
2. *Project → Project Settings → Plugins* and tick **Asobi**. Reload the project so Godot picks up the autoload.
The plugin auto-registers an `Asobi` autoload singleton — you do **not** need to add an `AsobiClient` node to your scene.
## Run a backend first
The SDK talks to an Asobi server. The fastest way to get one is:
```bash
git clone https://github.com/widgrensit/sdk_demo_backend
cd sdk_demo_backend && docker compose up -d
```
That serves at `http://localhost:8084` (HTTP + WebSocket on `/ws`) with a 2-player `demo` mode. For the full reference game (arena shooter) see [`asobi_arena_lua`](https://github.com/widgrensit/asobi_arena_lua).
## Quick Start
Use the `Asobi` autoload directly from any script:
```gdscript
func _ready() -> void:
Asobi.host = "localhost"
Asobi.port = 8084
var resp := await Asobi.auth.login("player1", "secret123")
if resp.has("error"):
push_error("Login failed: %s" % resp.error)
return
# match.matched (matchmaker push) and match.joined (reply to a
# client-initiated match.join) both signal "in a match — match.state
# will follow." Subscribe to matchmaker_matched and explicitly join.
Asobi.realtime.matchmaker_matched.connect(_on_matched)
Asobi.realtime.match_state.connect(_on_state)
Asobi.realtime.connect_to_server()
Asobi.realtime.add_to_matchmaker("demo")
func _on_matched(payload: Dictionary) -> void:
Asobi.realtime.join_match(payload["match_id"])
func _on_state(payload: Dictionary) -> void:
var players: Dictionary = payload.get("players", {})
print("Tick %s, %d players" % [payload.get("tick", 0), players.size()])
```
A complete worked example lives at `example/example_usage.gd`. A runnable demo (player vs. player + bots) is at [asobi-godot-demo](https://github.com/widgrensit/asobi-godot-demo).
## Features
- **Auth** - Register, login, token refresh
- **Players** - Profiles, updates
- **Matchmaker** - Queue, status, cancel
- **Matches** - List, details
- **Leaderboards** - Top scores, around player, submit
- **Economy** - Wallets, store, purchases
- **Inventory** - Items, consume
- **Social** - Friends, groups, chat history
- **Tournaments** - List, join
- **Notifications** - List, read, delete
- **Storage** - Cloud saves, generic key-value
- **Realtime** - WebSocket with signals for matches, chat, presence, matchmaking
See the [WebSocket protocol guide](https://github.com/widgrensit/asobi/blob/main/guides/websocket-protocol.md) for the full event surface.
## License
Apache-2.0