[0.6.x + 0.7.0 pre2] 游牧物理

[0.6.x + 0.7.0 pre2] 游牧物理

为Hytale实现真实的刚体物理。道具基于ode4j翻滚、停驻和碰撞;用物理枪可远距离移动、固定和投掷它们,或用重力枪抓取和推动它们。

杂项

每个版本的完整指南、截图和发布说明见 nomad-labs.co/physics。

Bug 反馈与问题咨询:我们的 Discord。

Nomad Physics

Nomad Physics 为 Hytale 道具添加刚体物理。扔下一个板条箱,用物理枪抓住某物并把它扔到房间另一头。道具会下落、滚动并与世界发生碰撞,模拟由服务器上的 ode4j 运行。玩家无需安装单独的客户端模组。

核心包含物理枪、重力枪、一个木制板条箱,以及 Rubber、Steel 和 Slick 演示方块。其他插件可以通过 PhysicsApi 使用同一套物理系统,包括保龄球和 War Games 等内容包。

在 Nomad Arcade 上体验

在 Nomad Arcade 服务器上亲自测试物理系统。加入地址:arcade.nomad-labs.co:5521。

在你的服务器上开始使用

开始使用

将 NomadPhysics-0.1.1.jar 安装到服务器的 mods 文件夹并重启服务器。升级时,请替换之前的 Nomad Physics jar,确保只安装一份。该 jar 已包含其资源文件。在开阔区域以服务器管理员身份运行以下命令:

/physics tool physgun
/physics tool gravgun
/physics demo crates

这些工具没有合成配方。使用 /physics tool physgun --player=PlayerName 或 /physics tool gravgun --player=PlayerName 将工具给予其他玩家。接收者必须与命令处于同一世界。

使用工具

使用工具

以下为默认的鼠标和 Use 键绑定。如果你重新绑定了控制键,请使用对应的主要、次要或 Use 操作。

物理枪

使用物理枪放置和整理道具。它可以搬运重物,不受重力枪的质量限制。

操作 动作
按住左键 抓取准星下的道具,并将其携带到你瞄准的位置。
松开左键 放开道具。
携带时右键 将道具冻结在原地。
未携带任何物品时右键点击已冻结的道具 解冻它。用左键抓取它也会解冻。
携带时按 F 进入旋转模式,然后环顾四周来转动道具。再次按 F 恢复携带。
携带时蹲下并向上或向下看 调整你持有道具的距离。

重力枪

使用重力枪将物体拉近或发射出去。

操作 动作
右键点击道具 将其拉向你并持在你面前。
再次右键 放下持有的道具,或取消进行中的拉取。
左键 踢出你持有或瞄准的道具。

重力枪的射程较短,且有携带质量限制。一个重到无法举起的普通道具仍然可以受到较弱的推击。生物和已注册所有者的目标不受该携带质量检查的限制。

方块模式

装备任意一把枪且未持有任何物品时,按 F 切换方块模式。HUD 会显示是否已开启。在方块模式下,枪可以将允许的方块从世界中拉出,并作为松散道具移动。它们稳定后会重新吸附回方块网格;如果没有合适的空间,则会作为物品掉落。

启用方块模式后,瞄准一个已放置的方块,用物理枪按住左键,或用重力枪右键点击,即可将其拾起。F 切换模式;它本身不会抓取方块。使用物理枪携带时,F 控制旋转。重力枪没有旋转或冻结模式。

拾取方块需要工具的权限以及 nomadphysics.blocks。服务器的 Blocks.AllowTags 和 Blocks.DenyIds 设置决定哪些方块类型可以被拾取。被拒绝的 ID 优先于允许的标签。

Rubber、Steel 和 Slick

三个演示方块都包含在免费核心中。在创造模式目录的 Blocks > Build 下找到它们,或使用服务器现有的 /give <player> <ItemId> 命令,配合下方的 ID。给予物品使用服务器的常规命令权限;它不会授予使用物理枪的权限。

