NQTR 活动(activity)是玩家可以执行的动作,例如在床上睡觉、订购商品等,并关联到一个导航元素(房间、地点或地图)。活动如何显示和触发(按钮、图标、精灵)由你的 UI 决定。
【初始化】使用 new ActivityBaseModel(id, onRun, props) 创建活动,并必须通过 RegisteredActivities.add(...) 注册。onRun(activity, props) 会收到 OnRunProps,通常会导航到叙事界面,然后跳转到剧情标签或节点。如果剧情用 ink 编写,则跳转到同名 ink 节点。
【ActivityProps】包括 name、timeSlot({ from, to? },仅在指定时间范围内有效)、dateScheduling({ from, to? },仅在指定日期范围内有效)、disabled / hidden(布尔值或 Pixi'VN 标记名)、renderIcon。
【关联(多对多)】活动只有关联到导航元素后才可用。初始化时可在房间/地点/地图构造函数中通过 activities: ["bed"] 关联,此关联不随游戏保存,因此版本间变更无需迁移。游戏过程中可通过 addActivity 关联,关联会随游戏保存,用于临时活动。
【取消关联】只能移除运行时关联的活动(removeActivity)。初始化时建立的关联无法移除,需通过 disabled/hidden 或 timeSlot/dateScheduling 控制。
【获取】RegisteredActivities.get(id) 和 RegisteredActivities.values()。activity.isActive(options?) 判断当前时间/日期是否可用;activity.expired 判断日期范围是否已过。
【自定义类】可继承 ActivityStoredClass 并实现 ActivityInterface,在 nqtr.d.ts 中扩展接口以加入 name、disabled、hidden、sprite?、icon?。构造函数调用 super(id, onRun, props) 并传入 ActivityStoredClassProps(timeSlot、dateScheduling)。通过 getStorageProperty/setStorageProperty 持久化 disabled/hidden。当 hidden 时重写 isActive 返回 false,并重写 run 在运行后刷新 UI(await runProps.invalidateInterfaceData())。
【常见问题】忘记 RegisteredActivities.add;在活动注册前按 id 关联(应先用后关,或依赖 id 列表/Vite 插件校验);建议使用稳定 id,因为 ink 命令会用到它。