剧本 Mod:剧情脚本与地图Scenario mods: story scripts and maps

数据 Mod 新增的行可以引用 Mod 自己目录里的剧情 Lua 和关卡地图,用来做自定义开局、引导和演出。不需要程序入口,PC 与手机都按数据 Mod 加载。 Rows added by a data mod can reference story Lua and level maps shipped inside the mod itself — for custom starts, guidance and cutscenes. No program entry is needed; PC and mobile load it as a data mod.

本页的查找规则和脚本运行模型按代码核对。示例 mods/ScenarioModExample 尚未在游戏内完整验收:自定义开局界面是否列出 Mod 追加的初始组合行、手机真机读取,都未验证。 The lookup rules and run model on this page were checked against the code. The example mods/ScenarioModExample has not been fully verified in game: whether the custom-start screen lists initial-combination rows added by mods, and reading on a real phone, are both untested.

剧情脚本不是 Lua 程序 ModStory scripts are not Lua program mods

两者都把 .lua 放在 <version>/Lua/,但是两套独立的机制,可以在同一个 Mod 里同时使用。 Both keep .lua files in <version>/Lua/, but they are separate mechanisms and one mod may use both.

剧情脚本(本页)Story script (this page)Lua 程序 ModLua program mod
如何声明Declared by数据行的字段,如 GuideMissionDef.scriptA field on a data row, e.g. GuideMissionDef.script清单的 luaMainluaMain in the manifest
何时运行Runs when存档中该引导节点被触发时The guide node is triggered inside a save游戏启动时加载,一直存在到退出Loaded at startup, alive until quit
运行环境Environment游戏共用的剧情 Lua 环境,同一时刻只运行一个脚本The game's shared story Lua environment; one script at a time每个 Mod 独立的 Lua 环境One Lua environment per mod
主要接口Main interfacemission 对象(剧情脚本参考)The mission object (story script reference)CS.* 调用 C#、ModDelegateDispatch 事件CS.* calls into C#, ModDelegateDispatch events
如何结束Ends by脚本自己调用 mission:endScript 或 mission:failScriptThe script calling mission:endScript or mission:failScriptonUnload

目录Layout

ScenarioModExample/
├─ Manifest/manifest.xml               ← packageId = scenario.example,不声明 luaMain← packageId = scenario.example, no luaMain
└─ v_common/
   ├─ Resources/Def/def.xml            ← 引导节点、地图、初始组合三行← guide node, map and initial-combination rows
   ├─ Resources/Map/StartMap.nsmt      ← 关卡地图← level map
   └─ Lua/ModStart.lua                 ← 剧情脚本← story script

查找规则Lookup rules

字段Field先在 Mod 内找Looked up in the mod first都找不到时If found nowhere
GuideMissionDef.script<version>/Lua/<script>.lua该引导节点失败,日志 Lua 文件不存在: …(Mod packageId)The guide node fails; log Lua 文件不存在: …(Mod packageId)
M_StarMapPath_Def.Path<version>/Resources/Map/<Path>.nsmt开档时报错 Mod 开局地图未找到,不回退到默认地图Starting the save throws Mod 开局地图未找到; there is no fallback map
  • 只对来自 Mod 的行生效,且只在该行所属 Mod 当前版本目录内查找。原版行不受影响,仍只读游戏目录。Applies only to rows that come from a mod, and only searches the owning mod's selected version folder. Built-in rows are unaffected and keep reading the game folder.
  • Mod 内没有同名文件时,按游戏自己的脚本 / 地图目录查找。所以 Mod 行也能引用官方脚本和地图;同名时 Mod 内的文件优先。When the mod has no such file, the game's own script / map folder is searched. Mod rows can therefore reference official scripts and maps; on a name clash the mod's file wins.
  • 路径必须是相对路径,不能含 .、.. 或空段;越出 Mod 目录直接报 Mod 资源路径非法。扩展名可省略。Paths must be relative with no ., .. or empty segments; escaping the mod folder raises Mod 资源路径非法. The extension may be omitted.
  • 引用 Mod 新增的行要写带前缀的完整 ID(<packageId>_<ID>),见ID 前缀。Reference rows added by a mod using the full prefixed ID (<packageId>_<ID>); see ID prefixing.

