用途
NQTR in ink 用于在采用 Pixi'VN 与 @drincs/nqtr 的项目里编写 .ink 文件。凡是需要改变或读取 NQTR 状态的 ink 行，都应使用本技能提供的井号命令，而不是把交互逻辑写在 TypeScript 标签中。实体（房间、活动、承诺、任务）必须已在 TypeScript 中定义并注册。
安装与初始化
在 ink 初始化时调用一次：
import { createNqtrHandler } from "@drincs/nqtr/ink"; createNqtrHandler();
createNqtrHandler(options?) 会注册下文全部命令以及任务变量读取器。可选参数包括：timeConverter(time: string) => number（默认把 "01:30" 转为 1.5，即把冒号替换为点）、dateConverter(date: string) => number（默认 Number）、wait(delta)（替换默认的时间/日期推进）、activityIds / commitmentIds / questIds / roomIds（只读 id 数组，例如 vitePluginNqtr 生成的 nqtr*Ids，用于校验 id）。未提供 id 数组时接受任意字符串。nqtrHandler() 是已弃用的别名。
主要命令
命令语法中 <...> 为占位符，并非 ink 插值。
-
enter room <roomId>：设置 navigator.currentRoom，位置与地图随之更新。
-
set time <time>：设置 timeTracker.currentTime，接受 18、18.30、18:30。
-
set date <date>：设置 timeTracker.currentDate。
-
wait：按 timeTracker.defaultTimeSpent 推进时间。
-
wait <time>：推进指定小时数，超过 dayEndTime 后进入下一天。
-
wait days <n>：推进 n 天，时间重置为 dayStartTime。
-
wait days <n> hours <t>：同时推进天与小时。
-
add activity <activityId> in <roomId>：运行时链接活动，随游戏保存。
-
remove activity <activityId> from <roomId>：解除运行时链接的活动。
-
add routine <commitmentId> in <roomId>：运行时链接承诺，随游戏保存。
-
remove routine <commitmentId>：移除运行时链接的承诺。
-
start quest <questId>：调用 quest.start(props)。
-
continue quest <questId>：调用 quest.continue(props)，进入下一阶段。
未知 id 会记录警告（如 Room x not found）并跳过该命令。命令需独占一行或作为内容行上的标签，放置规则遵循 pixi-vn-ink-hashtag-commands。
示例：
=== start ===
enter room mc_room
set time 08:00
add activity order_product in mc_room
start quest aliceQuest
mc: Let's begin.
wait 2
wait days 1 hours 8
-> DONE
任务变量
处理器还会在 ink 表达式中解析只读的任务状态，<id> 为任务 id：
- <id>_started：boolean
- <id>_completed：boolean
- <id>_failed：boolean
- <id>_currentStageIndex：number（从 0 开始；完成后为 stages.length）
示例：
=== talk_alice === { aliceQuest_currentStageIndex:
- 0: -> talk_alice0
- 1: -> talk_alice1
- else: alice: Thanks for the book. } -> DONE
= talk_alice0 alice: Can you order me a book from the PC?
continue quest aliceQuest
-> DONE
- {aliceQuest_started && not aliceQuest_completed} Ask about the quest
不要在 ink 中声明 VAR aliceQuest_started，该值来自 NQTR。任务失败没有对应井号命令：需在 TypeScript 中设置 quest.failed = true，或通过自定义井号命令实现（参见 pixi-vn-ink-hashtag-commands）。
无法从 ink 完成的操作
创建/注册实体、timeTracker.initialize、enter room 之外的 navigator 查询、quest.advanceIfCompleted、隐藏/禁用实体、timeTracker.isWeekend / currentTimeSlot，这些需在 TypeScript 中完成，或通过自定义井号命令、外部函数暴露。
从 UI 调用 ink 的典型方式
活动与承诺在 TypeScript 中执行 onRun(entity, props)；若要交由 ink 处理，可跳转到对应 knot：await narration.jump("knot_name", props)（ink knot 即 Pixi'VN 标签）。详见 nqtr-activity。