街道定位系统(API)

街道定位系统（API）

《赛博朋克 2077》原生追踪主要地区和分区，但并未为模组作者提供可靠的方式来查询玩家当前所在的精确街道或十字路口，即使周围有街道标识也是如此。

街道定位系统弥补了这一缺陷。它在后台静默运行，持续将 V 的位置解析到街道和交叉路口级别，并为任何需要精确街道级位置数据的模组提供 API。

我构建此系统是为了给车辆导航系统和信息小部件模组提供更多信息。但我也可以想象它在任务模组或类似项目中的用途。

核心功能与机制

1. 精确街道与十字路口追踪 — 原版游戏处理区和分区数据，而此 API 将位置追踪扩展到街道级别。它持续解析玩家位置，以确定主街道名称和最近十字路口。它还包含内置格式化器，可生成适合 UI 显示的变体（例如，自动将"Street"缩短为"St"或提供裸名称）。适用于导航和玩家位置信息。

2. 任意空间查询 — 位置追踪不仅限于玩家。此 API 允许你传入游戏世界中的任意 Vector4 坐标，并立即获取该精确点的街道数据或附近街道数组。适用于自定义信使任务、显示自定义地图图钉地址、动态命名 GPS 路径点，或追踪远处的 NPC 和载具。

3. 性能与配置 — 追踪循环针对后台执行进行了优化。模组作者可以完全控制系统资源占用，提供可调方法以调整扫描频率、微调搜索半径，或在脚本事件期间完全暂停追踪。

4. 修复环境与室内检测 — 作为街道位置追踪的副产品，此模组修复了游戏故障的环境检测。原版的 IsEntityInInteriorArea 函数经常返回误报（例如，在开阔屋顶上将 V 标记为"室内"）。此 API 通过结合 TweakDB 区域映射、物理天花板检测和一些实验性魔法（如有缺陷请报告），提供了更准确的 IsPlayerIndoor() 检查。例如，适用于 HUD 可见性设置。

5. 世界地图 UI 集成 — 该系统不仅默默在后台工作。街道名称和交叉路口信息直接注入世界地图 UI，让玩家在固定地图时可以直接在分区下方查看道路详细信息。

模组作者 API 文档

要在你的 REDscript 项目中使用此 API，请导入模块并获取系统实例。

初始化

import StreetLogger.System.*
import StreetLogger.Data.*

// 获取系统活动实例
let streetSys = StreetLocationSystem.GetInstance(GetGame());

1. 公共访问器（玩家位置）

读取 V 当前缓存的位�置数据。

// 原版级别区域数据
streetSys.GetCurrentDistrict()            // 例如："Watson"
streetSys.GetCurrentSubDistrict()         // 例如："Little China"

// 扩展街道级别数据
streetSys.GetCurrentStreetName()          // 例如："Goldsmith Street"
streetSys.GetCurrentCrossroad()           // 例如："Goldsmith Street & Bradbury Street"

// UI 格式化器
streetSys.GetCurrentStreetNameShort()     // 例如："Goldsmith St"
streetSys.GetCurrentStreetNameBare()      // 例如："Goldsmith"
streetSys.GetCurrentCrossroadShort()      // 例如："Goldsmith St & Bradbury St"
streetSys.GetCurrentCrossroadBare()       // 例如："Goldsmith & Bradbury"

// 环境状态
streetSys.GetLocationType()               // 返回 ELocationType（Outdoor、Indoor、Metro、OffRoad）
streetSys.IsPlayerIndoor()                // 返回 Bool
streetSys.GetCurrentLocationData()        // 返回完整的 StreetLocationData 结构体

2. 空间点查询与自定义区域

评估世界中任意坐标，独立于玩家。

// 获取特定 X、Y、Z 坐标的完整位置数据（地区、分区、街道名、交叉路口、类型、越野/室内、距离、坐标）
let locData = streetSys.GetLocationAtPosition(targetPos);

