roadrunner-core

RoadRunner Core

为所有 RoadRunner Agent 工作流提供基础支持。在 MATLAB 中管理 RoadRunner 连接、项目／场景／情景的生命周期以及句柄管理。生成供所有下游 RoadRunner 技能使用的 rrApp 句柄。

执行方式：所有 MATLAB 代码均通过 evaluate_matlab_code MCP 工具运行。绝不使用 matlab -batch。

适用场景

• 从 MATLAB 连接或启动 RoadRunner
• 创建、打开或保存项目、场景或情景
• 设置世界原点或场景范围
• 检查 RoadRunner 状态
• 安全关闭 RoadRunner
• 任何下游 RoadRunner 技能需要初始化 rrApp

不适用场景

• 未安装 RoadRunner — 此技能需要可正常运行的 RoadRunner 安装，无法安装该产品
• MATLAB 版本低于 R2022a — 较早版本不支持 roadrunner 类及相关 API
• rrApp 已存在且有效 — 重新运行 rrCoreInitialize 是安全的（具备幂等性），但没有必要；建议先检查 exist('rrApp','var')，以免产生额外开销
• 用户未提供安装或项目路径，且需要首次设置时 — 先询问用户，不要猜测路径
• RoadRunner 已按计划关闭 — 未经用户明确许可，不要重新连接或启动

---

1. Agent 如何使用此技能

首次设置（每台机器仅需一次 — 两级解析）

rrCoreInitialize 会通过两级方式自动处理设置：

级别	条件	操作
1	设置有效，且 roadrunner 类已在路径中	跳过设置 — 已完成配置
2	Agent 有 installFolder 和 projectPath 变量	以编程方式设置：addpath、savepath，并写入 MATLAB 设置。无需 GUI。

只需运行 rrCoreInitialize。 脚本会自动：

1. 连接到正在运行的实例（roadrunner.connect()）
2. 如果连接失败，则使用已保存的设置启动新实例（roadrunner()）
3. 如果尚未配置，则报错 PathsRequired — 随后询问用户 installFolder 和 projectPath，设置这些变量并重新运行

设置成功后会永久保存（跨 MATLAB 会话生效），无需再次设置。

不会弹出 GUI 对话框。 此技能不会调用 roadrunnerSetup。所有配置均以编程方式完成。

会话中的首次调用

1. 将技能脚本添加到 MATLAB 路径中（必须先完成此操作，才能找到 rrCoreInitialize）：

   addpath("<absolute-path-to-this-skill>/scripts");
   

   将 <absolute-path-to-this-skill> 替换为此技能目录的实际文件系统路径（即包含此 SKILL.md 文件的文件夹路径）。
2. 运行 rrCoreInitialize → 它会处理所有操作：连接到正在运行的实例，或使用已保存的设置启动实例；如果尚未配置，则会显示清晰的错误消息。
3. 如果报错 PathsRequired → 询问用户 installFolder 和 projectPath，将它们设置为变量，然后重新运行 rrCoreInitialize。
4. 继续处理用户的请求。

后续调用

1. 检查 exist('rrApp','var') — 如果不存在，则重新运行 rrCoreInitialize
2. 在决策逻辑表（第 3 节）中查找相应操作
3. 从 scripts/rrCoreCommands.m 中对应的 %% 标题下复制准确模式
4. 将占位符替换为实际值
5. 通过 evaluate_matlab_code 执行

核心原则

绝不即兴编写 API 调用。 每次执行 RoadRunner 操作前，都要阅读 rrCoreCommands.m 中对应的 %% 部分，并严格按原样复现。不要凭记忆猜测函数名、参数语法或参数顺序。这样可以避免虚构函数名、遗漏防护措施以及忘记使句柄失效。

如果不确定某项操作的正确语法，请先停下并阅读模式文件，然后再尝试调用。

---

2. 文件

文件	作用
scripts/rrCoreInitialize.m	直接运行。 初始化路径、连接和验证。
scripts/rrCoreCommands.m	模式参考。 Agent 读取 %% 部分，替换占位符，然后执行。

部署

首次使用时，Agent 会确保 RoadRunner API 已添加到 MATLAB 路径中（一次性执行 savepath）。此技能中的脚本是模式参考——Agent 会读取这些脚本，并通过 evaluate_matlab_code 复现相应模式。

---

3. 决策逻辑

