{"id":50115386,"url":"https://github.com/widgrensit/asobi-js","last_synced_at":"2026-05-23T14:34:13.763Z","repository":{"id":353440031,"uuid":"1199473102","full_name":"widgrensit/asobi-js","owner":"widgrensit","description":"TypeScript/JavaScript client SDK for Asobi game backend","archived":false,"fork":false,"pushed_at":"2026-05-01T17:10:10.000Z","size":31,"stargazers_count":0,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-01T19:13:51.523Z","etag":null,"topics":["asobi","client-sdk","game-backend","gamedev","javascript","multiplayer","sdk","typescript","websocket"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/widgrensit.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-02T11:38:20.000Z","updated_at":"2026-05-01T17:10:03.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/widgrensit/asobi-js","commit_stats":null,"previous_names":["widgrensit/asobi-js"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/widgrensit/asobi-js","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/widgrensit%2Fasobi-js","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/widgrensit%2Fasobi-js/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/widgrensit%2Fasobi-js/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/widgrensit%2Fasobi-js/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/widgrensit","download_url":"https://codeload.github.com/widgrensit/asobi-js/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/widgrensit%2Fasobi-js/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33400248,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-23T04:15:53.637Z","status":"ssl_error","status_checked_at":"2026-05-23T04:15:53.242Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["asobi","client-sdk","game-backend","gamedev","javascript","multiplayer","sdk","typescript","websocket"],"created_at":"2026-05-23T14:34:12.830Z","updated_at":"2026-05-23T14:34:13.754Z","avatar_url":"https://github.com/widgrensit.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# asobi-js\n\nTypeScript client SDK for the [Asobi](https://github.com/widgrensit/asobi) game backend. Universal — runs in modern browsers and Node 22+.\n\n## Scope\n\nasobi-js is a thin transport client for the asobi protocol. It connects, authenticates, encodes and decodes message frames, manages reconnection and session resume, and dispatches RPC calls and pubsub subscriptions. That's the whole library.\n\nasobi-js does not provide world or match abstractions, voting, terrain, economy, or any other game-shape helper — those are decisions your game makes, not your transport. Phaser, Three.js, and Pixi integrations live as opt-in adapters under [`examples/`](./examples/), not as a bundled API.\n\nKeeping the core small is deliberate: one library, one job, no surprises in your bundle, no opinions about how your game models itself. If you want game-shape primitives, write them on top of asobi-js — they are 50 lines, not a dependency.\n\n## Status\n\n**Pre-1.0.** The current v0.x publishes additional typed REST helpers (matchmaker, leaderboards, economy, social, etc.) inherited from earlier scaffolding. These are scheduled for removal as the SDK narrows to its protocol-only scope. Build new code against the WebSocket transport described below; treat the typed REST modules as deprecated.\n\n## Installation\n\n```bash\nnpm install @widgrensit/asobi\n```\n\n\u003e **Node 22+ required.** The SDK uses the global `WebSocket` and global `fetch`, both of which are stable in Node 22 and later. For Node 18 or 20, install [`ws`](https://www.npmjs.com/package/ws) and assign it to `globalThis.WebSocket` before importing.\n\n## Run a backend first\n\nThe SDK talks to an Asobi server. The fastest way to get one is the canonical SDK demo backend:\n\n```bash\ngit clone https://github.com/widgrensit/sdk_demo_backend\ncd sdk_demo_backend \u0026\u0026 docker compose up -d\n```\n\nThat serves at `http://localhost:8084` (HTTP + WebSocket on `/ws`) with a 2-player `demo` mode. For the full reference game (arena shooter, boons, modifiers, bots) see [`asobi_arena_lua`](https://github.com/widgrensit/asobi_arena_lua).\n\n## Quick start\n\n```ts\nimport { AsobiWebSocket } from \"@widgrensit/asobi\";\n\nconst ws = new AsobiWebSocket({\n  url: \"ws://localhost:8084/ws\",\n  token: \"your-session-token\",\n});\n\nawait ws.connect();\n\n// Subscribe to server-pushed events on any topic\nws.on(\"match.state\", (payload) =\u003e {\n  console.log(\"tick\", payload.tick);\n});\n\n// Fire-and-forget pubsub publish\nws.send(\"match.input\", { move_x: 1, move_y: 0 });\n\n// RPC: send and await a typed reply\nconst reply = await ws.send(\"match.join\", { match_id: \"abc\" });\nconsole.log(\"joined\", reply);\n\n// Disconnect cleanly\nws.close();\n```\n\nTopics (`match.state`, `world.entity_added`, etc.) are opaque to this SDK — you publish and subscribe to whatever your server emits. See the [WebSocket protocol guide](https://github.com/widgrensit/asobi/blob/main/guides/websocket-protocol.md) for the full event surface.\n\n## API\n\n```ts\nnew AsobiWebSocket({ url, token, reconnect?, reconnectInterval?, maxReconnectAttempts?, heartbeatInterval? })\n\nws.connect(): Promise\u003cRecord\u003cstring, unknown\u003e\u003e\nws.close(): void\nws.send(type: string, payload?: object): Promise\u003cRecord\u003cstring, unknown\u003e\u003e  // RPC\nws.on(event: string, handler: (payload) =\u003e void): void\nws.off(event: string, handler): void\n```\n\nThe `\"*\"` event receives every frame, useful for debugging or building a custom dispatcher.\n\n## Engine and framework adapters\n\nGame-engine and framework integrations live as opt-in examples, not as bundled exports:\n\n- `examples/phaser/` — Phaser 3 helper for driving the SDK from a Scene\n- `examples/three/` — Three.js loop integration\n- `examples/pixi/` — Pixi.js loop integration\n\n(Examples are added as community contributions land.)\n\nThe REST modules under `Asobi` are the v0.x compatibility surface — the long-term direction is protocol-only (everything over `AsobiWebSocket`).\n\n## Browser usage\n\nAnything modern (Chrome / Firefox / Safari / Edge evergreen, iOS Safari ≥15). Bundle with Vite, esbuild, Rollup, or Webpack — the package ships ESM with a `sideEffects: false` hint, so unused subsystems tree-shake out.\n\n## License\n\nApache-2.0\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwidgrensit%2Fasobi-js","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwidgrensit%2Fasobi-js","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwidgrensit%2Fasobi-js/lists"}