Testing on a phone over the LAN

Français · Type: how-to · Audience: author · Context: engine repository, created project · Status: ready · Applies from: 4.1.2

A game is made for a phone held in landscape. This page starts the development server so that a phone on the same Wi-Fi opens the game you are writing, with the reloads as you edit, and says what stays protected while it does.

What you get

The game you are editing, open on your phone at http://<your machine's address>:5173/, reloading each time you save a file. The Studio and the placement editor stay reachable from the phone too, but only with a one-session token the command prints.

Context and versions

• Engine repository: npm run dev:lan (and npm run studio:lan for the Studio). It exists since 3.0.0; since 4.1.2 the Studio's write routes also check the Host the browser sends (below).
• Created project (made by npx create-quest-n-click <folder> or quest-n-click create <folder>): there is no dev:lan script. Its dev passes extra options to Vite, so npm run dev -- --host serves the game on the network. That mode gives no token: the phone plays, but the Studio and the placement editor refuse every write that does not come from this machine (see Limits).

Prerequisites

• The game runs on your machine: npm run dev opens it at http://localhost:5173/ (The working loop).
• The phone and the machine are on the same network, and the network lets two devices talk to each other (a guest Wi-Fi or a public hotspot often does not).
• Your machine's firewall lets incoming connections reach Node on port 5173.

Where to run the commands

On your machine, in a terminal open in the engine repository (or in the created project, for its own command). Nothing runs on the phone: it only opens a URL.

Steps

1. Start the development server on the network.

   # in the engine repository, on your machine
   npm run dev:lan
   

   # in a created project, on your machine
   npm run dev -- --host
   

   dev:lan first points @game at the current game (GAME=<id>, else the game last selected, else package.json → config.game), then starts Vite listening on every interface (--host 0.0.0.0). Before Vite's own lines it prints a banner:

   LAN write access is protected by this one-session token:
     <token>
   Studio: http://192.168.1.20:5173/__studio/?token=<token>
   Layout editor: http://192.168.1.20:5173/?edit=<room>&token=<token>
   

   The address is your machine's first IPv4 address on the network. Vite then lists its own Network: URLs.

2. On the phone, open http://<that address>:5173/ and turn the phone to landscape.

3. Play what you just wrote. In the lamp of Your first game, tap the lamp with Use: the line shows, the prop changes, and the save remembers it when you reload. That is the loop: write a rule, place it, check, play.

4. Optional: to edit from another device, open the Studio or Layout editor URL of the banner, with its ?token=. The first request with the token sets an HttpOnly, SameSite=Strict cookie, so the next pages need no token in the URL. To start the Studio itself on the network, run npm run studio:lan instead of step 1 (engine repository): it opens the Studio's URL with the token.

Limit · dev-server-no-offline The development server is not the built game: the phone tests the rules, the placement, the text and the touch, not the installation as an app, the offline mode or the cache. Test those on a build served over HTTPS (Build and release a game, Sub-path, cache and service worker).

What stays protected

• Without dev:lan/studio:lan, Vite listens on 127.0.0.1 only (vite.config.ts): no other device reaches it.
• In LAN mode, every file-writing route of the Studio (the Studio's API, the placement editor's save) asks for the token: in the x-web-scumm-token header, in ?token=, or in the cookie. Without it: 401 Studio token required. The token is new at each start, unless WEB_SCUMM_STUDIO_TOKEN is set (environment variables).
• In every mode, those routes answer only to this machine's names (localhost, 127.0.0.1, [::1]) and, in LAN mode, to the addresses dev:lan printed. Any other Host gets 403 the Studio answers its own names only, so a page that rebinds a name to your port cannot write. A write whose Origin is another site gets 403 cross-origin Studio request refused.
• In a created project with npm run dev -- --host, no LAN address is on that list and no token exists: the phone plays the game, and any write through the Studio or the placement editor from the phone is refused with a 403. Edit on the machine itself.

Guarantee · lan-writes-need-token · referenced · executed on aff6caab7514 · scope self-checked by the author (AI), not reviewed In LAN mode, the Studio answers 401 to a request without the token, and 403 to a write whose Origin is another site even with the token. The test runs the guard on a local HTTP server; it does not start Vite.

Limit · lan-trusted-network The token protects writes, not reading: anyone on the same network can open and play the game while the server runs. Use it on a network you trust, and stop the server (Ctrl+C) when you are done.

Expected result, and how to check it

The phone shows the title screen, then the game in landscape. Save a room file on the machine: the phone reloads with the change. In the Studio opened from the banner's URL, a save goes through (no 401).

Common errors

Files or data changed

dev:lan itself writes nothing but the .cache/game link to the current game. What the phone saves (the game's progress) stays in the phone's browser storage. A write made through the Studio or the editor changes the game's files on the machine, as on localhost.

Recovery or going back

Stop the server with Ctrl+C: the token dies with it, and npm run dev goes back to listening on 127.0.0.1 only.

References

• tools/serve.ts and tools/serve-args.ts: what dev:lan and studio:lan start, the token and the banner.
• tools/studio/security.ts: the token, the names and the origin checked on each write.
• vite.config.ts: server.host, 127.0.0.1 unless WEB_SCUMM_LAN=1.
• Your first game, The working loop, Local and LAN security.
• Next: DSL reference for every field, Classic mechanics for famous mechanics written with them, The local Studio for the tool, Working with an AI for a whole game from the first idea to the release.

Edit the source of this page · Report an error