Technical requirements
Technical requirements
Size and files#
| Limit | Value |
|---|---|
| Total uncompressed build size | 250 MB |
| Number of files | 1,500 |
| Initial download | 50 MB. Above this the build is rejected. |
| Initial download, mobile target | 20 MB. Above this the validator warns and reviewers test on a phone. |
"Initial download" is what a first-time visitor must fetch before they can play. The upload validator estimates it from the uncompressed size of index.html, every file it references and the engine bootstrap payload (the Unity Build/ folder, Godot .pck and .wasm, Defold archives and scripts). Files you fetch later, after the game is running, do not count, so load levels and audio lazily. Separately, the Preview tool times the first gameplayStart and flags anything later than 20 seconds. For techniques see optimisation tips and first frame fast.
Games hosted on your own server (an https address that allows being framed from zokogames.com) are judged on time to gameplay and only earn if the SDK is integrated.
Relative paths only#
Every asset URL in your build must be relative (assets/hero.png, ./js/game.js). Absolute paths (/assets/hero.png) and hard-coded domains break when we host the game under its own path (games.zokogames.com/<game>/<build>/). Bundlers need a relative base: base: "./" in Vite, homepage: "." in Create React App, publicPath: "" in webpack.
What the validator rejects#
The zip must have index.html at its root (or inside a single top-level folder, which is stripped). The upload is refused when it contains:
- more than 1,500 files, or more than 250 MB unpacked;
- unsafe paths: absolute paths, drive letters,
.., backslashes, control characters, empty segments; - symbolic links, encrypted entries, unsupported compression methods or duplicate paths;
- executable or server-side files:
.php,.exe,.dll,.bat,.sh,.ps1,.jar,.py,.rb,.pl,.cgi,.asp,.jsp,.so,.apk,.lnkand similar, and.htaccess,web.config,php.ini; - suspicious compression ratios (a file over 1 MB that expands more than 200 to 1).
Warnings do not block the upload: __MACOSX and .DS_Store files are ignored, paths that differ only by case, an index.html that does not look like HTML, and a missing SDK script. The validator also detects your engine (Unity, Godot, Construct, GameMaker, Cocos, Defold) and whether the SDK script is referenced.
Iframe#
The game runs in a sandboxed iframe with these tokens: allow-scripts allow-same-origin allow-forms allow-pointer-lock allow-orientation-lock allow-modals allow-downloads allow-presentation. Popups are opt-in per game. Permissions delegated to the frame include autoplay, fullscreen, gamepad, clipboard write, accelerometer, gyroscope, microphone, camera and keyboard map.
Do not rely on window.top, cookies or third-party storage; use the data module. Do not add your own fullscreen button, the portal provides one.
Browsers#
- Chrome and Edge (current versions) are the baseline.
- Safari and Firefox must work as well. A game that fails on a browser can be disabled there.
- A game that does not run smoothly on a low-end 4 GB Chromebook can be disabled on those devices.
Mobile#
- Support touch if you tick mobile in the submission, and keep the same features as desktop.
- Detect the device with
SDK.user.systemInfo.device.type, not with touch events. Laptops have touch screens, and tablets have keyboards. - Orientation is set at submission and the portal prompts players to rotate. You do not need to lock orientation in code.
- On iOS and low-memory Android, cap
devicePixelRatioat 1 for canvases to avoid running out of memory. Unity games are switched off on iOS by default; tick Works on iOS only when you have tested it. - Respect safe-area insets (
env(safe-area-inset-*)) near screen edges, especially inside the mobile app shell whereapplicationTypeis not"web". - Test with the on-screen keyboard open if you have text input.
Audio on iOS#
Mobile Safari starts the AudioContext suspended and only lets you resume it inside a user gesture handler:
const ctx = new AudioContext();
function unlock() {
if (ctx.state !== "running") ctx.resume();
}
window.addEventListener("touchend", unlock, { once: true });
window.addEventListener("click", unlock, { once: true });Also honour SDK.game.settings.muteAudio and silence everything when an ad starts.
Scroll and keys#
The page must never scroll underneath the game. Cancel the default for wheel events and the keys the browser uses to scroll:
window.addEventListener("wheel", (e) => e.preventDefault(), { passive: false });
const SCROLL_KEYS = ["ArrowUp", "ArrowDown", "ArrowLeft", "ArrowRight", "Space"];
window.addEventListener("keydown", (e) => {
const typing = e.target instanceof HTMLInputElement || e.target instanceof HTMLTextAreaElement;
if (!typing && SCROLL_KEYS.includes(e.code)) e.preventDefault();
});Add user-select: none to the body so a drag does not highlight text, and touch-action: none on the canvas.
Sitelock#
You may lock the game to run only on ZokoGames, which stops copies being re-hosted. The portal serves games from zokogames.com and subdomains of it:
const host = location.hostname;
const allowed =
host === "zokogames.com" || host.endsWith(".zokogames.com") ||
host === "localhost" || host === "127.0.0.1"; // keep local development working
if (!allowed) {
document.body.textContent = "Play this game on zokogames.com";
throw new Error("sitelock");
}Never lock to a single exact hostname; we may serve from other subdomains. If the game is embedded elsewhere with your own server, set a Content-Security-Policy such as frame-ancestors 'self' *.zokogames.com.
Privacy#
If your game collects any personal data beyond what the SDK gives you, show a notice and link a privacy policy. Do not load third-party advertising or tracking scripts.