# Game AI Analyzer

**Repository Path**: SKINGAP/game-ai-analyzer

## Basic Information

- **Project Name**: Game AI Analyzer
- **Description**: 分析视频逆向写出文档和分析试玩内容
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-09
- **Last Updated**: 2026-07-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Game AI Reverse Engineer

Game AI Reverse Engineer turns gameplay or UA videos into structured game knowledge, design documents, and Codex-ready implementation specs. Phase 2 includes an operational React Analysis Workbench.

The product direction is not `video -> summary`. The core flow is:

```text
video -> Video Memory -> Game Event Stream -> Game Reasoning -> Documents
```

## Phase 1 Scope

Implemented in this repository:

- FastAPI backend.
- Video upload API.
- SQLite persistence with SQLAlchemy.
- OpenCV metadata reading and key-frame extraction.
- No-op OCR and ASR adapters with stable contracts.
- Video Memory Agent.
- Gameplay Agent.
- Mechanic Agent.
- Evidence-backed Codex specification data with deterministic 2D/3D Unity guidance.
- Markdown generation for `GAME_DESIGN_DOCUMENT.md`, `UA_REPORT.md`, and `GAME_SPEC.md`.
- Docker Compose backend service.
- Demo fallback when `OPENAI_API_KEY` is not configured.

- React and TypeScript Analysis Workbench.
- Chinese-first bilingual interface with an English option.
- Per-task Chinese or English analysis and generated documents.

## API

### Health

```http
GET /health
```

### Upload Video

```http
POST /api/video/upload
Content-Type: multipart/form-data
```

Form fields:

- `file`: the video file.
- `analysis_language`: optional, `zh-CN` (default) or `en`. The selected language is fixed for the task when it is uploaded.

Response:

```json
{
  "video_id": "uuid",
  "status": "uploaded",
  "analysis_language": "zh-CN"
}
```

### Start Analysis

```http
POST /api/analyze/{video_id}
```

The analysis runs as a FastAPI background task.

### Get Report

```http
GET /api/report/{video_id}
```

Returns status, errors, the task's `analysis_language`, Video Memory, gameplay JSON, mechanics JSON, and Markdown reports. The interface language can be switched independently; existing task output is not regenerated.

### List Recent Videos

```http
GET /api/videos
```

## Environment

Copy `.env.example` to `.env` and fill values as needed.

```text
OPENAI_API_KEY=
OPENAI_MODEL=gpt-5.2
ENABLE_DEMO_FALLBACK=true
DATABASE_URL=sqlite:///./storage/app.db
KNOWLEDGE_SEARCH_PROVIDER=local
QDRANT_URL=
QDRANT_API_KEY=
QDRANT_COLLECTION=game_ai_knowledge
QDRANT_SCORE_THRESHOLD=0.01
KNOWLEDGE_EMBEDDING_PROVIDER=hashing
KNOWLEDGE_EMBEDDING_MODEL=text-embedding-3-small
KNOWLEDGE_EMBEDDING_DIMENSIONS=384
KNOWLEDGE_EMBEDDING_BATCH_SIZE=64
```

If `OPENAI_API_KEY` is empty, the app still runs and produces clearly labeled demo fallback output. Set `ENABLE_DEMO_FALLBACK=false` if OpenAI failures should fail the task instead.

`KNOWLEDGE_SEARCH_PROVIDER=local` is the default and uses the JSON assets in `backend/knowledge`. Qdrant also defaults to deterministic, offline `hashing` embeddings. To opt in to semantic embeddings, set `KNOWLEDGE_EMBEDDING_PROVIDER=openai` and provide `OPENAI_API_KEY`; both indexing and every Qdrant query then make billable OpenAI Embeddings API requests. There is no silent fallback to hashing. See `docs/knowledge/qdrant-runbook.md` before enabling Qdrant or changing its embedding configuration.

`VITE_API_BASE_URL` is a frontend build-time variable and is unrelated to backend/OpenAI settings. Never prefix backend secrets or knowledge embedding variables with `VITE_`, because Vite-prefixed values can be exposed in browser assets.

## Local Development

Install Python 3.11, then run:

```bash
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
uvicorn backend.main:app --reload
```

In another terminal:

```powershell
pnpm.cmd --dir frontend install
pnpm.cmd --dir frontend dev
```

Open `http://localhost:5173`. Set `VITE_API_BASE_URL=http://localhost:8000` when the API is not reached through the same origin.

Run tests:

```bash
pytest -v
```

## Docker

```bash
docker compose up --build
```

Workbench runs on `http://localhost:5173` and the backend on `http://localhost:8000`. A `.env` file is optional; create one from `.env.example` when you want to set an OpenAI key or override defaults.

## Project Structure