数据行Data rows

v_common/Resources/Def/def.xml
<?xml version="1.0"?>
<ModXmlDef>
  <files />
  <rows>
    <!-- 地图:复制原版 PresetMap1,Path 指向本 Mod 的 Resources/Map/StartMap.nsmtMap: copy built-in PresetMap1; Path points at this mod's Resources/Map/StartMap.nsmt -->
    <ModDefRow Name="M_StarMapPath_Def" DependID="PresetMap1">
      <Item Name="ID">StartMap</Item>
      <Item Name="Name">示例 Mod 开局地图</Item>
      <Item Name="Path">StartMap.nsmt</Item>
    </ModDefRow>

    <!-- 初始基地组合:地表模板改为上面的地图,引用时写完整 IDInitial base combination: use the map above as surface template, referenced by full ID -->
    <ModDefRow Name="S_EditorKit_InitialCombination_Def" DependID="M-01">
      <Item Name="ID">M-Start</Item>
      <Item Name="Name">示例 Mod 初始基地</Item>
      <Item Name="TemplateID">scenario.example_StartMap</Item>
    </ModDefRow>

    <!-- 引导节点:最终 ID 为 scenario.example_StartGuide node: final ID is scenario.example_Start -->
    <ModDefRow Name="GuideMissionDef">
      <Item Name="ID">Start</Item>
      <Item Name="Name">示例 Mod 开局</Item>
      <Item Name="script">ModStart</Item>
      <Item Name="scriptfun">start</Item>
      <Item Name="Nextscript">-1</Item>
      <Item Name="EventTrigger">-1</Item>
    </ModDefRow>
  </rows>
</ModXmlDef>
GuideMissionDef 字段GuideMissionDef field含义Meaning
script脚本文件名,按上面的规则查找。Script file name, resolved by the rules above.
scriptfun入口函数名,必须是脚本里的全局函数。留空时使用 start。Entry function name; must be a global function in the script. Empty means start.
Nextscript下一个引导节点的 ID,没有则填 -1。ID of the next guide node, or -1 for none.
EventTrigger关联的事件 ID,多个用 | 分隔,没有则填 -1。具体触发时机本站未验证。Associated event IDs separated by |, or -1 for none. Exactly when they fire has not been verified for this site.
地图行的 DependID 可能不生效。M_StarMapPath_Def 不随启动加载,而是在存档里第一次用到时才读入;本站导出数据时(游戏停在封面)这张表是 0 行。Mod 的 XML 行在启动阶段转换,此时找不到 PresetMap1 这个模板,按代码该行会被跳过并记录 class or dependID not found: M_StarMapPath_Def PresetMap1。这是按代码和导出数据推断的,没有在游戏内实测;做地图类 Mod 时请先看日志确认这一行是否加入。 DependID on the map row may not work. M_StarMapPath_Def is not loaded at startup; it is read the first time a save needs it, and it had 0 rows when this site's data was exported (game at the title screen). Mod XML rows are converted during startup, when the PresetMap1 template cannot be found, so by the code the row is skipped with class or dependID not found: M_StarMapPath_Def PresetMap1. This is inferred from the code and the exported data, not tested in game; when building a map mod, check the log first to confirm the row was added.

示例中触发这个节点的方式:自定义开局时,“初始基地”选 Mod 的初始组合,“开局引导”填 scenario.example_Start。别的引导节点也可以用 Nextscript 指向它。 How the example triggers the node: in a custom start, pick the mod's combination as initial base and enter scenario.example_Start as the opening guide. Another guide node may also point to it through Nextscript.

脚本结构Script structure

脚本必须定义两个全局函数:call(mission, entry) 和入口函数。最简单的写法是在入口里同步做完并结束(取自示例 Mod): A script must define two global functions: call(mission, entry) and the entry function. The simplest form does its work synchronously in the entry and ends there (from the example mod):

