itch.io supports uploadingHTML games forplay directly in the browser. In order for your game to function it must beimplemented using web technologies such as HTML, JavaScript, and CSS. Manymoderngame engines supportexporting to HTML & Javascript, which will allow your players to run your gamedirectly in their browser without separate downloads or installs.

Note: Although in this guide we mention games specifically, you can uploadany kind of HTML/JavaScript/CSS project onitch.io.

Quickstart: Head over toNew Game or edit an existing page, pick“HTML Game” from theKind Of Game list, then upload your game packaged as aZIP file.

Getting started

itch.io supports running HTML/JavaScript/CSS projects directly in the browser by embeddinganiframe pointing to your uploaded code on youritch.io project page.All of your game’s assets are hosted by us so you don’t need to worry aboutuploading files anywhere else. There are two ways to upload an HTML5 game:

• Upload a ZIP file that contains all your project’s files, including anindex.html file that will be your game’s entry point.
• Upload a single HTML file that contains your entire game.

ZIP File

If your game is more than a single file, it must be uploaded as a ZIP file.

The ZIP file must contain a file calledindex.html, this is what people willsee when they go to play your game. The ZIP file should include all the filesnecessary to run your game. File names are case sensitive.

Your ZIP file can contain any kind of file you need for your game. Make sure touse relative paths when developing your game to ensure assets are loadedcorrectly. If you make a mistake or release a new version of your game feelfree to upload a new ZIP file and delete the old one.

HTML File

For simple projects that are self contained in a single.html file, youdirectly upload the file without zipping it.

Your page will not be able to reference any other files you've uploaded onitch.io page. If you need multiple files then you must upload a ZIP fileinstead.

Embed Options

On your project’s edit page, after uploading an appropriate file to be embedded,you will see a new section calledEmbed options where you can configure howyour code will be embedded.

There are two ways your game can be displayed:

• Embed in page — You provide the dimensions of the viewport, and the game will run directly on the page
• Click to launch in fullscreen — Upon clicking “Launch game” your game will expand to the entire viewport in fullscreen. It is not necessary to provide the dimensions. The code you provide should be able to adapt to various sizes.

Here are some of the other options we provide for customizing your embed:

• Click to Play — By default your project will require a click to start. This will ensure your game doesn’t slow the viewer’s browser when the itch.io page initially loads. If you have a lightweight project, you can disableClick to play and your project will start when the page loads. Keep in mind audio may be muted on some browsers when using auto-start.
• Fullscreen Button — We can automatically generate a fullscreen button for your project if the engine you are using doesn’t automatically provide one. This button will be overlayed on the bottom right of your page when using theEmbed in page launch mode.
• Scrollbars — Some projects are designed to be larger than the size of their viewport. Enabling scrollbars will allow viewers to scroll within theiframe. They are hidden by default.

Viewing Your Game

After setting your game’s dimensions and uploading the ZIP file you can previewyour game onitch.io. Upon first loading the game page,itch.io willtake a moment to process the archive.

Meanwhile you are free to customize your game page as you would with any othergame onitch.io.

Can I take payments with my HTML5 game?

Currently all HTML5 games onitch.io are set up to only take payments asdonations. However, it’s possible to sell access to your game by setting its“Kind of Game” to“Downloadable”. If you'd likeitch.io to supportpurchasable HTML5 games then you shouldget in touch.

ZIP file requirements

There are a couple of requirements for ZIP files in place to prevent abuse andto ensure a suitable experience for people running your project in theirbrowser:

• The ZIP file should not contain more than 1,000 individual files afterextraction.
• The maximum length of a file name including path should not be greater than240 characters long.
• The size of all the extracted content should not be greater than 500MB.
• The size any single extracted file should not be greater than 200MB.
• The filenames are case sensitive and should be encoded as UTF-8

If your game does not meet the requirements please consider distributing yourgame as downloadable instead. Very large HTML5 games tend to be a poorerexperience compared to the equivalent downloadable in respect to loading timeand performance.

Why do we have limits? Although many game engines allow you to exportanything as an HTML5 project, often you need to consider what the userexperience of playing the game will be like. You can think of an HTML5project like a website: many of the same performance optimizationrecommendations still apply. We have these default limits to encouragedevelopers to consider how their games are distributed, especially since it’sso easy these days to drop in prefab resources from asset-stores thatsignificantly increase the download size for the game.

Feel free tocontact us if you think these limits aren’t appropriatefor your project and we can see what we can do .

Customizing how your game is embedded

Visual customization

For projects that useClick to play, you can customize the what theviewport looks like before the game is launched. You can find these options onthe project’s theme editor.

• Background Image — A image that takes up the size of the viewport that sits behind thePlay button.
• Gradient — A gradient color can be overlayed on the viewport to help you match the colorscheme of your page.

Support for Mobile HTML5 Games

