OpenFrontIO/.claude/skills/run-openfront/SKILL.md

name, description

name	description
run-openfront	Build, run, and drive OpenFront locally. Use when asked to run the game, start the dev server, take a screenshot of the UI, verify a client change in the real app, or interact with the running game (lobby, modals, map picker).

OpenFront is a browser game (Lit + Pixi.js client, Node game server). Run the dev server with npm run dev (serves on http://localhost:9000, not Vite's default 5173), then drive it with headless Chromium via .claude/skills/run-openfront/driver.mjs. All paths are relative to the repo root.

Prerequisites (one-time per machine, no sudo)

The host (Ubuntu 26.04, headless) has no browser, and Playwright doesn't support 26.04 yet. setup.sh works around both: it installs Playwright (--no-save), downloads the ubuntu24.04 chromium-headless-shell via PLAYWRIGHT_HOST_PLATFORM_OVERRIDE, extracts the missing system libraries from .deb packages into ~/.cache/openfront-run/ (no root needed), and builds a local fontconfig (the host has no /etc/fonts; Skia FATALs without one).

bash .claude/skills/run-openfront/setup.sh

Deps were installed with npm run inst (npm ci --ignore-scripts) — do not use npm install.

Run the dev server

(npm run dev > /tmp/dev.log 2>&1 &)
timeout 60 bash -c 'until curl -sf http://localhost:9000 >/dev/null 2>&1; do sleep 1; done'

Stop it with pkill -f "tsx src/server/Server.ts"; pkill -f vite. ECONNREFUSED "Error polling lobby" lines in /tmp/dev.log are normal — the closed-source API isn't running in dev.

Drive it (agent path)

Smoke flow — home page, open the single-player modal, dump the map-picker state, screenshot:

node .claude/skills/run-openfront/driver.mjs
# screenshots: /tmp/openfront-run/home.png, /tmp/openfront-run/solo-modal.png

For ad-hoc flows, write a script inside the repo (so playwright resolves) importing the driver's helpers:

import {
  launch,
  gotoHome,
  openSoloModal,
} from "./.claude/skills/run-openfront/driver.mjs";
const { browser, page } = await launch(); // env/libs/fonts handled here
await gotoHome(page);
await openSoloModal(page);
// Lit components use light DOM — query and read properties directly:
const s = await page.evaluate(
  () => document.querySelector("map-picker")?.selectedMap,
);
await browser.close();

Run (human path)

npm run dev, open http://localhost:9000 in a browser. Useless headless.

Test

npm test                                      # full suite (Vitest)
npx vitest tests/MapConsistency.test.ts --run # single file

Gotchas

• Vite serves on port 9000, not 5173 (configured in vite.config.ts).
• Playwright on Ubuntu 26.04: npx playwright install chromium fails with "does not support chromium on ubuntu26.04-x64". Fix: PLAYWRIGHT_HOST_PLATFORM_OVERRIDE=ubuntu24.04-x64 (setup.sh does this).
• Browser dies at launch / mid-load: missing host libs (libnspr4.so, libatk-1.0.so.0, …) then a Skia FATAL (SkFontMgr_FontConfigInterface.cpp: Not implemented) from the absent fontconfig. launch() in driver.mjs injects LD_LIBRARY_PATH and FONTCONFIG_FILE pointing at ~/.cache/openfront-run/; diagnose new missing libs with DEBUG=pw:browser and ldd .../chrome-headless-shell | grep "not found".
• The single-player button is labeled "SOLO!", and the DOM has more than one (responsive layouts) — use button:visible with hasText: /solo/i.
• Lit + Vite HMR: custom elements can't be re-registered, so an already-open tab keeps old component code after an edit. Hard-reload (or re-goto) before judging behavior.
• PAGEERROR: ... reading 'inSpawnPhase' on the home page is pre-existing background noise, not your breakage.
• Wait ~3s after load before interacting — Lit components render client-side (driver's gotoHome does this).

Troubleshooting

• Cannot find package 'playwright' — your script is outside the repo; module resolution starts at the script's path, not cwd. Move it inside the repo (anywhere under the root works).
• Target page, context or browser has been closed immediately — re-run bash .claude/skills/run-openfront/setup.sh (the ~/.cache/openfront-run lib cache is missing or was cleared).
• EADDRINUSE on relaunch — a previous dev server is still up: pkill -f "tsx src/server/Server.ts"; pkill -f vite.