Roadrunner Build Scenario From Osc

Build RoadRunner Scenario from OpenSCENARIO

Interpret an OpenSCENARIO 1.x (.xosc) file and recreate the scenario in

RoadRunner using the roadrunner-scenario-authoring skill. Translates positions,

maps constructs, preserves relative references, and builds correct phase logic.

When to Use

• User has a .xosc file and wants to recreate it in RoadRunner
• User wants to programmatically build a scenario from OpenSCENARIO
• User says "build this .xosc in RoadRunner" or "recreate this scenario"
• User has an OpenSCENARIO file from a partner or standards body (e.g., Euro NCAP, ALKS)
• User wants to generate a MATLAB script from a .xosc file
• User says "convert this xosc to matlab" or "recreate with a matlab script"

When NOT to Use

• User says "import" a .xosc file — they want importScenario(rrApp, xoscPath), not this skill. Simply call the API directly.
• User wants to use RoadRunner's built-in importScenario (let them — it works for simple cases)
• User wants to create a scenario from scratch without a .xosc file (use roadrunner-scenario-authoring)
• User wants to export a scenario TO OpenSCENARIO (use roadrunner-export-scenario)

Critical Rules

• Never fabricate actions or conditions not present in the source XOSC.

If a construct cannot be mapped, skip it and warn the user.

• Never propose workarounds. Do not replace DistanceToPointCondition with

DurationCondition, do not substitute SimulationTimeCondition for unsupported

triggers, do not add any construct not in the source.

• Never simplify or duplicate trajectory vertices. Extract exactly the

polyline vertices present in the source XOSC — no fewer, no more. Do not

reduce 90 vertices to 5. Do not duplicate start/end points during extraction.

• Never guess scenes. Only report the .xodr filename from <LogicFile>.

Import it — do not search for a scene with a similar name.

• Never convert relative references to absolute. If the source uses

RelativeTargetSpeed delta=-8, preserve it as SpeedReference="actor" with

Direction="slower", Speed=8. Do not compute and hardcode 7 m/s.

• Never omit unsupported features silently. Always flag them explicitly in

the Scenario Description under "Unsupported Constructs."

• Describe intent, not XOSC structure. Collapse placeholder Acts

(MW_WaitAction) into end conditions. Do not create phases for scaffolding

elements that have no meaningful actor actions.

Workflow

This skill operates in two steps. Complete Step 1 first, present the description

to the user for review, then proceed to Step 2 only after approval.

Step 1: Analyze the .xosc and Produce a Scenario Description

Parse the .xosc and its referenced .xodr following this strict logical order.

1a. Validate the input

Read the .xosc XML. If the file is invalid XML, missing required elements, or

fails basic structural checks, stop and report the error. Do not guess or

assume missing data. If data is ambiguous, state the assumption explicitly.

1b. Resolve parameters, expressions, and catalogs

Before interpreting any values, resolve all references:

• ParameterDeclarations / VariableDeclarations: Evaluate ${...} expressions

to concrete numeric values. Process in declaration order (later params may

reference earlier ones).

• CatalogReferences: Read the referenced catalog XML file (from

<CatalogLocations>), find the entry by catalogName + entryName, extract

the vehicle/pedestrian definition (model3d path, category, bounding box).

% Parameter expression resolution example
params.HostSpeed_kph = 80;
params.LeadTime_s = 6;
params.hostSpeed_ms = params.HostSpeed_kph / 3.6;        % 22.2222
params.leadSpeed_ms = params.hostSpeed_ms * 0.5;         % 11.1111
params.initSeparation = (params.hostSpeed_ms + params.leadSpeed_ms) * params.LeadTime_s; % 200

1c. Describe the Init phase

For each actor's Private actions in <Init>:

• TeleportAction — convert position to world [x, y, z]:
• WorldPosition: use directly
• LanePosition: translate using .xodr (see scripts/xoscPositionToWorld.p)
• RoadPosition: translate using .xodr (see scripts/xoscPositionToWorld.p)
• CRITICAL: All parameters to xoscPositionToWorld MUST be numeric.

XML attributes are always strings — convert with str2double() before calling:

     pos = xoscPositionToWorld(xodrPath, 'LanePosition', ...
         'roadId', str2double(roadId), 'laneId', str2double(laneId), ...
         's', str2double(s), 'offset', str2double(offset));

Passing strings silently produces wrong coordinates (up to 12m error).

