
引力
Gravitational 是《赛博朋克 2077》中用于构建基于重力的游戏玩法的模组开发者资源。它提供逐 NPC 的重力、速度和旋转控制,以及独立的玩家移动 API。它被设计为其他模组的基础。并非独立的游戏体验。
查看大图[heading]描述[/heading]
Gravitational 为模组作者提供了一个可复用的基础,用于在《赛博朋克 2077》中创建基于重力的能力和移动系统。
其原生 NPC API 可控制单个布娃娃,而无需改变整个世界的重力。你可以悬停角色、施加自定义加速度、将其拉向某一点,或赋予其旋转动量。
独立的玩家 API 通过 V 现有的移动系统暴露重力和移动控制,为飞行及其他移动机制提供基础。
Gravitational 是模组作者的资源。 它不会自动添加能力、飞行控制或完整的游戏系统。那些体验属于构建在其之上的模组。
随附的 CET 面板包含可选的开发测试。这些测试演示了该资源的能力,而非其主要游戏功能。
Gravitational 不依赖 Emoting 或 V Can Fly。其他模组可以依赖 Gravitational;Gravitational 保持独立于它们。
[heading]主要功能[/heading]
[list] []单个 NPC 重力: 影响选定的布娃娃,而不改变世界重力。[/] []自定义重力方向: 向 NPC 施加世界空间加速度向量。[/] []重力缩放: 降低、禁用或反转 NPC 的重力。[/] []受控移动: 指令线性速度或注入旋转速度。[/] []多目标: 支持最多 32 个独立控制的 NPC。[/] []独立的玩家控制: 通过玩家移动控制器调整 V 的重力、请求移动并发射 V。[/] []可续期的控制会话: 短时所有权令牌通过续期支持更长的效果。[/] []清理机制: 显式释放控制或让其租约过期。[/] []随附的 NPC 准备辅助工具: 为符合条件的人类 NPC 准备布娃娃控制并管理恢复。[/] []诊断: 检查可用性、容量和各个控制会话的状态。[/] []可选 CET 测试: 可配置的 NPC 悬浮和玩家悬停演示。[/] [/list]
[heading]前置要求[/heading]
对于当前 0.4.10 包:
[list] []《赛博朋克 2077》2.50,可执行文件 3.0.88.46235[/] []RED4ext[/] []redscript[/] []Cyber Engine Tweaks 用于随附面板和随附的 NPC 标记初始化[/] [/list]
原生插件针对特定游戏版本。在与其他可执行文件版本配合使用前,请检查兼容性。
Emoting、V Can Fly、Codeware 和 TweakXL 并非 Gravitational 本身所需。
[heading]安装说明[/heading]
[list=1] []安装所需框架。[/] []关闭《赛博朋克 2077》。[/] []将压缩包解压到游戏安装文件夹,合并其中的 [code]bin[/code]、 [code]r6[/code] 和 [code]red4ext[/code] 文件夹。[/] []完全重启游戏。[/] []可选:在 CET 中打开 Gravitational 面板以查看其状态并运行开发测试。[/] [/list]
CET 的 Reload all mods 无法加载对原生 DLL 或 redscript 辅助脚本的更改。这些需要完全重启。
模组作者集成指南
[heading]1. 了解三个接口[/heading]
Gravitational 暴露三个独立接口:
[table][tr][th]接口[/th] [th]用途[/th] [th]当前 API 修订版本[/th] [/tr] [tr][td][code]Gravitational[/code][/td] [td]原生 NPC 布娃娃物理[/td] [td]4[/td] [/tr] [tr][td][code]GravitationalNPC[/code][/td] [td]可选的 NPC 准备与恢复[/td] [td]1[/td] [/tr] [tr][td][code]GravitationalPlayer[/code][/td] [td]玩家重力和移动控制[/td] [td]2[/td] [/tr] [/table]
这些 API 修订版本与包版本相互独立。
例如,包 0.4.10 仍包含原生 0.4.0 DLL 和 NPC API 修订版本 4。这是预期情况。
将 Gravitational 声明为你模组的依赖项。调用其已安装的接口;不要分发其类或原生插件的重命名副本。
[heading]2. 检查可用性[/heading]
在 CET Lua 模组中:
[code]local function gravityAvailable() return Gravitational and Gravitational.GetAPIVersion and Gravitational.GetAPIVersion() >= 4 and Gravitational.IsAvailable() end[/code]
对于随附的 NPC 辅助工具,还需检查:
[code]local function npcHelperAvailable() return GravitationalNPC and GravitationalNPC.GetAPIVersion() >= 1 and GravitationalNPC.IsReady() end[/code]
在你的模组初始化之后、开始效果之前调用这些函数。如果任一所需接口不可用,请报告明确的依赖错误。
[code]GravitationalNPC.IsReady()[/code] 检查其控制标记是否存在。随附的 Gravitational CET 组件会初始化该标记。
[heading]3. 准备一个 NPC[/heading]
原生 NPC API 作用于布娃娃身体。对普通的动画 NPC 调用它并不会自动创建合适的布娃娃。
你可以自行管理准备工作,或使用:
[code]local accepted = GravitationalNPC.Begin(player, target)[/code]
随附的辅助工具接受符合条件的活体人类 NPC。它会排除玩家、Boss、MaxTac、车辆乘员、处于工作点中的角色,以及已被控制或已处于布娃娃状态的目标。
被拒绝时,检查:
[code]local reason = GravitationalNPC.GetPreparationError(target)[/code]
准备是异步的。在后续更新中,等待:
[code]GravitationalNPC.IsRagdollReady(target)[/code]
随附客户端在获取控制前至少允许 0.2 秒,并使用准备超时。请遵循类似的有界方法,而不是无限等待。
仅对你自己模组成功开始的准备调用 [code]GravitationalNPC.End(target)[/code]。 不要释放另一个客户端的准备。
[heading]4. 获取原生控制[/heading]
布娃娃就绪后:
[code]local token = Gravitational.Begin(target, 2.0)[/code]
正令牌表示请求已被接受。零表示被拒绝——例如,目标不可用、已被占用或已达到容量上限。
被接受的请求不一定已经激活。轮询:
[code]local state = Gravitational.GetState(token)[/code]
[table][tr][th]状态[/th] [th]含义[/th] [/tr] [tr][td][code]0[/code][/td] [td]获取待处理[/td] [/tr] [tr][td][code]1[/code][/td] [td]激活[/td] [/tr] [tr][td][code]2[/code][/td] [td]已结束[/td] [/tr] [tr][td][code]-1[/code][/td] [td]无效、被拒绝或不再保留[/td] [/tr] [/table]
在施加效果前等待状态为 [code]1[/code]。使用有界的获取超时,如果获取失败则进行清理。
获得令牌后,不要每帧重复调用 [code]Begin[/code]。
[heading]5. 选择移动模式[/heading]
以下示例假设令牌处于激活状态。它们是可替代方案,而不是要一起执行的序列。
保留动量并移除重力
[code]Gravitational.SetGravity( token, Vector4.new(0, 0, 0, 0) )[/code]
这允许现有动量和碰撞继续存在,而不会有重力将 NPC 向下拉。
施加上升加速度
[code]Gravitational.SetGravity( token, Vector4.new(0, 0, 4, 0) )[/code]
这会施加上升加速度 4 m/s²。它是加速度,而不是目标速度。
缩放场景重力
[code]Gravitational.SetGravityScale(token, 0.25)[/code]
示例:
[list] [][code]1.0[/code]:普通场景重力。[/] [][code]0.25[/code]:四分之一重力。[/] [][code]0.0[/code]:零重力。[/] [][code]-1.0[/code]:反转场景重力。[/] [/list]
指令一个速度
[code]Gravitational.SetVelocity( token, Vector4.new(0, 0, 0.6, 0) )[/code]
这请求一个受控的向上速度 0.6 m/s。
添加旋转运动
[code]Gravitational.SetAngularVelocity( token, Vector4.new(0, 0, 0.4, 0) )[/code]
这会注入角速度。请在需要时施加,而不是每帧持续重置旋转。
重要的模式区别
[code]Begin[/code] 以零速度覆盖开始。
[list] [][code]SetVelocity[/code] 启用受控速度。[/] [][code]SetGravity[/code] 和 [code]SetGravityScale[/code] 会禁用该覆盖,允许物理驱动的移动。[/] []零加速度和零速度是不同的效果:一个允许漂移;另一个指令停止。[/] [/list]
如果你想要一个自由漂移的零重力目标,请在获取控制后显式调用 [code]SetGravity[/code] 并传入零向量。
[heading]6. 续期两个控制层[/heading]
使用较短的原生租约,并在效果持续期间续期。典型模式是两秒租约每 0.4 秒续期一次。
如果使用随附的准备辅助工具,也要续期它:
[code]local nativeOK = Gravitational.Renew(token, 2.0) local helperOK = GravitationalNPC.Renew(target)[/code]
跟踪两个结果。如果你的模组无法维持所有权,请结束效果并清理。
原生命令可能返回 [code]false[/code],包括原生命令门控繁忙时。客户端可以在后续更新中重试,同时检查状态和自己的超时;它不能假设每条命令都成功。
长效果应使用重复续期——而不是单个超长租约。
[heading]7. 正确释放[/heading]
对于通过随附辅助工具由你的模组准备的目标:
[code]Gravitational.Release(token) GravitationalNPC.End(target)[/code]
先释放原生控制,然后结束你的准备。
在以下情况下清理:
[list] []效果完成或取消。[/] []获取或续期失败。[/] []目标变得无效。[/] []玩家/会话变更。[/] []你的模组关闭或重新加载。[/] []你的效果应停止的菜单切换。[/] [/list]
原生恢复会针对相关物理更新被请求;它不是立即传送或位置重置。
只释放你自己的令牌。
[code]Gravitational.ReleaseAll()[/code] 也会影响其他客户端,旨在作为管理或紧急操作,而不是正常的逐模组清理。
[heading]NPC API 限制[/heading]
[table][tr][th]操作[/th] [th]当前限制[/th] [/tr] [tr][td]同时的 NPC 目标[/td] [td]32;查询 [code]GetCapacity()[/code][/td] [/tr] [tr][td]受控速度[/td] [td]幅度最高 3 m/s[/td] [/tr] [tr][td]角速度[/td] [td]幅度最高 0.8 rad/s[/td] [/tr] [tr][td]自定义加速度[/td] [td]幅度最高 40 m/s²[/td] [/tr] [tr][td]重力缩放[/td] [td]−4 到 +4[/td] [/tr] [tr][td]单次续期时长[/td] [td]大于 0,最高 10 秒[/td] [/tr] [/table]
向量使用世界坐标。原生 NPC API 会忽略其 W 分量。
一个租约一次拥有一个给定 NPC。对于重叠效果,重用你现有的令牌;不要试图窃取另一个模组的目标。
有用的诊断:
[code]print(Gravitational.GetStatus()) print(Gravitational.GetLeaseStatus(token))[/code]
[heading]8. 控制 V[/heading]
V 使用 [code]GravitationalPlayer[/code],而不是 NPC 布娃娃接口。
该辅助工具通过游戏的玩家移动参数和控制器输入控制 V。它不同于原生 NPC 物理实现。
检查 API 修订版本 2,然后开始:
[code]local player = Game.GetPlayer() local token = GravitationalPlayer.Begin(player, 2.0)[/code]
仅在 [code]token > 0[/code] 时继续。
Begin 请求零重力,但不会自动起飞。要发射:
[code]GravitationalPlayer.Launch(player, token, 5.0)[/code]
在后续更新中,检查:
[code]local state = GravitationalPlayer.GetState(player, token)[/code]
激活后,请求移动:
[code]GravitationalPlayer.SetVelocity( player, token, Vector4.new(0, 0, 1.0, 0) )[/code]
对于起飞,请让发射冲量生效后再指令新速度。V Can Fly 目前使用 0.35 秒的短暂发射间隔。
使用相同的玩家句柄和令牌进行续期和释放:
[code]GravitationalPlayer.Renew(player, token, 2.0)
-- When your effect ends: GravitationalPlayer.Release(player, token)[/code]
其他函数:
[table][tr][th]函数[/th] [th]用途[/th] [/tr] [tr][td][code]GetAPIVersion()[/code][/td] [td]查询玩家 API 修订版本[/td] [/tr] [tr][td][code]IsControlled(player)[/code][/td] [td]检查是否存在有效的玩家控制租约[/td] [/tr] [tr][td][code]IsGrounded(player)[/code][/td] [td]在受控时查询地面接触[/td] [/tr] [tr][td][code]GetFlightInput(player)[/code][/td] [td]读取映射的移动、上升/下降和冲刺输入[/td] [/tr] [tr][td][code]SetGravityScale(player, token, scale)[/code][/td] [td]更改玩家重力缩放并禁用速度覆盖[/td] [/tr] [tr][td][code]Now(player)[/code][/td] [td]读取模拟时间[/td] [/tr] [/table]
[code]GetFlightInput[/code] 返回:
[list] []X:横向移动。[/] []Y:前进/后退移动。[/] []Z:跳跃减去蹲下/切换蹲下。[/] []W:冲刺/切换冲刺。[/] [/list]
玩家速度幅度限制为 6 m/s。发射速度必须大于零且不超过 6 m/s。重力缩放接受 −4 到 +4。
玩家 API 目前不提供任意重力方向。它会缩放现有的上升/下降移动重力。
你的模组仍需负责相机相对转向、平滑、输入策略、飞行时长和着陆决策。V Can Fly 是一个实现这些行为的示例消费者。
[heading]参考实现[/heading]
该包包含:
[list] [][code]examples/suspend.lua[/code]:一个用于已准备布娃娃的最小原生客户端。将其更新和释放函数集成到你自己的生命周期中。[/] []随附的 CET [code]demo.lua[/code]:NPC 准备、获取、续期、目标选择和清理,以及玩家测试。[/] [][code]NPC.reds[/code]:随附的 NPC 准备/恢复辅助工具。[/] [][code]Player.reds[/code]:玩家控制接口和移动集成。[/] [/list]
阅读生命周期代码以及 API 调用。在构建可复用能力时,正确的所有权、续期和清理至关重要。
[heading]当前限制和开发状态[/heading]
Gravitational 仍处于实验阶段,且针对特定游戏版本。
原生 NPC 接口不提供通用车辆重力控制。随附的准备辅助工具故意排除若干特殊 NPC 类别和交互状态。
最新的 NPC 恢复修正和静止玩家悬停调整已通过离线检查,但仍需在游戏内确认。其他移动大修和异常 NPC 状态需要兼容性测试。
将 Gravitational 视为一个用于构建和测试的基础——它并不保证每个目标、动画或游戏情境都会表现一致。
正在加载版本记录…
正在加载评论…
评论在新手盒子客户端中发表,这里同步展示。