内置物理模块

The most commonly used type of body that enables simulation of physical bodies according to rigid body dynamics. Rigid bodies cannot be deformed — their geometry does not change no matter what happens.最常用的物理体类型，可根据刚体动力学模拟物理对象。刚体不可变形——无论发生什么情况其几何形状都不会改变。

注意

A Rigid body must have a Collision shape assigned.刚体必须配置碰撞形状（Collision shape）。

This type of body enables inverse kinematics and procedural animation for bone-animated characters. Essentially, this is a set of Rigid bodies, representing the character's bones connected by joints. These joints restrict the movement of the bones relative to each other, providing a realistic look.这类物理体可为骨骼动画角色实现逆向运动学和程序化动画。本质上是由多个刚体组成的集合，这些刚体通过关节连接形成角色的骨骼结构，关节会限制骨骼间的相对运动以实现逼真效果。

注意

A Ragdoll body can be assigned to Skinned Meshes only.布娃娃体只能分配给蒙皮网格（Skinned Mesh）。

To assign the Ragdoll body to the object, you should create a physical Ragdoll. You can automatically generate it based on the specified parameters or create it manually by preparing a Rigid body for each bone and then saving the bones hierarchy to a *.node file.要为对象添加布娃娃体，需要创建物理布娃娃系统。可根据参数自动生成，也可手动创建——为每块骨骼准备刚体后，将骨骼层级保存为*.node文件。

For proper automatic Ragdoll generation, the mesh should be in the Reference Pose (T-pose for human-like characters).要实现正确的自动布娃娃生成，网格应处于参考姿势（人形角色需保持T-pose）。

It enables real-time persuasive destruction of objects. A Fracture body is procedurally fractured into pieces when it collides with another body. Moreover, you can keep breaking these pieces until achieving the desired level of destruction.支持实时逼真的物体破坏效果。当破碎体与其他物体碰撞时，会按程序分裂成碎片。这些碎片还可继续破碎，直至达到所需的破坏程度。

注意

A Fracture body can be assigned to Dynamic Meshes only.破碎体只能分配给动态网格（Dynamic Mesh）。

The Fracture body (along with all the pieces it fractures into) is, in fact, a Rigid body that moves according to rigid body dynamics. When the body fractures, its mass is distributed among the pieces.破碎体（包括其分裂的所有碎片）本质上是遵循刚体动力学的刚体。当发生破碎时，其质量会分配给各个碎片。

There are three patterns of fracturing: slicing, cracking, and shattering. You should choose the appropriate one depending on the mechanical properties of the material used to create the object.提供三种破碎模式：切片式、裂纹式和粉碎式。应根据物体材质的机械特性选择合适的破碎模式。

The fracture patterns are specified in the code.破碎模式需通过代码指定。

It allows for the physical simulation of ropes, cables, and wires that can be torn. You can pin the ropes to the Rigid, Ragdoll, and Dummy bodies.用于模拟可断裂的绳索、电缆和电线的物理效果。你可以将绳索固定在刚体、布娃娃体和虚拟体上。

注意

A Rope body can be assigned to Dynamic Meshes only. We recommend using a cylinder mesh for the Rope body (for example, it can be a standard primitive cylinder).绳索体只能分配给动态网格（Dynamic Mesh）。建议使用圆柱体网格作为绳索体（例如可以使用标准原始圆柱体）。

To attach a rope to another body, use the Particles joint.要将绳索连接到其他物体，请使用粒子关节（Particles joint）。

It enables physical simulation of different types of textiles that can be torn. You can pin a Cloth body to the Rigid, Ragdoll, and Dummy bodies.用于模拟可撕裂的各种织物物理效果。你可以将布料体固定在刚体、布娃娃体和虚拟体上。

注意

A Cloth body can be assigned to Dynamic Meshes only.布料体只能分配给动态网格（Dynamic Mesh）。

Polygon triangulation of the mesh, for which the Cloth body is generated, should be as illustrated! Otherwise, it may not stretch properly and evenly in all directions.生成布料体的网格多边形三角剖分应该如图所示！否则可能无法在所有方向上正确均匀地拉伸。

