Publish a Unity Game on Itch.io: WebGL, ZIP & HTML5 Setup (Step-by-Step)

A complete release engineering guide covering root-level ZIP packaging, WebGL decompression fallbacks, Butler CLI automation, and browser canvas optimization.

Technical Abstract: Publishing an indie game on itch.io is often treated as a simple file upload, yet hundreds of developers struggle with black loading screens, memory crashes, and 404 errors. This guide breaks down the release pipeline, based on the comprehensive architectural guide published on GameUnity: How to Publish Your Unity Game on Itch.io.

📌 The Short Answer: How Do You Upload a Unity Game to itch.io?

Uploading a Unity game to itch.io is fairly straightforward, but the build format is where people often get tripped up:

• In-Browser Play (WebGL): If you want players to launch your game directly in their browser without downloading third-party files, WebGL is the right choice.
• Downloadable Play (Standalone): If you want players to install an expansive, high-fidelity experience, a ZIP containing the Windows/Mac build is simpler and avoids browser memory limits.

For a browser release, switch Unity's build platform to WebGL, build the project, and make sure index.html sits directly at the root level of your ZIP archive. If you run into deeper pipeline questions or want the complete architectural blueprint, review the complete Unity to itch.io publishing framework on GameUnity.

"The most common mistake indie developers make when publishing to itch.io is treating their build as a loose desktop folder. Itch.io is an automated server environment. If your WebGL ZIP contains a parent folder that hides index.html, the player gets a 404 or an unplayable canvas.

Build your project cleanly, verify your root directory structure before zipping, and automate your patch pipeline using Butler. That is the difference between a frustrating release and a seamless launch."

— Abdulrahman Maslmany, Lead Systems Architect

⚡ Quick Release Checklist

• WebGL Root Invariance: index.html must sit directly in the root of the ZIP file, never inside a nested parent folder.
• Decompression Fallback: Enable Gzip/Brotli fallback in Unity to eliminate black loading screens on itch.io.
• Standalone Integrity: Package the .exe, UnityPlayer.dll, and *_Data folder together. Never upload the .exe alone.
• Automated Updates: Use the Butler CLI to push binary delta patches directly from your terminal.

1. Architectural Decision: In-Browser WebGL vs. Downloadable Standalone ZIP

Selecting between an embedded in-browser experience and an offline desktop installer represents a fundamental engineering trade-off:

• When to Choose WebGL: WebGL reduces player friction to zero. Players click a link, wait a few seconds for assets to stream, and play immediately. It is indispensable for game jams, portfolio showcases, and web demos.
• When to Choose a Downloadable Standalone ZIP: Grants your game unconstrained access to high-performance desktop APIs (DirectX 12, Vulkan), full multi-threading, persistent disk I/O, and unrestricted system memory.
• The Critical Testing Rule: Always test the uploaded game directly on itch.io, not just inside the Unity Editor or localhost. Browser CORS security policies, iframe sandboxing, and mobile browser WebGL memory ceilings often trigger silent failures on itch.io that never appear locally.

2. Do You Need to Upload Every File? (Correct ZIP Structure)

A frequent question when preparing a Unity build is: "Do I need to upload every single file from the build folder, and how should it be packaged?"

The short answer: Yes, you must upload all compiled files, but how you compress them makes the difference between an instant success and a broken launch.

A. The WebGL HTML5 ZIP Architecture (The Root index.html Rule)

When Unity exports a WebGL project, it creates three core components:

1. index.html (The entry web document)
2. Build/ (Contains .wasm, .data, and .framework.js binaries)
3. TemplateData/ (Contains loading bars, icons, and style sheets)

❌ The #1 Mistake: Zipping the Parent Folder

plaintext
MyGame.zip
└── WebGL_Build_Folder/       <-- WRONG! Itch.io cannot detect index.html
    ├── index.html
    ├── Build/
    └── TemplateData/