Game SDK

Returns the current user or null if not logged in.

const user = await dmnshdGameSDK.user.get();
// { id, username, displayName, avatarUrl, tokens } | null

The tokens field contains the player's current platform token balance. Use this to check if the player can afford an item before calling inventory.purchase().

Returns the absolute URL of the platform's token coin image. Use this to display the token icon in your game's UI (shop screens, price tags, balance displays).

const coinUrl = dmnshdGameSDK.getTokenImageURL();
// "https://cdn.dmnshd.gg/coin.webp"

const img = document.createElement('img');
img.src = coinUrl;
img.width = 24;
img.height = 24;

This is a synchronous method — no await needed. Works before init() is called.

Fetch entries from a leaderboard. If the leaderboard doesn't exist yet, it will be created automatically when the first score is submitted.

const entries = await dmnshdGameSDK.leaderboard.get('default', { limit: 10 });
// [{ rank, score, metadata, createdAt, user: { id, username, ... } }]

Get the current player's own entry on a leaderboard. Returns null if the player has no entry or is not logged in.

const myEntry = await dmnshdGameSDK.leaderboard.getMy('default');
// { rank, score, metadata, createdAt } | null

Get leaderboard entries around the current player's rank. Useful for showing "your neighborhood" on the leaderboard. Returns an empty list if the player has no entry.

const { entries, myRank } = await dmnshdGameSDK.leaderboard.getAroundMy('default', { limit: 3 });
// entries: [{ rank, score, user, ... }]
// myRank: 42 | null

Submit a score. For BEST leaderboards (default), only updates if the new score beats the player's existing entry. For SUM leaderboards, scores accumulate. The SDK caches the player's best score locally to skip redundant server calls. Leaderboards are auto-created on first submission.

const result = await dmnshdGameSDK.leaderboard.postScore('default', 1500, { level: 5 });
// { success, updated, entry: { rank, score, metadata, createdAt } }

Leaderboards support two aggregation modes: BEST (default) keeps only the player's best score, SUM accumulates all submitted scores. Configure this in your game's dashboard.

List all save slots the player has used for this game.

const saves = await dmnshdGameSDK.saveGame.list();
// [{ id, slot, data, createdAt, updatedAt }]

Load data from a specific slot. Returns null if the slot is empty.

const data = await dmnshdGameSDK.saveGame.load(0);
// { level: 5, hp: 100, inventory: [...] } | null

Write data to a slot. Creates or overwrites the existing save.

await dmnshdGameSDK.saveGame.write(0, {
  level: 5,
  hp: 100,
  inventory: ['sword', 'potion'],
});

Delete a save slot.

await dmnshdGameSDK.saveGame.remove(0);

Get all non-secret achievements for this game, including which ones the current player has unlocked.

const { achievements, unlockedKeys } = await dmnshdGameSDK.achievement.getAll();
// achievements: [{ id, key, name, description, iconUrl, points }]
// unlockedKeys: ['first-kill', 'level-up']

Secret achievements won't appear in getAll() but can still be unlocked via unlock().

Unlock an achievement by its key. Safe to call multiple times — returns the existing unlock if already unlocked. Shows an in-game toast notification on first unlock.

const result = await dmnshdGameSDK.achievement.unlock('first-kill');
// { achievement: { key, name, points, ... }, unlockedAt, alreadyUnlocked }

Get all items defined for this game. Returns the full catalog regardless of what the player owns.

const items = await dmnshdGameSDK.inventory.getCatalog();
// [{ slug, name, description, thumbnailUrl, price, type, itemClass, metadata, ... }]

The price field is the token cost. Items with price: 0 are free to grant.

Get the current player's owned items for this game, including quantities.

const owned = await dmnshdGameSDK.inventory.get();
// [{ slug, name, type, ownedCount, acquiredAt, expiresAt, ... }]

Purchase an item for the player. If the item has a token price, the cost is deducted from the player's balance. For stackable items, increments the count. For singular items, only one can be owned.

const result = await dmnshdGameSDK.inventory.purchase('health-potion', 3);
// { success, tokens, item: { slug, name, type, ownedCount, acquiredAt } }
// tokens = updated balance after purchase

Throws an error if the player has insufficient tokens or already owns a singular item.

Use or consume an owned item. Decrements the count for stackable items. Removes the item entirely if the count reaches zero.

const result = await dmnshdGameSDK.inventory.consume('health-potion');
// { success, remaining: 2 }

Browse published levels. Returns metadata only — level data is not included in list results.

const result = await dmnshdGameSDK.levels.list({ sort: 'popular', limit: 10 });
// {
//   data: [{ id, slug, name, creatorName, difficulty, tags, likeCount, playCount,
//            completionRate, thumbnailUrl, publishedAt, ... }],
//   pagination: { page, limit, total, pages }
// }

List the current player's own levels across all statuses (DRAFT, PUBLISHED, ARCHIVED). Use this to let players manage their created levels.

const result = await dmnshdGameSDK.levels.listMy({ limit: 10 });
// {
//   data: [{ id, slug, name, status, difficulty, ... }],
//   pagination: { page, limit, total, pages }
// }

Fetch a published level including its full data payload. Only works for published levels.

const level = await dmnshdGameSDK.levels.get(id);
// { ...metadata, data: { /* your level JSON */ } }

Fetch one of the current player's own levels, including drafts. Useful for previewing a level before publishing.

const draft = await dmnshdGameSDK.levels.getMy(id);
// Returns level at any status (DRAFT, PUBLISHED, ARCHIVED)