An example of proper triangulation正确三角剖分的示例

To pin a cloth to a body so it would hang like a cape or a curtain, use the Particles joint.要将布料固定在物体上使其像披风或窗帘一样悬挂，请使用粒子关节（Particles joint）。

It enables the physical simulation of liquids of different densities and viscosities. It also allows creation of the buoyancy effect and wave dynamics.用于模拟不同密度和粘度的液体物理效果。还可以创建浮力效果和波浪动力学。

注意

A Water body can be assigned only to Water Meshes and Dynamic Meshes.水体只能分配给水面网格（Water Mesh）和动态网格（Dynamic Mesh）。

A mesh to which the Water body is assigned should meet several requirements:分配水体的网格需要满足以下要求：

• The mesh should be flat and have a uniform grid.网格应该是平坦的且具有均匀的网格结构
• The mesh should be oriented strictly along the axes.网格应严格沿轴线方向排列
• The mesh should have the UV map.网格应具有UV贴图

It is a static body that does not move and has no physical properties. It can be used as a prop when connecting other bodies using joints.这是一种静态物体，不会移动且没有物理属性。在使用关节连接其他物体时，可用作支撑物。

For example, by using a Dummy body assigned to a Dummy object, you can fix a physical cloth (a Cloth body) so it can hang without any visible attachments. If the Dummy body does not have any Collision shape assigned, it will not fall or interact with other physical bodies.例如，通过使用分配给虚拟对象（Dummy object）的虚拟体，你可以固定物理布料（布料体），使其无需可见连接点就能悬挂。如果虚拟体没有分配任何碰撞形状，它不会下落或与其他物理体交互。

An invisible Dummy body (with an assigned shape) which is used to attach a cloth body用于连接布料体的不可见虚拟体（带有分配的形状）

It is also a type of body without physical properties: it represents a spline along which an arbitrary rigid body can move. It can be used, for example, to create a physically simulated train moving along a rail track.这也是没有物理属性的物体类型：它代表一个样条曲线，任意刚体都可以沿着它移动。例如可用于创建沿轨道行驶的物理模拟火车。

A Path body which is used as a railway track for a train用作火车轨道的路径体

To connect a Rigid body to a Path body, use a Path joint.要连接刚体到路径体，请使用路径关节（Path joint）。

A sphere is the simplest and the fastest shape, as it has only one parameter — a radius. For this shape type, continuous collision detection is available. So, you can be sure it will not go through other objects, even if it moves at high speed (we will learn about that later).最简单的快速形状，仅需半径一个参数。支持连续碰撞检测，确保即使高速移动也不会穿透其他物体（后续详述）。

Using the spherical shape for any arbitrary mesh ensures collision detection.而且为任意网格使用球体形状可确保碰撞检测。

Dynamic Meshes approximated using spherical shapes使用球体形状近似的动态网格

To make the shape fit your object, you can adjust the sphere Radius:通过调整球体半径（Radius）使形状匹配物体：

A capsule is another fast collision shape with continuous collision detection available. You can use capsule shapes to approximate elongated objects like pillars or even human-like characters. These shapes help the characters go up and down the stairs smoothly, without stumbling at each step, as long as the steps are not too high. Capsule shapes also ensure that the character's arms or legs do not get stuck unexpectedly.另一种支持连续碰撞检测的快速形状。可用于近似柱子或人形角色等细长物体。这类形状能让人物上下楼梯时平稳移动（台阶不过高时），避免四肢意外卡住。

Dynamic Meshes approximated using capsule shapes使用胶囊体形状近似的动态网格

To make the shape fit your object, you can adjust the capsule Radius and Height:通过调整胶囊体半径（Radius）和高度（Height）适配物体：

A cylinder can be used to approximate elongated shapes with flat ends (for example, shafts, or pylons).适用于具有平坦末端的细长物体（如轴体或桥塔）。

Dynamic Meshes approximated using cylindrical shapes使用圆柱体形状近似的动态网格