用户意图	模式（%% 部分）	要替换的占位符
连接 / 初始化	INIT	—
连接但不启动	CONNECT_ONLY	—（如果没有正在运行的实例则报错）
创建新项目	NEW_PROJECT 或 NEW_PROJECT_WITH_ASSETS	projectPath — 询问用户是否包含基础资源（资源库）。始终先运行 rrCoreInitialize（调用 newProject 前，RoadRunner 必须正在运行且已打开任意项目）。
打开现有项目	OPEN_PROJECT	projectPath
保存项目	SAVE_PROJECT	—
创建新场景	NEW_SCENE	—
打开场景	OPEN_SCENE	sceneName — 如果找不到，则使用 LIST_SCENES 并提供选项
列出可用场景	LIST_SCENES	—
保存场景	SAVE_SCENE 或 SAVE_SCENE_AS	询问用户：“就地保存，还是使用新名称保存？”如果使用新名称 → 使用 SAVE_SCENE_AS 并设置 sceneName
创建新方案	NEW_SCENARIO	—
打开方案	OPEN_SCENARIO	scenarioName — 如果找不到，则使用 LIST_SCENARIOS 并提供选项
列出可用方案	LIST_SCENARIOS	—
保存方案	SAVE_SCENARIO	—
设置世界原点	CHANGE_WORLD_ORIGIN	lat、lon
设置场景中心和范围	CHANGE_SCENE_BOUNDS	x、y、w、h
仅设置场景中心	CHANGE_SCENE_CENTER	x、y
仅设置场景范围	CHANGE_SCENE_EXTENTS	w、h
清除世界投影	CLEAR_WORLD_PROJECTION	—
检查状态	STATUS	—
关闭 RoadRunner	CLOSE	—

适用版本： changeWorldSettings 需要 R2023b 或更高版本。其他所有操作从 R2022a 起均可用。

启动（由 rrCoreInitialize 处理）

首次设置完成后，如果没有正在运行的实例，rrCoreInitialize 会使用已保存的默认设置自动启动 RoadRunner。只有在使用非默认模式时才需要手动启动：

rrApp = roadrunner(ProjectFolder=projectPath, InstallationFolder=installFolder);

模式	添加此参数
无头（无 UI）	NoDisplay=true
无桌面 + 图形	NoDesktop=true
自定义端口	Ports=[apiPort, cosimPort]

手动启动仍需获得用户的明确许可。

---

4. 占位符

这些是在 rrCoreCommands.m 中使用的变量名称。Agent 会在执行前将其替换为实际值。

占位符	类型	示例
SKILL_SCRIPTS_DIR	string	（此技能 scripts/ 文件夹的绝对路径）
rrApp	roadrunner	（来自 rrCoreInitialize，绝不重新赋值）
projectPath	string	"D:/Projects/HighwayProject"
sceneName	string	"FourWaySignal.rrscene"
scenarioName	string	"CutInScenario"
lat	double	42.3021
lon	double	-71.3747
x、y	double	1445、1237
w、h	double	160、465
installFolder	string	"C:/Program Files/RoadRunner R2026a"

---

5. 句柄管理

此技能通过 rrCoreInitialize 生成 rrApp。会更改状态的操作（NEW_SCENE、OPEN_SCENE、NEW_SCENARIO、OPEN_SCENARIO、OPEN_PROJECT、CLOSE）包含 clear 语句，用于移除过期句柄。

---

6. 路径设置

首次使用时，RoadRunner API 路径会添加到 MATLAB 的已保存路径中。无需配置文件或环境变量。

添加 API 路径后，Agent 会运行 savepath — 使其在不同 MATLAB 会话间保持有效。如果用户升级 RoadRunner，Agent 会检测到失败（缺少 roadrunner 类或版本不匹配），并询问新的安装文件夹。

---

7. 关键规则

1. 始终先运行 rrCoreInitialize — 未验证 rrApp 前，绝不调用 RoadRunner API
2. 未经许可绝不启动 — 调用 roadrunner(ProjectFolder=...) 前，先询问用户
3. 每个会话只使用一个 rrApp — 绝不创建第二个连接
4. 每次调用前都要阅读模式 — 打开 rrCoreCommands.m，找到 %% 小节，并严格照做。不要凭记忆猜测语法。
5. 绝不自动保存 — NEW_SCENE、NEW_SCENARIO 和 CLOSE 模式会检测未保存的更改，但不会自动保存。始终询问用户是保存、另存为还是放弃更改。使用相同名称保存会覆盖原文件；如果该文件由旧版本创建，还可能导致向后兼容性问题。
6. 连接后验证版本 — 检查 rrApp.Version 并报告。如果用户要求特定版本，则在版本不匹配时发出警告。
7. 保存前先询问 — 需要保存时（新建场景/场景方案、关闭或用户明确要求保存），询问用户是原位保存、另存为新名称，还是放弃更改
8. 未找到时列出选项 — 如果 openScene 或 openScenario 因名称不存在而失败，使用 dir 列出可用的场景/场景方案，并向用户提供选项
9. 相对场景路径解析到 <project>/Scenes/
10. 路径不支持 Unicode
11. 句柄失效会自动处理 — 模式中包含 clear 语句
12. 所有执行都通过 MCP — 绝不使用 matlab -batch
13. close(rrApp) 会彻底终止 RoadRunner — 进程会退出。关闭后，roadrunner.connect() 将失败。必须重新启动 roadrunner() 才能重新连接。
14. 重新启动后不会恢复场景 — 关闭并重新启动后，RoadRunner 会打开项目，但显示空白场景。Agent 必须明确重新打开所需场景。