• RelativeObjectPosition: rotate dx/dy by entity heading, add to base position
• RelativeRoadPosition: inverse-lookup base entity road coords, offset s/t
• RelativeLanePosition: inverse-lookup base lane, compute target lane + s

(skip center lane when dLane crosses from negative to positive IDs)

• Process entities in dependency order: resolve reference entities first

• Heading — The RoadRunner API does not support setting actor orientation.

Actors always align with road direction at their anchor point. Do NOT include

heading in the scenario description — it cannot be applied.

Note: The h attribute from XOSC is still needed for RelativeObjectPosition

translation (to rotate dx/dy in the entity's local frame), but it is not set

on the placed actor.

• SpeedAction — record the speed value and whether it is absolute or relative.

For relative: describe as <abs(delta)> m/s <direction> relative to <ref actor>

where direction is "slower" (delta < 0), "faster" (delta > 0), or "same" (0).

• FollowTrajectoryAction — supported only if effectively starts at t=0.

This means either: (a) in Init, or (b) in Story where the trigger chain

resolves to t=0. Resolve by tracing: if Event StartTrigger is

StoryboardElementStateCondition(Act, runningState) → check Act's

StartTrigger; if that references Story's runningState → check Story's

StartTrigger. If the chain terminates at SimulationTimeCondition >= 0,

treat as t=0. If any link in the chain uses a non-zero time, duration,

distance, or other condition → not supported. Skip and warn.

When supported, extract exactly the polyline vertices as route waypoints

(never reduce, never duplicate start/end points). Determine speed reference:

• Has <Timing> in TimeReference → Speed Reference: "route-time-data".

Include the time attribute from each vertex in the description.

Ignore SpeedAction — timing overrides speed.

• Has <None/> in TimeReference → Speed Reference: absolute (use SpeedAction value)

Translate any non-WorldPosition vertices using scripts/xoscPositionToWorld.p.

• AssignRouteAction — same t=0 rule as FollowTrajectoryAction (resolve

trigger chain). When supported, extract all waypoints (LanePosition or

WorldPosition). Always use absolute speed from SpeedAction. If trigger

chain does not resolve to t=0 → not supported. Skip and warn.

• AddEntityAction — Typically paired with SpeedAction (sets position +

initial speed, same as TeleportAction + SpeedAction). May also combine

with FollowTrajectoryAction or AssignRouteAction — in those cases the

existing rules (items 4 and 5) apply. Extract position from the nested

<Position> element and convert to world [x, y, z]. Describe the actor

in the Actors section so the authoring skill places it via addActor.

Do not include Initial Speed in the Actors section — the actor has no

initialization. Speed is defined in the Phase Logic after the WaitAction.

Since addActor places all actors at scenario start (no mid-scenario

spawn), replicate the delayed appearance using phase logic:

• Look at the StartTrigger condition of the AddEntityAction event/act
• Describe a WaitAction phase (SystemActionPhase) as the actor's

FIRST phase — inserted before the actor's auto-created init phase

• Set the wait phase's end condition = the XOSC start condition
• The actor's auto-created init phase comes AFTER the WaitAction — this

is where speed/behavior is configured (e.g., ChangeSpeedAction)

• Do NOT add a pass-through phase before the WaitAction — the WaitAction

IS the first phase. Only two phases per actor: WaitAction → behavior

• Speed placement for AddEntityAction actors: The WaitAction phase carries

NO speed — it only waits for the spawn condition. Speed (e.g.,

ChangeSpeedAction at 17.88 m/s) must be placed on the auto-created init

phase that comes AFTER the WaitAction. Never assign speed on or before

the WaitAction.

• Movement mode constraint — If an actor has ChangeLaneAction or

ChangeLateralOffsetAction in Story, it must be in lane-following mode

(no route). Do NOT include route waypoints for such actors.

Ignore global init actions (e.g., EnvironmentAction) that do not affect actors.

1d. Describe the Story phase

The goal is to describe intent — what each actor does, what triggers it,

and what ends it. Do NOT preserve the XOSC structural hierarchy (Acts, Events,

ManeuverGroups). Collapse scaffolding into simple action descriptions.

Handling MW_WaitAction (placeholder Acts):

• Act with real action + MW_WaitAction: Describe as the main action with

the Act's StopTrigger as its end condition. Ignore the MW_WaitAction.

• Act with ONLY MW_WaitAction (no real action): This Act's StopTrigger is

the end condition for whatever phase PRECEDES it in the serial chain. Set the

condition directly on that preceding phase — do NOT create a separate

WaitAction phase. Exception: If there is no preceding phase, or the

preceding phase already has an end condition, create a WaitAction phase with

the Act's StopTrigger as the end condition.

Determining execution order:

Look at StartTriggers to determine serial/parallel relationships:

• StoryboardElementStateCondition(X, completeState) → runs after X ends
• StoryboardElementStateCondition(X, runningState) → runs parallel with X
• SimulationTimeCondition >= 0 → starts immediately

Parallel groups and serial successors:

When an Act contains multiple Events that run in parallel, they form a

ParallelPhase. If a subsequent action triggers on that Act's completeState,

it is serial after the ParallelPhase (the container), not after any

individual child phase. An Act completes when ALL its events finish — so the

successor must wait for the entire parallel group.

What to capture for each action:

• Actor, action type, action properties
• Phase name: use the name attribute from the XOSC <Action> tag
• What triggers it (start condition)
• What ends it (end condition — from Act StopTrigger or MW_WaitAction Act)
• Serial/parallel relationship to other actions

1e. Produce the Scenario Description

Write a structured description using roadrunner-scenario-authoring terminology

so the authoring skill can execute it directly:

## Scene
- OpenDRIVE file: <filename from LogicFile>
- Import required: yes (use `roadrunner-import-scene` with format "OpenDRIVE")

## Parameters (if any)
- <name> = <resolved value> (original expression: <expr>)

## Actors
For each actor:
- Name: <XOSC entity name>
- Type: Vehicle / Pedestrian
- Asset: <model3d path> (AssetType: "VehicleAsset" or "CharacterAsset")
- Initial Position: [x, y, z] (translated from <original position type>)
- Anchoring:
  - Lane-following (no route): autoAnchor (actor must be anchored to road for lane following)
    - **Exception:** If the actor's translated position is on a junction connector road,
      do NOT autoAnchor — anchoring on junctions shifts the position to an
      unpredictable anchor point. Place the actor at the exact world coordinates instead.
  - Path-following (has route): do NOT autoAnchor (positions are precise world coordinates)
- Movement Mode: path-following (has route) or lane-following (no route)
- **Anchoring and Movement Mode are REQUIRED fields.** Every actor description
  must explicitly state the anchoring decision (autoAnchor or NOT autoAnchor)
  and movement mode. Do not omit these even when the choice seems obvious from
  context — the downstream authoring skill needs them stated explicitly.
- Initial Speed: <value> m/s (absolute)
  OR: <delta> m/s <direction> relative to <reference actor>
- Route (if path-following):
  - Waypoints: [x, y, z] per row (ALL vertices — never simplify)
  - Timestamps: [t0, t1, t2, ...] (if timed trajectory — sets Point.Time)
  - Speed Reference: "route-time-data" (timed) or absolute value (untimed)
  - Freeform: true (route follows exact waypoint positions, not road geometry)
  - Do NOT autoAnchor route waypoints

## Phase Logic
Use RoadRunner action/condition type names (see references/openscenario-mapping.md):
For each meaningful action (skip MW_WaitAction placeholders):
- Actor: <who>
- Phase Name: <from XOSC Action name attribute>
- Action: <RoadRunner action type> (e.g., ChangeSpeedAction, ChangeLaneAction)
  - Properties: Speed=X, DynamicsShape="step", Direction="left", etc.
- Trigger: <RoadRunner condition type> (e.g., SimulationTimeCondition, DurationCondition)
  - Properties: Time=X, Duration=X, Distance=X, Rule="ge", etc.
- End Condition: <RoadRunner condition type> with properties
- Topology: serial after <previous> / parallel with <sibling>

## Scenario End Conditions
- End: <condition type> on RootPhase (e.g., SimulationTimeCondition, Time=60)
- Fail: <condition type> on RootPhase (e.g., CollisionCondition)

## Unsupported Constructs
- <construct>: <why it cannot be mapped>

1f. Present for review

Show the Scenario Description to the user. Ask:

*"Here is the scenario description I extracted. Review the actors, positions,

phase logic, and relative references. Should I adjust anything before generating

the MATLAB script?"*

Wait for user approval before proceeding to Step 2.

Step 2: Build the Scenario via Dependent Skills

After the user approves the scenario description, delegate execution to the

dependent skills. This skill does NOT generate MATLAB code. It only

interprets the .xosc and produces the description.

2a. Import the scene

Import into a new scene and create a new scenario:

• Call newScene(rrApp) to get a clean scene (no leftover roads)
• Import with ProjectionMode = "noprojection" to preserve the .xodr's native

coordinate system:

   importOpts = openDriveImportOptions;
   importOpts.ProjectionMode = "noprojection";
   importScene(rrApp, xodrPath, "OpenDRIVE", importOpts);

• Call newScenario(rrApp) to create a fresh scenario on the imported scene

2b. Build the scenario

**CRITICAL: You MUST invoke /roadrunner-scenario-authoring to build the

scenario. Do NOT write MATLAB code directly. Do NOT call MCP MATLAB tools

(mcp__matlab__evaluate_matlab_code, mcp__matlab__run_matlab_file) yourself.

The authoring skill handles all code generation and execution.**

Invoke /roadrunner-scenario-authoring with the full approved scenario

description as the argument. Prefix it with:

> Build the following scenario in RoadRunner. The scene is already

> imported and a new scenario has been created.

Then paste the complete scenario description (Actors, Phase Logic, End

Conditions, etc.) so the authoring skill can execute it directly.

Include the following mapping details in the instruction so the authoring

skill applies them correctly:

Anchoring rules:

• Lane-following actors (no route/trajectory): MUST autoAnchor — the actor

needs to be anchored to the road to follow lanes correctly.

• Path-following actors (have route): do NOT autoAnchor actor or route

waypoints — positions are precise world coordinates and autoAnchor would shift

them from their intended positions, misaligning trajectories.

CollisionCondition patterns (include in end conditions):

| XOSC Pattern | What to Specify |

|---|---|

| <EntityRef entityRef="ActorB"/> (specific pair) | "Collision between [Actor] and [ActorB]" |

| <ByType type="vehicle"/> (any vehicle) | "Collision between [Actor] and any vehicle" |

Multiple <ConditionGroup> elements (OR logic in StopTrigger): describe

each as a separate end/fail condition on RootPhase.

References

Consult these during Step 1 to map XOSC constructs to RoadRunner terminology:

• references/openscenario-mapping.md — XOSC action/condition types → RoadRunner API type names, state mapping, rule mapping, property mapping
• scripts/xoscPositionToWorld.p — MATLAB function: call to translate any XOSC position type to world [x, y, z] using the .xodr file

Common Mistakes

| Mistake | Why It's Wrong | Correct Approach |

|---------|---------------|-----------------|

| Skipping autoAnchor on lane-following actors without routes | Actor won't follow lane properly without being anchored to road | Lane-following actors (no route/trajectory) MUST be autoAnchored — EXCEPT on junction connector roads where anchoring shifts position |

| Using autoAnchor on junction connector roads | Anchoring on junctions shifts the actor to an unpredictable anchor point, misaligning the position | If the translated position is on a junction, place at exact world coordinates without autoAnchor |

| Using autoAnchor on path-following actors with routes | Shifts positions, misaligns trajectories | Path-following actors and their route waypoints should NOT be autoAnchored — positions are already precise world coordinates |

| Passing string parameters to xoscPositionToWorld | Function silently gives wrong coordinates (up to 12m error) | Always use str2double() on XML attribute values before calling: 'roadId', str2double(id), 'laneId', str2double(lane), 's', str2double(s), 'offset', str2double(off) |

| Adding a pass-through init phase before WaitAction for AddEntityAction actors | Adds an unnecessary phase; actor should do nothing until spawn time | WaitAction IS the first phase — only two phases: WaitAction → behavior |

| Including Initial Speed in Actors section for AddEntityAction actors | Actor has no initialization before the wait | Speed is set in Phase Logic after WaitAction, not in Actors section |

| Using ActorActionPhase for WaitAction | WaitAction is not an actor action | WaitAction must be in a SystemActionPhase |

Conventions

• This skill produces only the scenario description — never MATLAB code
• Delegate to roadrunner-import-scene for scene import, roadrunner-scenario-authoring for building
• Always resolve parameters/expressions to concrete values before translating positions
• Always resolve CatalogReferences to asset paths before describing actors
• Asset paths use project extensions: .fbx for vehicles, .rrchar for characters

----

Copyright 2026 The MathWorks, Inc.

----