To make the shape fit your object, you can adjust the cylinder Radius and Height:通过调整圆柱体半径（Radius）和高度（Height）适配物体：

A box is a cuboid shape that can approximate the volume of various objects: walls, doors, stairs, parts of mechanisms, car bodies, and many other things. You can choose the size of a box shape in each dimension arbitrarily.长方体形状，可近似墙体、门体、楼梯、机械部件、车身等多种物体的体积。可自由设置各维度尺寸。

Dynamic Meshes approximated using box shapes使用立方体形状近似的动态网格

To make the shape fit your object, you can adjust the box size (Size X, Size Y, Size Z):通过调整立方体尺寸（Size X, Size Y, Size Z）适配物体：

A convex hull is the slowest of all shapes. Usually, it is used for objects with complex geometry. This shape is the smallest one that can enclose vertices of the approximated mesh. At that, it includes holes and cavities of the mesh in the shape volume.速度最慢的形状，通常用于复杂几何体。这是能包围近似网格顶点的最小形状，会将网格的孔洞和凹陷包含在体积内。

To generate a convex hull, specify the Approximation Error value that allows reducing the number of vertices of the created shape. Note that simple and rough convex hulls with a small number of vertices are processed faster, so we recommend keeping the number of vertices as low as possible.生成凸包时需指定近似误差（Approximation Error）值来减少形状顶点数。注意顶点数少的简单粗糙凸包处理更快，建议尽可能减少顶点数。

The higher the error value, the fewer vertices in the generated shape, but the more mesh details are skipped.误差值越大，生成形状的顶点越少，但会跳过更多网格细节。

Approximation error = 0近似误差 = 0

Approximation error = 0.1近似误差 = 0.1

An autogenerated shape is a set of convex hulls that can approximate a complex concave object and exclude cavities from its volume.自动生成形状是一组凸包的集合，可用于近似复杂的凹面物体并排除其体积中的空腔。

In the picture below, you can see a complex concave object. On the left, it's approximated with a single convex hull. And on the right — with an autogenerated set of convex hulls.在下图中，你可以看到一个复杂的凹面物体。左侧使用单个凸包近似，右侧则使用自动生成的一组凸包近似。

When generating this type of shape, you should specify the following beside the Approximation Error value:生成此类形状时，除近似误差（Approximation Error）值外，还需指定：

• Recursion Depth that sets the degree of mesh decomposition.递归深度（Recursion Depth）：设置网格分解的程度
• Merging Threshold that determines the volume threshold for merging convex shapes after decomposition.合并阈值（Merging Threshold）：决定分解后凸形状合并的体积阈值

The values you specify affect how many shapes are generated and how well they fit the object.你指定的这些值会影响生成形状的数量及其与物体的匹配程度。

A fixed joint connects two bodies in a manner that strictly preserves their positions relative to each other. An example of such a connection in real life is welding or gluing two objects together. 固定关节以严格保持两个物体相对位置的方式连接它们。现实中的焊接或胶合就是这种连接的典型例子。

A hinge joint allows the connected bodies to rotate along the joint's axis at the anchor point. The joint has an angular motor attached. Hinge joints are used for doors and the arms and legs of characters.铰链关节允许连接的物体围绕锚点处的关节轴旋转。该关节附带有角度马达，常用于门的连接以及角色四肢的模拟。

A ball joint provides a point around which the connected objects can rotate. It is similar to the hip joint. You can limit rotation by using the corresponding parameters.球关节提供一个支点让连接物体可以围绕旋转，类似于人体髋关节的结构。你可以通过相应参数来限制旋转范围。

These joints are similar — they both allow movement along the joint axis, which can be used for piston simulation. The cylindrical joint has an additional degree of freedom — rotation around the joint axis. 这两种关节类似：都允许沿关节轴方向移动，可用于活塞模拟。圆柱关节额外具有绕轴旋转的自由度。

Prismatic Joint棱柱关节示意图	Cylindrical Joint圆柱关节示意图

