Skip to main content
Glama
README.md
# 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

A3.6/5.0

Scored across 3 tools

Disambiguation5/5

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.

Naming Consistency4/5

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.

Tool Count4/5

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.

Completeness4/5

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.