diff --git a/README.md b/README.md
new file mode 100644
index 0000000..3104bdf
--- /dev/null
+++ b/README.md
@@ -0,0 +1,139 @@
+# 交互式电影游戏引擎
+
+基于 Vue 3 + TypeScript 的浏览器端交互式电影游戏引擎。
+
+## 快速开始
+
+```bash
+npm install
+npm run dev
+```
+
+浏览器打开 `http://localhost:5173/` 即可体验示例剧情。
+
+## 如何使用
+
+### 1. 编写剧情 JSON
+
+在 `public/scenes/` 目录下创建 JSON 文件，定义你的场景和分支：
+
+```json
+{
+  "startScene": "scene_1",
+  "variables": {
+    "trust": 50,
+    "courage": 0
+  },
+  "scenes": {
+    "scene_1": {
+      "id": "scene_1",
+      "videoUrl": "/videos/scene_1.mp4",
+      "choices": [
+        {
+          "text": "打开左边的门",
+          "targetScene": "scene_2a",
+          "effects": [
+            { "type": "add", "target": "courage", "value": 10 }
+          ]
+        },
+        {
+          "text": "打开右边的门",
+          "targetScene": "scene_2b"
+        }
+      ]
+    },
+    "scene_2a": {
+      "id": "scene_2a",
+      "videoUrl": "/videos/scene_2a.mp4",
+      "nextScene": "ending"
+    },
+    "scene_2b": {
+      "id": "scene_2b",
+      "videoUrl": "/videos/scene_2b.mp4",
+      "choices": []
+    },
+    "ending": {
+      "id": "ending",
+      "videoUrl": "/videos/ending.mp4",
+      "choices": []
+    }
+  }
+}
+```
+
+**字段说明：**
+
+| 字段 | 说明 |
+|------|------|
+| `startScene` | 游戏开始的场景 ID |
+| `variables` | 全局变量初始值（如好感度、勇气值） |
+| `scenes` | 所有场景节点，key 为场景 ID |
+| `videoUrl` | 视频文件路径，放在 `public/videos/` 下 |
+| `choices` | 选项列表，为空或不存在时视为结局 |
+| `nextScene` | 没有选项时的默认下一场景（自动跳转） |
+| `effects` | 选择后的效果，类型: `set`/`add`/`toggleFlag` |
+| `conditions` | 选项的显示条件（`==`, `!=`, `>`, `<`, `>=`, `<=`, `hasFlag`） |
+
+### 2. 放置视频文件
+
+将视频文件放入 `public/videos/` 目录，推荐 MP4 (H.264) 格式。
+
+生成测试视频（需要 ffmpeg）：
+
+```bash
+ffmpeg -f lavfi -i "color=c=0x1a1a2e:s=1280x720:d=3" \
+  -vf "drawtext=text='章节标题':fontcolor=white:fontsize=32:x=(w-text_w)/2:y=(h-text_h)/2" \
+  public/videos/scene_1.mp4
+```
+
+### 3. 修改加载的剧情文件
+
+在 `src/App.vue` 中修改 `loadGame()` 的路径：
+
+```ts
+await loadGame('/scenes/your_story.json')
+```
+
+## 目录结构
+
+```
+moviegame/
+├── engine/                     # 框架无关的核心引擎（不依赖 Vue）
+│   ├── core/
+│   │   ├── Engine.ts           # 主循环
+│   │   ├── SceneManager.ts     # 场景管理
+│   │   ├── VideoManager.ts     # 视频播放控制
+│   │   └── StateManager.ts     # 状态/变量/条件系统
+│   └── types.ts                # 类型定义
+├── src/                        # Vue 播放器
+│   ├── components/
+│   │   ├── GamePlayer.vue      # 视频播放器
+│   │   └── ChoicePanel.vue     # 选项面板
+│   ├── composables/
+│   │   └── useGameEngine.ts    # 引擎 ↔ Vue 桥接
+│   ├── stores/
+│   │   └── gameStore.ts        # Pinia 状态
+│   ├── App.vue
+│   └── main.ts
+├── public/
+│   ├── scenes/demo.json        # 示例剧情
+│   └── videos/                 # 视频资源
+├── ROADMAP.md                  # 开发路线图
+└── package.json
+```
+
+## 当前状态
+
+**已完成 (P0 MVP)：** 单视频播放 + 选项分支 + 状态系统 + JSON 驱动
+
+**下一步 (P1)：** A/B 双缓冲无缝切换、条件分支、IndexedDB 存档系统
+
+详见 [ROADMAP.md](ROADMAP.md)。
+
+## 命令
+
+```bash
+npm run dev        # 启动开发服务器
+npm run build      # 构建生产版本
+npm run preview    # 预览构建结果
+```