Hinge, Ball, Cylindrical, and Prismatic joints are used to create connections in mechanisms with the specific restrictions of the movement of bodies relative to each other. In addition to these main types of joints, UNIGINE also provides auxiliary ones.铰链、球体、圆柱和棱柱关节用于在机械结构中创建具有特定运动限制的连接。除这些主要关节类型外，UNIGINE还提供辅助关节类型。

These joints are intended to simulate vehicles and the interaction of vehicle wheels with the ground.专为车辆模拟及车轮与地面交互设计。

They both simulate wheel suspension and have angular motors attached. The main difference is that the suspension joint operates with the physical shape of the wheel, which serves for accurate collision detection. While the wheel joint handles a virtual wheel and checks for intersections with the ground via ray-casting. This approach is faster and provides an acceptable result on smooth terrain. In case of a stepped ground surface, it is better to use the suspension joint.两者都模拟车轮悬挂系统并配备角度马达，主要区别在于：悬挂关节处理车轮的物理形状以实现精确碰撞检测，而车轮关节通过射线检测处理虚拟车轮与地面的交互，这种方式速度更快且在平坦地形效果良好。阶梯状地面建议使用悬挂关节。

注意

When creating a wheel or suspension joint, the order of connecting bodies matters: first, you add a joint to the vehicle frame and then specify the wheel to be attached.创建车轮或悬挂关节时，连接顺序很重要：先将关节添加到车架，再指定要连接的车轮。

A Particles joint allows pinning a Cloth or Rope body to a Rigid, Ragdoll, or Dummy body. For example, you can use it to hang a flag or attach a cloth to a character.用于将布料体或绳索体固定到刚体、布娃娃体或虚拟体上。例如可用于悬挂旗帜或将布料附着在角色身上。

A Path joint is used to attach a Rigid body to a Path body and to make the Rigid body move along this path.用于将刚体连接到路径体，并使刚体沿该路径移动。

Physical Wind is a cuboid-shaped object simulating wind blowing within its volume.物理风（Physical Wind）是一个立方体形状的对象，模拟在其体积内吹拂的风。

The wind only affects objects placed inside the Physical Wind box and having physical bodies assigned.风力仅影响放置在物理风框内且分配了物理体的对象。

注意

The Physical Wind can affect only the Cloth and Rigid bodies. At that, the Rigid body must have a collision shape assigned.物理风仅能影响布料体和刚体。其中，刚体必须分配有碰撞形状。

The wind differently affects objects with different physical properties. So, besides changing the Physical Wind parameters, you should adjust the parameters of the physical body.风力对不同物理属性的物体影响不同。因此除了调整物理风参数外，你还需要调整物理体的参数。

For example, if you place an object with the Cloth body inside the Physical Wind volume, the way it "waves in the wind" will vary depending on the Cloth body mass, rigidity, and other parameters.例如，如果在物理风体积内放置一个带有布料体的对象，其"随风飘动"的方式将取决于布料体的质量、刚度等参数。

When you set up the wind, you can change the size of the volume in which the wind blows, specify the wind velocity, attenuation threshold, and damping of the linear and angular velocities of the objects when they get inside the wind volume.设置风力时，你可以更改风吹拂区域的大小，指定风速、衰减阈值，以及物体进入风域时的线速度和角速度阻尼。

You can also choose which physical bodies are affected by the wind. For example, you can make only one flag flutter in the wind while the others stay still. For this purpose, there is the Physical mask — it must match the Physical mask of the physical body affected by the wind.你还可以选择哪些物理体会受到风的影响。例如，可以让一面旗帜在风中飘扬而其他保持静止。为此需要使用物理掩码（Physical mask），它必须与受风影响物理体的物理掩码相匹配。

The Physical Force and Physical Noise are objects for creating force fields.物理力（Physical Force）和物理噪声（Physical Noise）是用于创建力场的对象。

The Physical Force is a spherical object with a force that is applied to its center and attenuates within a specified radius. Objects within the sphere can pull up to or away from the center and rotate around it.物理力是一个球形对象，其施加的力作用于中心并在指定半径内衰减。球体内的物体可以被拉向或推离中心，并围绕其旋转。

