Skip to main content

Runtime

Games run in the Arcadible sandbox: a page of their own, on an origin of their own, in a frame of the play page. WebGL, WebGPU, WebAssembly, threads, audio, gamepads, fullscreen, and pointer lock are available. This page is what a game can rely on there, and what it can't.

Limitations​

Popups, native dialogs, downloads, top-level navigation, frames, files from other sites, connections to hosts you don't list, the camera, the microphone, and location aren't available. The restrictions isolate games from each other and from Arcadible, and keep behavior consistent wherever Arcadible runs games.

To test under the sandbox on your machine, run arc serve. To test on Arcadible itself, deploy a prerelease to staging and play it with arc play -r staging.

The sandbox​

The frame's sandbox allows scripts, same-origin storage, pointer lock, and orientation lock. No other sandbox flags are set. Your build carries the same sandbox in its own headers, so it applies wherever the build loads, at its own address too.

FeatureStatusWhat to do instead
JavaScript, WebAssembly, workersAllowed
localStorage, IndexedDB, Cache StorageAllowedRead Storage and saves first.
Pointer lockAllowedRequest it from a click or key press.
Screen orientation lockAllowedPrefer the orientation field.
window.open(), target="_blank" linksBlockedShow the URL, or a QR code, in the game.
Navigating the top windowBlockedKeep the game on a single page.
Navigating the game to another siteBlockedYour game's own pages load in its place. Another site's doesn't, under arc serve too.
alert(), confirm(), prompt(), print()BlockedDraw your own dialogs. Blocked calls return immediately without showing anything.
beforeunload promptsBlockedSave continuously instead of asking players to stay.
<form> submissionBlockedHandle buttons and the Enter key with your own event listeners. The submit event doesn't fire.
File downloadsBlocked
Frames: <iframe>, <object>, <embed>BlockedDraw everything in your game's own page.

Permissions​

The frame is granted these permissions, and no others.

GrantedEnables
autoplayAudio and video playback, subject to a browser's own autoplay rules; the Arcadible app plays without a gesture. See Input, audio, and lifecycle.
fullscreenelement.requestFullscreen(), from a click or key press.
gamepadThe Gamepad API.
accelerometerDevice motion, for touch-motion and motion.
gyroscopeDevice orientation and rotation rate.
screen-wake-locknavigator.wakeLock.request("screen"), to keep the display on during gamepad play or cutscenes.
cross-origin-isolatedSharedArrayBuffer and threads. See Cross-origin isolation.

Not available:

  • Camera and microphone. No getUserMedia(), so no voice chat or photo capture.
  • Location. No Geolocation API.
  • Clipboard. No navigator.clipboard reads or writes.
  • Sharing. No Web Share API. Players share your game from Arcadible.
  • Payments. No Payment Request API.
  • Device APIs. No WebXR, Web MIDI, WebUSB, WebHID, Web Serial, or Web Bluetooth.

On iOS and iPadOS, device motion also needs the player's consent: call DeviceMotionEvent.requestPermission() from a tap before you read the sensors.

How your game is loaded​

Every play link, such as https://play.arcadible.com/star-drift/, is a page that embeds your build in a full-size, sandboxed frame.

The play page at play.arcadible.com holds your game in a sandboxed frame from its own site ID on arcadible.io play.arcadible.com/star-drift/ site-id.arcadible.io

  • Each build has its own origin. Every deploy is published to a new https://<site-id>.arcadible.io/, where <site-id> is unique to that build. Two versions of your game are two different origins, which matters for saves and for your servers.
  • Your game is at the root. deploy_dir is served at /, so relative and root-relative paths both work. Prefer relative paths, which also work when the build is served from a subdirectory during local testing.
  • The play link's query string and hash aren't passed on. The frame always loads https://<site-id>.arcadible.io/, whatever follows the play link.
  • The Arcadible app uses the same play page, so everything here applies there too, with a few differences.
  • Play pages can't be embedded in other sites.
  • /arcadible/ is Arcadible's. Every build's origin serves the Arcadible SDK at /arcadible/sdk/v1.js, with its source map, and nothing else in /arcadible/, so your build can't have an arcadible folder at its root. See deploy_dir.

Static files​

Your build is served as static files, with no server-side code and no configuration.

