tianshu-engine/.opencode/skills/moviegame/SKILL.md

name, description

name	description
moviegame	Edit JSON-driven interactive movie game config files. Validates scene references, variables, and structure.

Movie Game Engine Skill

你正在编辑一个 JSON 驱动的交互电影游戏配置文件。先读文件、理解现有结构，再精确修改。

关键参考文件（需要时自行读取）

文件	内容
engine/types.ts	全部类型定义：SceneNode、Choice、Condition、Effect、QTEDefinition、GameData 等
docs/ARCHITECTURE.md	架构约束：A/B 双缓冲、JSON 驱动、事件系统
AGENTS.md	项目开发约定

当前编辑的故事配置文件路径由对话上下文提供（如 public/scenes/demo.json）。

核心操作规则（必须遵守）

1. key === id：scenes 对象 key 必须等于 SceneNode.id，始终一致。新增场景时两者设为相同值
2. 变量先声明后使用：新增 effects/conditions 引用新变量名 → 必须先在 GameData.variables 中追加声明（初始值建议 0）
3. 删除清理：删除场景时，必须清理所有其他场景中对它的引用：choices[].targetScene、nextScene、qte.successScene、qte.failScene、hotspots[].targetScene
4. 引用有效：所有 targetScene、nextScene（string 形式）、successScene、failScene、startScene 必须指向 scenes 中存在的 key
5. 保持结构：修改场景时保留所有已有字段，除非明确要求删除

变量使用位置（全部）

下列所有位置引用的变量名都必须在 GameData.variables 中声明：

位置	字段
Choice.effects	Effect.target
Choice.conditions	Condition.variable
nextScene (Choice[]) 每个路由的 effects	Effect.target
nextScene (Choice[]) 每个路由的 conditions	Condition.variable
SceneNode.onEnter	Effect.target
QTEDefinition.effects.success	Effect.target
QTEDefinition.effects.fail	Effect.target
Hotspot.effects	Effect.target
Hotspot.conditions	Condition.variable
AchievementDef.condition	Condition.variable
BattleHUDStat	variable
BattleResultStat	variable
ChapterInfo.defaultVariables	keys

Effect 格式：{ "type": "set", "target": "变量名", "value": 5 } 或 { "type": "add", "target": "变量名", "delta": 1 } Condition 格式：{ "variable": "变量名", "op": ">=", "value": 3 }（op 支持 > < >= <= == !=）

场景引用关系

• Choice.targetScene — 选项跳转目标
• nextScene — string = 直接跳转；Choice[] = 条件路由（逐条 evaluate conditions，第一条匹配的生效）
• QTEDefinition.successScene / failScene — QTE 成功/失败跳转
• Hotspot.targetScene — 热点跳转
• ChapterInfo.startScene — 章节起始场景
• EndingDef.sceneId — 结局关联场景
• GameData.startScene — 游戏起始场景