用途
NQTR 导航与地图模块用于在 NQTR 项目中定义和切换房间、地点与地图。它采用三层容器结构：地图包含地点，地点包含房间；角色（主角与 NPC）的位置由当前房间推导得出，当前地点和当前地图也由当前房间自动确定。这些术语是约定性的，在其他题材中可对应为行星、恒星系、星系等。
主要能力
- 实体创建与注册：通过 MapBaseModel、LocationBaseModel、RoomBaseModel 分别创建地图、地点和房间，每个实体需要指定父级。创建后必须使用 RegisteredMaps.add、RegisteredLocations.add、RegisteredRooms.add 注册，否则房间无法保存或从 ink 进入。
- 查询：RegisteredRooms.get(id)、RegisteredLocations.get(id)、RegisteredMaps.get(id) 按 ID 获取单个实体，.values() 返回全部；navigator.rooms、navigator.locations、navigator.maps 列出已注册实体。
- 导航：设置 navigator.currentRoom（可接受房间对象或其 ID）切换当前房间，地点与地图随之更新；也可在游戏开始时执行。navigator.currentRoomId、navigator.currentLocation、navigator.currentMap 可读取当前状态。navigator.clearExpiredActivities() 用于清除日程已结束的活动。
- 自定义类：可继承 RoomStoredClass、LocationStoredClass、MapStoredClass 并实现对应接口，在 nqtr.d.ts 中扩充属性（如名称、精灵/背景、禁用、隐藏、入口等）。构造函数形式为 Room(id, location, { activities?, routine? })、Location(id, map, activities?)、Map(id, activities?)。可变标志通过 getStorageProperty/setStorageProperty 存储。
- 图形元素：background 接受资源别名字符串或 TimeSlotsImage（按一天中的时间段切换图像）；sprite 接受资源别名字符串，或返回 PixiJS 元素的函数（例如带 eventMode: "static" 和 pointerdown 处理器的 Sprite）；icon 是返回 UI 元素（如 React 按钮）的函数。
- 地点默认入口房间：在 Room 与 RoomInterface 中加入 isEntrance，并在 Location 中暴露 entrance getter，返回带 isEntrance 的房间，若无则返回第一个房间，空则返回 undefined。地图 UI 可在点击地点图标时执行 navigator.currentRoom = location.entrance。
使用方式
- 按“地图 → 地点 → 房间”的顺序创建实体，每个实体传入父级。
- 将创建好的实体注册到对应的 Registered* 集合。
- 在游戏开始时或需要时设置 navigator.currentRoom。
- 内容文件之间相互引用时，导入顺序不能形成循环依赖：父级（先地图，后地点）由子级导入。
- 若项目使用 ink 处理故事侧导航，优先使用 nqtr-ink。
适用场景
适用于需要在 NQTR 中组织多房间、多地点、多地图的移动与导航逻辑的项目，例如角色在不同房间之间移动、通过地点图标进入地点默认房间、按时间段切换房间背景图像等。
限制与注意事项
- 忘记调用 Registered*.add 会导致房间无法保存或无法从 ink 进入。
- 常见做法是重写 rooms/locations 的 getter 以过滤隐藏项，但这样隐藏房间将不会出现在 location.rooms 中。
- 资料未提供收费、价格、平台支持范围或具体效果数据。
- 官方文档：pixi-vn.com/nqtr/navigation。