From 5a4acfc6bb8523556f2e8fa6664f1a33ff5509c4 Mon Sep 17 00:00:00 2001
From: cocos02 <cocos02@163.com>
Date: Fri, 12 Jun 2026 21:26:00 +0800
Subject: [PATCH] docs: update SCENE_JSON_SPEC with current types, deprecate
 flag fields

---
 docs/guide/SCENE_JSON_SPEC.md | 44 ++++++++++++++++++++++++++++++++++-
 engine/types.ts               |  4 ++--
 2 files changed, 45 insertions(+), 3 deletions(-)

diff --git a/docs/guide/SCENE_JSON_SPEC.md b/docs/guide/SCENE_JSON_SPEC.md
index e7f298f..31f7ba7 100644
--- a/docs/guide/SCENE_JSON_SPEC.md
+++ b/docs/guide/SCENE_JSON_SPEC.md
@@ -39,7 +39,9 @@ interface SceneNode {
   id: string
   type?: 'video' | 'image'
   videoUrl: string
+  streamingUrl?: Record<string, string>
   imageUrl?: string
+  thumbnail?: string
   contentSize?: { w: number; h: number }
   subtitleUrl?: string
   subtitles?: Record<string, string>
@@ -64,8 +66,10 @@ interface SceneNode {
 |------|------|------|
 | `id` | string | 场景唯一标识 |
 | `type` | string | `"video"` (默认) 或 `"image"`。image 类型展示图片+热点，不播放视频 |
-| `videoUrl` | string | 视频文件路径。image 场景可为空 |
+| `videoUrl` | string | 视频文件路径（本地 MP4，桌面版使用）。image 场景可为空 |
+| `streamingUrl` | object | Web 版使用的 CDN 流媒体路径。三档画质：`{ "超清 (1080P)": "...", "高清 (720P)": "...", "标清 (480P)": "..." }`。引擎根据 `getVideoMode()` 自动选择环境 |
 | `imageUrl` | string | 图片场景的图片路径 |
+| `thumbnail` | string | 场景缩略图路径 |
 | `contentSize` | object | 内容基准分辨率 `{ w: 1280, h: 720 }`，Hotspot 坐标基于此计算。用于 object-fit: contain 的偏移补偿 |
 | `subtitleUrl` | string | 回退字幕路径。优先使用 `subtitles` |
 | `subtitles` | object | 多语言字幕 `{ "zh": "...", "en": "..." }`。语言切换时自动选择 |
@@ -106,6 +110,7 @@ interface Choice {
 | `text` | 选项文本（回退值） |
 | `textKey` | i18n key，优先于 `text`。如 `"intro.choice.left_door"` |
 | `prompt` | 选择后浮现的提示文字（回退值） |
+| `promptKey` | prompt 的 i18n key。如 `"left_door.prompt.handshake"`。优先于 `prompt` |
 | `promptKey` | prompt 的 i18n key。如 `"left_door.prompt.handshake"` |
 | `targetScene` | 目标场景 ID |
 | `conditions` | 显示条件，不满足的选项隐藏 |
@@ -130,6 +135,7 @@ interface Hotspot {
   hideAt?: number
   conditions?: Condition[]
   effects?: Effect[]
+  timeLimit?: number
 }
 ```
 
@@ -145,6 +151,7 @@ interface Hotspot {
 | `targetScene` | 点击后跳转的场景 |
 | `conditions` | 显示条件 |
 | `effects` | 点击后触发的效果 |
+| `timeLimit` | 限时热点（秒），超时后热点消失 |
 
 ---
 
@@ -170,6 +177,7 @@ interface QTEDefinition {
 |------|------|
 | `triggerTime` | 触发时间（秒），视频播放到此时间弹出 QTE |
 | `prompt` | 提示文字（回退值） |
+| `promptKey` | i18n key。如 `"right_door.qte.dodge"`。优先于 `prompt` |
 | `promptKey` | i18n key。如 `"right_door.qte.dodge"` |
 | `keys` | 有效按键列表，如 `["ArrowLeft", "ArrowRight", "a", "d"]` |
 | `timeLimit` | 限时秒数 |
@@ -217,6 +225,15 @@ interface ChapterInfo {
 }
 ```
 
+| 字段 | 说明 |
+|------|------|
+| `id` | 章节 ID |
+| `label` | 章节名称（回退值） |
+| `labelKey` | i18n key，优先于 `label` |
+| `startScene` | 起始场景 ID。玩家到达此场景时章节自动解锁 |
+| `thumbnail` | 缩略图路径 |
+| `defaultVariables` | 从章节选择界面进入时的默认变量值。未设时 fallback 到全局 `variables` |
+
 ### AchievementDef
 
 ```typescript
@@ -232,6 +249,17 @@ interface AchievementDef {
 }
 ```
 
+| 字段 | 说明 |
+|------|------|
+| `id` | 成就唯一 ID |
+| `title` | 成就标题（回退值） |
+| `titleKey` | i18n key，优先于 `title` |
+| `description` | 成就描述（回退值） |
+| `descKey` | i18n key，优先于 `description` |
+| `icon` | 图标路径 |
+| `hidden` | `true` 时未解锁不显示标题和描述（显示 ???） |
+| `condition` | 解锁条件。变量满足时自动解锁并弹出 toast |
+
 ### EndingDef
 
 ```typescript
@@ -245,6 +273,15 @@ interface EndingDef {
 }
 ```
 
+| 字段 | 说明 |
+|------|------|
+| `id` | 结局唯一 ID |
+| `label` | 结局名称（回退值） |
+| `labelKey` | i18n key，优先于 `label` |
+| `sceneId` | 结局场景 ID。玩家到达此场景时结局自动标记已解锁 |
+| `chapterId` | 结局归属章节 ID（可选，BFS 自动推导） |
+| `thumbnail` | 缩略图路径 |
+
 ### LocalesConfig
 
 ```typescript
@@ -253,3 +290,8 @@ interface LocalesConfig {
   languages: string[]
 }
 ```
+
+| 字段 | 说明 |
+|------|------|
+| `path` | 语言文件目录（相对于 `assetBase`），如 `"locales/"` |
+| `languages` | 支持的语言列表，如 `["zh", "en", "ja"]` |
diff --git a/engine/types.ts b/engine/types.ts
index b32dd0b..e359d40 100644
--- a/engine/types.ts
+++ b/engine/types.ts
@@ -53,12 +53,12 @@ export interface Hotspot {
 
 export interface Condition {
   variable: string
-  op: '>' | '<' | '>=' | '<=' | '==' | '!=' | 'hasFlag'
+  op: '>' | '<' | '>=' | '<=' | '==' | '!=' | 'hasFlag'  // @deprecated hasFlag will be removed
   value: number | string | boolean
 }
 
 export interface Effect {
-  type: 'set' | 'add' | 'toggleFlag' | 'triggerEvent'
+  type: 'set' | 'add' | 'toggleFlag' | 'triggerEvent'  // @deprecated toggleFlag will be removed
   target: string
   value?: number | string | boolean
 }