itch.io Community » General » Release Announcements

BuildHarbor: offline HTML5 ZIP checks and opt-in repairs for itch.io uploads

A topic by P4ODEBATATA created 14 days ago Views: 60 Replies: 2

Viewing posts 1 to 2

Hi! I made BuildHarbor for HTML5 developers preparing an itch.io upload.

It checks your game ZIP for common packaging issues, including a missing root index.html, an extra wrapping folder, and supported asset-path capitalization mismatches.

You can review the findings, choose available repairs, and export a new ZIP without changing your original file. TXT and JSON reports are included.

It runs locally in a desktop browser: your game files aren't uploaded to a checking service.

This is a static checker, not a runtime debugger. You still need to test your final build on itch.io.

Introductory price: $2.99. Includes the app, a built-in worked example, and a Quick Start PDF.

Screenshots and full details:

https://p4odebatata.itch.io/buildharbor-html5-zip-repair

Happy to answer questions about the checks and their limitations.

CSAF — Core Systems Asset Factory14 days ago

One check you might consider, if it's not in there already: the path separators in the zip entry names. Zips written by the PowerShell zip cmdlet can store entry names with backslashes rather than the forward slashes the format expects. Ours were. That was on downloadable builds rather than HTML5, so I can't tell you how a browser build behaves, but it seems worth a look for a tool in this space. The firmer part is that it's hard to observe. We checked the same packages with a .NET zip reader and a Python one, and they normalise separators in opposite directions, so both gave a confident answer and the two disagreed. Reading the central directory bytes was the only thing that settled it. Capitalization and the wrapping folder are the two that bite us most, so those look like the right first checks.

P4ODEBATATA14 days ago

Thanks a lot — you found a real gap. I reproduced both cases and read the filename bytes in the ZIP central directory directly.

BuildHarbor 1.1.0 now:

• checks central-directory filename bytes before library normalization;

• reports the affected entries containing backslashes;

• offers an explicit “Normalize ZIP entry separators to /” repair;

• exports a new ZIP whose entry names use /, while preserving the original archive untouched;

• reopens and rescans the output to verify that no backslash entries remain.

I verified this with synthetic ZIPs. I still do not claim that every itch.io HTML5 runtime fails on backslash names; the final draft upload remains the authority. Capitalization and wrapping-folder checks remain in place too.

Thanks for pointing this out — your comment led directly to the fix: https://p4odebatata.itch.io/buildharbor-html5-zip-repair