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, up to 5MB), you can upload it directly. The file is validated and scanned for ad scripts, then stored as a new version.

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.
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. SDK feature analysis — RetiPie opens the release in the game sandbox, captures the first screen, detects orientation, and listens for SDK declarations such as leaderboards.
7. Version selection — for a draft, the new release becomes the game's current version right away. For a live game, it waits as a pending version and is sent to review; players keep the approved version until a moderator approves the new one.

Automated checks also flag risky patterns, such as remote scripts, eval, service workers, or code that tries to replace window.retipie. Moderators see these signals during review.

Automatic SDK feature detection

You do not need to manually select whether your game has a leaderboard. Declare it in game code:

retipie.game.configure({
  leaderboards: {
    default: { order: 'desc', unit: 'points', precision: 0 },
  },
});

When the analyzer sees that declaration, the current release is marked as leaderboard-enabled and the feed shows the leaderboard button. If a later release removes the declaration, old scores are kept but the button is hidden for the current release.

RetiPie also scans source files for retipie.leaderboards.submitScore(...) as a fallback, and a score submitted while players play also marks the leaderboard active. The runtime declaration is the preferred signal.

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 newest version becomes current. For a draft this happens as soon as the upload is processed; for a live game it happens once moderation approves the version. The previous version is then archived.
• A new version of a live game is submitted for review automatically. You don't need to press Submit for Review again.

You can view all versions of a game in the Releases card on the game detail page, 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

If the game is a draft, the new version becomes its current version right away. If the game is live, the new version goes to review first, and players keep the approved version until a moderator approves the new one.

Changes to a live game's details work the same way. A new title, description, category, tags or feed preview waits for review, and players see the approved details until then. The same goes for an age rating that lowers the minimum age; a stricter rating applies at once. If a moderator rejects an update, your game stays live as it was and you get an email with the reason.

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 and the upload screen follows it:

• Processing — the ZIP is being extracted and validated
• Completed — processing finished. A draft's new version is now current; a live game's new version is waiting for review
• Failed — extraction or validation failed, and the error message says why

If a ZIP upload fails, the previous version stays as it was. Fix the issues and re-upload.

FAQ