// 仅获取坐标处的街道名称
let streetName = streetSys.GetStreetNameAtPosition(targetPos);

// 获取坐标特定半径内的所有街道数组
let nearbyStreets = streetSys.GetNearbyStreets(targetPos, 50.0);

// 检查坐标是否位于模组作者定义的自定义室内
let isCustomIndoor = CustomIndoorZoneManager.IsInCustomZone(targetPos);

3. 反向查找与路径规划

查找夜之城中任何街道或交叉路口的 3D 坐标。

// 1. 查找街道中心或交叉路口的精确碰撞点
// 示例："Bradbury"、"Bradbury Street"或"Pershing & Ross"
let targetPos = streetSys.GetPositionByStreetName("Pershing & Ross");

if targetPos.X != 0.0 {
    // 找到街道或交叉路口！
}

// 2. 查找相对于参考位置在某条街道上的最近点
// 非常适合生成载具或将玩家路由到长高速公路最近入口
let playerPos = GameInstance.GetPlayerSystem(GetGame()).GetLocalPlayerControlledGameObject().GetWorldPosition();
let closestPos = streetSys.GetClosestPositionOnStreet("Pacific Boulevard", playerPos);

4. 调优与配置

动态调整系统性能占用。

streetSys.SetUpdateFrequency(1.0);         // 设置扫描间隔（秒）
streetSys.GetUpdateFrequency();            // 返回 Float

streetSys.SetGlobalRadiusOverride(100.0);  // 覆盖节点搜索半径
streetSys.GetGlobalRadiusOverride();       // 返回 Float

streetSys.PauseTracking();                 // 暂停后台追踪循环
streetSys.ResumeTracking();                // 恢复追踪循环

添加自定义室内区域（TweakXL）

如果你的模组引入了自定义室内空间、玩家住宅或地下区域，你无需编写任何 Redscript 即可向 API 注册它们。

在 r6/tweaks/ 中创建一个 yaml 文件，并定义你的自定义圆柱体：

StreetLogger.UserIndoorZones:
  zones:
    # 格式："ZoneName|X|Y|Z|Radius|HeightTolerance"
    - "SecretBunker|-1550.5|1240.2|15.0|25.0|10.0"

API 将自动识别此空间，并在玩家（或被查询的 Vector4 点）进入时，将 LocationType 切换为 Indoor。

要求与安装

• REDscript
• TweakXL（可选——仅当你想使用 yaml 文件添加自定义室内区域时需要）

安装： 解压压缩包，将 r6 文件夹直接放入你的《赛博朋克 2077》主安装目录，或使用模组管理器。

已知问题与限制

• 手工与自定义街道命名： 原版游戏底层的道路节点和样条数据出了名的不完整和碎片化，且不包含任何街道名称信息。因此，所有街道名称都必须手工映射。在 CDPR 未提供街道标识或既定传说名称的区域，创建了自定义名称以确保地图全覆盖。一些次要道路、高速公路匝道或小巷可能仍未命名，或道路名称存在错误。请报告它们！
• 原版引擎线路错误： 由于基础游戏的空间几何和道路线路偶尔未对齐或存在故障，你在沿特定道路接缝行驶时，可能会遇到街道名称短暂偏离目标的情况。
• 室内检测边缘情况： 虽然比原版 IsEntityInInteriorArea 检查可靠得多，但在一个多层垂直建筑结构的城市中自动检测室内空间相当棘手。该系统依赖自定义白名单和手动排除区域来修补 CDPR 损坏的触发盒，因此在不寻常位置仍可能偶尔出现误报或漏报。请报告它们！

致谢与特别感谢

非常感谢模组社区帮助将此系统变为现实，特别是：

• Coffee2A — 在追踪、映射和建立夜之城街道名称方面提供了巨大帮助。
• Cradilyex — 对游戏文件和车道定义提供了深入的技术见解，并找出了成功将街道名称附加到车道上的巧妙方法。

(他们可能会在路上看到自己的名字。)