roadrunner-core

Name: roadrunner-core
Author: matlab

github.com/matlabその他1.2k47 回インストール1 日前に更新

リポジトリ

roadrunner-core について

MATLAB から RoadRunner を操作するワークフローの基盤となるスキルです。接続の初期化とプロジェクト、シーン、シナリオの管理を行い、後続スキル向けに `rrApp` ハンドルを提供します。

主な機能

01RoadRunner の初期化または接続
02プロジェクトの作成、オープン、保存
03シーンとシナリオの管理
04ワールド原点とシーン範囲の設定
05状態確認と RoadRunner の終了

活用シーン

01後続スキル向けに RoadRunner を準備
02プロジェクトを開いてシーンを選択
03シナリオを作成または保存
04地理原点やシーン範囲を調整

MCP 対応

MATLAB の実行には `evaluate_matlab_code` MCP ツールを使用します。このツールを介して RoadRunner の操作を実行し、`rrApp` ハンドルを初期化します。

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/matlab/matlab-agentic-toolkit --skill roadrunner-core

インストール後、Claude Code で/roadrunner-coreを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

manifest.yaml

scripts/

rrCoreCommands.m

rrCoreInitialize.m

詳細

RoadRunner Core

すべてのRoadRunnerエージェントワークフローの基盤となるスキルです。MATLABからRoadRunnerへの接続、プロジェクト／シーン／シナリオのライフサイクル、ハンドル管理を行います。以降のすべてのRoadRunnerスキルで使用するrrAppハンドルを生成します。

実行：すべてのMATLABコードは、MCPツールのevaluate_matlab_codeを介して実行します。matlab -batchは使用しないでください。

使用する場合

MATLABからRoadRunnerに接続または起動する場合
プロジェクト、シーン、シナリオを作成、開く、または保存する場合
ワールド原点またはシーンの範囲を設定する場合
RoadRunnerのステータスを確認する場合
RoadRunnerを安全に終了する場合
以降のRoadRunnerスキルでrrAppの初期化が必要な場合

使用しない場合

RoadRunnerがインストールされていない場合 — このスキルには正常に動作するRoadRunnerのインストールが必要です。製品のインストールはできません。
MATLABのバージョンがR2022aより前の場合 — roadrunnerクラスと関連APIは、それ以前のリリースでは使用できません。
rrAppがすでに存在し、有効な場合 — rrCoreInitializeを再実行しても安全です（冪等性があります）が、必要はありません。オーバーヘッドを避けるため、まずexist('rrApp','var')で確認することをおすすめします。
初回セットアップが必要なのに、ユーザーからインストール先やプロジェクトのパスが提供されていない場合 — まずユーザーに確認し、パスを推測しないでください。
RoadRunnerが意図的に終了されている場合 — ユーザーの明示的な許可なしに再接続または再起動しないでください。

1. エージェントによるこのスキルの使用方法

初回セットアップ（マシンごとに1回 — 2段階の解決方法）

rrCoreInitializeは、2段階の方法を使ってセットアップを自動的に処理します。

段階	条件	処理
1	設定が有効で、`roadrunner`クラスがパス上にある	セットアップを省略 — 設定済み
2	エージェントに`installFolder`変数と`projectPath`変数がある	プログラムによるセットアップ：`addpath`、`savepath`を実行し、MATLABの設定を書き込みます。GUIは使用しません。

rrCoreInitializeを実行するだけです。 スクリプトが次の処理を自動的に行います。

実行中のインスタンスに接続します（roadrunner.connect()）。
接続に失敗した場合、保存済みの設定を使って新しいインスタンスを起動します（roadrunner()）。
未設定の場合はPathsRequiredエラーになります。その場合はユーザーにinstallFolderとprojectPathを尋ね、値を設定してから再実行します。

セットアップに成功すると、以降のMATLABセッションでも設定が永続します。再度行う必要はありません。

GUIダイアログは表示されません。 このスキルはroadrunnerSetupを呼び出しません。設定はすべてプログラムで行います。

セッション中の初回呼び出し

MATLABパスにスキルのスクリプトを追加します（rrCoreInitializeを見つける前に必要です）。
```
addpath("<absolute-path-to-this-skill>/scripts");
```
<absolute-path-to-this-skill>を、このスキルのディレクトリの実際のファイルシステムパス（このSKILL.mdファイルを含むフォルダー）に置き換えます。
rrCoreInitializeを実行します。実行中のインスタンスへの接続、保存済み設定を使った起動、未設定の場合の明確なメッセージを伴うエラーのいずれかを処理します。
PathsRequiredエラーが発生した場合は、ユーザーにinstallFolderとprojectPathを尋ね、変数として設定してからrrCoreInitializeを再実行します。
ユーザーのリクエストに進みます。

