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.
| Feature | Status | What to do instead |
|---|---|---|
| JavaScript, WebAssembly, workers | Allowed | |
localStorage, IndexedDB, Cache Storage | Allowed | Read Storage and saves first. |
| Pointer lock | Allowed | Request it from a click or key press. |
| Screen orientation lock | Allowed | Prefer the orientation field. |
window.open(), target="_blank" links | Blocked | Show the URL, or a QR code, in the game. |
| Navigating the top window | Blocked | Keep the game on a single page. |
| Navigating the game to another site | Blocked | Your game's own pages load in its place. Another site's doesn't, under arc serve too. |
alert(), confirm(), prompt(), print() | Blocked | Draw your own dialogs. Blocked calls return immediately without showing anything. |
beforeunload prompts | Blocked | Save continuously instead of asking players to stay. |
<form> submission | Blocked | Handle buttons and the Enter key with your own event listeners. The submit event doesn't fire. |
| File downloads | Blocked | |
Frames: <iframe>, <object>, <embed> | Blocked | Draw everything in your game's own page. |
Permissions
The frame is granted these permissions, and no others.
| Granted | Enables |
|---|---|
autoplay | Audio and video playback, subject to a browser's own autoplay rules; the Arcadible app plays without a gesture. See Input, audio, and lifecycle. |
fullscreen | element.requestFullscreen(), from a click or key press. |
gamepad | The Gamepad API. |
accelerometer | Device motion, for touch-motion and motion. |
gyroscope | Device orientation and rotation rate. |
screen-wake-lock | navigator.wakeLock.request("screen"), to keep the display on during gamepad play or cutscenes. |
cross-origin-isolated | SharedArrayBuffer 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.clipboardreads 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.
- 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_diris 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 anarcadiblefolder at its root. Seedeploy_dir.
Static files
Your build is served as static files, with no server-side code and no configuration.
| Limit | Detail |
|---|---|
| Size | See Limits: 64 MB compressed, 256 MB uncompressed, and 10,000 files. |
| Entry point | index.html at the root of deploy_dir. |
| Directory URLs | A path ending in / serves that directory's index.html. The same path without the trailing slash isn't redirected, and fails. |
| No rewrites | Every 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 paths | Ship.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 headers | You 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 code | PHP, 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.
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, andEventSource, 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 ablob: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:anddata: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-Originto 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
visibilitychangeandblurwithout 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:
| Behavior | Arcadible app | Browser |
|---|---|---|
| Window size | A small window shaped for your orientation, which players may resize; fill it | The browser tab |
| Fullscreen | requestFullscreen() fills the window. Players make the window fullscreen from the app's menu. | requestFullscreen() fills the screen |
| Background | Your game is throttled or paused when its window is minimized or covered | Your game is throttled or paused in hidden tabs |
| Audio autoplay | Allowed without a gesture | Needs a gesture |
| Storage | The app's own storage, separate from any browser | The browser's storage |
| User agent | A plain Chromium user agent | The 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.