Many HTML5 game engines support playing games through a mobile web browser. Ifyou know your project functions in a mobile browser then you can select theMobile Friendly option in the embed settings for your project.

When your itch.io page is loaded on a mobile device, it will useClick tolaunch in fullscreen mode regardless of how you've configured your embed fordesktop computers. This will ensure itch.io’s user interface does not interruptyour application, along with preventing an auto-starting game from unexpectedlyconsuming resources.

If you haven’t enabledMobile Friendly then a warning will be displayed tothe viewer that the game may not work, but they can still attempt to start it.

Game Engine Detection

When you upload your HTML5 game we'll scan the files to detect the game engineused automatically. This can help get your project listed in our browse pages.Here are some examples of HTML5 games using specific engines.

• Bitsy
• Twine
• PICO-8
• PuzzleScript
• TIC-80
• Unity

If you think we're missing a engine you cansuggest a new one.

Common Pitfalls

Here are some common issues people run into when uploading their project. Ifyou're about to upload something, or are having an issue, read through the list first.

• Not uploading a .ZIP file — If you are trying to upload a project that uses multiple files you must compress them as a ZIP file and upload that.We do not support any other archive types, (.rar,.tar.gz, and.7z are not supported). Uploading multiple files individually to the itch.io website will not work either, you must combine all necessary files into a ZIP file. Note that if your project is a single HTML file, then you can upload that directly and skip ZIPing it.
• Attempting to access a path that doesn’t point to a file — If you attempt to load a resource that doesn’t point to a file the request will fail. This includes attempting to access a folder (paths ending in/) instead of a specific file. Due to our security settings, our system will return a403 error instead of the more commonly seen404. (In Chrome you may seenet::ERR_ABORTED 403).
• Using absolute paths instead of relative paths — Your project is hosted on a subdirectory on our HTML CDN. If you use an absolute path in your sourcecode then it will cause the browser to attempt to make a request outside of the path of your project, and the request will fail. Absolute paths are paths that start with a/. You must use relative paths to access other files you have provided in your project.
• Mismatched cases when referencing files — The server that hosts your project’s files is case-sensitive. MacOS and Windows computers allow for files to be loaded case-insensitive. It’s possible your project works locally on your computer but fails after you upload it. Please check that all files you reference use the exact case that is shown on your file manager. This is commonly associated with anet::ERR_ABORTED 403 error in Chrome. If you have a file namedHello.png, you must reference it asHello.png, things likehello.png andHELLO.png will not work because the case does not match.
• Referencing external resources without HTTPS — If your project tries to load files or talk to an API on another domain, then that domain must be requested with HTTPS. For security reasons, itch.io is an HTTPS website with no exceptions. All modern browsers will generally block requests to other domains if they aren’t running on HTTPS. There are no exceptions. There are many free resources for adding HTTPS to your own domain, likeLet’s Encrypt.
• Uploading a very large game — Although many game engines allow you to export anything as an HTML/JavaScript project, often you need to consider what the user experience of playing the game will be like. For larger games, it’s often better to go for a downloadable version. This is why we have default limitations for project sizes (although you can contact us if you need lifted limits). Projects can still be easy to play with theitch.io app. You can think of an HTML project like a website: many of the same performance optimization recommendations still apply.

Exporting your game for itch.io

When exporting your game for itch.io we recommend using a template or markupthat allows for your game’s canvas to adjust to the size of the window is isplaced in. When using a fullscreen button the viewport size will dynamicallyadjust to the size of the viewer’s screen. Additionally, when running an HTML5game on a mobile device, the viewport will have a dynamic aspect ratio andresolution matching the user’s device.

Here are some recommend resources:

• Unity:https://seansleblanc.itch.io/better-minimal-webgl-template

If you have any other recommended resources or tips for configuration pleasesend them tosupport.

Compression

Some game engines will pre-compress assets as part of their build process. Inorder for these assets to download correctly, often the webserver will have todetect these and apply the appropriate headers for the particular file.

• If the content of the file is detected as gzip compressed, thecontent-encoding header togzip. Thecontent-type header of the file will detected and set by the extension, removing.gz if necessary.
• If the filename ends with the extension.br then we'll assume that the content is Brotli compressed and thecontent-encoding will bet set tobr. The Thecontent-type header of the file will then be detected and set by the extension, after removing the.br. (Note: Brotli encoding can not be detected like gzip, so we must depend on the.br extension). This approach is commonly used by Unity 2020 WebGL export.

Compressed file types

In order to reduce bandwidth and decrease loading times, itch.io’s CDN willautomatically apply GZIP compression to the following file types if they areprovided uncompressed.

File extensions:

• html
• js
• css
• svg
• wasm
• wav
• glb
• pck

If we aren’t able to match by extension, if we see the following content type on a file we will also attempt to compress it:

• application/x-javascript
• application/javascript
• text/javascript
• text/css
• text/html
• application/xml
• application/json
• image/svg+xml