Packaging and upload

Players install your game as a zip, unpacked on their phone, and play it offline. This page is everything about that zip, plus your store page art, plus every error the upload can give you.

The short version#

• One .zip, with index.html at the top.
• Every file inside it: scripts, images, sounds, fonts. Nothing loaded from the internet.
• Relative paths only: img/hero.png, never /img/hero.png.
• Allowed file types only (list below).
• At most 50 MB zipped, 150 MB unpacked, 2000 files.

The zip format#

Here's a typical game folder and the zip made from it:

index.html            <- must be at the top
twiddleplay-sdk.js    <- your copy of the SDK
game.js
style.css
assets/
  sprites.png
  music.ogg
  font.woff2
CREDITS.txt           <- licenses for free assets

What the server does with your zip:

• Looks for index.html at the top. If every file sits inside one top folder (like my-game/index.html), that folder is stripped for you, so zipping the folder itself also works.
• Drops __MACOSX/ and .DS_Store files that macOS adds. You don't need to remove them.
• Re-packs your files into a clean zip that the app downloads, and records its fingerprint (SHA-256) so the phone can check the download.

How to make the zip#

1. Open your game folder.
2. Select everything inside it (Ctrl+A).
3. Right-click > Send to > Compressed (zipped) folder.

1. Open your game folder in Finder.
2. Select everything inside it (Cmd+A).
3. Right-click > Compress.

cd my-game
zip -r ../my-game.zip . -x "*.DS_Store"

Limits#

The server counts the real bytes as it unpacks; it doesn't trust the sizes written in the zip. Smaller is better: players download your game on mobile data, and the upload page warns you when your game unpacks to more than 60% of the limit.

Allowed file types#

Only these extensions are allowed. Anything else rejects the whole upload.

The exact list, for copying into a script:

html htm js mjs cjs css json map png jpg jpeg gif webp avif svg ico bmp mp3 ogg oga wav m4a aac flac opus mp4 webm woff woff2 ttf otf eot txt xml csv md wasm data glb gltf bin atlas fnt plist webmanifest manifest unityweb pck

Things that are not allowed, and what to do instead:

Relative paths#

Your game is not served from the top of a website. It's served from a sub-folder like:

https://<games server>/play/g/<gameId>/<version>/index.html

So a path that starts with / points at the wrong place:

<!-- Good: relative to index.html -->
<img src="img/hero.png">
<script src="game.js"></script>
<link rel="stylesheet" href="./style.css">

<!-- Broken on Twiddle Play: starts at the top of the server -->
<img src="/img/hero.png">
<script src="/game.js"></script>

The same goes for paths in JavaScript and CSS:

heroImage.src = 'img/hero.png';          // good
// heroImage.src = '/img/hero.png';      // broken

/* Paths in CSS are relative to the CSS file */
@font-face { font-family: Pixel; src: url('fonts/pixel.woff2'); }

The only path that should start with / is the platform SDK tag, /sdk/v1/twiddleplay.js.

Offline and self-contained#

Players install your game and often play with no connection. So:

• Bundle every script and library. No <script src="https://cdn...">. Download the library file into your folder.
• Bundle your fonts. No Google Fonts links. Download the .woff2 files and use @font-face.
• No remote config, leaderboards, analytics or ad networks. Only Twiddle Play ads, through the SDK.
• No links to other websites. Games can't navigate away; the app blocks it.

The upload check lists every outside server your files mention (see below), and reviewers reject games that need the internet.

The upload checks#

After a successful upload, your version shows these checks. The reviewer sees them too.

Your store page#

The Store page tab is what players see in the app. Fill it in before you submit.

Icon#

• PNG, JPG or WebP.
• Square (width and height within 2% of each other).
• At least 256×256 and at most 1024×1024 pixels. 512×512 looks best.
• At most 1 MB.
• Your game's face on every shelf: bold, simple, no tiny text.

Screenshots#

• PNG, JPG or WebP, up to 6.
• At most 2 MB each, and the longest side at most 4096 pixels.
• 1080×1920 for portrait games, 1920×1080 for landscape.
• Take them from real gameplay. Drag to reorder them on the store page.

Images that are too big are rejected, never resized for you. If a screenshot is over 2 MB, export it as JPG or WebP.

Every error message, and how to fix it#

These are the exact messages the upload, store page and submit steps can show. Parts in {curly braces} are filled in with your file names and numbers.

Zip upload errors#

Account and limit errors#

Icon and screenshot errors#

Store page errors#

Submit errors#