v_common/Lua/ModStart.lua
local stopped = false

local function cleanup()
    stopped = true
end

function call(mission, entry)
    stopped = false
    mission:registerCleanup(cleanup)
    entry(mission)
end

function start(mission)
    if stopped then return end
    mission:showToast('示例 Mod 剧情 Lua 已运行')
    mission:endScript('ModStart')
end

需要等待玩家操作或界面播放时,用协程:call 把入口包成协程存进 co2,入口在调用会等待的接口后 coroutine.yield(),界面结束时游戏恢复协程。下面是官方脚本的写法(Origin-Main-IndustryA-Guide.lua,文本从略): To wait for the player or for UI to finish, use a coroutine: call wraps the entry in a coroutine stored in co2; the entry calls a waiting API and then coroutine.yield(), and the game resumes the coroutine when the UI is done. This is how an official script does it (Origin-Main-IndustryA-Guide.lua, text shortened):

local script = "Origin-Main-IndustryA-Guide"
local mission = nil
local co2

function call(m, f)
    mission = m
    co2 = coroutine.create(f)
    return co2
end

function start1(m)
    mission = m
    mission:disableEventDrive()
    mission:disableCamearDrag()
    mission:disableCamearZoom()
    mission:doForceTutorial()
    mission:pauseGame()

    local v1 = CS.UnityEngine.Vector2Int(-770, 282)
    local v2 = CS.UnityEngine.Vector2Int(-320, 323)
    local rect1 = CS.UnityEngine.Rect(0, 0, 2400, 1080)
    mission:introduceRect_Avatar(rect1, "Nora", "...", v1, v2, false, true)
    coroutine.yield()                 -- 等玩家点击后继续resumes after the player clicks

    mission:endScript(script)
end

一次运行的过程What happens in one run

GuideMissionTrigger → ScriptManager.TryLoadLua → ScriptInterface

  1. 引导节点被触发。已有剧情脚本在运行时,这次触发不会启动。The guide node is triggered. If another story script is running, this trigger does not start.
  2. 读取并编译脚本,执行顶层代码。The script is read, compiled and its top-level code runs. 顶层只做定义,不要在这里改游戏状态Only define things at top level; don't change game state here
  3. 检查全局函数 call 和入口函数是否存在,缺任意一个都失败:Lua 入口无效。The globals call and the entry function must exist; otherwise the run fails with Lua 入口无效.
  4. 调用 call(mission, entry);脚本此时仍未结束的话,接着恢复协程 co2。call(mission, entry) is invoked; if the script has not ended by then, the coroutine co2 is resumed. call 没创建 co2 又没在入口里结束 → 失败:Lua coroutine is missingNo co2 and not ended inside the entry → fails: Lua coroutine is missing
  5. 脚本每次 coroutine.yield() 后,等对应的界面、镜头或对白完成,游戏再恢复协程。After each coroutine.yield(), the game resumes the coroutine once the matching UI, camera move or dialogue finishes.
  6. 结束:mission:endScript 为完成;mission:failScript 或 Lua 报错为失败(日志 Lua 演出失败);读档、换档、退出为取消。Ending: mission:endScript completes; mission:failScript or a Lua error fails (logged as Lua 演出失败); loading another save or quitting cancels.
  7. 无论哪种结束,游戏都会逆序调用 registerCleanup 登记的函数,再恢复脚本改过的状态。只有“完成”才把引导节点记为已完成。However it ends, the game calls the functions registered with registerCleanup in reverse order and then restores the state the script changed. Only “completed” marks the guide node finished.
协程函数返回了却没有调用 endScript,并且没有界面在等待时,这次运行判为失败:Lua coroutine ended without endScript。每条路径都要以 endScript 或 failScript 收尾。 If the coroutine function returns without calling endScript and no UI is being waited on, the run fails with Lua coroutine ended without endScript. End every path with endScript or failScript.

常用的 mission 接口Common mission methods

