How to Package, Optimize & Upload Your HTML5 Game to BentoTiles (Step-by-Step)

Shipping an HTML5 game to a global web portal should be an exhilarating milestone, not an exercise in debugging broken asset paths and rejected ZIP archives. Yet, over 65% of first-time web game submissions to portals fail initial automated quality assurance (QA) because of a handful of preventable technical oversights: absolute path references, missing root entry files, unhandled Web Audio autoplay policies, or unscaled mobile canvas viewports.

At BentoTiles, we host approved games inside isolated, high-performance Cloudflare R2 edge containers served over secure HTTPS. This architecture guarantees blazing-fast, sub-2-second loading and bulletproof sandboxing—but it also requires that your game archive adheres to clean, standardized web packaging practices.

Whether you built your game using Phaser 3, Godot 4, Construct 3, PixiJS, Three.js, or Vanilla JavaScript Canvas, this step-by-step technical guide covers everything you need to package, optimize, test, and upload your game for seamless approval on BentoTiles.

---

Step 1: Exporting Clean Web Builds from Your Engine

Every major game development framework supports HTML5/WebAssembly export, but default export templates often include desktop or development clutter. Here is how to configure your build for optimal browser delivery:

Phaser 3 & PixiJS (Vite / Rollup / Webpack)

• Base Public Path: When building with bundlers like Vite, always configure the base URL to relative (./):

// vite.config.js
export default {
  base: './', // Crucial for relative asset loading
  build: {
    outDir: 'dist',
    assetsDir: 'assets',
  }
}

• Avoid External CDN Dependencies: Bundle your vendor libraries (such as Phaser, Howler, or Socket.io-client) directly into your bundle rather than relying on unpinned external cdnjs.cloudflare.com or unpkg.com tags. School campus filters and strict ad-blockers frequently block external third-party CDN scripts, causing your game to fail on student Chromebooks.

Godot 4 (HTML5 Web Export)

• Threads / SharedArrayBuffer: By default, Godot 4 exports utilize multi-threading, which requires specific Cross-Origin-Opener-Policy (COOP) and Cross-Origin-Embedder-Policy (COEP) headers. For maximum compatibility across web portals, export using the Single-Threaded build option if your game does not strictly require multi-threaded physics.
• VRAM Texture Compression: Enable VRAM texture compression (WebP / Basis Universal) to drastically reduce the size of your .pck package.
• Export Files: Your export output will generate:

- index.html (rename the export file to index.html)

- index.js

- index.wasm

- index.pck

Place all four files directly at the root of your ZIP archive.

Construct 3 & GDevelop

• In Construct 3, choose Project → Export → HTML5.
• Check Minify Script to strip whitespace and obfuscate variable names.
• Uncheck "Deduplicate images" if it generates complex symbolic links that fail in standard ZIP extractions.

Vanilla JavaScript & Canvas2D

• If you developed your game without an engine, organize your project into a clean folder structure:

my-game-zip/
├── index.html       <-- Absolute root of the archive
├── style.css
├── js/
│   ├── main.js
│   └── game.js
└── assets/
    ├── sprites/
    └── audio/

---

Step 2: The Golden Rule of Relative Paths & Cloudflare R2 Sandboxing

This is the single most common reason game submissions fail automated QA.

