# Braking Scenario: Hard Stop Evaluation (Deterministic)

This document provides a technical guide to the **Lead Vehicle Hard Braking** scenario, including its architectural design, common CARLA-specific pitfalls, and the robust fixes implemented to ensure 100% repeatability.

---

## 🏗️ 1. Scenario Architecture

The Braking scenario consists of two main actors on a multi-lane road (default: **Town10HD_Opt**):
1.  **Ego Vehicle**: The vehicle under test, tracking a set of target coordinates or following a lead vehicle.
2.  **Lead Vehicle**: An NPC spawn 25m ahead on the same lane.

**Success Metric**: The Ego ADNC stack must detect the lead vehicle's emergency deceleration and brake safely without collision.

---

## 🏎️ 2. Critical Spawning Fixes (Lessons Learned)

During implementation, we identified several subtle CARLA behaviors that led to `RuntimeError: Spot occupied` failures. These are now documented for all future scenario developers.

### 🛑 Issue A: Stale Physics (Synchronous Mode Delay)
- **Problem**: When spawning a new actor in **Synchronous Mode**, its location (`get_location()`) often defaults to stale values (like `0,0,0`) until the world's physics engine has processed at least one frame.
- **Impact**: Calculating NPC spawn points based on the Ego's position immediately after spawning resulted in NPCs appearing at the map origin instead of ahead of the Ego.
- **Fix**: Added an explicit **`world.tick()`** call in the core orchestrator immediately after the Ego is spawned and before the scenario's `setup()` method is called. This "settles" the Ego and guarantees accurate coordinate data.

### 🛑 Issue B: Ground-Mesh Clipping & Bounding Box Overlap
- **Problem**: CARLA waypoints sit exactly on the road surface (`Z = 0.0`). Spawning a vehicle's center-point at this height causes its collision box (chassis and tires) to overlap with the road mesh.
- **Impact**: CARLA identifies this overlap as an "obstacle" and fails the spawn with a "Spot occupied" error.
- **Fix**: Implemented a mandatory **0.5m Z-offset (lift)** for all NPC spawn transforms. NPCs are spawned slightly in the air and "dropped" onto the road, which is the industry-standard way to ensure collision-free actor placement in CARLA.

### 🛑 Issue C: Deterministic "Spawn-and-Move" Pattern
- **Problem**: Directly spawning an actor at an absolute intersection coordinate (`P2` from our showcase) is fragile and frequently fails due to microscopic geometry conflicts in Town10.
- **Fix**: Developed a two-stage **Spawn-and-Move** pattern:
  1.  Spawn the Ego at a "safe" map spawn index (provided by `map.get_spawn_points()`).
  2.  Immediately translate it to the target scenario coordinates using **`set_transform()`**.
  - **Result**: `set_transform` is significantly more lenient than `try_spawn_actor`, ensuring we never fail to reach our starting intersection.

---

## 🧪 3. Parametric Tuning via CLI

The orchestrator now supports dynamic parameter injection for the braking scenario:
```powershell
./run.bat braking --params "BRAKE_FRAME=120,LEAD_DISTANCE_M=30"
```
-   **BRAKE_FRAME**: The exact simulation frame where the lead vehicle disengages autopilot and applies a `brake=1.0` override.
-   **LEAD_DISTANCE_M**: The initial separation between Ego and Lead vehicle.

---
*Created: March 2026 | Intel Repository — ADAS Development*