Uploading Games

This guide covers how to prepare, upload, and manage versions of your game on RetiPie.

Upload formats

RetiPie accepts two upload formats:

Single HTML file

If your entire game is contained in one .html file (inline CSS, inline JavaScript, embedded assets), you can upload it directly. The file is validated, scanned for ad scripts, and published as-is.

ZIP archive

If your game has multiple files — HTML, CSS, JavaScript, images, audio, fonts — package them as a .zip archive. This is the most common format for production games.

ZIP structure requirements:

• The archive must contain an index.html file
• index.html should be at the root of the ZIP, or inside a single root folder

RetiPie automatically detects and strips a single common root folder. For example, both of these structures work:

game.zip
  index.html
  style.css
  main.js
  assets/
    player.png

game.zip
  my-game/
    index.html
    style.css
    main.js
    assets/
      player.png

In the second case, my-game/ is automatically stripped so index.html ends up at the root.

What happens during upload

When you upload a game file, the following pipeline runs:

1. Presigned URL — the dashboard requests a secure upload URL. You upload directly to storage, not through the API server.
2. File type detection — after upload confirmation, the server reads the file header to detect whether it's a ZIP or HTML file using magic bytes.
3. Validation — for HTML files: size check, content verification, and ad scanning. For ZIP files: the archive is queued for background extraction and validation.
4. Release creation — a new release version is created automatically. The current active release is archived.
5. File processing — HTML files are copied to their versioned storage path immediately. ZIP files are extracted, each file is validated (content type, size, magic bytes, ad scanning), and then stored.
6. Activation — the new release becomes the active version serving to players.

Version management

RetiPie uses a release-based version system:

• Every upload creates a new version. Version numbers auto-increment (v1, v2, v3, etc.).
• Maximum 3 versions are kept. When a new version is uploaded and the limit is exceeded, the oldest archived version and its files are permanently deleted.
• The latest version is active by default. When you upload, the previous active version is archived and the new one becomes active.

You can view all versions of a game in the game detail page on your dashboard, including their status (active or archived).

Re-uploading and updating

To upload a new version of an existing game:

1. Go to your dashboard
2. Click on the game you want to update
3. Click Upload New Version
4. Upload your updated .html or .zip file
5. The new version is created and activated automatically

Your game stays published throughout this process. The new version replaces the old one as soon as processing completes.

Device preview

After uploading, the dashboard shows a device preview of your game. This renders your game in the same sandboxed iframe environment that players use, so what you see in the preview is what players get.

Use the preview to verify that:

• Your game loads without errors
• Layout and controls work at different screen sizes
• All assets (images, audio, fonts) load correctly
• The game is playable from start to finish

Upload status

For ZIP uploads, processing happens in the background. You can check the status of your upload in the dashboard:

• Processing — the ZIP is being extracted and validated
• Active — processing completed and the version is live
• Failed — extraction or validation failed (check the error message for details)

If a ZIP upload fails, the previous version remains active. Fix the issues and re-upload.

FAQ