DEV Community: zzzu2221

What I Checked Before Shipping a Browser Game to itch.io

zzzu2221 — Tue, 18 Aug 2026 05:35:20 +0000

I uploaded a small first-person sci-fi demo to itch.io this week. The build already ran in a normal browser, so I expected the upload to be the easy part.

It was not difficult, but it did force me to separate “works on my machine” from “someone else can actually play this.” A browser game inside an itch.io page has a few extra ways to fail: the iframe can lose focus, a remote asset can stall, and a refresh can expose state that was never properly reset.

Here is the checklist I used before calling the build public.

Start from a clean page

My first pass was deliberately boring. I opened the game from its public page, clicked into the frame, and checked every control shown in the instructions: movement, sprint, jump, interaction, universe switching, and the memory log.

That click into the frame matters. Keyboard input that works perfectly in a local tab may do nothing until the embedded game has focus. A player will not diagnose that problem; they will assume the game is broken and leave.

I also tried resizing the window and returning to the page after switching tabs. The goal was not to cover every browser combination. I just wanted to catch the obvious cases that make a playable build feel dead on arrival.

Refresh in the middle, not only at the beginning

A fresh load is the easiest state a game will ever see. I refreshed while moving through the first area, after interacting with an object, and after switching between the available universes.

For each refresh I checked three things:

the player started from a valid position;
old input handlers were not duplicated;
the UI and game state agreed about what was available.

Restart bugs are easy to miss in short demos because the first run looks fine. The second run is where duplicated timers, stale flags, and half-reset objects usually become visible.

Test the network assumptions

This build uses Three.js and two background music files that are loaded remotely. That keeps the package small, but it also means the game is not truly self-contained.

I tested the public build from a fresh tab instead of trusting cached files from development. I also made the dependency clear on the game page. If the network is slow, a player should know whether the game is loading or has failed; silence and a blank frame are not useful feedback.

For a later build I would rather package more of those assets locally. For this first public version, documenting the limitation was more honest than pretending it did not exist.

Do not expose a checkout that cannot finish

The larger project has more areas and systems than the itch.io demo. The uploaded build only includes the first three universes: the engine core, a low-gravity area, and a high-entropy dystopian area.

I kept later content out of the playable path and did not leave an incomplete purchase flow inside the itch.io version. A button that looks like a real checkout but cannot complete is worse than a clear “demo ends here” boundary.

This was less about payment implementation and more about player trust. The public build should only promise what it can deliver in that session.

Play more than the opening minute

A loading screen and ten seconds of movement can make almost any prototype look functional. I played several complete sessions and kept going after the first successful interaction.

I wanted to know whether switching universes remained understandable, whether the controls stayed responsive, and whether the game still had something meaningful to investigate after the initial visual impression wore off.

The result is still a demo, not a finished commercial game. Publishing it was useful precisely because the boundary is now visible. I can ask for feedback on the actual browser build instead of showing screenshots and guessing how it feels.

Be specific about generated content

Some of the project's content was produced with generative AI tools, then assembled, edited, and tested as an interactive game. I included that disclosure on the itch.io page.

For me, “AI-generated” is not a substitute for testing. The useful question is still whether a player can load the page, understand the controls, move through the available spaces, refresh, and continue without hidden state breaking the experience.

If you want to try the current browser build and tell me where it breaks, it is here: ENTROPY: The Critical Loop on itch.io.

I am especially interested in iframe focus problems, loading failures, and anything that behaves differently after a refresh.

Why Restart Bugs Reveal Hidden Game State

zzzu2221 — Sun, 16 Aug 2026 07:02:49 +0000

A game can look correct until the player presses Restart. That button is one of the fastest ways to expose hidden state.

In a small browser game, I treat restart as a full lifecycle test rather than a visual reset.

What restart should clear

A restart should create a fresh run:

player position and health;
score and collected items;
enemy timers and active projectiles;
win and lose flags;
keyboard and pointer listeners;
pending animation and timeout callbacks.

Resetting only the score is not enough if an old enemy loop is still running.

A simple failure pattern

A common implementation keeps game objects in module-level variables and starts a new animation loop on every restart. The first run works. After two restarts, movement feels faster, collisions fire twice, and the result becomes inconsistent.

The bug is not in the button label. It is in ownership of the running state.

Make the lifecycle explicit

I prefer a small state machine: loading → playing → won/lost → restarting.

The transition into restarting should stop the current loop, remove listeners, cancel timers, and create a new run context. The new context then owns its entities and callbacks.

Test the failure path first

I run this sequence several times:

Start a fresh game.
Lose intentionally.
Restart.
Win or lose again.
Refresh the page and repeat.

If the second run differs from the first without a design reason, I inspect duplicated listeners, stale references, and callbacks that still point at the previous run.

The practical lesson

Restart is more than a convenience button. It is a compact test of whether the game has a coherent lifecycle. When restart is reliable, win, lose, refresh, and replay are usually easier to reason about as well.

A Game Wallet Is More Than a Number: Handling Retries and Concurrency

zzzu2221 — Sun, 16 Aug 2026 06:45:33 +0000

A game wallet often starts as a single balance field. That is fine for a prototype, but payment retries and unreliable networks quickly make the number hard to trust.

A player can tap “buy,” lose the connection, and try again. A store callback can arrive more than once. Two devices can spend the same account at nearly the same time.

The fix is to treat the balance as a cached view of a ledger.

Record every change

Instead of silently changing a balance, record events such as:

a verified payment granting virtual currency;
an item purchase spending currency;
a refund creating a compensating entry;
an administrative adjustment with an explicit reason.

The current balance remains useful for fast reads, but the ledger explains where it came from.

Make payment delivery idempotent

A payment callback is a message that may be retried. I use an idempotency key derived from the provider and transaction ID, then enforce uniqueness in the database.

The delivery flow is straightforward:

Verify the external transaction.
Record the payment.
Grant currency with the unique key.
Mark delivery complete.
Return the original result for later retries.

This prevents a temporary network problem from becoming a double grant.

Protect spending too

Client-side balance checks are useful for interface feedback, but they cannot protect an account. The server should lock the wallet row, check the available amount, write the ledger entry, and update the cached balance in one transaction.

The same request key should return the original purchase result instead of charging twice.

Keep payment, wallet, and item orders separate

A real-money payment, a virtual-currency movement, and item delivery are connected but different events:

payment order → wallet grant → item order → wallet spend

That separation makes refunds and reconciliation much easier. When something goes wrong, support can identify which step is missing instead of guessing from one mutable number.

Tests that expose the real failures

Before building a large shop UI, test repeated callbacks, crashes between payment and delivery, concurrent spends, timeout retries, failed item delivery, and refunds after currency has been spent.

The important shift is simple: a wallet is not just a number. It is a history of decisions. Making those decisions explicit and idempotent keeps payment failures explainable.