HTML5 game publishing
A Game State Machine Instead of Boolean Flags
Replace isPlaying, isPaused and gameOver with one state and a transition table. Enter, update and exit, ad breaks as states, stale timers and debugging.
Most HTML5 games start with a handful of boolean flags: isPlaying, isPaused, showMenu, gameOver. After a few weeks, the combinations multiply. What happens if the player pauses during the game-over animation? What if an ad finishes after they have already pressed restart? The bugs that follow are strange, hard to reproduce and show up in the worst place: reviews. A small state machine replaces the flags with a single answer to "what is the game doing right now?". This post shows a compact, practical one.
The problem with flags
Four booleans give sixteen combinations, and most of them are meaningless. A game that is both isPlaying and gameOver is a bug, but nothing prevents it. Every new feature, such as a tutorial, a rewarded ad, a level-complete screen, doubles the number of cases you have to think about.
A state machine says: at any moment the game is in exactly one state, and from each state only certain transitions are allowed. Everything else is impossible by construction.
A minimal state machine
const states = {
loading: { enter: startLoading, update: tickLoading, exit() {} },
menu: { enter: showMenu, update() {}, exit: hideMenu },
playing: { enter: startRun, update: tickGame, exit() {} },
paused: { enter: showPause, update() {}, exit: hidePause },
adBreak: { enter: showAd, update() {}, exit() {} },
gameOver: { enter: showResult, update: tickResult, exit() {} },
};
const allowed = {
loading: ['menu'],
menu: ['playing'],
playing: ['paused', 'adBreak', 'gameOver'],
paused: ['playing', 'menu'],
adBreak: ['playing', 'menu', 'gameOver'],
gameOver: ['menu', 'playing'],
};
let current = null;
function go(next, data) {
if (current && !allowed[current].includes(next)) {
console.warn('blocked transition', current, '->', next);
return false;
}
if (current) states[current].exit();
current = next;
states[next].enter(data);
return true;
}
function frame(dt) { states[current].update(dt); render(); }
The transition table is the valuable part. It documents every legal path through the game on one screen, and it refuses the illegal ones loudly in development. Try pausing during gameOver and the machine says no, instead of leaving you with a half-frozen screen.
What goes inside enter, update and exit
- enter: everything you do once on arrival: show a screen, start music, reset a counter, start a timer.
- update: per-frame logic, only for states that need it. A menu does not need updates.
- exit: cleanup. Hide the screen, stop timers, remove listeners that this state added.
The common bug is forgetting the exit step, so a pause menu's keyboard handler keeps firing in the next state. Pair every addEventListener in enter with a removeEventListener in exit.
Where ads and interruptions fit
An ad is an interruption that can end in three ways: the player watches it, it fails to load, or the player closes it. Model it as a state with a defined return, rather than a function that you hope returns. When you enter adBreak, remember where you came from, pause audio and game time, and leave through exactly one exit, whatever the outcome:
let returnTo = 'playing';
function requestInterstitial(from) {
returnTo = from;
go('adBreak');
sdk.showInterstitial({
onClose: () => go(returnTo),
onError: () => go(returnTo),
});
}
That is the idea behind our post on resuming from onClose or onError. The same pattern covers the platform asking you to pause or mute. See pause, resume and mute in the PlayKovo SDK. A single entry point for "stop the game" and "resume the game" keeps these requests from stacking up.
Nested states: gameplay inside a level
A game can have states inside states, such as playing being made of intro, running and bossFight. Do not flatten them into one huge list. Give the playing state its own small machine with the same helper, and let the outer machine treat it as one block. The outer transitions (pause, ad, game over) stay simple, and the inner ones can change freely.
Handle timers and async work carefully
Most state bugs come from asynchronous work that finishes in the wrong state. A setTimeout started in gameOver that fires after the player has already restarted will push the game into a bad place. Two safeguards:
- Store timer ids per state and clear them in
exit. - Check the current state when an async callback resolves:
if (current !== 'gameOver') return;.
For fetches or loads, use a token that increments on every state change, and ignore results that carry an old token.
Make it debuggable
- Log every transition in development with a timestamp.
- Show the current state in a debug overlay, as in a debug overlay for the PlayKovo SDK.
- Add a way to jump to a state from the console during testing.
- When you hit a bug, add the offending transition to the table (or remove it) so it cannot recur.
A state machine does not make a game simpler, but it makes it predictable. If you only adopt one habit from this post, make it the transition table.


