xiaokun/netease-modsdk-wiki
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
1d963e83079d80a7833fdb2ed511009c93316eaa
netease-modsdk-wiki/docs/mcdocs/1-ModAPI/接口/物理.md
小坤 1d963e8307
Some checks failed
Deploy VitePress to AliYun OSS / build-and-deploy (push) Has been cancelled
Details
补充3.7版本文档：物理系统API/事件/枚举值、游戏设置事件、物品ID变更、物理使用指南
2026-03-02 00:17:03 +08:00

13 KiB
Raw Blame History

sidebarDepth
sidebarDepth
1

物理

索引

接口
描述
AddBoxGeometry 服务端 给自定义刚体创建盒形碰撞体
AddForce 服务端 对自定义刚体的质心添加力，对运动学刚体无效
CreatePxActor 服务端 给实体创建自定义刚体
GetQuaternion 服务端 客户端 获取自定义刚体的四元数旋转
Raycast 服务端 客户端 射线检测，获取与射线相交的碰撞体。目前仅支持获取自定义刚体
SetActorFlag 服务端 设置物理实体的行为开关
SetGlobalPose 服务端 设置自定义刚体的变换（直接瞬移）
SetKinematicTarget 服务端 设置运动学刚体的目标变换，仅对开启了PxRigidBodyFlag.eKINEMATIC的自定义刚体生效
SetRigidBodyFlag 服务端 设置自定义刚体的行为开关
SetRigidDynamicLockFlags 服务端 设置自定义刚体的约束

AddBoxGeometry

服务端

method in mod.server.component.physxCompServer.PhysxComponentServer

  • 描述

    给自定义刚体创建盒形碰撞体

  • 参数

    参数名
    数据类型
    		 说明
    localTransform tuple(float,float,float) 盒子中心相对实体原点的偏移
    halfX float 表示盒子长度的一半
    halfY float 表示盒子高度的一半
    halfZ float 表示盒子宽度的一半
    staticFriction float 静摩擦系数
    dynamicFriction float 动摩擦系数
    restitution float 弹性恢复系数，范围：[0, 1]
    eventMask int PxEventMask枚举，用于监听碰撞事件，默认为PxEventMask.Null，即不需要碰撞事件
    userData None或str 可记录自定义数据，长度不超过20，默认为None

  • 返回值

    数据类型
    		 说明
    bool 是否成功

  • 备注

    • 目前只能在AddEntityServerEvent事件中使用，不存档
    • 世界中同时存在的碰撞体上限为8192个

  • 示例

import mod.server.extraServerApi as serverApi
comp = serverApi.GetEngineCompFactory().CreatePhysx(entityId)
comp.AddBoxGeometry((0, 0.9, 0), 0.3, 0.9, 0.3, 0.05, 0.05, 0)

AddForce

服务端

method in mod.server.component.physxCompServer.PhysxComponentServer

  • 描述

    对自定义刚体的质心添加力，对运动学刚体无效

  • 参数

    参数名
    数据类型
    		 说明
    dir tuple(float,float,float) 在全局坐标系中定义的力/冲量
    mode int PxForceMode枚举，施加力/冲量时使用的模式

  • 返回值

    数据类型
    		 说明
    bool 是否成功

  • 示例

import mod.server.extraServerApi as serverApi
from common.minecraftEnum import PxForceMode
comp = serverApi.GetEngineCompFactory().CreatePhysx(entityId)
# 添加一个向上的速度
comp.AddForce((0,1,0), PxForceMode.eVELOCITY_CHANGE)

CreatePxActor

服务端

method in mod.server.component.physxCompServer.PhysxComponentServer

  • 描述

    给实体创建自定义刚体

  • 参数

    无

  • 返回值

    数据类型
    		 说明
    bool 是否成功

  • 备注

    • 只能在AddEntityServerEvent事件中使用，不存档
    • 只能对自定义生物使用，不支持玩家与原版实体。自定义生物需移除minecraft:physics等原生物理组件，并且使用SetBlockControlAi关闭ai

  • 示例

import mod.server.extraServerApi as serverApi
comp = serverApi.GetEngineCompFactory().CreatePhysx(entityId)
comp.CreatePxActor()

GetQuaternion

服务端 客户端

服务端接口

method in mod.server.component.physxCompServer.PhysxComponentServer

  • 描述

    获取自定义刚体的四元数旋转

  • 参数

    无

  • 返回值

    数据类型
    		 说明
    tuple(float,float,float,float) 四元数

  • 备注

    非自定义刚体返回(0,0,0,1)

  • 示例

import mod.server.extraServerApi as serverApi
comp = serverApi.GetEngineCompFactory().CreatePhysx(entityId)
print comp.GetQuaternion()

客户端接口

method in mod.client.component.physxCompClient.PhysxComponentClient

  • 描述

    获取自定义刚体的四元数旋转

  • 参数

    无

  • 返回值

    数据类型
    		 说明
    tuple(float,float,float,float) 四元数

  • 备注

    非自定义刚体返回(0,0,0,1)

  • 示例

import mod.client.extraClientApi as clientApi
comp = clientApi.GetEngineCompFactory().CreatePhysx(entityId)
print comp.GetQuaternion()

Raycast

服务端 客户端

服务端接口