Objects are pulled up to the center and rotated around it by the Physical Force物体被物理力拉向中心并围绕其旋转

You can control the attenuation of the force affecting the object that moves away from the force center. In addition, you can adjust the intensity of the attraction and rotation forces that define the speed and direction of rotation.你可以控制物体远离力中心时受力的衰减。此外，可以调整定义旋转速度和方向的吸引力和旋转力强度。

The Physical Noise is a cuboid-shaped area that adds a distribution flow based on a volumetric noise texture. This effect simulates a force field that affects particles and physical bodies.物理噪声（Physical Noise）是一个立方体形状的区域，它基于体积噪声纹理添加分布流。这种效果模拟了影响粒子和物理体的力场。

注意

• Physical Noise affects only the Cloth, Rope, and Rigid bodies. At that, the Rigid body must have a collision shape assigned.物理噪声仅影响布料体、绳索体和刚体。其中刚体必须分配有碰撞形状。
• Physical Noise will affect particles only if their physical mass is non-zero. You can set this in the settings of the Particles object.只有当粒子的物理质量非零时，物理噪声才会影响它们。你可以在粒子对象设置中调整此参数。

The direction of the force affecting particles and physical bodies within the Physical Noise volume is stored in the Noise texture — a 3D texture, where each texel stores the force direction.影响物理噪声体积内粒子和物理体的力的方向存储在噪声纹理（Noise texture）中——这是一个3D纹理，每个纹素存储力的方向。

To be sure that the force at the current point affects the physical body entering the Physical Noise volume according to the Noise texture, you need to provide the texture generation and sampling parameters for the Noise texture, along with the Force multiplier.为确保当前点的力根据噪声纹理影响进入物理噪声体积的物理体，你需要为噪声纹理提供纹理生成和采样参数，以及力乘数（Force）。

The Physical Water is a cuboid-shaped object that allows the simulation of water interaction effects within its volume.物理水（Physical Water）是一个立方体形状的对象，允许模拟其体积内的水体交互效果。

This effect is helpful for the simulation of physical interactions of bodies with the Water Global, as this water object doesn't support the Water body because of large-scale computations. You can use the Physical Water to simulate the floating physical bodies within a certain area.此效果有助于模拟物体与全局水（Water Global）的物理交互，因为水体对象由于大规模计算不支持水物理体（Water body）。你可以使用物理水来模拟特定区域内的浮动物理体。

To add the Physical Water to your scene, select Create → Water → Physical Water in the Menu Bar of UnigineEditor.要向场景添加物理水，在UnigineEditor菜单栏中选择 Create → Water → Physical Water（创建→水体→物理水）。

注意

• The Physical Water can only interact with the Cloth and Rigid bodies. At that, the Rigid body must have a collision shape assigned.物理水仅能与布料体和刚体交互。其中刚体必须分配有碰撞形状。
• Physical Water does not simulate waves.物理水不模拟波浪。

The bodies with different physical properties act differently in the Physical Water. So, besides changing the Physical Water parameters, you should adjust the parameters of the physical body as well.具有不同物理属性的物体在物理水中的表现不同。因此除了调整物理水参数外，你还需要调整物理体的参数。

You can also create additional water effects with Physical Water — for example, foam on the water surface or water splashes — by generating particles in the contacts between the Rigid bodies and Physical Water. Add your Particles object as a child to Physical Water to implement the required effect.你还可以用物理水创建额外水效果：例如水面泡沫或水花——通过在刚体与物理水接触时生成粒子。将你的粒子对象作为子级添加到物理水以实现所需效果。

注意

You cannot generate particles in the contact between the water and the Cloth body since these bodies cannot float in the water.无法在水体与布料体接触时生成粒子，因为这些物体不能浮在水面上。

The Physical Trigger is an effect that fires events when physical objects get inside or outside its volume.物理触发器是一种当物理对象进入或离开其体积范围时触发事件的效果。

The trigger can be of the box, sphere, capsule, or cylinder shape.触发器可以是立方体、球体、胶囊体或圆柱体形状。