LimitDetail
SizeSee Limits: 64 MB compressed, 256 MB uncompressed, and 10,000 files.
Entry pointindex.html at the root of deploy_dir.
Directory URLsA path ending in / serves that directory's index.html. The same path without the trailing slash isn't redirected, and fails.
No rewritesEvery URL maps to exactly one file. Client-side routes like /level/3 return an error, so use the hash (#/level/3) or in-memory state instead.
Case-sensitive pathsShip.png and ship.png are different files. A build that works on macOS or Windows can fail on Arcadible because of a case mismatch.
No custom headersYou can't set headers per file. Builds that rely on the server adding Content-Encoding to precompressed .br or .gz files won't load; see below.
No server-side codePHP, API routes, and server functions don't run. Host your backend separately; see Networking.

Compressed engine builds​

Some engines, including Unity and some Godot templates, can emit files that are already Brotli- or gzip-compressed and expect the server to label them with Content-Encoding. Arcadible serves each file as it is, so either:

  • disable compression in the engine's build settings, or
  • enable a decompression fallback, such as Unity's Decompression Fallback option, which decompresses the files in JavaScript.

Cross-origin isolation​

Play pages are cross-origin isolated, and delegate isolation to your game. SharedArrayBuffer is available, so multithreaded engine exports, such as Godot with threads or Emscripten builds with pthreads, run.

Isolation needs nothing from you: everything your game loads comes from its own build (Networking), which is served with the headers isolation needs.

Storage and saves​

Each version of your game starts with empty browser storage. Each build has its own origin, so whatever a version keeps in localStorage, IndexedDB, or Cache Storage stays with that version, and your next release can't read it. To keep progress, settings, and preferences across versions, use saves, which the play page keeps for your game. Browser storage stays the place for what a version can rebuild, such as a cache or downloaded content.

Version 1.0 has its save; version 1.1 starts with empty storage and can't reach the old save 1.1.0 A version 1.2.0 A version save Its save Empty No save carried over

Browser storage, saves included, is also separated:

  • Per browser and per app. Progress in a browser isn't visible in the Arcadible app or another browser.
  • Per embedding site. Browsers partition a frame's storage by the page it's in, so opening https://<site-id>.arcadible.io/ directly shows different data. Saves are the play page's, so they aren't partitioned.
  • Evictable. Browsers can clear it when space runs low or the player clears site data. Safari clears it after seven days of use without a visit to Arcadible (WebKit).

Builds don't support cookies. Every build's origin is under arcadible.io, which browsers treat as one site, so a cookie your game sets can be read or replaced by other games. Most browsers also block or partition a frame's cookies. Keep progress in saves, and use tokens for your servers.

Networking​

Your game reaches its own build: its files, and the Arcadible SDK, which talks to Arcadible for it. It can also connect to the hosts you list in client.outbound_hosts, such as your own API. Everything else is refused, by a content security policy your build is served with.

  • Listed hosts are for connections: fetch(), XHR, WebSockets, WebTransport, and EventSource, over HTTPS and WSS, on the default port. Up to 8, each by its exact name.
  • Everything else comes from your build: your engine, its libraries, fonts, and every image, sound, and video, rather than loading them from a CDN or a font service. To show an image from a host, fetch() it and use a blob: URL.
  • Anything not listed is refused. A request to another site fails as a network error, and the console reports it as a Content Security Policy violation.
  • blob: and data: URLs work, for what your game makes itself, such as a generated image or a worker's script.
  • CORS for your hosts. Each must send Access-Control-Allow-Origin to your game, as for any cross-origin request.
  • Authenticate with tokens, not cookies, which builds don't support.

The origin changes every build. Have your hosts accept any origin ending in .arcadible.io, or send Access-Control-Allow-Origin: *. A fixed allowlist works for the build you test, and breaks on the next deploy.

Under arc serve, your own machine is reachable too, without listing it, so a local server beside your game answers it.

Input, audio, and lifecycle​

  • Gestures. In a browser, audio, fullscreen, pointer lock, and the iOS motion permission all need a click, tap, or key press, and must be requested in its handler. The Arcadible app plays audio without one (The Arcadible app and browsers). See Make the first touch part of the game.
  • iPhone. Safari draws a game in its frame at a reduced frame rate until the game plays sound, which needs a tap. If your opening needs smooth motion, ask for that tap first: a title the player taps to start works.
  • Focus. The play page focuses your frame when it loads, so key presses reach it immediately.
  • Escape always exits fullscreen and pointer lock. You receive the key press, but can't stop it.
  • Gamepads appear only after the player presses a button. Listen for gamepadconnected.
  • Closing. Nothing warns players before they close your game. Before Arcadible closes or reloads it, it pauses it, and waits a moment for your pause listener to save. See Pause, save, and resume.
  • Background. Browsers throttle hidden tabs, and the Arcadible app throttles a game's window the same way when it's minimized or covered. Pause when Arcadible says, with the SDK's pause, or on visibilitychange and blur without it; see Pause, save, and resume.

The Arcadible app and browsers​

A game that works in a browser works in the Arcadible app, with these differences:

BehaviorArcadible appBrowser
Window sizeA small window shaped for your orientation, which players may resize; fill itThe browser tab
FullscreenrequestFullscreen() fills the window. Players make the window fullscreen from the app's menu.requestFullscreen() fills the screen
BackgroundYour game is throttled or paused when its window is minimized or coveredYour game is throttled or paused in hidden tabs
Audio autoplayAllowed without a gestureNeeds a gesture
StorageThe app's own storage, separate from any browserThe browser's storage
User agentA plain Chromium user agentThe browser's

Your game can't tell the Arcadible app from a browser, and shouldn't need to. Detect capabilities instead, such as matchMedia("(pointer: coarse)") for touch.