docs: add F1 24 UDP data format reference

2026-07-27 18:38:16 +08:00
parent 9cb8c12c89
commit 2ca8dc53f4
1 changed files with 318 additions and 0 deletions
@@ -0,0 +1,318 @@
+
+## 🏎️ F1 24 UDP Telemetry 规范总览
+
+### 📌 官方文档
+- **官方规范 Word 文档**：[EA Forums — Data Output from F1 24 v27.2x.docx](https://forums.ea.com/t5/s/tghpe58374/attachments/tghpe58374/f1-24-general-discussion-en/4624/1/Data%20Output%20from%20F1%2024%20v27.2x.docx)
+- **GitHub 开源解析库参考**：https://github.com/MacManley/f1-24-udp
+
+---
+
+## ⚙️ 游戏设置
+
+在游戏中启用 UDP 遥测：**Game Options → Settings → Telemetry Settings**
+
+| 设置项 | 推荐值 |
+|---|---|
+| `UDP Telemetry` | On |
+| `UDP Broadcast Mode` | Off（多设备时可开启） |
+| `UDP IP Address` | 接收端 IP（本机用 `127.0.0.1`） |
+| `Port` | `20777`（默认） |
+| `UDP Send Rate` | `20Hz`（默认，最高 60Hz） |
+| `UDP Format` | `2024` |
+
+> ⚠️ 注意：游戏仅在玩家进入 **计时圈（timed lap）** 后才开始发送有效遥测数据。
+
+---
+
+## 📦 数据编码
+
+- **字节序**：Little Endian
+- **对齐**：packed（无填充）
+- **最大车辆数**：22
+
+### 数据类型
+
+| 类型 | 说明 |
+|---|---|
+| `uint8` / `int8` | 无符号/有符号 8-bit |
+| `uint16` / `int16` | 无符号/有符号 16-bit |
+| `uint32` | 无符号 32-bit |
+| `uint64` | 无符号 64-bit |
+| `float` | 32-bit 浮点 |
+
+---
+
+## 📋 包头结构（PacketHeader）
+
+**大小：29 bytes**
+
+```c
+struct PacketHeader {
+    uint16  m_packetFormat;              // 2024
+    uint8   m_gameYear;                  // 年份后两位，如 24
+    uint8   m_gameMajorVersion;          // 主版本号 "X.00"
+    uint8   m_gameMinorVersion;          // 次版本号 "1.XX"
+    uint8   m_packetVersion;             // 包类型版本号，从 1 开始
+    uint8   m_packetId;                  // 包类型 ID（见下表）
+    uint64  m_sessionUID;                // 会话唯一 ID
+    float   m_sessionTime;               // 会话时间戳
+    uint32  m_frameIdentifier;           // 帧标识符
+    uint32  m_overallFrameIdentifier;    // 全局帧标识符（Flashback 不回退）
+    uint8   m_playerCarIndex;            // 玩家车辆索引
+    uint8   m_secondaryPlayerCarIndex;   // 分屏第二玩家索引（255 = 无）
+};
+```
+
+---
+
+## 🆔 包类型 ID 汇总
+
+| ID | 包名称 | 说明 | 频率 | 大小 |
+|---|---|---|---|---|
+| 0 | **Motion** | 所有车辆物理运动数据 | 菜单设定频率 | 1349 B |
+| 1 | **Session** | 会话信息（赛道、剩余时间） | 2/秒 | 753 B |
+| 2 | **Lap Data** | 所有车辆圈速数据 | 菜单设定频率 | 1285 B |
+| 3 | **Event** | 会话事件 | 事件触发时 | 45 B |
+| 4 | **Participants** | 参与者列表 | 每 5 秒 | 1350 B |
+| 5 | **Car Setups** | 车辆调校参数 | 2/秒 | 1133 B |
+| 6 | **Car Telemetry** | 遥测数据（速度/油门/DRS等） | 菜单设定频率 | 1352 B |
+| 7 | **Car Status** | 车辆状态（燃油/ERS等） | 菜单设定频率 | 1239 B |
+| 8 | **Final Classification** | 最终排名 | 结果界面每 5 秒 | 1020 B |
+| 9 | **Lobby Info** | 多人游戏大厅信息 | 大厅中 2/秒 | 1306 B |
+| 10 | **Car Damage** | 车辆损伤数据 | 10/秒 | 953 B |
+| 11 | **Session History** | 圈速和轮胎历史 | 20/秒（轮询车辆） | 1460 B |
+| 12 | **Tyre Sets** | 轮胎组详细数据 | 2/秒 | 231 B |
+| 13 | **Motion Ex** | 玩家车辆扩展运动数据 | 菜单设定频率 | 237 B |
+| 14 | **Time Trial** | 计时赛专用数据 | 1/秒（仅TT） | 101 B |
+
+---
+
+## 🔍 各包数据结构详解
+
+### 1. Motion Packet（ID=0）
+包含所有 22 辆车的物理数据。
+
+```c
+struct CarMotionData {
+    float  m_worldPositionX, m_worldPositionY, m_worldPositionZ; // 世界位置 (m)
+    float  m_worldVelocityX, m_worldVelocityY, m_worldVelocityZ; // 世界速度 (m/s)
+    int16  m_worldForwardDirX, m_worldForwardDirY, m_worldForwardDirZ; // 前向向量（÷32767 归一化）
+    int16  m_worldRightDirX, m_worldRightDirY, m_worldRightDirZ;       // 右向向量
+    float  m_gForceLateral, m_gForceLongitudinal, m_gForceVertical;    // G 力分量
+    float  m_yaw, m_pitch, m_roll;                                     // 角度 (rad)
+};
+// PacketMotionData: PacketHeader + CarMotionData[22]
+```
+
+---
+
+### 2. Session Packet（ID=1）
+包含当前会话完整信息，如天气、温度、赛道、规则、辅助设置等。
+
+关键字段：
+- `m_weather`: 0=晴, 1=少云, 2=阴, 3=小雨, 4=大雨, 5=暴雨
+- `m_trackId`: 赛道 ID（-1=未知，见附录）
+- `m_sessionType`: 会话类型
+- `m_formula`: 0=F1 Modern, 1=F1 Classic, 2=F2, 3=F1 Generic, 4=Beta, 6=Esports, 8=F1 World, 9=F1 Elimination
+- `m_safetyCarStatus`: 0=无, 1=实体安全车, 2=虚拟安全车, 3=编队圈
+- `m_weatherForecastSamples[64]`: 天气预测（最多 64 样本，适配冲刺赛周末）
+- `m_weekendStructure[12]`: 周末赛程结构
+- `m_sector2LapDistanceStart` / `m_sector3LapDistanceStart`: 赛段起点距离
+
+---
+
+### 3. Lap Data Packet（ID=2）
+```c
+struct LapData {
+    uint32 m_lastLapTimeInMS;               // 上一圈时间 (ms)
+    uint32 m_currentLapTimeInMS;            // 当前圈耗时 (ms)
+    uint16 m_sector1TimeMSPart;             // S1 毫秒部分
+    uint8  m_sector1TimeMinutesPart;        // S1 分钟部分
+    uint16 m_sector2TimeMSPart;             // S2 毫秒部分
+    uint8  m_sector2TimeMinutesPart;        // S2 分钟部分
+    uint16 m_deltaToCarInFrontMSPart;       // 与前车差距毫秒
+    uint8  m_deltaToCarInFrontMinutesPart;  // 与前车差距分钟
+    uint16 m_deltaToRaceLeaderMSPart;       // 与领跑者差距毫秒
+    uint8  m_deltaToRaceLeaderMinutesPart;  // 与领跑者差距分钟
+    float  m_lapDistance;                   // 当前圈已跑距离 (m)
+    float  m_totalDistance;                 // 总行驶距离 (m)
+    float  m_safetyCarDelta;                // 安全车时间差 (s)
+    uint8  m_carPosition;                   // 赛道排名
+    uint8  m_currentLapNum;                 // 当前圈数
+    uint8  m_pitStatus;                     // 0=无, 1=进站中, 2=维修区
+    uint8  m_numPitStops;                   // 已进站次数
+    uint8  m_sector;                        // 0=S1, 1=S2, 2=S3
+    uint8  m_currentLapInvalid;             // 0=有效, 1=无效
+    uint8  m_penalties;                     // 累计罚时 (s)
+    uint8  m_driverStatus;                  // 0=车库, 1=飞行圈, 2=回场圈, 3=出场圈, 4=赛道上
+    uint8  m_resultStatus;                  // 0-7 (invalid/active/finished/DNF/DSQ等)
+    float  m_speedTrapFastestSpeed;         // 速度陷阱最快速度 (km/h)
+    // ... 等
+};
+```
+
+---
+
+### 4. Event Packet（ID=3）
+事件代码：
+
+| 代码 | 事件 | 代码 | 事件 |
+|---|---|---|---|
+| `SSTA` | 会话开始 | `SEND` | 会话结束 |
+| `FTLP` | 最快圈速 | `RTMT` | 退赛 |
+| `DRSE` | DRS 启用 | `DRSD` | DRS 禁用 |
+| `TMPT` | 队友进站 | `CHQF` | 方格旗 |
+| `RCWN` | 冠军产生 | `PENA` | 处罚发出 |
+| `SPTP` | 速度陷阱触发 | `STLG` | 发车灯 |
+| `LGOT` | 灯灭起跑 | `DTSV` | Drive-through 已执行 |
+| `SGSV` | Stop-Go 已执行 | `FLBK` | Flashback |
+| `BUTN` | 按钮状态 | `RDFL` | 红旗 |
+| `OVTK` | 超车 | `SCAR` | 安全车事件 |
+| `COLL` | 碰撞事件 | | |
+
+---
+
+### 5. Car Telemetry Packet（ID=6）
+```c
+struct CarTelemetryData {
+    uint16 m_speed;                        // 速度 (km/h)
+    float  m_throttle;                     // 油门 (0.0~1.0)
+    float  m_steer;                        // 转向 (-1.0~1.0)
+    float  m_brake;                        // 刹车 (0.0~1.0)
+    uint8  m_clutch;                       // 离合 (0~100)
+    int8   m_gear;                         // 档位 (1-8, N=0, R=-1)
+    uint16 m_engineRPM;                    // 引擎转速
+    uint8  m_drs;                          // DRS: 0=关, 1=开
+    uint8  m_revLightsPercent;             // 转速灯百分比
+    uint16 m_revLightsBitValue;            // 转速灯位值
+    uint16 m_brakesTemperature[4];         // 刹车温度 (°C)
+    uint8  m_tyresSurfaceTemperature[4];   // 胎面温度 (°C)
+    uint8  m_tyresInnerTemperature[4];     // 胎内温度 (°C)
+    uint16 m_engineTemperature;            // 引擎温度 (°C)
+    float  m_tyresPressure[4];             // 胎压 (PSI)
+    uint8  m_surfaceType[4];               // 路面类型
+};
+```
+
+---
+
+### 6. Car Status Packet（ID=7）
+```c
+struct CarStatusData {
+    uint8  m_tractionControl;         // 0=关, 1=中, 2=全
+    uint8  m_antiLockBrakes;          // 0=关, 1=开
+    uint8  m_fuelMix;                 // 0=Lean, 1=Standard, 2=Rich, 3=Max
+    uint8  m_frontBrakeBias;          // 前刹车比 (%)
+    float  m_fuelInTank;              // 燃油量 (kg)
+    float  m_fuelCapacity;            // 油箱容量
+    float  m_fuelRemainingLaps;       // 剩余油量可跑圈数
+    uint8  m_drsAllowed;              // DRS 是否允许
+    uint16 m_drsActivationDistance;   // DRS 激活距离 (m)
+    uint8  m_actualTyreCompound;      // 实际轮胎配方 (16=C5, 17=C4, 18=C3, 19=C2, 20=C1, 21=C0, 7=半雨, 8=全雨)
+    uint8  m_visualTyreCompound;      // 视觉轮胎配方 (16=软, 17=中, 18=硬)
+    uint8  m_tyresAgeLaps;            // 轮胎使用圈数
+    int8   m_vehicleFiaFlags;         // FIA 旗帜 (-1=未知, 0=无, 1=绿, 2=蓝, 3=黄)
+    float  m_enginePowerICE;          // 内燃机功率 (W)
+    float  m_enginePowerMGUK;         // MGU-K 功率 (W)
+    float  m_ersStoreEnergy;          // ERS 储能 (J)
+    uint8  m_ersDeployMode;           // 0=无, 1=Medium, 2=Hotlap, 3=Overtake
+    float  m_ersHarvestedThisLapMGUK; // MGU-K 回收能量
+    float  m_ersHarvestedThisLapMGUH; // MGU-H 回收能量
+    float  m_ersDeployedThisLap;      // 已使用 ERS 能量
+};
+```
+
+---
+
+### 7. Car Damage Packet（ID=10）
+```c
+struct CarDamageData {
+    float  m_tyresWear[4];          // 轮胎磨损 (%)
+    uint8  m_tyresDamage[4];        // 轮胎损伤 (%)
+    uint8  m_brakesDamage[4];       // 刹车损伤 (%)
+    uint8  m_frontLeftWingDamage;   // 前左翼损伤 (%)
+    uint8  m_frontRightWingDamage;  // 前右翼损伤 (%)
+    uint8  m_rearWingDamage;        // 尾翼损伤 (%)
+    uint8  m_floorDamage;           // 底板损伤 (%)
+    uint8  m_diffuserDamage;        // 扩散器损伤 (%)
+    uint8  m_sidepodDamage;         // 侧箱损伤 (%)
+    uint8  m_drsFault;              // DRS 故障 (0/1)
+    uint8  m_ersFault;              // ERS 故障 (0/1)
+    uint8  m_gearBoxDamage;         // 变速箱损伤 (%)
+    uint8  m_engineDamage;          // 引擎损伤 (%)
+    uint8  m_engineMGUHWear;        // MGU-H 磨损 (%)
+    uint8  m_engineESWear;          // ES 磨损 (%)
+    uint8  m_engineCEWear;          // CE 磨损 (%)
+    uint8  m_engineICEWear;         // ICE 磨损 (%)
+    uint8  m_engineMGUKWear;        // MGU-K 磨损 (%)
+    uint8  m_engineTCWear;          // TC 磨损 (%)
+    uint8  m_engineBlown;           // 引擎爆缸 (0/1)
+    uint8  m_engineSeized;          // 引擎卡死 (0/1)
+};
+```
+
+---
+
+### 8. Motion Ex Packet（ID=13）— 运动平台关键包
+
+专为 **运动模拟平台（D-BOX 等）** 设计，包含更多细节：
+
+```c
+float m_suspensionPosition[4];      // 悬挂位置 [RL, RR, FL, FR]
+float m_suspensionVelocity[4];      // 悬挂速度
+float m_suspensionAcceleration[4];  // 悬挂加速度
+float m_wheelSpeed[4];              // 各轮速度
+float m_wheelSlipRatio[4];          // 滑移率
+float m_wheelSlipAngle[4];          // 滑移角
+float m_wheelLatForce[4];           // 横向力
+float m_wheelLongForce[4];          // 纵向力
+float m_wheelVertForce[4];          // 垂向力
+float m_heightOfCOGAboveGround;     // 重心高度
+float m_localVelocityX/Y/Z;         // 局部速度
+float m_angularVelocityX/Y/Z;       // 角速度 (rad/s)
+float m_angularAccelerationX/Y/Z;   // 角加速度 (rad/s²)
+float m_frontWheelsAngle;           // 前轮转角 (rad)
+float m_frontAeroHeight;            // 前底盘高度
+float m_rearAeroHeight;             // 后底盘高度
+float m_frontRollAngle;             // 前悬挂侧倾角
+float m_rearRollAngle;              // 后悬挂侧倾角
+float m_chassisYaw;                 // 底盘偏航角 (rad) — 可用于判断侧滑
+```
+
+---
+
+### 9. 其余包简介
+
+| 包 | 关键内容 |
+|---|---|
+| **Final Classification (8)** | 最终排名、圈数、积分、最佳圈速、轮胎使用记录 |
+| **Lobby Info (9)** | 多人游戏大厅的玩家信息 |
+| **Session History (11)** | 每辆车的全部圈速历史 + 轮胎使用历史（最多 100 圈） |
+| **Tyre Sets (12)** | 轮胎组详情：配方、磨损度、可用性、圈速差等 |
+| **Time Trial (14)** | 计时赛专属：玩家最佳、个人最佳、对手数据 |
+
+---
+
+## 🔒 隐私：Your Telemetry 设置
+
+当玩家设置 `Your Telemetry = Restricted` 时，以下数据对其他玩家**归零**：
+- **Car Status**：燃油、ERS 相关数据
+- **Car Damage**：所有损伤数据
+- **Tyre Sets**：全部轮胎组数据
+
+---
+
+## 🆕 F1 24 相比 F1 23 的主要变化
+
+1. 会话包中新增模拟/规则选项
+2. 新增安全车事件详情（`SCAR`）
+3. 大厅和参与者包中新增在线名称、Your Telemetry、F1 World Tech Level
+4. 圈速包中新增与前车/领先者的分钟差距字段
+5. 最终排名包改为结果界面每 5 秒重复发送
+6. 新增 **Time Trial 包**（ID=14）
+7. Motion Ex 包新增底盘高度（plank height）、悬挂侧倾角、底盘偏航角
+8. 新增碰撞事件（`COLL`）
+9. 新增周末赛程结构（`m_weekendStructure`）
+10. 天气预测数组从 56 扩展到 64
+11. 圈速包新增速度陷阱数据
+12. Car Setup 包新增发动机制动参数 + 下次进站前翼值