html5-games-token-saver
# html5-games-token-saver
MCP server that checks a built HTML5 game against the CrazyGames portal rules and answers with dense JSON:
a list of failures, warnings and rules it could not exercise, instead of screenshots and one-off Playwright
scripts in the agent context. `game_check` does the same inside the game: a scenario played in every size and
language, what a player would see wrong in a Phaser canvas UI as text.
## Install
```
claude mcp add html5-games-token-saver -- npx -y @alex-apps/html5-games-token-saver
```
The game needs Playwright with Chromium (`npm i -D @playwright/test && npx playwright install chromium`); the server
takes it from the game's `node_modules`. Build the game before a check: the tools read `dist`, not `src`.
## Tools
| Tool | What it does | Time |
|---|---|---|
| `cg_build_check` | Size, file count, `index.html` at root, absolute paths, resources from foreign hosts, zip slashes, SDK version, viewport meta, `user-select`, stale build. Dist folder or release zip. | ms |
| `cg_sdk_session` | Plays the build in an emulated portal frame with an SDK v3 emulator, idles, hides the tab. Verdicts below. | ~10 s + idle |
| `cg_frame_audit` | DOM in each frame size at boot, at each `check` step, at the end: windows inside the frame, reachable controls, rendered text size, rewarded vs no-ad button size, page overflow, scrollers without a custom bar on phones. | seconds per size |
| `game_check` | Plays a scenario inside the game in sizes x languages. At each `check` the scene probe reads the Phaser display list: missing textures, labels and buttons cut by the screen edge, tiny text, small touch targets, overlapping labels, text spilling out of its plate; plus page errors. Opt-in shots of a box, a texture inventory, comparison with an earlier run. | seconds per run |
`cg_sdk_session` rules: first `gameplayStart`, bytes loaded before it, loading order, start/stop pairs, a pause on
every window and a resume on close, an SDK member hit repeatedly (a render loop or a per-second timer), SDK reads
with no input, autosave every 30 s, save on hide, `localStorage` writes on the portal, sound during an ad, rewarded
cooldown, banner refresh, console errors, 404s inside the frame, requests to foreign hosts, SDK members the emulator
does not implement.
A rule the run could not reach comes back in `unchecked` with the reason; it is never reported as a pass.
## How it emulates the portal
No server and no port. `page.route` answers `www.crazygames.com/game/<slug>` with a page holding an iframe of
`games.crazygames.com/en_US/<slug>/index.html`, serves the build from disk (folder or zip) under that path, and
serves the SDK emulator at `sdk.crazygames.com`. A host check or an iframe check in the game sees the portal.
Foreign requests get an empty 204 and are listed. A probe injected before the game scripts records SDK calls and
property reads, `localStorage` writes, windows opening and closing (`role=dialog`, `dialog[open]`, `aria-modal`), and
the audio level tapped in front of `AudioContext.destination`, so the mute check works for any engine.
Playwright is taken from the game's `node_modules` (its e2e already installs it and its browsers), then from next to
this package.
## Scenario
The only game-specific part. `cg-scenario.json` in the game root, or the same fields as tool arguments:
```json
{
"init": "window.__mtDebug = true",
"query": "?debug=1",
"dialog": "[role=dialog]",
"steps": [
{ "waitFor": "data-testid=settings-open" },
{ "click": "data-testid=settings-open" },
{ "check": "settings" },
{ "tap": [0.005, 0.005] },
{ "press": "Escape" },
{ "eval": "window.__mt.requestMidgame()" },
{ "rewardedTwice": "[data-testid=bonuses-modal] button:has-text(\"Watch\")" },
{ "wait": 2500 }
]
}
```
Selectors are Playwright selectors inside the game frame; taps are viewport fractions, so one scenario serves every
frame size and canvas games. A click is a player's click at the element's centre (game buttons pulse and never look
stable to Playwright); on phone sizes clicks and taps are touches. `waitFor` takes `timeoutMs` for slow 3D boots.
`check` holds the screen 4.5 s in a session (a per-second timer shows) and measures in the audit, after finite CSS
animations end. `rewardedTwice` watches a rewarded ad, then clicks the same button again at once.
Windows and their `gameplayStop` are matched by order, not by clock: a 3D game under SwiftShader sent the stop
10 s after the click and showed the window 3.5 s later.
## game_check
The game side is a folder in the game root: `game-check/adapter.js` and scenarios `game-check/<name>.json`. The
adapter runs before the game scripts and sets `window.__check`: `game()` returns the `Phaser.Game`, `ui` lists the
UI scene keys (their objects must stay on screen), `skip(o)` marks UI objects pinned to the world (names over units),
and short game steps the scenarios call (start a level, grant gold, select, open a tab, where a card is). The
internals a check needs change with the game; the adapter changes with them, not every check.
```json
{
"init": "__check.save({ tutored: true })",
"ready": "__check.menu()",
"sizes": ["desk", "phone", "land"],
"langs": ["en", "ru", "de"],
"steps": [
{ "eval": "__check.start(1)" },
{ "until": "__check.deckOpen()" },
{ "value": "__check.armySize()", "as": "army" },
{ "tapAt": "__check.card('warrior')" },
{ "check": "after hiring" },
{ "shot": "deck", "box": [0, 0.6, 1, 0.4] },
{ "textures": "^warrior-", "sheet": true }
]
}
```
Steps of the portal scenario work as there; the canvas adds `until` (a JS condition), `value` (a JS value reported
with its label), `tapAt` (a JS point `{x, y}` in CSS px), `check` with probe thresholds in `opts` (`minText` 11,
`minTarget` 44, `overlap` 0.33, `spill` 2), `shot` of the whole viewport or a `box` (viewport shares or a JS box),
and `textures` (keys matching a regex: a PNG and a pixel fingerprint each; `prep` runs first, `sheet` glues them).
Sizes are `desk` 1280x720, `small` 800x450, `cg` 1080x607, `phone` 390x844, `land` 844x390, `tablet` 1024x768
(the last three touch, pixel ratio 2) or any WxH with `m` for a touch phone. The locale of each run is also in
`window.__CHECK_ENV.lang` for a game that keeps its language in a save.
The answer folds runs: one line per finding with the checks and runs it appeared in (`*` every run, `phone/*` every
language of a size, `*/de` every size of a language). A label under an image drawn later (a window over the deck) is
hidden and not checked. With `base` set to the `out` of an earlier run, each shot reports its share of changed pixels
and where, and each inventory its changed, added and removed keys with one was|now sheet of only those. The build
opens in the emulated portal frame; `url` opens a dev server instead, where adapter steps can import `/src/` modules.
## Verified on
- A fixture game (`fixtures/mini-game`) where each reviewer rule is broken by a query flag: the clean run passes
every rule, each flag fails its rule (`npm run smoke`).
- Muscle Titans 1.7.0 and 2.0.1, built from git before the fixes for two reviewer emails: the session finds
`inviteLink` called every second, the save copy in `localStorage`, autosave once a minute, unlimited rewarded
ads, `isUserAccountAvailable` read every second; the audit finds the missing iOS scrollbar. 2.0.2, the fixed
version, passes all of them. Not checkable by the tool: the midgame countdown text and the banner suggestion.
- Blocky Barber and TowerDefence (three.js; TowerDefence renders over a second per frame under SwiftShader):
scenarios open every window and both pass; their ads are off before Full Launch, so the ad rules stay unchecked.
- `game_check`: a canvas fixture (`fixtures/canvas-game`) where each probe finding is planted once and a label under
a window must not be found, plus the inventory comparison (`npm run smoke`). A Phaser 4 strategy game in
development, on its dev server: 7 languages x 3 sizes found a card cut by the right edge on phones, captions under the bottom edge in
landscape and 40 px buttons; the inventory of 2571 textures takes 7 s and showed a loading change left every
picture identical.
## Limits
- Chromium under SwiftShader: WebGL works, timings are slower than a real GPU.
- The portal's real iframe `allow` list is not known; the emulated one is permissive.
- `textSize` uses 12 px, the owner's threshold, not a docs number.
- Custom iOS scrollbars are recognised by class names and roles; a miss is a warning.
- A canvas-drawn interface cannot be measured from the DOM; the audit says so in `unchecked`; `game_check` reads it
from the Phaser scene, through the game's adapter. Other canvas engines need their own probe.
- Unity and Godot export plugins are assumed to call the same JS SDK; not verified.
## Commands
```
npm test build + unit tests (node:test)
npm run smoke real MCP client over stdio against the fixture game
node tools/run.mjs build|session|audit|game <path> [...] one tool without a client
```
TDQS
Scored across 3 tools
Each tool targets a different validation phase—static build checks, SDK/runtime behavior, and DOM/layout measurement—with no overlapping scope. Descriptions clearly delineate what each covers.
All tools share the cg_ prefix and snake_case, forming a predictable namespace. However, they use noun phrases rather than a verb_noun pattern, so naming is consistent but not action-oriented.
Three tools is on the low side but each covers a broad, distinct area of game validation (static, SDK, frame). The count is reasonable for a focused audit suite, though additional specialized checks would not be unexpected.
Covers static build checks, runtime SDK behavior, and layout auditing, forming a solid validation surface for HTML5 game portals. Minor gaps could include performance/network diagnostics or automated fix suggestions, but core workflows are addressed.