When your game is uploaded to BentoTiles, it is not hosted at the domain root (e.g. https://bentotiles.com/assets/player.png). Instead, it runs inside an isolated, sandboxed subfolder served from our global Cloudflare R2 edge storage:

https://games.bentotiles.com/games/[your-game-slug]/index.html

The Difference Between Absolute and Relative Paths

• ❌ Absolute Root Path (BROKEN):

  <img src="/assets/player.png">
  <script src="/js/engine.js"></script>

In the browser, this tells the client to look at https://games.bentotiles.com/assets/player.png, which does not exist! Your sprites will fail to load with a 404 error, and your canvas will display a blank screen.

• ✅ Relative Path (CORRECT):

  <img src="./assets/player.png">
  <!-- Or simply: -->
  <img src="assets/player.png">

This tells the browser to resolve the asset relative to the current index.html directory (https://games.bentotiles.com/games/[your-game-slug]/assets/player.png). Every texture, sprite sheet, audio file, JSON level data, and WebAssembly binary must use relative paths.

Index.html Must Sit at the Absolute Root of the ZIP

When compressing your files into a .zip archive, select the contents of your build directory—do not zip the parent folder itself.

• ❌ Incorrect ZIP structure: MyGame.zip/MyGameFolder/index.html
• ✅ Correct ZIP structure: MyGame.zip/index.html (with assets directly beside it)

Ensure all file names are lowercase and avoid spaces or special characters (e.g., use boss_level_1.png instead of Boss Level #1 (Final).png). Cloudflare R2 and Linux storage clusters are strictly case-sensitive.

---

---

Step 3: Supporting Responsive Viewports, Touch & Audio Autoplay

To earn a top rating and reach maximum players on BentoTiles, your game should run smoothly on both desktop monitors and mobile touchscreens.

1. Viewport Meta Configuration

Ensure your index.html includes a responsive viewport meta tag inside the to prevent unwanted pinch-to-zoom gestures and mobile letterbox distortion:

<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no, viewport-fit=cover">

Add CSS to lock the canvas dimensions and disable elastic bounce scrolling:

html, body {
  margin: 0;
  padding: 0;
  width: 100%;
  height: 100%;
  overflow: hidden;
  background-color: #000;
  touch-action: none; /* Prevents default browser swipe-to-refresh */
}
canvas {
  display: block;
  width: 100%;
  height: 100%;
  object-fit: contain; /* Preserves your aspect ratio with clean borders */
}

2. Touch Events and Dual Controls

Don't limit your audience to desktop keyboards. If your game uses WASD or Arrow Keys for movement:

• Provide on-screen virtual buttons or swipe gesture detection on touch-enabled devices ('ontouchstart' in window).
• Map physical key listeners using both e.code and e.key (e.g. KeyW and ArrowUp) for international keyboards.

3. The Web Audio Autoplay Policy

Modern browsers (Chrome, Safari, Firefox, and Edge) automatically block audio playback until the player interacts with the document via a click or tap gesture.

If your game attempts to play background music immediately upon initialization, the browser will throw an unhandled AudioContext was not allowed to start exception, occasionally muting all subsequent game audio.

// Resume AudioContext on first user interaction
function unlockAudio() {
  if (myAudioContext && myAudioContext.state === 'suspended') {
    myAudioContext.resume().then(() => {
      console.log('AudioContext successfully unlocked');
    });
  }
  window.removeEventListener('click', unlockAudio);
  window.removeEventListener('touchstart', unlockAudio);
  window.removeEventListener('keydown', unlockAudio);
}

window.addEventListener('click', unlockAudio);
window.addEventListener('touchstart', unlockAudio);
window.addEventListener('keydown', unlockAudio);

---

Step 4: Metadata That Drives High-CTR Player Clicks

When players browse the BentoTiles bento grid, your metadata determines whether they click into your game or scroll past. Optimizing your submission metadata directly increases your initial play counts:

1. Title: Punchy, clear, and memorable (e.g., Neon Drift Pursuit or Bento Tank Duel). Avoid version numbers, brackets, or generic filler like "My First Game v1.2".
2. Tagline: A single high-impact sentence under 80 characters that communicates the core hook (e.g., "High-speed 2-player tank warfare with ricochet cannonballs on a single keyboard.").
3. Gameplay Description: Write 2 to 4 descriptive paragraphs explaining the objective, mechanics, special powerups, and win conditions. Clear descriptions help Google index your game's dedicated landing page.
4. Controls Legend: Detail exact control bindings for all players:

- Player 1: WASD to steer, Space to shoot

- Player 2: Arrow keys to steer, Enter to shoot

- Mobile: Left virtual joystick to steer, right tap button to fire

1. High-Contrast 1280×720 Thumbnail: Your thumbnail is your game's movie poster. Show actual gameplay action with vibrant colors and bold silhouettes. Avoid tiny unreadable text or blank title screens.
2. Genre & Keyword Tags: Tag your submission with high-traffic categories: 2-player, multiplayer, unblocked, arcade, action, puzzle, or io-games.

---

---

Step 5: Pre-Flight Testing Checklist Before You Click Submit

Before uploading your ZIP archive to the BentoTiles Developer Portal, execute this 2-minute pre-flight checklist:

• [ ] Local HTTP Server Test: Test your unzipped folder using a local web server (npx serve . or python3 -m http.server 8080) rather than opening file:///C:/index.html. Verify all textures, sounds, and fonts load with zero 404 errors.
• [ ] Console Inspection: Open Chrome DevTools (F12), switch to the Console tab, and play through two complete game loops. Confirm there are zero uncaught JavaScript errors or memory warnings.
• [ ] ZIP Size Check: Keep your complete ZIP archive under 15 MB for rapid mobile streaming. Use WebP for images and 128kbps OGG/MP3 for audio. Submissions over 50 MB face extended scrutiny.
• [ ] Cross-Browser Verification: Check that your game initializes smoothly in both Google Chrome and Apple Safari.

---

The Review Pipeline: What to Expect After Submission

Once you hit submit on your developer dashboard:

1. Automated Security & Path Scan (Instant): Our pipeline unpacks your archive in an isolated container, verifies the root index.html, checks for relative asset compliance, and scans for malware or external redirects.
2. Human QA & Playtest (1–3 Business Days): Our editorial team tests gameplay balance, control responsiveness, and device compatibility.
3. Beta Testing & Approval: Your game receives an initial public playtest window. If performance metrics meet our threshold, your title is approved and instantly featured on the BentoTiles homepage grid and category hubs.

If any issue arises, you will receive clear, actionable feedback directly in your dashboard explaining what needs adjustment so you can resubmit immediately.

Ready to share your creation with millions of browser players? Submit your game to BentoTiles today or explore our Developer Documentation.

---