物品 物品 ID 松散时的行为
Rubber Block Nomad_Demo_Rubber 哑光红色橡胶,带圆角。在坚固地形上弹跳,每次弹跳高度递减直至停止。
Steel Weight Nomad_Demo_Steel 质量是普通方块的四倍,因此相同冲量对它的移动更小。适合撞倒松散堆叠。
Slick Block Nomad_Demo_Slick 较低的摩擦力使它比普通松散方块滑得更远。放置后,玩家会像在冰上一样在其上滑动。

像普通方块一样放置一个,启用方块模式,然后使用上述控制将其抓取。每个方块独立移动。用物理枪松开左键将其放下,或用重力枪左键将其扔出。要冻结一个,用物理枪携带它并右键;未持有任何物品时,右键点击已冻结的方块将其解冻。让它稳定回网格,然后再次拾取:它的材质行为在每次拾取时都会恢复。破坏它会返还其自身的物品以供重新放置。

演示方块使用常规的 Furniture 拾取标签,因此它们可与默认允许列表配合使用。管理员限制仍然适用。Rubber 的弹跳和 Steel 的额外质量在松散时生效;Slick 在放置时也使用原版冰的玩家移动设置。Steel 遵循与普通方块相同的重力,且 Rubber 不是玩家蹦床。

哪些对象支持物理?

对象 预期表现
物理道具 两把枪都可以移动它们。物理枪可以冻结和旋转它们。
世界方块 在世界中保持不变,直到在方块模式下被拾取。只有被允许的方块类型可以被移除。
生物和动物 在启用生物处理时可以被拾取。它们的 AI 在受物理控制时暂停,释放后恢复。如果启用了生物伤害,硬着陆可能会伤害它们。
水中的道具 配置了浮力密度的刚体可以漂浮。没有浮力的刚体会下沉。
其他模组的实体 其模组必须注册集成,枪才能接管控制。Nomad Longships 就是一个例子;其集成决定哪些船体可以被拾取。

如果你最喜欢的模组对象在启用此功能后出现异常,请告诉我,我会尽力解决。也请将其作者指向下方的集成说明。

权限与配置

服务器设置

为玩家授予你希望他们使用的工具和操作的权限:

默认权限 允许
nomadphysics.physgun 使用物理枪。
nomadphysics.gravitygun 使用重力枪。
nomadphysics.blocks 使用任一工具拾取世界方块。还需要工具自身的权限。
nomadphysics.admin 通过 /physics tool 上的额外权限检查来分发工具。

这些节点是可配置的。它们与服务器的命令权限分开,因此请通过常规权限设置保持管理命令受限。

插件在首次启动时会在其数据目录中创建 config.json。编辑前请停止服务器,然后重启以加载更改。

配置部分 你可以更改的内容
Physgun 射程、最小和最大携带距离、距离调整以及权限节点。
GravityGun 射程、携带距离、MassCap、PuntSpeed、对重物的较弱推击以及权限节点。
Blocks 允许的标签、拒绝的方块 ID、基础质量、每名玩家的空中方块限制以及权限节点。Steel Weight 使用基础质量的四倍。
Creatures 启用或禁用生物拾取、调整其限制,以及通过 Damage 开启或关闭着陆伤害。
Impact 道具击中玩家造成的伤害和击退。将 Enabled 设为 false 以禁用该冲击处理。
Diagnostics 调查问题时将此顶级标志设为 true。默认关闭。

实用管理员命令

命令 用途
/physics status 显示当前世界的物理状态。
/physics stats 检查刚体数量、模拟开销和接触。
/physics holds 列出活动持有和已冻结的道具。
/physics unfreeze all 解冻当前世界中所有被工具冻结的道具。
/physics unfreeze PlayerName 解冻该玩家冻结的道具,该玩家必须在当前世界在线。
/physics blocks 检查方块允许列表和空中方块。
/physics creatures 检查生物设置和活动生物领养。
/physics owners 列出已注册的模组集成及其领养的实体。
/physics joints 列出当前世界的关节。
/physics clear 清除世界的物理模拟,包括内容包创建的道具。用于重置测试区域,不要作为活跃游戏中的常规清理命令。

