RegisterLADS
服务端
-
描述
注册LADS系统 -
参数
| 参数名 | 数据类型 | 说明 |
|---|---|---|
| EntityId | str | 实体ID |
| ControlVehicleByDictFunction | function | 控制载具的所有运动标志的函数实例 |
| ControlVehicleThrottleFucntion | function | 控制载具的油门的函数实例 |
| JsonId | str | JSON配置模板ID（行为包modconfigs目录下文件名，不含.json后缀），如'lads_demo'。None则用代码内置默认配置 |
| LADSConfig | dict | 热更覆盖配置，优先级最高（覆盖JSON模板和默认值）。支持11个模块子字典，每个模块均可选，不传的模块用JSON/默认值 |
| StateCallBackFunctionInstance | function | 状态变更回调函数，当主状态/ACC子状态/AES等级/变道阶段/路口阶段任一变化时调用，传入状态快照字典(见GetLADSState返回值)。None则不回调 |
| IgnoreEntityTypes | list | 不计入避让实体的实体类型名称列表（如['minecraft:player','minecraft:zombie']）。匹配这些实体类型的实体不会被AES/ACC当作避让或跟车目标（行人/动物等可填此忽略）。None或空列表则避让所有实体 |
-
返回值
无 -
备注
-
填参数请参考激光雷达参数计算器进行填写。
-
配置合并优先级（从低到高）： 代码默认值 < JSON模板(JsonId) < 热更覆盖(LADSConfig)
-
注册时自动清理该载具的旧持久化路口决策数据（LADS_TurnDecision/IntersectionCooldown/State）， 避免脚本重载后残留的旧路口阶段导致车辆跳过红绿灯检查（重载后重新注册即可恢复干净状态）
-
LADSConfig结构（JSON模板格式见 modconfigs/lads_demo.json或下方单独Json示例）：
-
模块键名用内部简短键名（如'ACC'），JSON中用'santsue:acc'格式，框架自动映射
-
功能模块完整参数说明
Hardware 雷达硬件配置
控制激光雷达的线数、扫描角度、周期等硬件级参数
参数名 类型 默认值 说明 LiDARNum int 88 水平激光雷达线数（线数越多扫描越密） LiDARAngle float 180 水平扫描角度（度，180=前向半圆扫描） LiDARVertNum int 17 垂直激光雷达线数（覆盖上下坡检测） LiDARVertAngle float 45.0 垂直扫描角度（度，-22.5到+22.5） LiDARSpeed int 30 激光雷达扫描周期Tick（值越小扫描越快，越耗性能） LiDARSpeedStep int 1 周期扫描间隔Tick ControlInterval int 3 已废弃：车辆控制频率由round-robin调度控制（每30tick每车至少执行1次，N<=30时每tick执行1辆），保留兼容旧配置 ACC 自适应巡航
前车识别+位置差分测速+TTC线性回归预测+PID跟车，只在State==2巡航时工作
- 跟车（Follow）：只识别已注册LADS的载具为前车，过滤行人/动物
- 障碍Brake：对所有前方实体生效（含非载具），慢速前进给AES留避让机会
- 前车Brake：前车急刹时几乎停车
参数名 类型 默认值 说明 DetectRange float 45.0 前车识别最大距离(格)，超出此距离不识别为前车 LaneWidth float 1.5 同车道横向偏移阈值(格)，|横向偏移|<此值视为同车道(用于Follow跟车) ObstacleLaneWidth float 3.0 障碍检测横向阈值(格)，非载具实体|横向偏移|<此值视为前方障碍(用于Brake避障，比跟车更宽) OffDist float 40.0 Off阈值(格)，前车>此距离或无前车时不干预油门 BrakeDist float 5.0 Brake距离阈值(格)，前车<此距离触发紧急减速 ObstacleBrakeDist float 12.0 障碍Brake距离阈值(格)，非载具实体<此距离触发减速(比跟车更远，提前避障) BrakeTTC float 2.5 Brake的TTC阈值(秒)，预测碰撞时间<此值触发紧急减速 FollowDist float 20.0 目标跟车距离(格)，PID保持此车距 TimeHeadway float 40.0 时距系数(2秒=40tick)，目标距离=max(FollowDist, TimeHeadway×前车速度) Kp float 0.005 距离误差比例系数（越大响应越快，易超调） Kd float 0.015 距离误差微分系数（抑制超调，提高稳定性） FollowMaxAcc float 0.20 Follow状态最大油门（前车慢时上限） FollowAccMargin float 0.08 Follow状态前车快时额外油门（MaxAcc=前车速度+此值） BrakeMaxAcc float 0.02 Brake状态最大油门（前车急刹时几乎停车） ObstacleBrakeSpeedMin float 0.04 障碍Brake油门下限（慢速前进，给AES留避让机会） ObstacleBrakeSpeedMax float 0.08 障碍Brake油门上限（慢速前进） SpeedMargin float 0.03 速度区间下限=上限-此值 SpeedFilterAlpha float 0.3 前车速度低通滤波当前值权重（越小越平滑，越大越灵敏） TTCSlopeThreshold float -0.005 TTC回归斜率阈值（斜率<此值才预测碰撞） HistoryTicks int 40 历史数据保留时长(tick)，2秒=40tick LKA 车道保持（纯追踪+反馈闭环）
预瞄点控制+弯道强度反馈闭环，小弯走原始参数，持续大转向才逐步增强
参数名 类型 默认值 说明 LookaheadBase float 6.0 基础预瞄距离(格)，预瞄越远转向越平缓 LookaheadReduceRight float 3.0 右弯强度1时预瞄减少量(6→3晚打，防止右弯提前切弯) LookaheadReduceLeft float 1.5 左弯强度1时预瞄减少量(6→4.5，左弯可提前打) CorrectCoefBase float 0.12 基础修正系数（转向力度比例） CorrectCoefAdd float 0.12 弯道强度1时附加系数(0.12→0.24，弯越急修正越强) MaxDeltaBase float 0.10 基础每帧最大转向变化（防抖动） MaxDeltaAdd float 0.08 弯道强度1时附加(0.10→0.18，急弯允许更快转向) TurnLimitBase float 0.45 基础转向限幅（正常巡航最大转向值） TurnLimitAdd float 0.20 弯道强度1时附加(0.45→0.65，急弯放宽限幅) CurveActivateThreshold float 0.35 RawTurn>此值逐步增强弯道强度（判定为急弯） CurveDecayThreshold float 0.20 RawTurn<此值逐步衰减弯道强度（判定为小弯/直路） CurveActivateRate float 0.15 增强速率(每帧+0.15，约7帧达到满强度) CurveDecayRate float 0.08 衰减速率(每帧-0.08，约13帧回归正常) SharpCurveThreshold float 0.3 弯道强度>此值触发急弯减速 LaneWidthDefault float 4.0 无路沿时默认车道宽度(格) RoadCenterCoef float 0.15 无黄线时按道路中心修正的系数 EdgeCorrectCoef float 0.20 道路边缘偏离矫正力度系数 EdgeCorrectTrigger float 2.0 路沿<此距离(格)触发强制回正 NoLookExtraCoef float 0.1 无预瞄点时附加修正系数 AES 自动紧急转向
转弯/巡航中前方近距离障碍三级避让：同侧绕过→紧急反打→全堵刹停
- 避让空间判断使用横向清空距离(LeftClearance/RightClearance)，不是前方距离
- 横向清空距离 = 前方ClearanceForwardRange格内障碍的横向偏移绝对值最小值
- 触发距离自动叠加车头前悬补偿（见碰撞盒自动补偿机制）
参数名 类型 默认值 说明 TriggerDistTurn float 5.0 转弯中AES触发距离(格，转弯速度慢所以近) TriggerDistCruise float 8.0 巡航中AES触发距离(格，速度快要提前) AESLimit float 0.95 AES转向输出限幅 SameTurnRight float 0.95 右转中同侧(右)避让力度 OppTurnLeft float -0.9 右转中反打(左)力度 SameTurnLeft float -0.95 左转中同侧(左)避让力度 OppTurnRight float 0.9 左转中反打(右)力度 SameTurnCruiseA float 0.85 巡航同侧避让力度(选右侧绕过) OppTurnCruiseA float -0.8 巡航反打力度(选右侧时反侧) SameTurnCruiseB float -0.85 巡航同侧避让力度(选左侧绕过) OppTurnCruiseB float 0.8 巡航反打力度(选左侧时反侧) SameSideThreshold float 2.5 同侧横向清空距离>此值(格)可绕过(Level 1) OppSideThreshold float 3.5 反侧横向清空距离>此值(格)可反打(Level 2) AEB 紧急避障决策
仅在AES无法解决（全堵）时触发AEB紧急避障(State 0)，全堵刹停由AES Level 3处理
- SafeDist已废弃：全堵刹停改由AES Level 3在执行层处理，保留兼容旧配置
- 紧急避障距离自动叠加车头前悬补偿（见碰撞盒自动补偿机制）
参数名 类型 默认值 说明 EmergencyDist float 2.0 前方<此距离(格)且两侧堵→State 0紧急避障(刹车+音效) SafeDist float 3.0 已废弃：全堵刹停改由AES Level 3在执行层处理，保留兼容旧配置 SideBlockDist float 2.5 侧方横向清空距离<此值(格)视为堵(无避让空间)，AEB用 SpeedControl 速度控制
各状态下的油门区间（SpeedMin, SpeedMax），控制车辆速度
参数名 类型 默认值 说明 PauseScanSpeedMin float 0.04 已废弃：路口扫描改为完全停车（油门0.0+Brake=1.0），保留兼容旧配置 PauseScanSpeedMax float 0.08 已废弃：路口扫描改为完全停车（油门0.0+Brake=1.0），保留兼容旧配置 AESSpeedMin float 0.04 AES激活时油门下限 AESSpeedMax float 0.08 AES激活时油门上限 SharpCurveSpeedMax float 0.15 急弯油门上限基准 SharpCurveSpeedMin float 0.10 急弯油门下限基准 SharpCurveSpeedSlope float 0.05 急弯油门随曲率衰减系数(曲率越大速度越低) IntersectionTurnSpeedMin float 0.03 路口转弯油门下限 IntersectionTurnSpeedMax float 0.07 路口转弯油门上限 IntersectionCruiseSpeedMin float 0.06 路口内直行油门下限 IntersectionCruiseSpeedMax float 0.12 路口内直行油门上限 IntersectionApproachSpeedMin float 0.08 接近路口油门下限 IntersectionApproachSpeedMax float 0.18 接近路口油门上限 LaneChangeSpeedMin float 0.04 变道油门下限 LaneChangeSpeedMax float 0.10 变道油门上限 LaneChangeNarrowSpeedMin float 0.02 窄路变道油门下限(路宽<5) LaneChangeNarrowSpeedMax float 0.06 窄路变道油门上限 LaneChangeMidSpeedMin float 0.03 中等路变道油门下限(路宽<7) LaneChangeMidSpeedMax float 0.08 中等路变道油门上限 CruiseSpeedMin float 0.1 正常巡航油门下限 CruiseSpeedMax float 0.3 正常巡航油门上限 TurnOutputLimit float 0.95 转向输出限幅 TurnOutputThreshold float 0.1 转向>此值才输出(防抖) LaneChange S形变道
逆行检测后S形变道纠正：MovingOver右打→Returning回正→完成
参数名 类型 默认值 说明 ReverseDetectOffset float 0.5 黄线偏移>此值(格)判定逆行 TurnDist3 float 0.22 距黄线>3格的基础力度 TurnDist1_5 float 0.20 距黄线1.5-3格的基础力度 TurnDist0_8 float 0.17 距黄线0.8-1.5格的基础力度 TurnDistBase float 0.14 距黄线<0.8格的基础力度 MovingOverMaxTurn float 0.42 变道最大转向力度 MovingOverRiseRate float 0.05 力度上升速率(宽路，越小越平滑) MovingOverRiseRateNarrow float 0.07 力度上升速率(窄路，越快变道越急) NarrowWidthThreshold float 1.3 WidthCoef>此值视为窄路 ForwardCoefTrigger float 10.0 前方距离<此值(格)触发ForwardCoef加速变道 ReturningBase float -0.18 回正阶段基础反打力度(负值=左打) ReturningDecayTicks float 15.0 回正反打衰减周期(tick) ReturningEndTicks int 20 回正完成最小tick ReturningEndTurnThreshold float 0.08 回正完成纯追踪输出阈值 ReturnMaxDelta float 0.08 回正阶段每帧最大转向变化 ReturningWeightEndTicks float 20.0 回正反打权重归零周期 MovingOverMinTicks int 5 进入回正阶段最小tick Turn 路口转弯控制
路口转弯力度+路沿保护（防止转弯冲出路沿）
参数名 类型 默认值 说明 TurnStrengthDefault float 0.5 默认转弯力度 TurnStrengthLeft float 0.6 左转力度（左转转大弯，力度大） TurnStrengthRight float 0.45 右转力度（右转转小弯，力度小） RoadEdgeProtectTrigger float 3.0 路沿<此距离(格)开始衰减转弯力度 RoadEdgeProtectRange float 0.5 衰减过渡范围(触发距离-此值开始衰减) RoadEdgeReverseTrigger float 1.5 路沿<此距离(格)强制反打回正 RoadEdgeReverseTurn float 0.3 路沿反打力度 LiDAR 雷达扫描算法
雷达数据过滤、道路方块识别、障碍物判定、侧方清空距离统计等算法参数
参数名 类型 默认值 说明 ExpireTick int 200 雷达数据过期tick(10秒，过期自动清理) DetectRange int 30 雷达检测最大距离(格) ObstacleRelY float -1.0 障碍物最小RelY(过滤脚下方块，-1=车底以下不算障碍) RoadRelYMin float -3.0 道路方块最小RelY(覆盖下坡1格路面) RoadRelYMax float 1.0 道路方块最大RelY(覆盖上坡1格顶面) BlockDetectDist int 15 道路方块检测最大距离(格) FrontBlockDist int 5 前方堵路检测距离(格) MedianDistMin int 2 中央分隔带检测最小距离 MedianDistMax int 15 中央分隔带检测最大距离 MedianLatRange float 4.0 中央分隔带横向检测范围(格) ForwardDistMin int -2 有效前方距离下限(含车后2格，用于白线检测) ClearanceForwardRange float 10.0 侧方清空距离统计的前方范围(格)，AES/AEB避让空间判断用 Blocks 道路方块标识符配置
LADS识别路面、车道分隔线、停止线所使用的方块identifier，支持每辆车独立配置不同的道路方块 每个字段支持str（单个方块）或list（多种方块，如单黄线+双黄线都识别为黄线）
参数名 类型 默认值 说明 RoadBlock str 或 list minecraft:polished_deepslate 道路方块identifier（路面材料，用于车道识别/路口道路检测/中央分隔带判定） YellowBlock str 或 list minecraft:yellow_terracotta 黄线方块identifier（车道分隔线，用于LKA车道保持/逆行检测），如['minecraft:yellow_terracotta','minecraft:aabb_block'] WhiteBlock str 或 list dfm:baiyoulu_cebianzhixian 白线方块identifier（停止线/路口边线，用于路口检测/停止线聚类/PCA出口识别） System 系统开关配置
LADS系统级开关：音效播放、决策日志控制和汇入完成销毁检测
参数名 类型 默认值 说明 IsSound bool True 是否播放音效（注册上线/下线/紧急避障/刹停提示音），False则静音 IsLog bool False 是否输出决策变动日志（主状态切换/ACC子状态切换/AES等级切换/AEB/路口各阶段日志），True时输出到logging.debug DestroyCheckDist float 16.0 汇入路口成功后销毁检测的距离阈值(格)。用网易CanSee接口遍历serverApi.GetPlayerList()所有玩家，全部玩家都看不见该载具且与载具距离均大于此值时，状态快照NeedDestroy=True提示可销毁（防止无人视角载具堆积卡顿） 碰撞盒自动补偿机制
注册LADS时自动调用
LASystem.GetEntitySize(EntityId)(碰撞盒宽高)和LASystem.SetEntityScale(EntityId, None)(缩放倍率)， 计算车头前悬补偿 = 碰撞盒宽 × 缩放 / 2（车头到实体中心的距离），缓存到VehicleFrontOffset。 AES触发距离(TriggerDistCruise/Turn)和AEB紧急避障距离(EmergencyDist)自动加上此补偿值， 使大车提前避让。例如：碰撞盒宽4格×缩放1.0/2=2格补偿，巡航AES触发距离从8格→10格。 无需开发者配置，自动适配任意尺寸载具。接口获取失败时补偿为0，退化为原配置距离。
-
TSR 交通信号识别（虚拟红绿灯系统）
路口通行秩序调度系统，用虚拟红绿灯数据控制多方向来车通行顺序，避免路口交汇冲突。
- 红绿灯是虚拟数据，无实际方块，只保持通行秩序
- 每个路口独立管理，一次只给一个入口方向绿灯，倒计时切换
- 车辆接近路口时自动注册红绿灯（首次锁定停止线坐标时）
- 红灯时车辆在停止线前停车等待，绿灯时通行
- 开关：`LADS.EnableTrafficLight`（True开启/False关闭），开发期间默认开启
红绿灯配置（TrafficLightConfig，脚本层30Tick=1秒，非MC原生20Tick）：
|参数名|类型|默认值|说明|
|:-:|:-:|:-:|:-:|
|GreenDuration|int|900|绿灯持续时间(tick，900Tick=30秒)|
|YellowDuration|int|60|黄灯过渡时间(tick，60Tick=2秒，预留)|
|MergeDistance|float|15.0|路口合并距离(格，同一路口不同方向入口合并到同一路口ID)|
|MinGreenInterval|int|120|切换绿灯最小间隔(tick，120Tick=4秒，防止频繁切换)|
调度规则：
1. 路口ID：基于停止线世界坐标查找附近MergeDistance内已有路口合并，没有则新建
2. 入口ID：基于车辆行驶方向量化到N/S/E/W四个主方向
3. 每个路口维护入口字典，一次只给一个入口绿灯
4. 绿灯倒计时结束后变红灯，切换到下一个有等待车辆的入口给绿灯
5. 没有等待车辆时所有入口红灯
6. 等待车辆加入Waiters集合，红绿灯根据Waiters非空判断是否给绿灯
7. 按固定顺序N/E/S/W选择绿灯入口，保证切换稳定；调度时过滤已注销载具的僵尸EntityId
8. **WaitFrontCar（排队等前车）时不添加Waiter**：后车等待前车通过路口时由排队机制管理，红绿灯按正常调度放行，避免死锁
9. 方向隔离：不同入口（不同方向）的车辆各自独立等待绿灯，互不阻塞（同一路口S/N/W方向由红绿灯按顺序调度）
接口详见下方独立章节：[RegisterTrafficLight](#RegisterTrafficLight) / [GetTrafficLightState](#GetTrafficLightState) / [SetTrafficLightEnabled](#SetTrafficLightEnabled) / [SetTrafficLightConfig](#SetTrafficLightConfig) / [GetTrafficLightConfig](#GetTrafficLightConfig)
转弯期间静止载具检测
转弯期间（Pending/Turning/Aligning阶段）ACC/AES/AEB被抑制，但需要检测前方静止载具
（其他道路停止等待的车），避免转弯时撞上。
- 用3条射线（前方+左右30度）覆盖转弯路线，只检测实体不检测方块
- 只检测**未注册LADS的载具**（已注册的LADS载具会自己按规则避让，不当作障碍，避免多车路口互等死锁）
- 前方载具距离<车头前悬+1.5格：完全停车等待
- 前方载具距离<5格：减速慢行（油门0.01~0.03）
路口状态机（6阶段）
车辆接近路口时进入路口流程，按阶段流转：`Approaching → Scanning → Pending → Turning → Aligning → PassThrough` → 完成（清空TurnDecision）。
|阶段|行为|
|:-:|:-:|
|Approaching|接近停止线，减速行驶。首次锁定停止线坐标时自动注册红绿灯，到达停止线前3格（StopThreshold=VehicleFrontOffset+3.0）进入Scanning|
|Scanning|完全停车（油门0.0+Brake=1.0）等待一个完整雷达扫描周期（约33tick），期间禁止慢速前进（防止红绿灯放行后越过停止线导致LiDAR扫不到侧方出口）。采集白点+道路方块，聚类+PCA检测出口+决策方向|
|Pending|等待路口入口空间，驶过停止线≥3格后进入Turning|
|Turning|执行转弯（直行跳过此阶段直接PassThrough），转角≥75°且越过出口白线后进入Aligning|
|Aligning|转弯后反打回正对齐车道（AlignTurn=min(0.40, RemainYaw*0.025)），释放条件：①车头对齐(剩余<8°)+前方>10格 ②检测到顺行黄线 ③兜底20tick防卡死|
|PassThrough|直行通过路口，越过前方出口白线后完成，清空TurnDecision|
- 扫描失败重试：Candidates为空时重置扫描计时器，最多3次重试（RetryWait完全停车），仍失败则复制前车转弯方向（跟随前车）
- PCA漏检补全：只识别出1个转弯出口(3或4)时，检查直行方向(RoadBlocks中前方5-15格、横向±3格)是否有道路方块，有则补全直行出口[2]
- 出口封堵过滤：`_FilterBlockedExits`对每个候选出口方向发射射线（前方8格），5格内有方块则过滤该方向（防止撞被封堵的建筑）
- **汇入完成销毁检测**：Aligning对齐完成（汇入路口成功）时，用网易CanSee接口遍历`serverApi.GetPlayerList()`所有玩家，全部玩家都看不见该载具（CanSee=False）且与载具距离均大于`System.DestroyCheckDist`（默认16格）时，状态快照`NeedDestroy=True`提示可销毁（防止无人视角载具堆积卡顿）。任一玩家可见或距离≤阈值则`NeedDestroy=False`
多车排队隔离机制
多车通过同一路口时，为避免LiDAR共享缓存数据互相污染导致PCA误判，采用三层隔离：
1. **RegisterOrder注册顺序**：先注册的载具优先通过路口，后车等待前车
2. **WaitingFrontCar停止LiDAR扫描**：后车等待期间`WaitingFrontCar[EntityId]=True`，ServerTick跳过LiDAR扫描，不写入共享缓存，避免污染前车PCA检测
3. **停止线世界坐标路口隔离**：`_CheckFrontCarInIntersection`用停止线世界坐标判断同一路口（距离<15格），不同路口不互相干扰
- 等待范围：前车在**任一阶段**（Approaching/Scanning/Pending/Turning/Aligning/PassThrough）都触发等待——前车Approaching时后车也必须停扫，否则LiDAR污染前车数据
- **方向隔离**：只等待**同入口（同方向）**的前车，不同入口（如S/N/W三个方向）的车辆不互相等待，各自由红绿灯调度通过，避免多车多路口死锁
- **WaitFrontCar时不添加红绿灯Waiter**：避免后车被卡住后Waiter残留导致红绿灯死循环
- **Scanning阶段也检查WaitFrontCar**：后车已进入Scanning后前车才进入路口流程时，后车暂停扫描回退等待
SuppressObstacleAvoidance（路口避障抑制）
路口全流程（Approaching/Scanning/Pending/Turning/Aligning/PassThrough）+ 冷却期60tick内，抑制ACC/AES/AEB障碍避让（`_DecideObstacleAvoidance`返回State=2）。
原因：路口转弯时横向偏移大，正常障碍检测会误判转弯路径上的道路/路沿为障碍。
转弯期间的前方载具由`_DetectFrontVehicleInTurn`专用检测处理（见上文"转弯期间静止载具检测"）。
速度控制优先级（11级）
转弯前方载具停车 > 红绿灯等待 > 扫描重试 > 前车等待(WaitFrontCar) > 转弯减速(TurnFrontSlow) > 路口转弯 > 路口直行 > 接近路口 > 变道 > ACC跟车 > 正常巡航
性能调度（round-robin）
ServerTick采用round-robin轮流调度：每tick只执行固定数量载具，单tick开销可控，避免N辆车同时执行VehicleControl造成ServerTick累积延迟。
- 分帧策略由`SetVehicleControlTickMode`接口控制（默认30tick循环/自定义ntick/auto自适应）
- 默认30tick循环：N<=30时每tick执行1辆，N>30时每tick执行ceil(N/30)辆，每30tick每车至少执行1次
- 自定义ntick：所有载具平分在ntick内执行完，VehiclesPerTick=ceil(N/ntick)，ntick越小响应越快但单tick开销越大
- auto自适应：每30tick检查房主ping，ping>40ms增大ntick降低开销，ping<40ms减小ntick提高响应，目标延迟稳定在40ms以内
- LiDAR扫描仍按自身周期（LiDARSpeed+LiDARSpeedStep）执行，被轮到时若不满周期则跳过扫描
- 雷达缓存过期清理统一在ServerTick每tick执行一次（`_ExpireLiDARData`），避免N辆车各清理一次重复开销
- AES日志仅在AES等级变化时输出，持续避让不刷屏（减少日志IO开销）
- 路口流程/ACC跟车中的车辆由_TickIntersectionVehicle/_TickACCVehicle递归调度（BindNextTickFunction）独立执行，不受round-robin影响
- 接口用法示例
LADS = LASystem.LADS() # 获取LADS实例
TGVCVSystem = serverApi.GetSystem('TSC_GTA_VC_Vehicle', 'TSC_GTA_VC_VehicleServerSystem')
# 0. 调用方自行解除驾驶位限制（RegisterLADS不代管此接口）
TGVCVSystem.ControlVehicle_SetCanControl(EntityId, 1.0)
# 1. 基础注册（载具控制函数 + 默认配置）
LADS.RegisterLADS(EntityId, TGVCVSystem.ControlVehicleByDict, TGVCVSystem.ControlVehicle_Throttle)
# 2. 仅用JSON模板（推荐，参数集中管理）
LADS.RegisterLADS(EntityId, TGVCVSystem.ControlVehicleByDict, TGVCVSystem.ControlVehicle_Throttle, 'lads_demo')
# 3. JSON模板 + 热更覆盖部分参数（小改动无需新建JSON）
LADS.RegisterLADS(EntityId, TGVCVSystem.ControlVehicleByDict, TGVCVSystem.ControlVehicle_Throttle, 'lads_demo', LADSConfig={
'ACC': {'FollowDist': 15.0},
'Hardware': {'LiDARSpeed': 20},
})
# 4. 带状态变更回调（决策状态变化时回调，可用于UI显示/日志记录/外部联动）
def OnStateChange(StateInfo):
print('[外部] {} 状态变更：{} ACC={}'.format(
StateInfo['EntityId'], StateInfo['StateName'], StateInfo['ACCSubStateName']))
LADS.RegisterLADS(EntityId, TGVCVSystem.ControlVehicleByDict, TGVCVSystem.ControlVehicle_Throttle,
'lads_demo', StateCallBackFunctionInstance=OnStateChange)
# 5. 忽略特定实体类型（玩家/僵尸等不计入避让和跟车目标）
LADS.RegisterLADS(EntityId, TGVCVSystem.ControlVehicleByDict, TGVCVSystem.ControlVehicle_Throttle,
'lads_demo', IgnoreEntityTypes=['minecraft:player', 'minecraft:zombie'])
-
ControlVehicleByDictFunction函数规范
-
描述
控制载具的所有运动标志，同时传入所有的运动标志 -
参数
参数名 数据类型 说明 VehicleId str 车辆实体ID ControlDict dict 控制字典 -
备注
ControlDict: 控制字典的键，值取（0，1） -
Forward: 前进
-
Backward: 后退
-
Brake: 刹车
-
TurnLeft: 左转
-
TurnRight: 右转
-
SuperSpeedUp: 超级加速
-
示例
# 前进+左转+刹车+快速加速 VehicleServerSystem.ControlVehicleByDict(victimId,{ "Forward": 1.0, "Backward": 0.0, "TurnLeft": 1.0, "TurnRight": 0.0, "Brake": 1.0, "SuperSpeedUp": 1.0, }) -
-
ControlVehicleThrottleFucntion函数规范
-
描述
单独控制载具的油门（前进、后退、停止、超级加速） -
参数
参数名 数据类型 说明 VehicleId str 车辆实体ID ControlFlag float 控制标志，取值范围：[-1.0,1.0]、超出范围则是超级加速 Ratio float 最大速度比例，取值范围：[0.0,1.0]，默认值为：1.0 -
返回值
无 -
备注
ControlFlag 取值说明： -
(0.0, 1.0]: 前进
-
[-1.0, 0.0): 后退
-
0.0: 停止
-
其他: 超级加速 注意：当需要保持预期速度匀速前进的时候，可以通过调整最大速度比例Ratio来控制预期速度，同时ControlFlag一定要大于0，才能保证车辆会达到最大速度匀速前进。如果ControlFlag等于0则会进入自然减速状态。
-
示例
# 0.6倍率加速度，0.75倍最大速度前进 TSC_GTA_VC_VehicleServerSystem.ControlVehicle_Throttle(entityId, 0.6, 0.75) # 后退 TSC_GTA_VC_VehicleServerSystem.ControlVehicle_Throttle(entityId, -1.0) # 停止 TSC_GTA_VC_VehicleServerSystem.ControlVehicle_Throttle(entityId, 0.0) # 超级加速 TSC_GTA_VC_VehicleServerSystem.ControlVehicle_Throttle(entityId, 2.0) -
-
Json完整示例 灵免以太测试环境中的行为包
modconfigs下拥有该示例。
{
"format_version": "2.10.3",
"santsue:lads": {
"santsue:acc": {
"DetectRange": 45.0,
"LaneWidth": 1.5,
"ObstacleLaneWidth": 3.0,
"OffDist": 40.0,
"BrakeDist": 5.0,
"ObstacleBrakeDist": 12.0,
"BrakeTTC": 2.5,
"FollowDist": 20.0,
"TimeHeadway": 40.0,
"Kp": 0.005,
"Kd": 0.015,
"FollowMaxAcc": 0.20,
"FollowAccMargin": 0.08,
"BrakeMaxAcc": 0.02,
"ObstacleBrakeSpeedMin": 0.04,
"ObstacleBrakeSpeedMax": 0.08,
"SpeedMargin": 0.03,
"SpeedFilterAlpha": 0.3,
"TTCSlopeThreshold": -0.005,
"HistoryTicks": 40
},
"santsue:lka": {
"LookaheadBase": 6.0,
"LookaheadReduceRight": 3.0,
"LookaheadReduceLeft": 1.5,
"CorrectCoefBase": 0.12,
"CorrectCoefAdd": 0.12,
"MaxDeltaBase": 0.10,
"MaxDeltaAdd": 0.08,
"TurnLimitBase": 0.45,
"TurnLimitAdd": 0.20,
"CurveActivateThreshold": 0.35,
"CurveDecayThreshold": 0.20,
"CurveActivateRate": 0.15,
"CurveDecayRate": 0.08,
"SharpCurveThreshold": 0.3,
"LaneWidthDefault": 4.0,
"RoadCenterCoef": 0.15,
"EdgeCorrectCoef": 0.20,
"EdgeCorrectTrigger": 2.0,
"NoLookExtraCoef": 0.1
},
"santsue:aes": {
"TriggerDistTurn": 5.0,
"TriggerDistCruise": 8.0,
"AESLimit": 0.95,
"SameTurnRight": 0.95,
"OppTurnLeft": -0.9,
"SameTurnLeft": -0.95,
"OppTurnRight": 0.9,
"SameTurnCruiseA": 0.85,
"OppTurnCruiseA": -0.8,
"SameTurnCruiseB": -0.85,
"OppTurnCruiseB": 0.8,
"SameSideThreshold": 2.5,
"OppSideThreshold": 3.5
},
"santsue:aeb": {
"EmergencyDist": 2.0,
"SafeDist": 3.0,
"SideBlockDist": 2.5
},
"santsue:speed_control": {
"PauseScanSpeedMin": 0.04,
"PauseScanSpeedMax": 0.08,
"AESSpeedMin": 0.04,
"AESSpeedMax": 0.08,
"SharpCurveSpeedMax": 0.15,
"SharpCurveSpeedMin": 0.10,
"SharpCurveSpeedSlope": 0.05,
"IntersectionTurnSpeedMin": 0.03,
"IntersectionTurnSpeedMax": 0.07,
"IntersectionCruiseSpeedMin": 0.06,
"IntersectionCruiseSpeedMax": 0.12,
"IntersectionApproachSpeedMin": 0.08,
"IntersectionApproachSpeedMax": 0.18,
"LaneChangeSpeedMin": 0.04,
"LaneChangeSpeedMax": 0.10,
"LaneChangeNarrowSpeedMin": 0.02,
"LaneChangeNarrowSpeedMax": 0.06,
"LaneChangeMidSpeedMin": 0.03,
"LaneChangeMidSpeedMax": 0.08,
"CruiseSpeedMin": 0.1,
"CruiseSpeedMax": 0.3,
"TurnOutputLimit": 0.95,
"TurnOutputThreshold": 0.1
},
"santsue:lane_change": {
"ReverseDetectOffset": 0.5,
"TurnDist3": 0.22,
"TurnDist1_5": 0.20,
"TurnDist0_8": 0.17,
"TurnDistBase": 0.14,
"MovingOverMaxTurn": 0.42,
"MovingOverRiseRate": 0.05,
"MovingOverRiseRateNarrow": 0.07,
"NarrowWidthThreshold": 1.3,
"ForwardCoefTrigger": 10.0,
"ReturningBase": -0.18,
"ReturningDecayTicks": 15.0,
"ReturningEndTicks": 20,
"ReturningEndTurnThreshold": 0.08,
"ReturnMaxDelta": 0.08,
"ReturningWeightEndTicks": 20.0,
"MovingOverMinTicks": 5
},
"santsue:turn": {
"TurnStrengthDefault": 0.5,
"TurnStrengthLeft": 0.6,
"TurnStrengthRight": 0.45,
"RoadEdgeProtectTrigger": 3.0,
"RoadEdgeProtectRange": 0.5,
"RoadEdgeReverseTrigger": 1.5,
"RoadEdgeReverseTurn": 0.3
},
"santsue:lidar": {
"ExpireTick": 200,
"DetectRange": 30,
"ObstacleRelY": -1.0,
"RoadRelYMin": -3.0,
"RoadRelYMax": 1.0,
"BlockDetectDist": 15,
"FrontBlockDist": 5,
"MedianDistMin": 2,
"MedianDistMax": 15,
"MedianLatRange": 4.0,
"ForwardDistMin": -2,
"ClearanceForwardRange": 10.0
},
"santsue:hardware": {
"LiDARNum": 88,
"LiDARAngle": 180,
"LiDARVertNum": 17,
"LiDARVertAngle": 45.0,
"LiDARSpeed": 30,
"LiDARSpeedStep": 1,
"ControlInterval": 3
},
"santsue:blocks": {
"RoadBlock": "minecraft:polished_deepslate",
"YellowBlock": "minecraft:yellow_terracotta",
"WhiteBlock": "dfm:baiyoulu_cebianzhixian"
},
"santsue:system": {
"IsSound": true,
"IsLog": false,
"DestroyCheckDist": 16.0
}
}
}
IsLADSRegistered
服务端
-
描述
判断实体是否已注册LADS智驾系统- 用于ACC前车识别过滤（只跟车已注册LADS的载具，不跟行人/动物等非载具实体）
- 开发者可调用此接口判断某实体是否在LADS管控下
-
参数
| 参数名 | 数据类型 | 说明 |
|---|---|---|
| EntityId | str | 实体ID |
-
返回值
bool，True=已注册LADS，False=未注册 -
示例
LADS = LASystem.LADS()
if LADS.IsLADSRegistered(EntityId):
print('该实体已注册LADS智驾系统')
GetLADSState
服务端
-
描述
查询载具当前LADS决策状态（供开发者实时获取载具驾驶状态）- 返回最新决策状态快照，未注册返回None
-
参数
| 参数名 | 数据类型 | 说明 |
|---|---|---|
| EntityId | str | 载具实体ID |
- 返回值
dict或None，未注册返回None，已注册返回状态字典：
{
'EntityId': str, # 载具实体ID
'State': int, # 主状态码(0=紧急避障 1=刹停 2=巡航 3=左转避让 4=右转避让)
'StateName': str, # 主状态中文名
'ACCSubState': int, # ACC子状态(0=Off 1=Follow 2=Brake)
'ACCSubStateName': str, # ACC子状态名
'AESLevel': int, # AES等级(0=未激活 1=同侧避让 2=紧急反打 3=全堵刹停)
'AESLevelName': str, # AES等级名
'LaneChangePhase': str, # 变道阶段('None'/'MovingOver'/'Returning')
'IntersectionPhase': str, # 路口阶段('None'/'Approaching'/'Scanning'/'Pending'/'Turning'/'Aligning'/'PassThrough')
'VehiclePos': tuple, # 车辆坐标(x,y,z)
'FrontCarId': str or None, # ACC前车ID（无前车时为None）
'FrontDist': float, # ACC前车距离(格，无前车时999.0)
'NeedDestroy': bool, # 汇入路口成功后是否提示可销毁（全部玩家均不可见且距离均大于System.DestroyCheckDist时为True）
}
- 示例
LADS = LASystem.LADS()
StateInfo = LADS.GetLADSState(EntityId)
if StateInfo:
print('{} 当前状态：{} ACC={}'.format(
StateInfo['EntityId'], StateInfo['StateName'], StateInfo['ACCSubStateName']))
ResetLADS
服务端
-
描述
清空所有已注册的LADS智驾系统- 归零所有载具控制（油门+运动标志）
- 播放下线音效（任一载具开启音效时）
- 清空状态追踪
- 清理所有载具在红绿灯中的Waiters（逐个移除，不影响红绿灯路口注册数据）
-
参数
无（接受任意参数，均不使用） -
返回值
无 -
备注
ControlVehicle_SetCanControl（解除驾驶位限制）不在ResetLADS内调用，由调用方自行管理 -
示例
LADS = LASystem.LADS()
LADS.ResetLADS()
UnRegisterLADS
服务端
-
描述
取消注册单个载具的LADS智驾系统- 归零该载具控制（油门+运动标志）
- 清空该载具的状态追踪、配置缓存、存档路口决策数据
- 清理该载具在红绿灯中的Waiter（不影响其他载具）
- 按该载具的IsSound配置决定是否播放下线音效
- 未注册的EntityId直接返回False，不做任何操作
-
参数
| 参数名 | 数据类型 | 说明 |
|---|---|---|
| EntityId | str | 载具实体ID |
-
返回值
bool，True=已注册并成功取消，False=未注册无需取消 -
备注
ControlVehicle_SetCanControl（恢复驾驶位限制）不在本接口内调用，由调用方自行管理 -
示例
LADS = LASystem.LADS()
if LADS.UnRegisterLADS(EntityId):
print('已取消该载具的LADS注册')
else:
print('该载具未注册LADS')
RegisterTrafficLight
服务端
-
描述
为路口的某个入口注册虚拟红绿灯（TSR交通信号识别系统）- 若路口/入口不存在则创建，已存在则不覆盖（保持当前红绿灯状态）
- 路口ID由
_FindOrCreateIntersection生成（基于停止线世界坐标查找附近MergeDistance内已有路口合并，没有则新建） - 入口ID由
_GenEntranceId生成（基于车辆行驶方向量化到N/S/E/W四个主方向） - 红绿灯是虚拟数据，无实际方块，只保持通行秩序
- 通常由LADS内部在车辆首次锁定停止线坐标时自动调用，开发者一般无需手动调用
-
参数
| 参数名 | 数据类型 | 说明 |
|---|---|---|
| IntersectionId | str | 路口ID（由_FindOrCreateIntersection生成） |
| EntranceId | str | 入口ID（由_GenEntranceId生成，N/S/E/W） |
| EntrancePos | tuple | 停止线世界坐标 (x, y, z) |
| EntranceDir | tuple | 入口方向 (dx, dz) |
-
返回值
无 -
示例
LADS = LASystem.LADS()
# 手动注册红绿灯（通常LADS会自动调用，无需手动注册）
IntersectionId = LADS._FindOrCreateIntersection((100.0, 64.0, 200.0))
EntranceId = LADS._GenEntranceId((1.0, 0.0, 0.0)) # 返回'E'
LADS.RegisterTrafficLight(IntersectionId, EntranceId, (100.0, 64.0, 200.0), (1.0, 0.0))
GetTrafficLightState
服务端
-
描述
查询路口某入口的红绿灯状态- 未注册的路口/入口默认返回'Green'(不阻塞交通)
- 红绿灯系统关闭时（SetTrafficLightEnabled(False)）所有查询返回'Green'
-
参数
| 参数名 | 数据类型 | 说明 |
|---|---|---|
| IntersectionId | str | 路口ID |
| EntranceId | str | 入口ID（N/S/E/W） |
-
返回值
str，'Red'(红灯，需停车等待) / 'Green'(绿灯，可通行) -
示例
LADS = LASystem.LADS()
State = LADS.GetTrafficLightState('int_100_200', 'E')
if State == 'Red':
print('红灯，需停车等待')
else:
print('绿灯，可通行')
SetTrafficLightEnabled
服务端
-
描述
开关红绿灯系统（TSR交通信号识别）- 开启后：车辆接近路口自动注册红绿灯，按红绿灯状态停车等待/通行
- 关闭后：所有已注册红绿灯立即失效，所有入口视为绿灯放行，不阻塞交通
- 关闭时清空所有入口的等待车辆（Waiters），让正在等红灯的车立即放行
- 已注册的红绿灯数据保留，再次开启时恢复使用
-
参数
| 参数名 | 数据类型 | 说明 |
|---|---|---|
| Enabled | bool | True=开启红绿灯系统，False=关闭 |
-
返回值
无 -
示例
LADS = LASystem.LADS()
# 关闭红绿灯系统（所有路口立即放行）
LADS.SetTrafficLightEnabled(False)
# 再次开启（恢复使用已注册的红绿灯数据）
LADS.SetTrafficLightEnabled(True)
SetTrafficLightConfig
服务端
-
描述
设置红绿灯系统配置参数（覆盖默认配置，只更新传入的字段）- 脚本层30Tick=1秒，设置时按需换算
- 已在倒计时中的绿灯不会立即应用新的GreenDuration，下一次切换绿灯时生效
- 配置更新时输出日志（旧值→新值）
-
参数
| 参数名 | 数据类型 | 说明 |
|---|---|---|
| Config | dict | 配置字典，支持字段见下表 |
Config支持字段：
| 字段名 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| GreenDuration | int | 900 | 绿灯持续时间(tick，900Tick=30秒) |
| YellowDuration | int | 60 | 黄灯过渡时间(tick，60Tick=2秒，预留) |
| MergeDistance | float | 15.0 | 路口合并距离(格，同一路口不同方向入口合并到同一路口ID) |
| MinGreenInterval | int | 120 | 切换绿灯最小间隔(tick，120Tick=4秒，防止频繁切换) |
-
返回值
无 -
示例
LADS = LASystem.LADS()
# 设置绿灯60秒(1800tick)、黄灯3秒(90tick)
LADS.SetTrafficLightConfig({'GreenDuration': 1800, 'YellowDuration': 90})
# 只修改路口合并距离
LADS.SetTrafficLightConfig({'MergeDistance': 20.0})
GetTrafficLightConfig
服务端
-
描述
查询红绿灯系统当前配置参数- 返回配置字典的副本，修改返回值不影响内部配置
-
参数
无 -
返回值
dict，包含字段：
{
'GreenDuration': int, # 绿灯持续时间(tick)
'YellowDuration': int, # 黄灯过渡时间(tick)
'MergeDistance': float, # 路口合并距离(格)
'MinGreenInterval': int, # 切换绿灯最小间隔(tick)
}
- 示例
LADS = LASystem.LADS()
Config = LADS.GetTrafficLightConfig()
print('当前绿灯时长:{}tick ({}秒)'.format(Config['GreenDuration'], Config['GreenDuration'] / 30.0))
SetVehicleControlTickMode
服务端
-
描述
设置VehicleControl分帧调度模式（控制ServerTick中每tick执行多少辆车的VehicleControl）- 影响所有已注册LADS载具的VehicleControl调度频率，不影响LiDAR扫描周期和路口/ACC递归调度
- 已注册载具立即生效，无需重新注册
- 默认模式为
True（30tick循环），保持向后兼容
分帧策略说明：
| 模式 | 参数值 | 行为 | 适用场景 |
|---|---|---|---|
| 30tick循环 | True | NTick=30，每tick执行ceil(N/30)辆，每辆车1秒内至少执行1次 | 默认模式，通用场景 |
| 自定义ntick | int(>0) | 所有载具平分在ntick内执行完，VehiclesPerTick=ceil(N/ntick) | 需要精确控制调度频率的场景 |
| auto自适应 | None | 每30tick检查房主ping，动态调整ntick，目标延迟稳定在40ms以内 | 联机或车辆数变化大的场景 |
-
自定义ntick参数范围：[1, 120]，超出会自动钳制到边界值
-
自定义ntick示例：ntick=15时，N=2车辆每tick1辆2tick循环；N=31车辆每tick3辆约11tick循环
-
auto模式调整规则：ping>60ms快速增大ntick(+5/次)；ping 40-60ms缓慢增大(+1)；ping 25-40ms保持；ping<25ms减小(-2)
-
auto模式调整范围：[5, 60]，N<=5时不调整（车少时30tick循环开销本就极低）
-
auto模式使用
LASystem.GetPlayerPing(LASystem.GetHostPlayerId())获取房主延迟 -
模式切换会输出
logging.debug日志（Auto调整时也会输出NTick变化日志） -
参数
| 参数名 | 数据类型 | 说明 |
|---|---|---|
| Mode | True/int/None | 调度模式：True=30tick循环（默认）/int=自定义ntick/None=auto自适应 |
-
返回值
bool，True=设置成功，False=参数非法（保持原模式不变） -
示例
LADS = LASystem.LADS()
# 1. 默认30tick循环（保持向后兼容）
LADS.SetVehicleControlTickMode(True)
# 2. 自定义15tick平分（更快响应，单tick开销更大）
LADS.SetVehicleControlTickMode(15)
# 3. auto模式，根据房主ping自适应（联机推荐）
LADS.SetVehicleControlTickMode(None)
# 4. 边界处理示例
LADS.SetVehicleControlTickMode(200) # 自动钳制到120
Success = LADS.SetVehicleControlTickMode(0) # 返回False，参数非法
Success = LADS.SetVehicleControlTickMode(-5) # 返回False，参数非法
Success = LADS.SetVehicleControlTickMode(False) # 返回False，False是int子类但被排除
RegisterLiDAROnly
服务端
-
描述
只注册雷达扫描，不注册智能驾驶系统- 只执行激光雷达扫描，数据写入共享缓存（AllCacheLiDARData），可通过GetLiDARData获取
- 不执行车辆控制（VehicleControl）、不触发ACC/AES/AEB/LKA/路口决策等智驾功能
- 适用于：只需雷达感知数据但不需要自动驾驶的场景（如手动驾驶辅助感知、数据采集、可视化雷达点云等）
- RegisterLADS和RegisterLiDAROnly互斥，同一EntityId只能注册其中一种，先注册的生效
- 配置合并优先级同RegisterLADS：代码默认值 < JSON模板(JsonId) < 热更覆盖(LADSConfig)
- 只合并Hardware/LiDAR/Blocks/System模块，其他模块（ACC/AES/AEB等）不生效
- 取消注册调用UnRegisterLADS即可（与LADS共用取消接口）
-
参数
| 参数名 | 数据类型 | 说明 |
|---|---|---|
| EntityId | str | 实体ID |
| JsonId | str | JSON配置模板ID（modconfigs目录下文件名，不含.json后缀）。None则用代码内置默认配置 |
| LADSConfig | dict | 热更覆盖配置，优先级最高。只需传Hardware/LiDAR/Blocks模块，其他模块不生效 |
-
返回值
bool，True=注册成功，False=已注册LADS或LiDAROnly（不覆盖） -
示例
LADS = LASystem.LADS()
# 基础注册：只扫描雷达，用默认配置
LADS.RegisterLiDAROnly(EntityId)
# 用JSON模板 + 自定义雷达线数
LADS.RegisterLiDAROnly(EntityId, 'lads_demo', LADSConfig={
'Hardware': {'LiDARNum': 128, 'LiDARSpeed': 20}
})
# 同一EntityId已注册LADS时调用会返回False
Success = LADS.RegisterLiDAROnly(EntityId)
if not Success:
print('该载具已注册LADS或LiDAROnly，不覆盖')
# 取消注册（与LADS共用接口）
LADS.UnRegisterLADS(EntityId)
GetLiDARData
服务端
-
描述
获取雷达扫描数据（供外部读取雷达感知结果）- 需先调用RegisterLiDAROnly或RegisterLADS注册雷达，否则返回None
- 雷达数据存在共享缓存AllCacheLiDARData中，按扫描周期自动更新
- 可传入VehiclePos/VehicleDir/RightDir将世界坐标转换为车体相对坐标(Fd前向距离/Lt横向距离)
- 未传入VehiclePos时返回原始世界坐标数据（Fd/Lt为None）
-
参数
| 参数名 | 数据类型 | 说明 |
|---|---|---|
| EntityId | str | 实体ID |
| VehiclePos | tuple or None | 车辆世界坐标(x,y,z)，传入则将雷达点转为车体相对坐标(Fd,Lt)，None则返回原始世界坐标 |
| VehicleDir | tuple or None | 车辆前向方向(dx,0,dz)，配合VehiclePos使用 |
| RightDir | tuple or None | 车辆右侧方向(dx,0,dz)，配合VehiclePos使用 |
| DataType | str | 数据类型过滤：'All'=全部/'Block'=方块/'Entity'=实体 |
- 返回值
dict或None，未注册返回None，已注册返回：
{
'Blocks': [ # 方块数据列表
{
'Pos': (x, y, z), # 方块世界坐标
'Fd': float, # 前向距离(格，正值=前方，负值=后方)，未传入VehiclePos时为None
'Lt': float, # 横向距离(格，正值=右侧，负值=左侧)，未传入VehiclePos时为None
'identifier': str, # 方块标识符（如'minecraft:yellow_glazed_terracotta'）
'Timer': int, # 数据写入时的AllTick，可用于判断数据新鲜度
},
...
],
'Entities': [ # 实体数据列表
{
'Pos': (x, y, z), # 实体世界坐标
'Fd': float, # 前向距离
'Lt': float, # 横向距离
'entityId': str, # 实体ID
'identifier': str, # 实体标识符
'Timer': int, # 数据写入时的AllTick
},
...
],
'ScanTick': int, # 调用时的AllTick（可用于判断数据新鲜度，与Item.Timer比较）
'FirstScanDone': bool, # 首轮扫描是否完成（False时数据不完整）
}
- 示例
LADS = LASystem.LADS()
import serverApi
from mod.common.modLoader import GetDirFrom
# 1. 获取原始世界坐标数据（不转换坐标）
Data = LADS.GetLiDARData(EntityId)
if Data and Data['FirstScanDone']:
for Block in Data['Blocks']:
print('方块:{} 坐标:{} 标识:{}'.format(Block['Pos'], Block['identifier']))
# 2. 获取车体相对坐标数据（Fd前向距离/Lt横向距离）
compPos = serverApi.GetEngineCompFactory().CreatePos(EntityId)
compRot = serverApi.GetEngineCompFactory().CreateRot(EntityId)
Pos = compPos.GetPos()
Rot = compRot.GetRot()
# 注意：灵免以太角度转换
NormalYaw = LASystem.LeftHandToNormalAngle(Rot[1])
VehicleDir = serverApi.GetDirFromRot((0.0, NormalYaw))
RightDir = (-VehicleDir[2], 0.0, VehicleDir[0])
Data = LADS.GetLiDARData(EntityId, Pos, VehicleDir, RightDir)
if Data:
# 筛选前方5格内的方块
FrontBlocks = [b for b in Data['Blocks'] if b['Fd'] is not None and 0 < b['Fd'] < 5.0]
print('前方5格内方块数:{}'.format(len(FrontBlocks)))
# 3. 只获取实体数据
EntityData = LADS.GetLiDARData(EntityId, DataType='Entity')
if EntityData:
for Ent in EntityData['Entities']:
print('实体:{} 标识:{}'.format(Ent['entityId'], Ent['identifier']))
