# Local Flight Simulation Service

Offline mock service for the first milestone.

## Run

```powershell
npm run service
```

The default URL is:

```text
http://127.0.0.1:4317
```

## Endpoints

- `GET /health`
- `GET /aircraft`
- `POST /trim`
- `POST /simulate`
- `POST /cancel`

## Coordinate and Heading Conventions

- Local position is `[east, up, north]` in meters.
- True heading `0 deg` points north.
- Clockwise heading is positive.
- Counter-clockwise heading is negative.

## Rates

- `sampleRateHz` controls the output sample frequency returned to the web client.
- `integrationRateHz` controls the internal JSBSim integration frequency and defaults to `120`.
- The web client currently requests `sampleRateHz: 30` and `integrationRateHz: 120`.
- `trim: false` skips pre-simulation trim. This is useful for F-22 maneuver research because the bundled F-22 model can run from initial conditions even when longitudinal trim fails.

The mock service currently supports:

- `straight`
- `climb`
- `descent`
- `level-turn`
- `control-script`
- `cobra`

## Maneuver Research Path

This project treats special maneuvers as reusable control-input studies:

1. Use `control-script` for raw elevator/aileron/rudder/throttle timelines.
2. Build named maneuver templates, such as `cobra`, on top of those timelines.
3. Compare mock output against the JSBSim backend.
4. Improve or replace aircraft XML models when high-alpha/post-stall data is not credible.

`control-script` parameters:

```json
{
  "timeline": [
    { "t": 0.0, "elevator": 0, "aileron": 0, "rudder": 0, "throttle": 0.85 },
    { "t": 0.5, "elevator": 0.8, "aileron": 0, "rudder": 0, "throttle": 1.0 },
    { "t": 1.6, "elevator": 0, "aileron": 0, "rudder": 0, "throttle": 1.0 }
  ]
}
```

`cobra` is currently an experimental template. It is useful for plumbing and visualization, but physical credibility depends on the selected JSBSim aircraft model having high-alpha and post-stall aerodynamic tables.

The default F-22 research path uses `f22cobra-jsbsim`, a project-local copy of the bundled F-22 model with manual TVC command support. The current stable near-cobra baseline uses the closed-loop Cobra controller:

```json
{
  "aircraftId": "f22cobra-jsbsim",
  "durationSec": 5,
  "initialState": { "position": [0, 3000, 0], "velocityMps": 120, "headingDeg": 0 },
  "trim": false,
  "maneuver": {
    "type": "cobra",
    "parameters": {
      "controlMode": "closed-loop",
      "pullDurationSec": 0.7,
      "recoveryDurationSec": 2.0,
      "targetAlphaDeg": 80,
      "pitchRateLimitDegS": 80,
      "maxElevatorCmd": -0.45,
      "recoveryElevatorCmd": 0.65,
      "pullTvcCmd": -0.05,
      "recoveryTvcCmd": 0.85,
      "throttleCmd": 1,
      "speedbrakeCmd": 0
    }
  }
}
```

This baseline reaches roughly 70-72 degrees alpha in the current model, keeps peak pitch rate around 120-125 deg/s, and recovers to low alpha by the end of the run. Higher-alpha open-loop settings can still be tested with `"controlMode": "open-loop"`, but they tend to deep-stall or over-rotate with the current F-22 aerodynamic tables.