method in mod.server.component.physxCompServer.PhysxComponentServer

  • 描述

    射线检测，获取与射线相交的碰撞体。目前仅支持获取自定义刚体

  • 参数

    参数名
    数据类型
    		 说明
    dimensionId int 维度id
    origin tuple(float,float,float) 射线的起点
    dir tuple(float,float,float) 射线的方向
    maxDist float 射线的最大长度，最大128
    maxHits int 获取射线相交的前N个碰撞体，最大为16，默认为1

  • 返回值

    数据类型
    		 说明
    list(dict) 返回相交的碰撞体的信息。每个元素的内容见备注

  • 备注

    返回列表的每个元素为一个dict，内容如下：

    {
    "entityId": str,                # 碰撞体所属的实体id
    "userData": str或None,          # 碰撞体的userData
    "pos": (float,float,float),     # 相交的位置
    "normal": (float,float,float),  # 碰撞体在相交位置的法线
    "dist": float,                  # 射线起点与相交点的距离
}

  • 示例

import mod.server.extraServerApi as serverApi
comp = serverApi.GetEngineCompFactory().CreatePhysx(levelId)
print comp.Raycast(0, (0,80,0), (0,1,0), 5)

客户端接口

method in mod.client.component.physxCompClient.PhysxComponentClient

  • 描述

    射线检测，获取与射线相交的碰撞体。目前仅支持获取自定义刚体

  • 参数

    参数名
    数据类型
    		 说明
    origin tuple(float,float,float) 射线的起点
    dir tuple(float,float,float) 射线的方向
    maxDist float 射线的最大长度，最大128
    maxHits int 获取射线相交的前N个碰撞体，最大为16，默认为1

  • 返回值

    数据类型
    		 说明
    list(dict) 按顺序返回相交的碰撞体的信息。每个元素的内容见备注

  • 备注

    返回列表的每个元素为一个dict，内容如下：

    {
    "entityId": str,                # 碰撞体所属的实体id
    "userData": str或None,          # 碰撞体的userData
    "pos": (float,float,float),     # 相交的位置
    "normal": (float,float,float),  # 碰撞体在相交位置的法线
    "dist": float,                  # 射线起点与相交点的距离
}

  • 示例

import mod.client.extraClientApi as clientApi
comp = clientApi.GetEngineCompFactory().CreatePhysx(levelId)
print comp.Raycast((0,80,0), (0,1,0), 5)

SetActorFlag

服务端

method in mod.server.component.physxCompServer.PhysxComponentServer

  • 描述

    设置物理实体的行为开关

  • 参数

    参数名
    数据类型
    		 说明
    flag int PxActorFlag枚举

  • 返回值

    数据类型
    		 说明
    bool 是否成功

  • 示例

import mod.server.extraServerApi as serverApi
from common.minecraftEnum import PxActorFlag
comp = serverApi.GetEngineCompFactory().CreatePhysx(entityId)
# 不受重力
comp.SetActorFlag(PxActorFlag.eDISABLE_GRAVITY, True)

SetGlobalPose

服务端

method in mod.server.component.physxCompServer.PhysxComponentServer

  • 描述

    设置自定义刚体的变换（直接瞬移）

  • 参数

    参数名
    数据类型
    		 说明
    pos tuple(float,float,float)或None 目标位置，None表示位置不变
    rot tuple(float,float,float,float)或None 目标旋转，用四元数表示，None表示旋转不变

  • 返回值

    数据类型
    		 说明
    bool 是否成功

  • 示例

import mod.server.extraServerApi as serverApi
comp = serverApi.GetEngineCompFactory().CreatePhysx(entityId)
# 瞬移到0,80,0，旋转不变
comp.SetGlobalPose((0,80,0), None)

SetKinematicTarget

服务端

method in mod.server.component.physxCompServer.PhysxComponentServer

  • 描述

    设置运动学刚体的目标变换，仅对开启了PxRigidBodyFlag.eKINEMATIC的自定义刚体生效

  • 参数

    参数名
    数据类型
    		 说明
    pos tuple(float,float,float)或None 目标位置，None表示位置不变
    rot tuple(float,float,float,float)或None 目标旋转，用四元数表示，None表示旋转不变

  • 返回值

    数据类型
    		 说明
    bool 是否成功

  • 示例

import mod.server.extraServerApi as serverApi
comp = serverApi.GetEngineCompFactory().CreatePhysx(entityId)
# 位置移动到0,80,0，旋转不变
comp.SetKinematicTarget((0,80,0), None)

SetRigidBodyFlag

服务端

method in mod.server.component.physxCompServer.PhysxComponentServer

  • 描述

    设置自定义刚体的行为开关

  • 参数

    参数名
    数据类型
    		 说明
    flag int PxRigidBodyFlag枚举
    val bool 开关

  • 返回值

    数据类型
    		 说明
    bool 是否成功

  • 示例

import mod.server.extraServerApi as serverApi
from common.minecraftEnum import PxRigidBodyFlag
comp = serverApi.GetEngineCompFactory().CreatePhysx(entityId)
comp.SetRigidBodyFlag(PxRigidBodyFlag.eKINEMATIC, True) # 设置为运动学刚体

SetRigidDynamicLockFlags

服务端

method in mod.server.component.physxCompServer.PhysxComponentServer

  • 描述

    设置自定义刚体的约束

  • 参数

    参数名
    数据类型
    		 说明
    flag int PxRigidDynamicLockFlag枚举

  • 返回值

    数据类型
    		 说明
    bool 是否成功

  • 示例

import mod.server.extraServerApi as serverApi
from common.minecraftEnum import PxRigidDynamicLockFlag
comp = serverApi.GetEngineCompFactory().CreatePhysx(entityId)
# 锁定xyz轴旋转
comp.SetRigidDynamicLockFlags(PxRigidDynamicLockFlag.eLOCK_ANGULAR_X | PxRigidDynamicLockFlag.eLOCK_ANGULAR_Y | PxRigidDynamicLockFlag.eLOCK_ANGULAR_Z)