致模组作者:使用 PhysicsApi

Physics API

Java API 面向服务器插件。服务器所有者无需编写代码即可使用上述工具和命令。

添加依赖

针对 NomadPhysics-0.1.1.jar 中的核心和插件 API 进行编译。对于 Gradle Kotlin 构建,将 jar 放入项目的 libs 目录并添加:

dependencies {
    compileOnly(files("libs/NomadPhysics-0.1.1.jar"))
}

将此依赖条目添加到你的插件的 manifest.json:

{
  "Dependencies": {
    "co.nomadlabs:NomadPhysics": "*"
  }
}

在服务器上将 Nomad Physics 与你的插件一同安装。保持依赖为 compileOnly;将物理类的另一份副本打包进你的 jar 可能会使你的插件获得一个独立的 API 持有者。

生成、移动和移除道具

为你要使用的世界创建一个 PhysicsExample,然后在已加载区域中使用刚体中心位置调用 spawn。此示例将原版 Minecart 模型生成为物理道具,并沿世界的 X 轴推动它。当你的功能使用完毕时,在该世界仍在运行时调用 clear。

import co.nomadlabs.physics.Quat;
import co.nomadlabs.physics.Vec3;
import co.nomadlabs.physics.plugin.api.BodyHandle;
import co.nomadlabs.physics.plugin.api.PhysicsApi;
import com.hypixel.hytale.server.core.universe.world.World;

public final class PhysicsExample {
    private final World world;
    private BodyHandle prop;

    public PhysicsExample(World world) {
        this.world = world;
    }

    public void spawn(Vec3 centre) {
        world.execute(() -> {
            PhysicsApi physics = PhysicsApi.get();
            if (physics == null || prop != null) return;

            prop = physics.spawnBody(world, "Minecart", centre, Quat.IDENTITY);
            if (prop != null) {
                physics.applyImpulse(prop, new Vec3(8, 0, 0), centre);
            }
        });
    }

    public void clear() {
        world.execute(() -> {
            PhysicsApi physics = PhysicsApi.get();
            if (physics != null && prop != null) physics.removeBody(prop);
            prop = null;
        });
    }
}

PhysicsApi.get() 在初始化前和关闭后返回 null。当模型未知、目标区块未加载或世界达到其刚体上限时,spawnBody 可能返回 null。使用 bodyCap() 查询上限,而不是硬编码。

在所属世界的线程上运行模拟调用。 world.execute(...) 将工作调度到那里。接触、冲击和领养回调已在该线程上运行;保持它们简短并避免阻塞式 I/O。冲量使用 kg·m/s,作用点使用世界坐标。在依赖存储的句柄之前检查 bodyState(handle):该刚体消失后它会返回 null。

更多 API 功能

API 用途
spawnBody(..., BodySpec) 选择质量、浮力、滚动阻力和其他刚体设置。
bodyState、entityOf、bodyOf 读取刚体状态或查找物理刚体与其实体之间的关联。
spawnBlockBody 生成一个松散方块,稳定后吸附回世界。其刚体句柄在此时失效。
addContactListener / removeContactListener 接收刚体接触事件。注册一次,并在移除时保留同一监听器对象。
addImpactListener / removeImpactListener 单独于刚体接触接收玩家冲击事件。
addHinge、addSlider、addBall 将刚体彼此连接或连接到世界。保留返回的关节句柄,并用 removeJoint 释放它。
adopt / release 临时将现有实体的物理控制权交出,然后归还。
registerAdoptable / unregisterAdoptable 让物理枪识别并拾取你的模组拥有的实体。
registerLiftOwner / unregisterLiftOwner 让携带操作通过你的模组选择的刚体移动多部件对象。
registerMachine 注册一个可由内容包物品放置和拾取的机器。

当你的集成关闭时,移除你的监听器和注册。当你的功能不再需要生成的刚体时,移除它们。对于领养的实体,使用 release 以便其所有者重新获得控制权。

让你的实体与枪配合工作