Create a new draft level. The level is private until publish() is called. Level data must not exceed 512 KB.

const level = await dmnshdGameSDK.levels.create({
  gameId: 'abc123',
  name: 'The Floating Ruins',
  data: { tiles: [...], spawnPoint: { x: 0, y: 5, z: 0 } },
  difficulty: 'HARD',
  tags: ['platformer', 'ruins'],
});
// { id, slug, status: 'DRAFT', ... }

Update a level's fields. Passing a new data value increments the level's version. Owner only.

await dmnshdGameSDK.levels.update(id, {
  name: 'The Floating Ruins v2',
  data: { tiles: [...], spawnPoint: { x: 0, y: 6, z: 0 } },
  tags: ['platformer', 'ruins', 'hard'],
});

Upload a preview image for a level you own (while the game is embedded on dmnshd.gg). Uses a Blob or File — e.g. from canvas.toBlob(), fetch(...).then(r => r.blob()), or a file input. Max 256 KB; JPEG, PNG, or WebP. Returns the updated level including thumbnailUrl.

const level = await dmnshdGameSDK.levels.uploadThumbnail(levelId, imageBlob);
// level.thumbnailUrl → '/uploads/levels/…' (use with your CDN / site origin)

Make a draft or archived level publicly visible. Owner only.

const level = await dmnshdGameSDK.levels.publish(id);
// { ...level, status: 'PUBLISHED', publishedAt: '...' }

Soft-delete a level. It becomes invisible to other players but is not permanently removed. Owner only.

await dmnshdGameSDK.levels.remove(id);

Toggle a like on a published level. Calling again removes the like.

const { liked, likeCount } = await dmnshdGameSDK.levels.like(id);
// liked: true | false
// likeCount: updated total

Record that a player started playing a level. Call this when the level loads. This increments playCount and is used to calculate the completion rate — so always call it before submitCompletion.

// Call when the level starts
await dmnshdGameSDK.levels.recordPlay(levelId);

Record a completed run. Increments completionCount and updates the completion rate. All fields are optional.

const completion = await dmnshdGameSDK.levels.submitCompletion(levelId, {
  score: 4200,
  durationMs: 93_500,
  metadata: { deaths: 3, coinsCollected: 12 },
});
// { id, levelId, userId, score, durationMs, metadata, createdAt }

Publish the host's room to the matchmaking list and become its owner. Automatically starts a heartbeat (~30s) to keep the lobby alive; if the player closes the tab or loses connection, the lobby is removed within ~60s. Returns the created lobby. Requires login.

const lobby = await dmnshdGameSDK.matchmaking.host({
  peerCode: myPeer.id,
  maxPlayers: 4,
  name: 'Sunday casuals',
  metadata: { map: 'forest', mode: 'ctf' },
});
// { id, peerCode, hostUsername, maxPlayers, currentPlayers: 1, status: 'open', ... }

A player can only host one lobby per game; calling host() while another is active closes the previous one first.

Update the currently hosted lobby. Pass any subset of currentPlayers, maxPlayers, name, status, or metadata. currentPlayers is clamped to maxPlayers; status is auto-derived ('open'/'full') unless you set it to 'in_game' or 'closed'.

await dmnshdGameSDK.matchmaking.update({ status: 'in_game' });
await dmnshdGameSDK.matchmaking.update({ currentPlayers: 3 });

Convenience shortcut for update({ currentPlayers: n }). Call this whenever a peer connects or disconnects on your host so the lobby browser stays accurate.

peer.on('connection', () => dmnshdGameSDK.matchmaking.setPlayerCount(connectedPeers.size + 1));

Close the host's lobby and stop the heartbeat. Safe to call multiple times. The SDK does this automatically if heartbeats fail (e.g. server-side TTL expired). For graceful shutdown, call this from your game's exit / beforeunload handler.

window.addEventListener('beforeunload', () => dmnshdGameSDK.matchmaking.close());

Return all public lobbies for the current game. Sorted by current player count descending (almost-full lobbies first), then by creation time. Private lobbies are excluded.

const lobbies = await dmnshdGameSDK.matchmaking.list();
for (const l of lobbies) {
  console.log(`${l.name ?? l.hostUsername}: ${l.currentPlayers}/${l.maxPlayers}`);
}

Return the best joinable lobby (most current players that still has open slots), or null if none qualify. Doesn't reserve a slot — connect to the returned peerCode, and the host will reflect your join when their player count updates.

const lobby = await dmnshdGameSDK.matchmaking.quickJoin();
if (lobby) {
  myPeer.connect(lobby.peerCode);
} else {
  // No public lobbies — host one instead
}

Fetch a single lobby by id, including private ones. Returns null if the lobby is expired or doesn't belong to this game. Useful for invite links that carry a lobby id.

const lobby = await dmnshdGameSDK.matchmaking.get(invitedLobbyId);

Announce the host's active lobby in the dmnshd.gg Discord with a one-click join link (/games/<slug>?join=<peerCode>). The user must own an active lobby for this game. Rate-limited server-side to once per (user, game) per 5 minutes.

const { success, retryAfterSeconds } = await dmnshdGameSDK.matchmaking.broadcast();
if (!success) showToast(`Try again in ${retryAfterSeconds}s`);

Returns { success: true } on success, or { success: false, retryAfterSeconds } when on cooldown.

Returns the id of the lobby this client is currently hosting (synchronous), or null if none.