To add the Physical Trigger to your scene, select Create → Logic → Physical Trigger in the Menu Bar of UnigineEditor.要向场景添加物理触发器，在UnigineEditor菜单栏中选择Create → Logic → Physical Trigger（创建→逻辑→物理触发器）。

To be detected by the trigger, a physical object must have both:要被触发器检测到，物理对象必须同时具备：

• A physical body with the Physical mask that matches the Physical mask of the trigger.物理掩码（Physical mask）与触发器相匹配的物理体（body）
• A shape with the Collision mask that matches the Collision mask of the trigger.碰撞掩码（Collision mask）与触发器相匹配的碰撞形状（shape）

You can obtain the physical bodies participating in the contact with the Physical Trigger and their collision shapes via API. In addition, you can get values such as the depth of penetration of the body into the trigger, the coordinates of the contact point and the normal to it.你可以通过API获取与物理触发器接触的物理体及其碰撞形状。此外，还可以获取物体穿透触发器的深度、接触点坐标和法线等值。

To define actions to be performed when the body enters and leaves the trigger, do the following:要定义物体进出触发器时执行的操作，请按以下步骤：

1. Create a new PhysicalCatcher component (use the code below).创建一个新的 PhysicalCatcher 组件（使用以下代码）
2. Implement handler functions for the Enter and Leave events receiving a Body as the first argument.实现接收Body作为第一个参数的Enter和Leave事件处理函数
3. In the init() function, get the instance of the Physical Trigger and subscribe for the Enter or Leave event via the connect() method specifying the corresponding implemented handler function.在init() 函数中获取物理触发器实例，并通过connect()方法订阅Enter或Leave事件，指定对应的处理函数

#pragma once
#include <UnigineComponentSystem.h>
#include <UniginePhysicals.h>
#include <UniginePhysics.h>
class PhysicalCatcher :
	public Unigine::ComponentBase
{
public:
	// 组件所绑定的物理触发器
	COMPONENT_DEFINE(PhysicalCatcher, ComponentBase);
	// -------------------------------
	COMPONENT_INIT(init);
	COMPONENT_SHUTDOWN(shutdown);

private:
	// 组件所绑定的物理触发器
	Unigine::PhysicalTriggerPtr physicalTrigger = nullptr;
	// 用于管理事件订阅的辅助变量
	Unigine::EventConnections trigger_event_connections;
	// 进入和离开事件的处理器
	void trigger_enter(const Unigine::Ptr<Unigine::Body>& body);
	void trigger_leave(const Unigine::Ptr<Unigine::Body>& body);

protected:
	// 主循环重写方法
	void init();
	void shutdown();
};

#include "PhysicalCatcher.h"
REGISTER_COMPONENT(PhysicalCatcher);

using namespace Unigine;
using namespace Math;

// 组件初始化方法
void PhysicalCatcher::init()
{
	// 将节点转换为PhysicalTrigger类型
	physicalTrigger = checked_ptr_cast<PhysicalTrigger>(node);

	if (physicalTrigger != nullptr)
	{
		// 订阅进入事件，当物体进入触发器区域时调用对应函数
		physicalTrigger->getEventEnter().connect(trigger_event_connections, this, &PhysicalCatcher::trigger_enter);

		// 订阅离开事件，当物体离开触发器区域时调用对应函数
		physicalTrigger->getEventLeave().connect(trigger_event_connections, this, &PhysicalCatcher::trigger_leave);
	}
}

void PhysicalCatcher::shutdown()
{
	// 移除所有事件订阅
	trigger_event_connections.disconnectAll();
}

// 进入触发器时执行的处理器
void PhysicalCatcher::trigger_enter(const Unigine::Ptr<Unigine::Body>& body)
{
	// ...
}

//  离开触发器时执行的处理器
void PhysicalCatcher::trigger_leave(const Unigine::Ptr<Unigine::Body>& body)
{
	// ...
}

Now, assign the implemented component to the desired Physical Trigger node in UngineEditor.现在，将已实现的组件分配至Unigine编辑器中所需的物理触发器节点。