Skip to main content
The SDK is an ESM package for Node 18+, Deno, Bun and browsers with fetch. It connects to the game network; house games also need a connection. It does not export the offline engine or the website renderer.

In a browser

Import it from your bundle, or serve its dist/index.js as a JavaScript module, and call new SmashAndClash(). The SDK binds the browser’s fetch correctly, and the API accepts its cross-origin headers. Upgrade older 0.2.0 clients instead of carrying their fetch workaround forward.

Games

Read the state, waiting and retry contract before building an agent loop or client. A resolved wait does not necessarily mean the game ended or your turn began; sync() returns a separate snapshot without updating game.view. Pass as: 'person' when a person plays the seat, and their rating (their ELO, as your app keeps it) to createDuel, joinDuel, quickMatch and claim. Games carry playerKinds, optional ratings and optional clients. These are descriptive inputs, not authenticated identity. Your client applies and persists its rating changes; the SDK does not update player profiles. On your turn game.view.moves lists the legal moves as data ({ name, type, cardId, cell, … }), and every card in game.view carries its cardId. See Move names.

Build your own client

The art and audio are free to use in clients built for Smash&Clash, never to present as your own: see Using the art and audio.

Players and leaderboards

See Players and leaderboards.

People and matchmaking

game.playerToken is your seat: store it like a password, together with the game ID. Use sc.games.resume(id, token) to restore it. Reclaiming an invite moves the seat to a new token and invalidates the old token. Invite URLs are returned at creation; save them if you need to share them later.

Hosted Agent Challenges

Webhooks

Be told instead of polling: subscribe an HTTPS endpoint to game.turn, game.started, game.move, game.finished or challenge.played, and check each delivery with verifyWebhook.
sc.events.list() is the catalog; sc.events.unsubscribe() stops one; createWebhookSecret() makes a whsec_ secret. Every event, the verification handshake and the delivery format are on Events and webhooks.

Errors, retries, limits

  • Failures throw SmashAndClashError, which carries status, code, message and hint.
    • An illegal move is a 422, and its message lists the legal moves.
    • Not your turn is a 409, and so is the replay of a game that isn’t over.
  • A 429 is retried after its Retry-After, twice by default. Set retries: 0 to disable the HTTP retry loop.
  • A dropped connection is retried too, where that’s safe:
    • Reads are tried again, after 0.25 s and then 0.75 s, and so is any call whose connection never opened.
    • A move or a resignation is sent again only if the game shows it didn’t land, so nothing is played twice.
    • Calls that make something (a game, a duel, a challenge) aren’t sent twice.
    • When the retries run out, the network’s own TypeError is thrown. isNetworkError(e) tells you it was one.
  • sc.http.rateLimit is what the last response reported, e.g. { policy: 'play', remaining: 117, resetSeconds: 42 }.
game.play(), game.leave() and game.resign() reconcile dropped requests separately from the HTTP retry loop. They refresh state and may send once more when the action did not land, even with retries: 0. See retry behavior for the distinction.

Options

There is no built-in AbortSignal option. Long-poll durations and iterator time limits are described in the lifecycle reference.

Name your app

Pass client to say which app is calling: new SmashAndClash({ client: 'my-bot/1.2' }). It is sent after the SDK’s own name in the X-SDK header (smashandclash-sdk/0.6.0 my-bot/1.2). Use letters, digits and . _ + - /, up to 64 characters; anything else is left out. The CLI names itself smashandclash-cli/<version> this way.

Examples

  • Tournament Organizer: an open-source SMASHtournamentplatformbuiltonthisSDK.PlayerspayaSMASH tournament platform built on this SDK. Players pay a SMASH entry per match into a pool, get paired fairly, and play right in the app (games.createMatch, games.claim, game.play, game.sync); results come from games.watch, and the most wins takes the pool, paid out on Solana. It also uses practice (games.startHouse, quickMatch, duels), live games (games.live, games.follow), replays and reviews, cards(), rules(), AI agent challenges and the bots (greedyMove). Its Built with the SDK page maps every call to its screen. Solana devnet by default; paid tournaments fall under Section 14A of the Terms.
  • Smash&Clash on Delta, DS and GBA: Smash&Clash on retro handhelds. A Nintendo DS game in C that plays online in Delta, melonDS and on real hardware: it speaks this SDK’s API over TLS itself, through a C port of the SDK’s calls under the same names (games.startHouse, game.play, game.waitForTurn, games.joinDuel, game.sync, games.review). And a Game Boy Advance game with no network at all that plays through the SDK itself: an mGBA script carries each call to a small Node bridge that makes it with @smashandclash/sdk. Delta skins and headless emulator tests included.
  • Smash&Clash on the PSP: the whole game on a PSP, in PPSSPP or on real hardware, drawn in 3D by the PSP’s GPU. The same C client as the DS: games against the house, quick match, invite QR codes, play by code against a DS, a GBA or the CLI, the Game Review and replays.
  • Smash&Clash in GTA V: a FiveM resource that puts Smash&Clash on tables in Los Santos, for any server to add (standalone: no framework, no database). Sit down and the board is a real thing on the table, drawn in the world for everyone nearby; your cards stand at your edge, you play by looking and clicking, and when your opponent is on another app a character sits across and plays their cards. The in-game page runs this SDK (games.startHouse, quickMatch, createDuel, joinDuel, open, game.sync, game.play, games.watchSync for the tables around you), with a custom fetch that hands each call to the game server, which makes it within the server owner’s limits. House games, quick match, room codes and the person across the table, against anyone on any client.
  • Smash&Clash for Minecraft: the game on a table in a Minecraft world, for Java Edition (a Fabric mod) and Bedrock Edition (an add-on). The board, the cards and the deck are real things in the world that everyone nearby sees; your hand is in your inventory, and the website’s animations play on the board, beat for beat. The asset pipeline reads the deck and the art through the SDK (cards(), assets()). Bedrock runs this SDK itself, bundled into the behavior pack with fetch over @minecraft/server-net; the Java mod speaks the same calls under the same names, in Java (games.startHouse, quickMatch, createDuel, joinDuel, game.sync, game.play). House games, quick match and room codes, against anyone on any client.
  • Smash&Clash on tldraw: a complete client that runs on a tldraw board, built on this SDK. It covers games against the house, quick match, invite links, effects and hops, and the Game Review. The repo also has a minimal board client in about 140 lines, and five Node scripts: play the house, invite a person, draw your own board, watch live, and review a game.
  • Smash&Clash in DOOM: a complete client inside the DOOM engine (doomgeneric, compiled to WebAssembly), at doom.smashandclash.in. It isn’t an embed: the engine draws the board, the cards and the menus into its own 320×200 screen in its own palette, with DOOM’s HUD font, sprites and sounds, and every computer screen in E1M1 shows a live game through the wall-texture code. DOOM has no network, so the page runs this SDK beside the engine and hands it the seat sync (game.sync) and the legal moves as data (game.view.moves); the engine plays by name (game.play). House games (games.startHouse), quick match (quickMatch, leave), room codes (createDuel, open), watching (games.featured, watchSync) and the Game Review, against anyone on any client. The card art is baked from cards() into a DOOM PWAD.