# Game Experience Analyzer
**Parent project:** [GameDesignOS by Paranoia](../README.en.md)
**Languages:** [简体中文](./README.md) | English
Turn game screenshots, recordings, trailers/PVs, and video links into traceable evidence plus actionable design judgment.
`game-experience-analyzer` is an agent skill / Markdown skill package for game design analysis. It does not watch a video and write a loose reaction essay. It first builds screenshot, keyframe, and timestamp evidence, then routes the task into the right lens: early experience, gameplay mechanics, game dissection, holistic product analysis, MDA, systems-narrative fusion, single-player flow, trailer heat prediction, foresight opportunity, genre strategy, commercialization, or UX/UI.
It is built for game designers, producers, publishing and marketing teams, competitor research, AI-assisted game teams, and anyone who needs to turn "this game feels good/bad" into "where is the evidence, what is the problem, and how should we validate the next step?"
Copyright (c) 2026 Paranoia. Licensed under the MIT License.
## Why This Exists
Game experience analysis often fails in two ways:
- **Feeling without evidence.** It says "addictive", "bad pacing", or "strong hook" without pointing back to a frame, timestamp, UI element, or loop.
- **One template for every game.** Casual games, single-player games, SLG, X+SLG, trailers, playtest recordings, and screenshot audits all get forced into the same wording.
This skill has a narrow practical goal:
```text
Input media -> Evidence timeline -> Mode router -> Design lenses -> Actionable report
```
It identifies the input source and analysis intent first, then chooses strategy based on genre and sample boundaries. Hook/Loop/Link/Surprise is one available lens, not the universal answer.
## What It Can Analyze
| Input | Best For | Output Style |
| --- | --- | --- |
| Screenshot | UI hierarchy, primary goal clarity, crowded entry points, reward expression, static hook | visual evidence table + UX/experience diagnosis |
| Local recording | first hour, onboarding, tutorials, gameplay loop, monetization interruptions | timeline + event stream + feature ledger |
| Trailer / PV | heat potential, clarity of selling point, conversion path, edit direction | heat potential tier + validation plan |
| Video link | public videos, competitor recordings, cloud clips, social media snippets | access notes + visible evidence + degraded analysis when needed |
## Analysis Modes
| Mode | Use When | Core Questions |
| --- | --- | --- |
| `early_experience` | first login, onboarding, first hour, stickiness | Why does the player continue? Does the first loop close? |
| `gameplay_mechanics` | mechanics, core loop, player actions | What does the player do? How do actions create feedback and growth? |
| `holistic_game_analysis` | whole product, positioning, experience and market together | Do positioning, play structure, content supply, monetization, and window fit each other? |
| `whole_game_mda` | user explicitly asks for MDA | Are Mechanics, Dynamics, and Aesthetics aligned or broken? |
| `systems_narrative_fusion` | theme, value conflict, play-as-narrative | Is the theme generated by mechanics, choices, and consequences? |
| `single_player_design` | single-player flow, level, boss, narrative, open or semi-open structure | Do critical path, pacing, agency, and challenge feedback work? |
| `trailer_heat_prediction` | PV, trailer, ad creative | How strong are the first seconds, selling point, proof of play, platform fit, and conversion bridge? |
| `foresight_opportunity` | opportunity window, project value, whether to follow a direction | What is the opportunity type, remaining window, Go/No-Go condition, minimum validation deadline, and kill condition? |
| `genre_benchmark` | genre strategy, benchmark, X+SLG | Which strategies migrate, and which do not? |
| `problem_diagnosis` | what is wrong, how to fix it | What is the root cause, smallest change, owner, and validation metric? |
## Diagnosis Packs
Diagnosis packs are not new analysis modes. They route a user scenario into existing modes and required sections.
| Pack | Primary Mode | Use |
| --- | --- | --- |
| PV heat diagnosis | `trailer_heat_prediction` | Judge first-second hook, selling point repetition, shareable peaks, and validation path. |
| First-hour retention diagnosis | `early_experience` | Diagnose first-hour flow, feature ledger, confusion/failure signals, and retention hooks. |
| Core-loop diagnosis | `gameplay_mechanics` | Diagnose core actions, decision points, resource economy, progression unlocks, and loop closure. |
| Game dissection diagnosis | `holistic_game_analysis` + `gameplay_mechanics` | Break down player verbs, action-goal alignment, uncertainty, system dynamics, content flow, audience desire, playable theme, and transfer boundary. |
| Steam/store conversion diagnosis | `trailer_heat_prediction` + `ux_ui` | Diagnose first screen, tags, screenshot order, trailer bridge, and wishlist CTA. |
| Project greenlight risk diagnosis | `foresight_opportunity` | Judge window phase, opportunity type, Go/No-Go, minimum validation, and kill conditions. |
| Monetization interruption diagnosis | `commercialization` | Diagnose whether paid/ad/welfare prompts break the player's current goal. |
| Single-player pacing diagnosis | `single_player_design` | Diagnose critical path, pacing beats, agency, challenge feedback, and finish intent. |
## Foresight Window Defaults
Foresight work separates the opportunity validation window from the full development cycle.
| Scope | Default Validation Window | Meaning |
| --- | --- | --- |
| Casual / light games | 1-3 months | Quickly validate direction with assets, prototypes, clicks, retention, or conversion signals. |
| Micro / midcore-heavy games | 3-6 months | Validate core gameplay, retention, monetization bridge, or market conversion before continuing to observe. |
| Large projects | Custom development cycle | Development may take longer, but staged opportunity validation still needs shorter checkpoints. |
## Quick Start
Use it in any agent environment that can load local skills or Markdown skill packages:
```text
Use $game-experience-analyzer to analyze this local gameplay recording into timestamped evidence, gameplay mechanics, MDA, Hook/Loop/Link/Surprise scores, and actionable recommendations.
```
Chinese requests are also natural:
```text
用 game-experience-analyzer 分析这个单机游戏录屏，重点看关卡主路径、节奏、玩家自主权、挑战反馈和整体 MDA。
```
```text
用 game-experience-analyzer 分析这个游戏宣传片，预测它有没有爆款潜力，并给出证据、置信度和验证指标。
```
```text
用 game-experience-analyzer 判断这个题材和玩法方向现在还值不值得做，给出窗口期、Go/No-Go、最小验证截止和 Kill 条件。
```
```text
用 game-experience-analyzer 做游戏拆解诊断包。先写 dissection_goal 和样本边界，再拆玩家动词、动作-目标对齐、不确定性、系统动态、内容流、受众动机、可玩主题和迁移边界。
```
## Example Output
See:
- [`examples/README.md`](./examples/README.md)
The index lists the current public example with its `input_type`, `diagnosis_pack`, `main_mode`, `confidence_boundary`, and output file.
## Tooling
| Source | Minimum Setup | Better Setup |
| --- | --- | --- |
| Screenshot | direct visual analysis | OCR when UI text changes judgment |
| Local video | `ffmpeg` for frame extraction | sampled frames + dense event timeline |
| Video URL | browser access or visible metadata | `yt-dlp` equivalent + frame extraction |
| Speech/subtitles | optional | ASR only when voice/subtitle changes judgment |
When tooling is missing, the report keeps `tool_readiness`: missing items, impact, recommended setup, and the degraded scope of the current analysis.
## Evidence Rules
- Every important judgment must point back to a screenshot region, timestamp, keyframe, page metadata, or user-provided fact.
- Screenshots cannot directly prove pacing, feel, waiting time, or loop closure; mark those claims as `uncertain`.
- Trailers/PVs can only predict heat potential and validation paths, not guaranteed sales, revenue, or downloads.
- External research must pass VOI: browse only when it can change genre judgment, version facts, benchmark standards, market heat, window phase, Go/No-Go, or recommendation priority.
- Outputs must distinguish `known`, `unknown`, `uncertain`, `access_notes`, and `tool_readiness`.
## Project Boundary
Temporary collaboration instructions are not public project rules. A user may ask an agent to follow a one-off order, avoid a phrase, use a temporary case, or execute a session-specific sequence; those instructions bind the current task only.
Only write a change into this skill when at least one condition is true:
- It reliably improves analysis quality for other users.
- It is a public, reusable, verifiable method, template, example, or maintenance rule.
- The user explicitly asks to preserve it in the project.
Otherwise, treat it as local collaboration context and do not place it in README, SKILL, references, templates, or examples.
## Package Layout
```text
game-experience-analyzer/
|-- SKILL.md
|-- README.md
|-- README.en.md
|-- agents/
| `-- openai.yaml
|-- evals/
| |-- evals.json
| |-- negative_cases.md
| `-- rubric.yaml
|-- examples/
| |-- README.md
| `-- survival-33-days-gameplay-experience-report.md
|-- references/
| |-- analysis-mode-router.yaml
| |-- diagnosis-pack-router.yaml
| |-- foresight-opportunity-lens.zh-CN.md
| |-- game-dissection-diagnosis.zh-CN.md
| |-- genre-strategy-router.yaml
| |-- sample-scope-gate.zh-CN.md
| |-- single-player-analysis.zh-CN.md
| |-- system-design-review-lens.zh-CN.md
| |-- tooling-setup.zh-CN.md
| |-- trailer-heat-prediction.zh-CN.md
| `-- video-analysis-workflow.zh-CN.md
`-- templates/
|-- analysis-input.json
|-- evidence-index.schema.json
|-- experience-report.md
|-- game-dissection-report.md
|-- issue-card.md
|-- mode-output-map.yaml
|-- quick-triage-report.md
|-- structured-output.example.json
|-- structured-output.schema.json
`-- trailer-heat-report.md
```
## Validation
Run from the repository root:
```text
python scripts/validate_repo.py
python scripts/validate_skill.py game-experience-analyzer
```
All JSON/YAML files should parse cleanly.
## Design Principle
```text
Evidence first.
Mode before framework.
Genre before recommendation.
VOI before research.
Validation before confidence.
```