下面是官方脚本里用得最多、且已按代码核对的接口;全部方法见剧情脚本参考。标“等待”的接口调用后要 coroutine.yield()。 These are the most used methods in official scripts that were checked against the code; the full list is in the story script reference. Methods marked “waits” must be followed by coroutine.yield().

接口Method作用Effect
endScript(label)正常结束,label 只写进日志。Ends normally; label only goes to the log.
failScript(reason)以失败结束并记录原因。Ends as failed and logs the reason.
registerCleanup(fn)登记结束时要调用的清理函数。Registers a function to call when the run ends.
showToast(text)弹出一条提示,文本原样显示。Shows a toast with the text as is.
introduceRect_Avatar(...)高亮屏幕区域并显示带头像的引导文字。等待。Highlights a screen area with avatar guidance text. Waits.
showWord(text)在对白界面显示一段文字。等待。Shows a line in the dialogue view. Waits.
locationCell(x, y, scale, time, wait)镜头移到指定格;wait 为 true 时等待到位。Moves the camera to a cell; with wait = true it waits for arrival.
pauseGame() / playGame() / setFpsScale(n)暂停、恢复地面逻辑,设置速度倍率。Pause or resume ground simulation; set its speed multiplier.
disableCamearDrag() / disableCamearZoom() / disableEventDrive()禁用镜头拖动、缩放、地图输入;各有对应的 enable…。Disable camera drag, zoom and map input; each has a matching enable….
showCmd_Main() / hideCmd_Main()显示、隐藏主界面底部栏。Show or hide the main HUD's bottom bar.
checkLua(check, next) + checkFinish()约每秒调用一次名为 check 的函数,返回 true 后启动 next。用来等一个游戏内条件。Calls the function named check about once a second and starts next once it returns true — for waiting on an in-game condition.
triggerEvent(id)触发 TK_EventTriggerDef 中的事件。Triggers an event from TK_EventTriggerDef.

结束时自动恢复的状态State restored when the run ends

脚本通过 mission 改过下列状态时,游戏在运行结束(完成、失败、取消)时把它们恢复为脚本开始前的值,前提是之后没有别的系统再改动过。所以中途失败不会把镜头或输入永久锁住;需要保留的效果请用游戏数据(事件、任务)表达,而不是这些临时开关。 When a script changes the following through mission, the game restores them to their pre-script values when the run ends (completed, failed or cancelled), provided nothing else changed them afterwards. A mid-way failure therefore never leaves the camera or input locked; for lasting effects use game data (events, missions) rather than these temporary switches.

  • 镜头拖动、缩放开关与镜头跟随Camera drag and zoom switches, camera follow
  • 地图输入开关、强制引导状态、按钮点击限制Map input switch, forced-tutorial state, button click limits
  • 暂停状态与逻辑速度Pause state and simulation speed
  • 主界面各栏的显示状态Visibility of the main HUD bars
  • 背景音乐与音效的停止状态Stopped state of music and sound

注意事项Things to watch

  • 剧情 Lua 环境是全游戏共用的。除 call 和入口函数外都用 local,避免和官方脚本、其他 Mod 的全局变量互相覆盖。每次启动前游戏会清掉 call、co2、continue、fairyContinue、fairyYield 和入口函数名这几个全局。The story Lua environment is shared by the whole game. Use local for everything except call and the entry function, so your globals don't collide with official scripts or other mods. Before each start the game clears the globals call, co2, continue, fairyContinue, fairyYield and the entry function name.
  • 脚本里也能用 CS.*(如上例的 CS.UnityEngine.Rect),手机上同样受 IL2CPP 限制。Scripts may also use CS.* (like CS.UnityEngine.Rect above); on mobile the same IL2CPP limits apply.
  • 显示给玩家的文本是否查语言表因接口而异:showToast 原样显示,showTip 把参数当作文本 Key。其他接口请在游戏里确认。Whether player-facing text is looked up in the language table depends on the method: showToast shows it as is, showTip treats the argument as a text key. Check other methods in game.
  • packageId 不要含下划线,原因见清单。Keep underscores out of packageId; see Manifest for why.