Embedding Castle Games

Castle decks are playable in the browser with no install and no sign-in, so they work embedded on another site exactly as they do on Castle. Embedding is supported and encouraged — you don't need permission or an API key.

Quick start

Copy this, replacing DECK_ID with the id from the deck's URL (https://castle.xyz/d/DECK_ID):

<iframe
  src="https://castle.xyz/d/DECK_ID?embed=true"
  width="450"
  height="729"
  frameborder="0"
  scrolling="no"
  credentialless
  allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
  style="border-radius: 10px; max-width: 100%; aspect-ratio: 450/729; height: auto;"
></iframe>

You can also get this from Castle itself: open a deck, choose Share, then Embed.

The embed URL

https://castle.xyz/d/DECK_ID?embed=true

?embed=true swaps the full site chrome for a compact frame — the game, plus a small attribution bar crediting the creator and linking back to Castle. Without it you get the whole deck page, which also works in an iframe but wastes space.

Options

Parameter	Description
embed=true	Use the compact embed chrome.
bg=RRGGBB	Background color behind the card, as a 3- or 6-digit hex value (bg=1a1a1a). Anything else is ignored.

Sizing

The card is 5:7 portrait, with a fixed 99px of chrome below it. So for a given width:

height = round(width × 7/5) + 99

The default 450×729 comes from that formula. To scale it, pick a width and recompute — or let CSS do it, which is what the snippet above does:

aspect-ratio: 450/729;
max-width: 100%;
height: auto;

Don't set an arbitrary aspect ratio. The chrome is a fixed height rather than a proportional one, so a ratio that isn't derived from the formula will letterbox the game or crop the attribution bar.

oEmbed

Castle is a registered oEmbed provider, so many platforms turn a pasted deck link into a playable embed with no work on your part. If yours doesn't, the endpoint is:

https://castle.xyz/api/oembed?url=https%3A%2F%2Fcastle.xyz%2Fd%2FDECK_ID&format=json

It returns a rich response with the iframe HTML ready to insert:

{
  "version": "1.0",
  "type": "rich",
  "provider_name": "Castle",
  "provider_url": "https://castle.xyz",
  "title": "Play verity by @my3terio on Castle",
  "author_name": "my3terio",
  "author_url": "https://castle.xyz/@my3terio",
  "html": "<iframe src=\"https://castle.xyz/d/DECK_ID?embed=true\" ...></iframe>",
  "width": 450,
  "height": 729,
  "thumbnail_url": "https://image.castle.xyz/..."
}

Notes:

• Only JSON is supported. format=xml returns 501.
• maxwidth and maxheight are honored, and the response keeps the correct shape — maxwidth=300 gives 300×519, maxheight=400 gives 215×400.
• Deck pages advertise the endpoint, so oEmbed consumers that auto-discover will find it without being told:

  <link rel="alternate" type="application/json+oembed" href="https://castle.xyz/api/oembed?url=...&format=json" />
• Playlist (/p/) and profile (/@) pages are not oEmbed endpoints. Decks (/d/) only.

For embed platforms

Deck pages publish several kinds of embed metadata, because different platforms accept different things:

Tag	Consumer	Points at
<link rel="alternate" type="application/json+oembed">	oEmbed consumers	The oEmbed endpoint
<link rel="iframely player">	Iframely	The interactive iframe
twitter:card=player, twitter:player	X player cards	The interactive iframe
og:video	Chat apps that only render video files	A short gameplay clip

The interactive iframe is the canonical embed. The og:video MP4 is a recorded gameplay clip published for platforms that can't host an interactive frame — it's a preview of the game, not the game. If your platform can render an iframe, prefer the oEmbed response or the player tags; falling back to og:video gives your users a video where a playable game was available.

Deck pages set no X-Frame-Options and no frame-ancestors restriction, so framing is allowed from any origin.

Good to know

• No account required. Anyone can play an embedded deck without signing in or installing the app.
• Attribution is built in. The embed frame credits the creator and links back to their profile and to Castle. Please leave it intact.
• Sound. Decks may play audio. Browsers generally require the visitor to interact with the frame before audio starts; the allow="autoplay" in the snippet above permits it where the browser does.
• Private and deleted decks won't render. If an embed goes blank, check the deck is still public by opening its URL directly.