---

name: roadrunner-build-scenario-from-osc description: > Build a RoadRunner Scenario programmatically from an OpenSCENARIO 1.x (.xosc) file using the roadrunner-scenario-authoring skill. Use when the user wants to recreate a scenario from a .xosc file, interpret an OpenSCENARIO file and build it programmatically, reconstruct a .xosc as a RoadRunner scenario, generate a MATLAB script from a .xosc file, or convert an OpenSCENARIO file to MATLAB code. Do NOT use when the user says "import" a .xosc file — that means they want RoadRunner's built-in importScenario API, not programmatic reconstruction. Handles position translation (LanePosition and RoadPosition to world coordinates), construct mapping, relative references, trajectory/route handling, parameter expressions, catalog references, and phase logic topology. license: https://www.mathworks.com/content/dam/mathworks/license/pmrl/license.md metadata: author: MathWorks version: "1.0"

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

1. Never fabricate actions or conditions not present in the source XOSC. If a construct cannot be mapped, skip it and warn the user.

2. 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.

3. 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.

4. Never guess scenes. Only report the .xodr filename from <LogicFile>. Import it — do not search for a scene with a similar name.

5. 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.

6. Never omit unsupported features silently. Always flag them explicitly in the Scenario Description under "Unsupported Constructs."

7. 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>:

1. 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

2. 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.

3. 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).

4. 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.

5. 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.

6. 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.

7. 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