实现 AdoptableOwner,并在你的插件的 start() 中使用 NomadPhysicsPlugin.registerAdoptable("yourgroup:YourPlugin", owner) 注册它。此注册是线程安全的,可以在世界存在之前发生。当你的插件关闭时,使用相同的 ID 配合 unregisterAdoptable。

回调 你的模组的职责
claims(store, entity) 返回这是否是你的实体之一。保持此检查廉价。
describe(store, entity) 返回带有其形状和设置的 AdoptRequest,或返回 null 以拒绝拾取,例如当它被占用或锁定时。
onAdopt(store, entity) 为此实体暂停你自己的移动或 AI。返回 false 以取消领养。
onRelease(store, entity, finalPose, reason) 从最终姿态恢复你自己的行为。使用此处提供的实体引用;缓存的引用可能已被替换。

AdoptRequest 包含一个 AdoptShape 和一个 AdoptOptions。形状描述以方块为单位的正盒半尺寸,以及盒中心相对于实体原点在实体局部坐标中的偏移。选项设置质量、浮力、客户端碰撞、返回已稳定实体的阈值、摩擦和恢复系数。原有的五参数 AdoptOptions 构造函数仍然可用,摩擦为 0.8,恢复系数为 0。finalPose 是刚体的中心和朝向;实体原点是 finalPose.centre().minus(finalPose.rotation().rotate(pivotOffset))。

释放原因有 REST、OWNER_RECALLED、ENTITY_GONE 和 WORLD_CLOSED。释放回调只触发一次。对于 ENTITY_GONE,实体引用可能已失效,因此在访问组件之前检查它。

如果物理支持对你的模组是可选的,请通过已安装的物理插件的类加载器加载其类,并使用反射代理实现 AdoptableOwner。对直接导入的 PhysicsApi 进行空检查并不能消除 jar 依赖。NomadPhysicsPlugin 上的静态注册方法也可用于该可选集成路径。

更新日志

0.1.1

向免费核心添加了三个可放置的演示方块:

  • Rubber Block: 哑光红色橡胶,带圆角,弹跳高度递减直至稳定。调校为强反弹,同时保持抓地力。
  • Steel Weight: 质量是普通方块的四倍,对松散道具的撞击更重。
  • Slick Block: 松散时滑得更远,放置后为玩家提供类似冰的滑动表面。

在创造模式目录的 Blocks > Build 下找到它们,或使用 /give <player> Nomad_Demo_Rubber、Nomad_Demo_Steel 或 Nomad_Demo_Slick。两把物理枪都可以在方块模式下拾取它们。每个方块在稳定并再次拾取后都会保持其材质行为。

更新了演示模型、纹理和物品栏图标。澄清了工具指南:未持有任何物品时 F 切换方块模式;常规抓取输入拾取方块,物理枪处理冻结和旋转。插件作者现在可以通过 AdoptOptions 设置摩擦和恢复系数;现有的五参数构造函数保持兼容。

0.1.0

首个版本:刚体、地形和模型形状碰撞、关节、物理枪和重力枪,以及其他插件可用的 PhysicsApi。包含一个带物品栏图标的可放置板条箱。内容包可以通过 PhysicsApi.registerMachine 将机器注册为可放置物品:看向一个方块即可放置,然后潜行 + F 拾取。每世界的方块和速度预算限制堆叠造成的负载。除非在配置中启用 Diagnostics,否则诊断日志关闭。

基于 Nomad Physics 的内容包

核心免费且将保持免费。游戏作为独立内容包在其之上运行,在我们的网站上出售:

  • Nomad Physics: Bowling — 现已推出。完整的球道,具有真实的十瓶计分、回球和摆瓶,适用于任何运行此核心的服务器。在 nomad-labs.co/bowling 获取。
  • Playground 和 War Games — 即将推出。关注 nomad-labs.co/products 或 Discord 的发布通知。

每个内容包都需要安装此核心,因此请保持更新:nomad-labs.co/physics 始终显示当前版本。

更多来自 Nomad Labs