2回目以降の呼び出し

exist('rrApp','var')を確認します。存在しない場合はrrCoreInitializeを再実行します。
Decision Logicテーブル（セクション3）で操作を確認します。
scripts/rrCoreCommands.mの対応する%%見出しの下から、正確なパターンをコピーします。
プレースホルダーを実際の値に置き換えます。
evaluate_matlab_codeを介して実行します。

重要な原則

API呼び出しを即興で作らないでください。 RoadRunnerを操作する前に、rrCoreCommands.mの対応する%%セクションを読み、そこにあるコードをそのまま再現してください。関数名、引数の構文、パラメーターの順序を記憶から推測しないでください。これにより、実在しない関数名、ガードレールの不足、ハンドルの無効化忘れを防げます。

操作の正しい構文がわからない場合は、実行を中断し、呼び出しを試みる前にパターンファイルを読んでください。

2. ファイル

ファイル	役割
`scripts/rrCoreInitialize.m`	直接実行します。パス、接続、検証を初期化します。
`scripts/rrCoreCommands.m`	パターンの参照用です。エージェントが `%%` セクションを読み取り、プレースホルダーを置換して実行します。

デプロイ

初回使用時に、エージェントは RoadRunner API が MATLAB パスに含まれていることを確認します（savepath は一度だけ実行します）。このスキルのスクリプトはパターンの参照用です。エージェントは内容を読み取り、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`	ユーザーに確認します：「現在の場所に保存しますか、それとも新しい名前で保存しますか？」新しい名前の場合は、`sceneName` を指定して `SAVE_SCENE_AS` を使います
新しいシナリオを作成	`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 で使用される変数名です。エージェントは実行前に、これらを実際の値に置換します。

プレースホルダー	型	例
`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 のパスを追加した後に savepath を実行します。これにより、MATLAB のセッション間で設定が保持されます。ユーザーが RoadRunner をアップグレードすると、エージェントは失敗（roadrunner クラスが見つからない、またはバージョンが一致しない）を検出し、新しいインストールフォルダーを確認します。

7. 重要なルール

必ず最初に rrCoreInitialize を実行する — 検証済みの rrApp がない状態で RoadRunner API を呼び出さないでください
許可なく起動しない — roadrunner(ProjectFolder=...) を実行する前に、必ずユーザーに確認してください
セッションごとに rrApp は 1 つだけ — 2 つ目の接続を作成しないでください
呼び出しの前に必ずパターンを読む — rrCoreCommands.m を開き、該当する %% セクションを見つけて、記載どおりに再現してください。記憶を頼りに構文を推測しないでください。
自動保存しない — NEW_SCENE、NEW_SCENARIO、および CLOSE のパターンは未保存の変更を検出しますが、自動保存はしません。必ずユーザーに、保存、名前を付けて保存、または破棄のどれにするか確認してください。同じ名前で保存すると元のファイルが上書きされ、そのファイルが古いバージョンで作成されていた場合、後方互換性が損なわれる可能性があります。
接続後にバージョンを確認する — rrApp.Version を確認して報告してください。ユーザーが特定のバージョンを指定している場合、一致しなければ警告してください。
保存前に確認する — 保存が必要な場合（新しいシーン／シナリオ、終了、または明示的な保存要求）、現在の場所に保存するか、新しい名前で保存するか、変更を破棄するかをユーザーに確認してください
見つからない場合は一覧表示する — 名前が存在しないため openScene または openScenario が失敗した場合は、dir を使って利用可能なシーン／シナリオを一覧表示し、選択肢をユーザーに提示してください
相対シーンパスは <project>/Scenes/ に解決されます
パスでは Unicode はサポートされません
ハンドルの無効化は自動 — パターンには clear 文が含まれています
すべての実行は MCP 経由 — matlab -batch は使用しないでください
close(rrApp) は RoadRunner を完全に終了させます — プロセスが終了します。終了後は roadrunner.connect() が失敗します。再接続するには、新たに roadrunner() を起動する必要があります。
再起動時にシーンは復元されません — 終了して再起動すると、RoadRunner はプロジェクトを開きますが、シーンは空白のままです。エージェントは目的のシーンを明示的に再度開く必要があります。

8. 避けるべきパターン

ユーザーの許可なく RoadRunner を起動しないでください
すでに接続済みの場合、roadrunner(ProjectFolder=...) を呼び出さないでください — 重複したインスタンスが起動します
roadrunner.connect(port, port) に引数を 2 つ渡さないでください — ポートは 1 つだけ指定してください
閉じている、または無効な 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.

Markdown 対応

ログインしてコメント

基本情報

作者: matlab
リポジトリ: matlab/matlab-agentic-toolkit
カテゴリ: その他
インストール数: 47
GitHub スター: 1,221

問題を報告