📱 Guide

Mobile browser game: making yours work on a phone

A phone is not a small laptop. Four things break when your game meets one, they are always the same four, and none of them needs a rewrite or an app.

Updated 27 October 2026 10 min read By the Agent Games team

Jump to a section

The four faults, and why it is always these four
Fault one: the page moves instead of the game
Fault two: there is no keyboard to press
Fault three: the layout was drawn for a wide window
Fault four: nothing on screen can be read
The prompt that applies all four at once
Testing it honestly
When the answer is that it stays a keyboard game
Common questions
Where to go next

Your game already runs on a phone. The browser is the same browser. What fails is everything around the game. The page scrolls under a finger. The controls are keys nobody has. The layout was drawn for a wide window, and the numbers in the corner are too small to read. Those four faults cover nearly every report of a game being broken on mobile.

A phone is not a small laptop

The size of the screen is the least of it. The pointer is a finger that hides what it touches. The browser moves its own bars up and down while you play. The player is holding the thing in one hand, probably with the other hand busy. A layout that only shrinks gets all of that wrong, and still looks fine in a narrow desktop window.

The four faults, and why it is always these four#

Fixing them is not a port. It is four changes to a game you already have, and three of them are a line each. The fourth is a design decision you have to make yourself, because it depends on what the game is.

Work down the list rather than reacting to whatever you noticed first. The scroll fault usually masks the others, because you never reach the game long enough to see them.

Fault one: the page moves instead of the game#

By default the browser owns every gesture on the page. A drag is a scroll. A quick double tap is a zoom. A long press selects text and offers to copy it. Your game sees none of that, because the browser decided the gesture was about the document before your code was asked.

The fix is one CSS rule on the canvas: touch-action: none. It tells the browser that gestures starting on that element are not navigation, so they get delivered to your handlers instead. Add user-select: none beside it and the copy menu stops appearing mid-game. Models leave both out constantly, because on a desktop they change nothing at all.

The browser can take a gesture back

Even with the rule in place, a gesture can be cancelled part way through. The browser fires pointercancel and stops sending moves. Code that only clears its state on pointerup never hears about it, and the player is left holding a ship that keeps drifting. Handle the cancel exactly like a release, every time.

Pointer events are worth asking for by name. One set of handlers covers mouse, finger and stylus, so you are not maintaining a touch version of the input code next to a mouse version. The game then asks what the player wants, never which device answered.

Fault two: there is no keyboard to press#

A game driven only by arrow keys is not hard to play on a phone. It is impossible. Something has to stand in for those keys, and the first idea everybody has is to draw them on the screen. That is usually the worst of the available options.

A drawn D-pad fails for a physical reason, not an aesthetic one. Your thumb hides the button it is pressing, so the only feedback you get is whether the game moved.

The better patterns all share one property. The player does not have to aim at anything small, and the control does not sit on top of the thing they are watching. Which one suits you depends on how many decisions the game asks for per second.

If the game is	Ask for	Because
A runner or a faller	Tapping either half of the screen	There is no target for the thumb to find
Steering something	A drag anywhere, with the object following	The finger never has to sit over the action
A platformer	Two wide zones along the bottom corners	One thumb moves, the other jumps
A shooter	Drag to move, and firing handled for you	Shooting by hand costs a thumb you lack
A puzzle or a board	Tapping the piece the player means	The board was already the control
Mostly waiting or reading	One large button that advances	A single target beats any gesture

The last two rows are the ones people forget. A game of taps on the board itself needs no added controls at all, and often only needs the bigger targets.

Make every target 44 pixels or more. That is roughly the contact patch of an adult thumb. Anything smaller gets missed, and a missed tap reads as a bug in your game.
Let the game act on its own where it can. Firing, accelerating and advancing are all things a game can do by itself. Each one you automate is a control you do not have to find room for.
Show touch controls only to touch. Draw them the first time a pointer event arrives from a finger, so desktop players never see buttons they cannot use.
Keep the keyboard working. You are adding an input, not replacing one. The same game should still play with keys when it is opened on a laptop.

If you find yourself cutting the game down until a single tap covers it, that is a different craft and a good one. Designing around one input from the start is the subject of the casual game guide, which treats it as the brief rather than the compromise.

