# GameAnalytic

> Analyze any Play Store / App Store game via Scrapling: scrape metadata + all reviews, then let ai-chat's agent synthesize marketing & game-design docs to recreate the product

| | |
|---|---|
| Version | 1.0.1 |
| Category | AI & Agents |
| Permissions | process.spawn, shell.exec, filesystem.read, filesystem.write, network.remote |
| Depends on | ai-chat |

# GameAnalytic

Analyze any Play Store / App Store game from its URL: scrape metadata + user reviews with Scrapling,
then let the ai-chat agent synthesize Marketing & Game-Design docs detailed enough to recreate the
product. The plugin owns the **data** (scraping); the ai-chat agent owns the **intelligence** (analysis
+ writing the docs), so no LLM API key lives here.

**Type:** `backend` — see `.claude/skills/kazuo-create-plugin/references/plugin-examples.md`.
Full design notes: `.claude/features/game-analytic.md`.

## Requirements

Python + Scrapling on the machine running the app:

```
pip install "scrapling[fetchers]"
```

Set the interpreter in Settings → `pythonPath` if it isn't on PATH. The 🔧 button (Check deps) reports
what's missing.

## Files

- `manifest.json` — `mainEntry=main/index.js`; `defaultSettings`: `pythonPath`, `maxReviews`, `docLang`;
  `requirements.python=true`.
- `widget.html` / `js/widget.js` / `css/widget.css` — **multi-line URL box (one link per line)** +
  max-reviews + language. One line → single report; **2+ lines → cross-platform report** (scrape-multi →
  mini comparison + combined analysis, Export HTML → export-html-multi). Ctrl/⌘+Enter to run. Single-report
  preview: metadata, review stats, an **Analysis & estimates card** (investment score + signal, downloads/
  revenue, game age, version-regression warning, top features, tech score) and **Top evidence** (most-voted
  praise/complaint — replaces the raw review list). Optional analysis-docs textarea, Export HTML, Copy
  analysis prompt (builds 3 docs: Marketing + Game Design + **Investment**) / Copy raw JSON, 🔧 check-deps.
- `settings.html` / `js/settings.js` / `css/settings.css` — same fields as the widget overlay, used by
  the Plugin Manager screen and the pop-out window.
- `locales/en.json5` / `locales/vi.json5` — UI strings.
- `main/index.ts` (+ `main/index.js`) — IPC channels `plugin:game-analytic:{check-deps,scrape,scrape-multi,
  fetch-page,youtube,export-html,export-html-multi}` + `getMcpTools` exposing `check_deps`, `scrape_game(url)` (full),
  `analyze_game(url)` (compact), `export_html(url, docs?, lang?)`, plus **cross-platform**:
  `analyze_multi(urls[], maxReviews?)` (scrape + merge several URLs into one compact multi analysis),
  `export_html_multi(urls[], ...)` (open one combined report), and **research**: `fetch_page(url)` (fetch a
  homepage/guide/company page) + `youtube_research(query, withComments?, maxVideos?)` (top videos + **Shorts**
  + real comments via innertube; honest `commentsError` when a clip has none). Both export tools accept `homepageUrls[]` and
  `youtubeQueries[]` → the plugin fetches them and renders an "External sources" section (homepage cards +
  YouTube video lists).
- `main/analytics.ts` (+ `.js`) — in-plugin analytics engine (no LLM, no deps): `computeAnalytics(result)`
  returns a rough downloads & revenue estimate, rating health, sentiment, monetization signals + depth,
  technical health, top praises/complaints, **lifecycle** (age, last update, launch→update), **per-version
  score breakdown + regression flag**, **rating trend over time** (Play), **current-vs-lifetime rating**
  (App Store), **feature inventory** (each feature tagged by source — developer/description vs players —
  and by player sentiment: positive/negative mention counts → like-ratio → liked/mixed/disliked),
  **dev responsiveness**, **localization/reach**, **platform support**
  (OS + iPhone/iPad/iPod form-factor breakdown + tablet flag), an **investment
  scorecard** (5 sub-scores + overall + risks), and **most-voted praise/complaint quotes**. Also owns the
  shared NLP (`tokenize`, `EMOTION_LEXICON`, `STOPWORDS`, `buildWordClouds`). `scraper-engine.scrape()`
  attaches `result.analytics` automatically. Honest limits: no pre-launch dev time, no real
  retention/DAU/revenue — only labelled proxies.
- `main/html-report.ts` (+ `.js`) — self-contained report via a shared `pageShell` + sticky **table of
  contents** + hero-stats band, organised into **numbered, colour-accented sections** (1 Executive
  summary + verdict, 2 Platforms, 🌐 External sources when `research.pages` given, 3 Technical, 4 Business,
  5 Users & sentiment, 6 Features with source + like/dislike sentiment, 7 Docs). External sources renders
  homepage guide cards + YouTube video lists (with honest comment-error notes).
  `buildReportHtml(result, docs, lang, research?)` = single platform; `buildMultiReportHtml(multi, docs, lang, research?)` = **cross-platform**
  (section 1 adds a gap card, section 2 a per-store comparison table; sections 3–6 run on the pooled
  combined analysis). Content per section: investment scorecard, downloads/revenue estimate + disclaimer,
  lifecycle + version breakdown + rating trend, supported platforms (clickable store link + Apple/Google-Play
  icon, OS + iPhone/iPad/iPod form factors + tablet + languages + size), rating health, monetization,
  feature inventory, technical health + dev replies, praises/complaints (each risk has a title + a detailed
  numbers-backed reason), top-voted evidence quotes + two **word clouds** (player emotions + features talked
  about, hover for counts). Raw reviews are NOT listed. `test/build-report.test.js` checks it
  (`node test/build-report.test.js`).
- `main/scraper-engine.ts` (+ `.js`) — resolves the Python interpreter, runs the scraper scripts, and
  attaches `computeAnalytics(result)` to every scrape result.
- `main/scraper/` — Python (Scrapling): `check_deps.py`, `common.py`, `appstore.py`, `playstore.py`
  (metadata from ld+json + the richer `ds:5` blob → installs/exact-installs, version, release/updated
  dates, screenshots; index paths verified 07/2026, null on mismatch), `scrape.py`, **`fetchpage.py`**
  (fetch a web page → title/description/headings/text/links), **`youtube.py`** (search videos + Shorts +
  real comments), `requirements.txt`. Runnable standalone: `python scrape.py --url <store-url> --max-reviews 200`
  / `python fetchpage.py --url <homepage-url>` / `python youtube.py --query "<game> gameplay" --with-comments`.

## Default settings

- `pythonPath` — default: `""` (auto-detect `python`/`python3`)
- `maxReviews` — default: `2000` (Play Store fetches up to 2000 via internal RPC; App Store is capped at
  ~500 by Apple's review RSS)
- `docLang` — default: `"vi"`

## Usage

1. Open Kazuo AI → Plugin Manager → GameAnalytic appears automatically → Install → Enable.
2. In the widget, paste a game URL (e.g. `https://play.google.com/store/apps/details?id=...` or
   `https://apps.apple.com/us/app/.../id...`), pick language + max reviews, click Analyze.
3. To get the Marketing / Game-Design docs: attach this plugin to an ai-chat session (the agent calls
   `scrape_game` itself), or click **Copy analysis prompt** and paste it into ai-chat.
4. For a visual report: click **Export HTML** (optionally paste the AI docs first) to open a dashboard +
   docs report in your browser. The agent can also call `export_html` to do this in one step.

After editing any `main/*.ts`, recompile: `npx tsc -p tsconfig.plugins.json` (from the project root).