---

8. 反模式

• 未经用户许可，不要启动 RoadRunner
• 已连接时，不要调用 roadrunner(ProjectFolder=...) — 这会启动重复实例
• 不要向 roadrunner.connect(port, port) 传入两个参数 — 使用单个端口
• 不要对已关闭或无效的 rrApp 调用任何函数
• 不要省略模式中的 clear 语句
• 不要编造 rrCoreCommands.m 中不存在的函数调用（例如，不要使用 save(rrApp)、saveSceneAs、switchScenario 或 Latitude=lat）
• 不要硬编码安装路径 — 使用 rrCoreInitialize 中的解析链
• 未经用户询问，不要保存场景 — saveScene(rrApp, name) 会静默覆盖现有文件
• 不要混淆“关闭 MATLAB”和“关闭 RoadRunner” — 它们是独立进程
• 不要假设重新启动后会恢复场景 — 不会；始终明确重新打开

---

9. 项目结构

<RoadRunner Project>/
├── Assets/              3D models, materials, textures
├── Scenes/              .rrscene files
├── Scenarios/           .rrscenario files
├── Exports/             Exported output
├── Project/             Project metadata
└── Scripts/             User scripts (optional)

---

10. API 行为说明

项目

• newProject 会创建任何缺失的父文件夹
• 文件夹名称会成为项目名称
• 如果 openProject 指向已打开的项目，仍会创建一个新的空白场景

场景

• 相对路径解析到 <project>/Scenes/
• .rrscene 扩展名可选 — 如果缺失，RoadRunner 会自动追加
• 如果场景属于其他项目，RoadRunner 会切换到该项目
• 保存时如果存在已修改的资源，项目也会一并保存
• 如果名称已存在，saveScene(rrApp, name) 会静默覆盖 — 不会确认
• 对未命名（新建）的场景调用 saveScene(rrApp) 会报错 — 必须提供名称
• 子文件夹路径可用（例如，"Scenarios/subfolder/Name"）

场景

• newScenario、openScenario、saveScenario 从 R2022a 起可用
• 打开新场景会自动关闭当前场景
• 即使在空白（未保存）场景中，也可以打开场景

世界设置

参数	类型	描述
WorldOrigin	[lat lon]	地理空间世界原点
SceneCenter	[x y]	场景工作区中心
SceneExtents	[w h]	场景工作区尺寸
ClearWorldProjection	logical	清除当前投影

从 R2023b 起可用。

状态属性

rrStatus = status(rrApp);
rrStatus.Project.Filename         % Current project path
rrStatus.Project.UnsavedChanges   % true/false
rrStatus.Scene.Filename           % Current scene path
rrStatus.Scene.UnsavedChanges     % true/false
rrStatus.Scenario.Filename        % Current scenario path
rrStatus.Scenario.UnsavedChanges  % true/false

属性	描述
rrApp.InstallationFolder	RoadRunner 安装路径
rrApp.Version	版本字符串
rrApp.NoDisplay	控制台模式标志
rrApp.NoDesktop	无桌面模式标志

关闭

• close(rrApp) 不会提示保存——关闭前务必保存
• 会删除关联的 roadrunner 对象——关闭后不要再使用该变量
• 会彻底终止 RoadRunner 进程——不只是断开连接
• 关闭后，roadrunner.connect() 将失败（没有可连接的对象）
• 通过 roadrunner() 重新启动后，项目会恢复，但场景不会——会显示空白场景
• 端口验证强制要求端口范围为 1024–65535

连接

rrApp = roadrunner.connect();           % Default port 35707
rrApp = roadrunner.connect(portNumber); % Explicit port

模式	语法	使用场景
GUI（默认）	roadrunner(ProjectFolder=...)	交互式使用
无头模式	roadrunner(ProjectFolder=..., NoDisplay=true)	批处理/CI，无 UI
无桌面 + 图形	roadrunner(ProjectFolder=..., NoDesktop=true)	需要渲染的导出
自定义端口	roadrunner(ProjectFolder=..., Ports=[apiPort, cosimPort])	多实例

---

版权所有 2026 The MathWorks, Inc.

---