Fault three: the layout was drawn for a wide window#

Portrait is taller than it is wide, which inverts every assumption a desktop layout makes. A play area that was short and wide now has to be tall and narrow, or it sits as a stripe across the middle with nothing above or below it.

Start with the viewport meta tag. Without it a phone pretends to be a wide desktop and scales the result down, so everything is correct and unreadable. Ask for width=device-width, an initial scale of 1, and viewport-fit=cover.
Size the canvas from its own measured box. Let CSS decide how big the element is, then read that size back and set the drawing buffer to match. The common version reads the window size instead, which is a different number and often the wrong one.
Expect the height to change while playing. Phone browsers hide and show their bars as the page moves, so the usable height is not a constant. Anything that measured once at startup will be wrong a few seconds later.
Stay off the very bottom edge. A notch eats the top and a home indicator eats the bottom. A swipe that starts on the bottom edge belongs to the operating system, not to you, so nothing the player must hit should live there.
Redraw on rotation as well as resize. Turning the phone is the fastest way to find a layout that was computed once and never again.

If the game genuinely needs a wide view, say so and letterbox it. A tall black band above and below a correctly proportioned game is honest, and it is far better than a stretched one. What you want to avoid is a game that silently crops, because the player cannot tell that the thing about to hit them is off screen.

Fault four: nothing on screen can be read#

Hold a phone where you actually hold it and compare that to a laptop screen. Everything you drew is now about a third of the size, in a brighter room, while moving. Text at 12 pixels was already small on a monitor. Here it is decoration.

The instinct is to shrink the layout until it fits. Do the opposite. Decide what the player needs in order to make their next decision, keep that, and remove the rest. A score, a life count and one warning will fit at a readable size. A score, a life count, a combo meter, a timer, a minimap and a hint line will not.

Count what is on screen before you resize any of it. Four things at a readable size beat nine things you have to squint at.
Drop thin lines and small detail. A one pixel outline and a four pixel gap both disappear. Solid shapes and strong contrast survive the trip.
Never explain anything with a hover. There is no hover on a phone. A tooltip is simply a piece of information the player does not get.
Check it as a thumbnail. Shrink a screenshot until it is the size of a stamp. Whatever you can still identify is what a player sees at a glance.

The prompt that applies all four at once#

Paste your game in first, then this. Fill in the bracketed line with what the game actually is, because the control scheme is the one part that cannot be chosen for you.

PromptCopy this, paste it, send it

Here is my game. It plays fine on a desktop with a keyboard and is
unusable on a phone. Make it work on a phone. Do not change the game
itself, and do not add a framework.

CONTROLS: the game is [describe it in one line]. Add touch input that
suits it, choosing one of: tapping the left or right half of the
screen, dragging anywhere with the player following the finger, or two
wide zones along the bottom corners with one action each. Do not draw
a four button D-pad or a virtual joystick. Use pointer events, and
treat pointercancel exactly like pointerup, because the browser can
take a gesture away halfway through. Keep the keyboard controls
working as they are. Every tap target must be at least 44 by 44 CSS
pixels, and none may sit against the bottom edge of the screen.

GESTURES: put canvas { touch-action: none; user-select: none; } in the
CSS, so a drag reaches the game instead of scrolling the page and a
long press cannot pop up the copy menu.

LAYOUT: add a viewport meta tag with width=device-width, an initial
scale of 1, and viewport-fit=cover. The canvas must fill its container
and take its drawing size from that container's measured box, never
from window.innerWidth or window.innerHeight. Phone browsers hide and
show their own bars while the game runs, so re-measure on resize and
on rotation rather than once at startup. It has to be playable with
the phone held upright. If the game truly needs a wide view, letterbox
it rather than cropping it.

READABILITY: assume every player is seeing this at a third of the size
I am. Remove anything on screen that is not needed for the next
decision, and make what remains bigger. Nothing may depend on
hovering, and nothing important may be a thin line.

TIMING: base all movement on the seconds elapsed since the previous
frame, capped at 0.05, so a slower phone plays the same game as my
laptop. Collect every number worth tuning into one CONFIG object at
the top, with a comment on each.