```text
backend/
  api/          FastAPI routes
  agents/       Video Memory, Gameplay, Mechanic, UA, and Codex agents
  core/         Settings and environment configuration
  knowledge/    Provider-backed game knowledge loading and search
  models/       SQLAlchemy and Pydantic models
  pipeline/     Video processing, OCR/ASR adapters, orchestration, documents
  prompts/      Versionable agent prompts
frontend/       React/Vite Analysis Workbench
storage/
  videos/       Uploaded videos
  frames/       Extracted key frames
  reports/      Generated markdown reports
tests/          Unit and smoke tests
```

## Future Phases

Remaining Phase 2 extensions:

- Knowledge base enrichment.
- Additional knowledge enrichment and semantic embedding providers.

Phase 3:

- Codex Agent refinement for game-specific code generation.
- Unity batch compilation, Play Mode verification, and automated repair.

Completed Phase 3 foundation:

- Completed analyses can generate immutable Unity 2022.3.62f2 prototype versions from the Workbench.
- Generated projects include deterministic 2D/3D placeholder gameplay, state flow, win/restart behavior, an Editor scene bootstrap, and GAME_SPEC acceptance checks.
- Projects are stored under `storage/unity_projects/<video_id>/v<version>` and are not compiled or opened automatically.

### Docker Base Image

The Dockerfile uses `PYTHON_IMAGE` as a build argument. The default is `public.ecr.aws/docker/library/python:3.11-slim` because it was reachable during local verification. Override it if your environment prefers Docker Hub:

```bash
PYTHON_IMAGE=python:3.11-slim docker compose up --build
```

## Phase 1.1 Verification

Phase 1.1 adds an automated generated-video roundtrip test. It creates a tiny MP4 at test time, uploads it through the API, starts analysis, and verifies the report payload contains Video Memory, GDD, UA report, and GAME_SPEC output.

Every current `GAME_SPEC.md` targets Unity 2022.3.62f2, C#, and UGUI. It records an evidence-backed 2D or 3D decision with confidence and rationale, then provides scenes, scripts, Prefabs, UI, ordered implementation steps, and later Play Mode checks. Insufficient or contradictory dimensional evidence uses a visibly documented low-confidence 2D fallback. This phase generates Markdown specifications only; it does not create, compile, open, or run a Unity project.

Run it with:

```bash
docker run --rm -v E:\Git\game-ai-analyzer:/app -w /app game-ai-analyzer-backend python -m pytest tests/test_api_roundtrip.py -v
```

## Phase 2 Backend Intelligence

Phase 2 currently adds backend intelligence without adding a frontend-first workflow:

- `KnowledgeRepository` loads genres, mechanics, patterns, and monetization JSON assets.
- `KnowledgeSearchProvider` defines the stable search contract used by API routes and agents.
- `LocalVectorSearch` is the default `local` provider and preserves the existing result shape.
- `build_knowledge_search` selects the provider from `KNOWLEDGE_SEARCH_PROVIDER`.
- `QdrantKnowledgeSearchProvider` performs filtered vector queries through Qdrant's universal query API.
- `HashingTextEncoder` provides stable, offline 384-dimensional development embeddings.
- `QdrantKnowledgeIndexer` creates the collection and upserts stable UUID points from the JSON assets.
- `MechanicAgent` uses the provider contract to infer mechanics from Video Memory and gameplay JSON.
- `UaAgent` now produces Phase 2 scoring for hook, clarity, fun density, emotion curve, conversion risk, and optimization variants.

### Knowledge Search

```http
GET /api/knowledge/search?q=merge%20upgrade%20reward&limit=5
```

Response shape:

```json
{
  "query": "merge upgrade reward",
  "limit": 5,
  "source": null,
  "provider": "local",
  "results": [
    {
      "source": "mechanics",
      "item": {"name": "Merge"},
      "score": 0.6667,
      "matched_terms": ["merge", "upgrade"]
    }
  ]
}
```

Filter by source with `source=mechanics`, `source=genres`, `source=patterns`, or `source=monetization`. API callers should rely on the stable response shape and the `provider` field instead of importing concrete search classes.

### Qdrant Quick Start

```powershell
docker compose --profile qdrant up -d qdrant
docker compose --profile qdrant run --rm -e QDRANT_URL=http://qdrant:6333 backend python -m backend.knowledge.index_knowledge --recreate
```

Set `KNOWLEDGE_SEARCH_PROVIDER=qdrant`, then start the backend with the same profile. Local search is restored by setting the provider back to `local`. Detailed collection, reindex, verification, and rollback instructions are in `docs/knowledge/qdrant-runbook.md`.

Reference documentation:

- `docs/api/data-contracts.md`
- `docs/knowledge/authoring-guide.md`
- `docs/knowledge/qdrant-runbook.md`
- `docs/ops/verification.md`
- `docs/product/user-workflow.md`

## Repository Automation

`AGENTS.md` instructs future agents to verify, commit, and push completed work automatically. If push fails because of authentication, network, or remote conflicts, the local commit should be preserved and the failure reason should be reported.