From f8857edb9960e9e796382562afd2424f7643bb1e Mon Sep 17 00:00:00 2001
From: moriy <786332118@qq.com>
Date: Tue, 28 Apr 2026 17:49:06 +0800
Subject: [PATCH] Add shared simulation API schema

---
 shared/examples/level-turn-request.json   |  18 +++
 shared/schemas/flight-sim-api.schema.json | 137 ++++++++++++++++++++++
 2 files changed, 155 insertions(+)
 create mode 100644 shared/examples/level-turn-request.json
 create mode 100644 shared/schemas/flight-sim-api.schema.json

diff --git a/shared/examples/level-turn-request.json b/shared/examples/level-turn-request.json
new file mode 100644
index 0000000..2a359d8
--- /dev/null
+++ b/shared/examples/level-turn-request.json
@@ -0,0 +1,18 @@
+{
+  "aircraftId": "f16-mock",
+  "sampleRateHz": 30,
+  "durationSec": 10,
+  "initialState": {
+    "position": [0, 1000, 0],
+    "rotation": [0, 0, 0, 1],
+    "velocityMps": 120,
+    "headingDeg": 0
+  },
+  "maneuver": {
+    "type": "level-turn",
+    "parameters": {
+      "turnRateDegPerSec": 9,
+      "bankDeg": 45
+    }
+  }
+}
diff --git a/shared/schemas/flight-sim-api.schema.json b/shared/schemas/flight-sim-api.schema.json
new file mode 100644
index 0000000..956678d
--- /dev/null
+++ b/shared/schemas/flight-sim-api.schema.json
@@ -0,0 +1,137 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://local-flight-sim/schemas/flight-sim-api.schema.json",
+  "title": "Local Flight Simulation API",
+  "description": "Shared wire schema for the Web client and local simulation service. Heading convention: true heading 0 degrees points north, clockwise is positive, counter-clockwise is negative.",
+  "$defs": {
+    "Vec3": {
+      "type": "array",
+      "items": { "type": "number" },
+      "minItems": 3,
+      "maxItems": 3
+    },
+    "Quat": {
+      "type": "array",
+      "items": { "type": "number" },
+      "minItems": 4,
+      "maxItems": 4,
+      "description": "[x, y, z, w]"
+    },
+    "InitialState": {
+      "type": "object",
+      "required": ["position", "velocityMps"],
+      "properties": {
+        "position": {
+          "$ref": "#/$defs/Vec3",
+          "description": "Local meters [east, up, north]."
+        },
+        "rotation": { "$ref": "#/$defs/Quat" },
+        "velocityMps": { "type": "number", "exclusiveMinimum": 0 },
+        "headingDeg": {
+          "type": "number",
+          "description": "True heading. 0 is north, clockwise positive, counter-clockwise negative."
+        }
+      },
+      "additionalProperties": true
+    },
+    "FlightSample": {
+      "type": "object",
+      "required": ["t", "position", "rotation", "velocityMps", "headingDeg"],
+      "properties": {
+        "t": { "type": "number", "minimum": 0 },
+        "position": {
+          "$ref": "#/$defs/Vec3",
+          "description": "Local meters [east, up, north]."
+        },
+        "rotation": { "$ref": "#/$defs/Quat" },
+        "velocityMps": { "type": "number" },
+        "headingDeg": {
+          "type": "number",
+          "description": "True heading. 0 is north, clockwise positive, counter-clockwise negative."
+        },
+        "angularVelocity": { "$ref": "#/$defs/Vec3" },
+        "alphaDeg": { "type": "number" },
+        "betaDeg": { "type": "number" },
+        "loadFactor": { "type": "number" },
+        "mach": { "type": "number" },
+        "qbar": { "type": "number" },
+        "verticalSpeedMps": { "type": "number" },
+        "pitchRateDegS": { "type": "number" },
+        "rollRateDegS": { "type": "number" },
+        "yawRateDegS": { "type": "number" },
+        "throttle": { "type": "number" },
+        "controlInputs": {
+          "type": "object",
+          "properties": {
+            "elevator": { "type": "number" },
+            "aileron": { "type": "number" },
+            "rudder": { "type": "number" },
+            "throttle": { "type": "number" },
+            "tvc": { "type": "number" },
+            "speedbrake": { "type": "number" }
+          },
+          "additionalProperties": false
+        },
+        "controlSurfaces": {
+          "type": "object",
+          "properties": {
+            "elevatorDeg": { "type": "number" },
+            "aileronDeg": { "type": "number" },
+            "rudderDeg": { "type": "number" },
+            "tvcDeg": { "type": "number" },
+            "speedbrakeNorm": { "type": "number" }
+          },
+          "additionalProperties": false
+        },
+        "fcs": {
+          "type": "object",
+          "properties": {
+            "tvcPosNorm": { "type": "number" },
+            "tvcInhibit": { "type": "number" },
+            "thrustNorm": { "type": "number" },
+            "throttleOverride": { "type": "number" },
+            "pitchRateCmd": { "type": "number" }
+          },
+          "additionalProperties": true
+        }
+      },
+      "additionalProperties": true
+    },
+    "SimulateRequest": {
+      "type": "object",
+      "required": ["aircraftId", "sampleRateHz", "durationSec", "initialState", "maneuver"],
+      "properties": {
+        "aircraftId": { "type": "string" },
+        "sampleRateHz": { "type": "number", "exclusiveMinimum": 0 },
+        "integrationRateHz": {
+          "type": "number",
+          "exclusiveMinimum": 0,
+          "description": "Internal dynamics integration frequency. JSBSim defaults to 120 Hz; sampleRateHz remains the output sampling frequency."
+        },
+        "trim": {
+          "type": "boolean",
+          "description": "Whether the backend should attempt trim before simulation. F-22 maneuver research may use false when JSBSim trim cannot find a steady state."
+        },
+        "durationSec": { "type": "number", "exclusiveMinimum": 0 },
+        "initialState": { "$ref": "#/$defs/InitialState" },
+        "maneuver": {
+          "type": "object",
+          "required": ["type"],
+          "properties": {
+            "type": {
+              "type": "string",
+              "enum": ["straight", "climb", "descent", "level-turn", "control-script", "cobra"]
+            },
+            "parameters": {
+              "type": "object",
+              "description": "Maneuver-specific parameters. Cobra supports controlMode=open-loop|closed-loop. Closed-loop Cobra parameters include targetAlphaDeg, recoveryAlphaDeg, pitchRateLimitDegS, holdPitchRateDegS, pullDurationSec, holdDurationSec, recoveryDurationSec, maxElevatorCmd, recoveryElevatorCmd, pullTvcCmd, recoveryTvcCmd, throttleCmd, and speedbrakeCmd.",
+              "additionalProperties": true
+            }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}