TESTING: finish by listing what I should check in device emulation at
360 pixels wide, and what I can only find out on a real phone.

The sentence about the container's measured box is the one that gets skipped. Reading the window size is correct on a desktop and wrong on a phone about half the time, so nothing you do on your laptop will ever show you the difference.

Testing it honestly#

A narrow desktop window is not a phone. It has a mouse, which is accurate to the pixel in a way no thumb is. Its browser furniture stays exactly where it is. Its pixel density is different, so your text is sharper than it will really be. It never rotates, and it has no notch.

Device emulation in the browser developer tools is the minimum bar. Pick a real device preset, turn on touch emulation, and work at 360 pixels wide. That catches the layout faults and most of the readability ones. It still cannot tell you how the game feels.

Only a real phone shows the bars moving. They slide away as you interact and come back when you stop, and the layout has to cope both ways.
Only a real phone shows your hand. You find out how much of the screen a palm covers, and whether the control is where your thumb already was.
Use somebody else's phone too. Yours has your text size settings, your browser and your habits. A second device finds the thing yours agreed to overlook.
Open it the way a player would. Tap a link, wait for it to load on a normal connection, and start playing without reading anything first.

One more thing a real phone will tell you. It is several times slower than the machine you wrote the game on, so a fault your laptop was hiding may appear here as stutter. That is a subject of its own, and why your browser game lags is the place for it rather than this one.

📱Games on this site

When the answer is that it stays a keyboard game#

Not every game should be made to work on a phone. A game that wants six keys held at once has nowhere to put them. A game built around aiming at a precise point has no way to show you where the point is, because your finger is in front of it. A flight sim with a dozen bindings is not waiting for a better control scheme.

Simplifying those games for touch usually produces a worse version of a good game. The honest move is to leave the game alone and say what it is. A line on the start screen reading best played with a keyboard costs you nothing. It also stops a player deciding your game is broken, when it is simply not for the device in their hand.

What that line should never cover up is laziness. The test is whether touch would change the game or only the input. If the game survives being played with a thumb, make it work. If it has to become a different, smaller game, let it stay what it is.

Common questions#

Why does my game scroll the page instead of responding?

The browser claimed the gesture before your code saw it. Add touch-action: none to the canvas in your CSS, which tells it those gestures are not navigation. This is the single most common reason a working game feels dead on a phone, and it changes nothing on a desktop, so it is easy to never notice.

Do I need to turn it into an app?

No. A browser game already runs on every phone, with no store, no download and no review. The work is in the controls and the layout, not in the packaging. Wrapping the same four faults in an app only moves them somewhere harder to update.

Should I add an on-screen joystick?

Try everything else first. A joystick has no edges to feel, so the thumb drifts off it, and it covers part of the screen the player needs. Tapping a half, dragging anywhere and two wide corner zones all beat it for most games. Keep it for the case where the player really does need free movement in every direction.

How do I stop the browser bars from breaking my layout?

Do not measure the window. Let CSS size the element, read the size back from the element itself, and re-read it whenever the page resizes or rotates. The bars change the usable height while the game is running, so anything measured once at startup goes stale within seconds.

Does it have to work in both portrait and landscape?

Portrait is the one that matters, because that is how a phone is held when a link gets tapped. Landscape is worth supporting if the game needs the width. What fails is assuming one and quietly cropping in the other, which the player experiences as things arriving out of nowhere.

Can I test this properly without a phone?

You can get most of the way. Device emulation with touch turned on at 360 pixels wide finds the layout and readability faults. It cannot show you the moving browser bars, the real pixel density or what your hand covers. Borrow a phone before you tell anybody it works.

Where to go next#

Once it plays under a thumb, put it up. Games on Agent Games get opened on phones far more often than on laptops, so this is the work that decides whether most people ever finish a round. Opening a few of the games here on your own phone is a quick way to see which of them took it seriously.

The canvas sizing and input code behind all of this sits in the 2D guide. If the controls still feel wrong after the fixes above, the single input approach in the casual guide is the next thing to try. Repair prompts for other common faults are collected in the prompt guide.

Built something? Put it on Agent Games.

Publishing takes a file and a minute. Your game gets its own page listing the model, the prompt and the token count, and anyone can play it without signing up.

Publish a game