⛓️ Cable

缆绳（Cable）代表一种物理约束，它将两个 Actor 连接起来，并在它们之间提供类似绳索的视觉表现。

Server Only🔁Not Distributable🧑‍💻API Source

👪Inheritance

This class shares methods and events from Base Entity, Base Actor, Base Paintable.

---

nanos world Cables are composed primarily of two Unreal Engine components: a Cable and a PhysicsConstraint. 前者仅用于视觉呈现，后者则向 Cable 的两端施加实际的物理效果。

信息

Cable 的视觉效果可以通过 :SetForces()、:SetCableSettings() 和 :SetRenderingSettings() 方法进行调整。这些方法对施加的物理没有影响，仅对视觉表现生效。

Cable 的物理效果可以通过 :SetAngularLimits() 和 :SetLinearLimits() 进行调整。

在连接 Cable 的两端后，可以调整物理设置，以改变该约束对物体的作用方式。

提示

当其中一边断开连接时，Cable 会自动被销毁

🎒 示例

Server/Index.lua

local my_cable = Cable(Vector())
local cube_01 = Prop(Vector(100, 100, 100), Rotator(), "nanos-world::SM_Cube")
local cube_02 = Prop(Vector(200, 0, 100), Rotator(), "nanos-world::SM_Cube")

my_cable:AttachStartTo(cube_01)
my_cable:AttachEndTo(cube_02)

🛠 构造函数

Default Constructor

No description provided

local my_cable = Cable(location, enable_visuals?, spawn_mode?)

Parameters

Type	Name	Default	Description
Vector	location	Required parameter	生成的世界坐标位置
boolean	enable_visuals	true	切换缆绳视觉效果的开关
SpawnMode	spawn_mode	SpawnMode.Immediate	传入 SpawnMode.AfterConstructor 或 SpawnMode.Manual 可避免立即将实体发送至客户端，在需要配置多项设置时使用此选项可提升性能。最后必须调用 FinishSpawn()

🗿 静态函数

Inherited Entity Static Functions

Cable inherits from Base Entity Class, sharing it's methods and functions:
Base Entityscripting-reference/classes/base-classes/entity

	Returns	Name	Description
	table of Base Entity	GetAll	返回一个包含调用此方法的类中所有实体的表
	Base Entity	GetByIndex	返回该类中指定索引处的特定实体
	integer	GetCount	返回该类当前存在的实体数量
	table of table	GetInheritedClasses	获取使用 继承系统 创建的、直接继承自该类的所有子类列表
	iterator	GetPairs	返回一个包含该类所有实体的迭代器，用于 pairs() 循环
	table or nil	GetParentClass	如果该类是使用 继承系统 创建的，则获取其父类
	table	Inherit	使用 继承系统 继承此类
	boolean	IsChildOf	如果该类是使用 继承系统 创建的，检查此类是否为另一个类的子类
	function	Subscribe	为该类的所有实体订阅一个 事件
	function	SubscribeRemote	订阅从服务器调用的自定义远程事件
		Unsubscribe	退订此包内该类中此 事件 的所有回调，或者仅取消传入的特定回调

This class doesn't have own static functions.

🦠 函数

Inherited Entity Functions

Cable inherits from Base Entity Class, sharing it's methods and functions:
Base Entityscripting-reference/classes/base-classes/entity

	Returns	Name	Description
		BroadcastRemoteEvent	直接在此实体上向所有玩家调用自定义远程事件
		BroadcastRemoteInRadiusEvent	直接针对此实体调用自定义远程事件，并将该事件传递给半径范围内的所有玩家
		CallRemoteEvent	直接在此实体上向特定玩家调用自定义远程事件
		CallRemoteEvent	直接在此实体上调用自定义远程事件
		CallRemotePlayersEvent	直接在此实体上调用自定义远程事件，并将事件传递给玩家列表
		Destroy	销毁该实体
		FinishSpawn	如果此实体是以延迟 spawn_mode 生成的，则完成生成过程并将该实体发送至客户端
	table of string	GetAllValuesKeys	获取所有存储值的键名列表
	table	GetClass	获取该实体的类
	integer	GetID	获取该实体的全网通用网络 ID（在客户端和服务器上相同）
	any	GetValue	获取此实体上存储在给定键处的 值
	boolean	HasAuthority	获取本地上下文是否对此实体拥有主控（如果由客户端生成则为 true，由服务器生成则为 false）
	boolean	IsA	递归检查此实体是否继承自某个类
	boolean	IsBeingDestroyed	如果该实体正在被销毁，则返回 true
	boolean	IsSpawned	获取此实体是否已完成生成
	boolean	IsValid	如果该实体有效（即未被销毁且指向一个有效的实体），则返回 true
		SetSpawnMode	从继承类的构造函数中覆盖此实体完成生成的时间点
		SetValue	在此实体中设置一个值
	function	Subscribe	在这个特定实体上订阅一个事件
	function	SubscribeRemote	在这个特定实体上订阅一个从服务器调用的自定义远程事件
		Unsubscribe	退订此包内该实体中此 事件 的所有回调，或者仅取消传入的特定回调

Inherited Actor Functions

Cable inherits from Base Actor Class, sharing it's methods and functions:
Base Actorscripting-reference/classes/base-classes/actor

	Returns	Name	Description
		AddActorTag	向该 Actor 添加一个虚幻 Actor 标签
		AddAngularImpulse	向该 Actor 添加角冲量。适用于单次瞬间爆发
		AddImpulse	向该 Actor 添加冲量。适用于单次瞬间爆发
	boolean	AttachTo	将该 Actor 附加到任何其他 Actor 上，可选择附加在特定骨骼处
		Detach	将该 Actor 从其附加的 Actor 上分离
	table of string	GetActorTags	获取该 Actor 上的所有虚幻 Actor 标签
	Vector	GetAngularForce	获取该 Actor 的角外力（由 SetAngularForce() 设置）
	float	GetAngularVelocity	返回此 Actor 的角速度
	table of Base Actor	GetAttachedEntities	获取附加到该 Actor 的所有 Actor
	Base Actor or nil	GetAttachedTo	获取该 Actor 所附加到的父级 Actor
	string	GetAttachedToSocket	获取此 Actor 所附加到的骨骼或插槽名称
	table	GetBounds	获取此 Actor 的包围盒，便于计算其在世界中的尺寸
	CollisionType	GetCollision	获取该 Actor 的碰撞类型
	integer	GetDimension	获取该 Actor 的维度
	float	GetDistanceFromCamera	获取该 Actor 距离相机的距离
	Vector	GetForce	获取该 Actor 的持续外力（由 SetForce() 设置）
	float	GetLifeSpan	获取此 Actor 被销毁前剩余的时间（秒）
	Vector	GetLocation	获取该 Actor 在游戏世界中的位置
	float	GetMass	返回此 Actor 的质量
	Player or nil	GetNetworkAuthority	获取该 Actor 的网络主控玩家
	Vector	GetRelativeLocation	如果该 Actor 已附加，获取其相对位置
	Rotator	GetRelativeRotation	如果该 Actor 已附加，获取其相对旋转
	Rotator	GetRotation	获取该 Actor 在游戏世界中的角度值
	Vector	GetScale	获取该 Actor 的缩放比例
	float	GetScreenPercentage	获取该 Actor 在屏幕中所占尺寸的百分比
	table	GetSocketTransform	在给定骨骼或插槽名称的情况下，获取世界空间中的插槽变换
	Vector	GetVelocity	获取该 Actor 当前的速度
	boolean	HasNetworkAuthority	如果本地玩家当前是该 Actor 的网络主控（Network Authority），则返回 true
	boolean	IsGravityEnabled	如果该 Actor 启用了重力，则返回 true
	boolean	IsInWater	如果该 Actor 处于水中，则返回 true
	boolean	IsNetworkDistributed	如果该 Actor 当前处于网络分配状态，则返回 true
	boolean	IsVisible	如果该 Actor 可见，则返回 true
		RemoveActorTag	从该 Actor 中移除一个虚幻 Actor 标签
		RotateTo	在一定时间内平滑旋转该 Actor 到指定角度
		SetAngularForce	向该 Actor 添加一个永久的角外力，设为 Vector(0, 0, 0) 可以取消
		SetCastShadow	设置该 Actor 是否投射阴影
		SetCollision	设置该 Actor 的碰撞类型
		SetDimension	设置此 Actor 的维度。Actor 仅能看见并与处于同一维度中的实体进行交互
		SetDistanceOptimizationMultiplier	设置此 Actor 的距离优化系数
		SetForce	向该 Actor 添加一个永久的外力，设为 Vector(0, 0, 0) 可以取消
		SetGravityEnabled	设置该 Actor 是否启用重力
		SetHighlightEnabled	设置该 Actor 是否启用高亮显示，以及使用哪个高亮索引值
		SetLifeSpan	设置该 Actor 被销毁前的生存时间（秒）。经过这段时间后，Actor 将被自动销毁。
		SetLocation	设置该 Actor 在游戏世界中的位置
		SetNetworkAuthority	设置某个玩家拥有此 Actor 的网络主控
		SetNetworkAuthorityAutoDistributed	设置该 Actor 是否在玩家之间自动分配网络主控
		SetOutlineEnabled	设置该 Actor 是否启用描边，以及使用哪个描边索引值
		SetRelativeLocation	在局部空间中设置该 Actor 的相对位置（仅在此 Actor 已附加时生效）
		SetRelativeRotation	在局部空间中设置该 Actor 的相对旋转（仅在此 Actor 已附加时生效）
		SetRenderCullDistance	设置该 Actor 的渲染剔除距离
		SetRotation	设置该 Actor 在游戏世界中的旋转
		SetScale	设置该 Actor 的缩放比例
		SetVisibility	设置该 Actor 是否可见
		TranslateTo	在一定时间内平滑地将该 Actor 移动到某个位置
	boolean	WasRecentlyRendered	获取该 Actor 最近是否在屏幕上被渲染过

Inherited Paintable Functions

Cable inherits from Base Paintable Class, sharing it's methods and functions:
Base Paintablescripting-reference/classes/base-classes/paintable

	Returns	Name	Description
	Color	GetMaterialColorParameter	从该 Actor 的材质中获取 Color 参数
	float	GetMaterialScalarParameter	从该 Actor 的材质中获取 Scalar 参数
	string	GetMaterialTextureParameter	从该 Actor 的材质中获取 Texture 参数
	Vector	GetMaterialVectorParameter	从该 Actor 的材质中获取 Vector 参数
		ResetMaterial	将指定索引处的材质重置为原始材质
		SetMaterial	设置该 Actor 指定索引处的材质
		SetMaterialColorParameter	设置该 Actor 材质中的 Color 参数
		SetMaterialFromCanvas	将该 Actor 指定索引处的材质设为 Canvas 对象
		SetMaterialFromSceneCapture	将该 Actor 指定索引处的材质设为 SceneCapture 对象
		SetMaterialFromWebUI	将该 Actor 指定索引处的材质设为 WebUI 对象
		SetMaterialScalarParameter	设置该 Actor 材质中的 Scalar 参数
		SetMaterialTextureParameter	将该 Actor 材质中的纹理参数设为一张图像
		SetMaterialVectorParameter	设置该 Actor 材质中的 Vector 参数
		SetPhysicalMaterial	使用新的物理材质覆盖该 Actor 的物理材质

	Returns	Name	Description
	boolean	AttachEndTo	将此缆绳的末端附加到另一个 Actor 的特定骨骼或相对位置上
	boolean	AttachStartTo	将此缆绳的始端附加到另一个 Actor 的特定骨骼或相对位置上
		DetachEnd	断开此缆绳的末端连接
		DetachStart	断开此缆绳的始端连接
	Base Actor or nil	GetAttachedEndTo	获取附加到末端的 Actor
	Base Actor or nil	GetAttachedStartTo	获取附加到始端的 Actor
		SetAngularLimits	设置此缆绳的物理角限制
		SetAngularMotorSLERPOrientationSettings	设置是否启用 SLERP 角朝向驱动以及目标朝向
		SetAngularMotorSLERPVelocitySettings	设置是否启用 SLERP 角速度驱动以及目标角速度
		SetAngularMotorTwistAndSwingOrientationSettings	设置启用哪些 twist 和 swing 角朝向驱动以及目标朝向
		SetAngularMotorTwistAndSwingVelocitySettings	设置启用哪些 twist 和 swing 角速度驱动以及目标角速度
		SetCableSettings	设置此缆绳的整体设置（仅限视觉效果）
		SetForces	设置应用到缆绳上的外力（仅限视觉效果）
		SetLinearLimits	设置此缆绳的物理线性限制
		SetLinearMotorPositionSettings	设置启用哪些线性位置驱动以及目标位置
		SetLinearMotorVelocitySettings	设置启用哪些线性速度驱动以及目标速度
		SetPhysicsConstraintSettings	设置此缆绳与物理约束相关的设置
		SetRenderingSettings	设置此缆绳的渲染设置（仅限视觉效果）

---

Slow

AttachEndTo

将此缆绳的末端附加到另一个 Actor 的特定骨骼或相对位置上。为了优化性能，建议将此方法作为设置缆绳时最后调用的方法。

注¹：你可以只附加末端，而始端将固定在缆绳的位置。

注²：如果未设置线性限制，该实体将直接吸附到另一个 Actor 上。或者，你也可以通过将其作为参数传递来保持物理约束的偏移量。

local attached_successfully = my_cable:AttachEndTo(other, relative_location?, bone_name?, constraint_offset?)

Parameters

Type	Parameter	Default	Description
Base Actor	other	Required parameter	要附加到的 Actor
Vector	relative_location?	Vector(0, 0, 0)	相对于 Actor 或骨骼的偏移量
string	bone_name?		要附加到哪根骨骼。如果为空，它将附加到 Actor 本身，否则将附加到网格体对应的骨骼/插槽上
Vector	constraint_offset?	Vector(0, 0, 0)	应用在附加末端的物理约束偏移量，使用另一个 Actor 的局部空间坐标

Returns

Type	Description
boolean	是否成功附加

---

Moderate

AttachStartTo

将此缆绳的始端附加到另一个 Actor 的特定骨骼或相对位置上。为了优化性能，如果你希望同时附加始端和末端，建议先附加始端，以避免重复计算。

local attached_successfully = my_cable:AttachStartTo(other, relative_location?, bone_name?)

Parameters

Type	Parameter	Default	Description
Base Actor	other	Required parameter	要附加到的 Actor
Vector	relative_location?	Vector(0, 0, 0)	相对于 Actor 或骨骼的偏移量
string	bone_name?		要附加到哪根骨骼。如果为空，它将附加到 Actor 本身，否则将附加到网格体对应的骨骼/插槽上

Returns

Type	Description
boolean	是否成功附加

---

Optimal

DetachEnd

断开此缆绳的末端连接

my_cable:DetachEnd()

---

Optimal

DetachStart

断开此缆绳的始端连接

my_cable:DetachStart()

---

Optimal

GetAttachedEndTo

获取附加到末端的 Actor

local attached_actor = my_cable:GetAttachedEndTo()

Returns

Type	Description
Base Actor or nil	附加到末端的 Actor

---

Optimal

GetAttachedStartTo

获取附加到始端的 Actor

local attached_actor = my_cable:GetAttachedStartTo()

Returns

Type	Description
Base Actor or nil	附加到始端的 Actor

---

Optimal

SetAngularLimits

设置此缆绳的物理角限制

my_cable:SetAngularLimits(swing_1_motion, swing_2_motion, twist_motion, swing_1_limit?, swing_2_limit?, twist_limit?)

Parameters

Type	Parameter	Default	Description
ConstraintMotion	swing_1_motion	Required parameter	指示是否启用 Swing1 限制
ConstraintMotion	swing_2_motion	Required parameter	指示是否启用 Swing2 限制
ConstraintMotion	twist_motion	Required parameter	指示是否启用 Twist 限制
float	swing_1_limit?	0	沿 XY 平面的运动角度。这定义了圆锥体第一个对称角
float	swing_2_limit?	0	沿 XZ 平面的运动角度。这定义了圆锥体第二个对称角
float	twist_limit?	0	沿 X 轴滚转的对称角

---

Optimal

SetAngularMotorSLERPOrientationSettings

设置是否启用 SLERP 角朝向驱动以及目标朝向

my_cable:SetAngularMotorSLERPOrientationSettings(enable_drive_slerp?, strength?, target?)

Parameters

Type	Parameter	Default	Description
boolean	enable_drive_slerp?	false	启用 SLERP 角朝向驱动
float	strength?	0	驱动的位置强度（刚度）
Rotator	target?	Rotator(0, 0, 0)	角驱动的目标朝向

---

Optimal

SetAngularMotorSLERPVelocitySettings

设置是否启用 SLERP 角速度驱动以及目标角速度

my_cable:SetAngularMotorSLERPVelocitySettings(enable_drive_slerp?, strength?, target?)

Parameters

Type	Parameter	Default	Description
boolean	enable_drive_slerp?	false	启用 SLERP 角速度驱动
float	strength?	0	驱动的速度强度（阻尼）
Vector	target?	Vector(0, 0, 0)	目标角速度

---

Optimal

SetAngularMotorTwistAndSwingOrientationSettings

设置启用哪些 twist 和 swing 角朝向驱动以及目标朝向

my_cable:SetAngularMotorTwistAndSwingOrientationSettings(enable_drive_twist?, enable_drive_swing?, strength?, target?)

Parameters

Type	Parameter	Default	Description
boolean	enable_drive_twist?	false	启用 twist 角朝向驱动
boolean	enable_drive_swing?	false	启用 swing 角朝向驱动
float	strength?	0	驱动的位置强度（刚度）
Rotator	target?	Rotator(0, 0, 0)	角驱动的目标朝向

---

Optimal

SetAngularMotorTwistAndSwingVelocitySettings

设置启用哪些 twist 和 swing 角速度驱动以及目标角速度

my_cable:SetAngularMotorTwistAndSwingVelocitySettings(enable_drive_twist?, enable_drive_swing?, strength?, target?)

Parameters

Type	Parameter	Default	Description
boolean	enable_drive_twist?	false	启用 twist 角速度驱动
boolean	enable_drive_swing?	false	启用 swing 角速度驱动
float	strength?	0	驱动的速度强度（阻尼）
Vector	target?	Vector(0, 0, 0)	目标角速度

---

Optimal

SetCableSettings

设置此缆绳的整体设置（仅限视觉效果）

my_cable:SetCableSettings(length, num_segments?, solver_iterations?, enable_stiffness?)

Parameters

Type	Parameter	Default	Description
float	length	Required parameter	缆绳的自然静止长度。默认值为 100。最小值为 0
integer	num_segments?	10	缆绳拥有的分段数量。默认值为 10。最小值为 1
integer	solver_iterations?	1	解算器迭代次数，控制缆绳的“刚性”。默认值为 1。最大值为 16
boolean	enable_stiffness?	true	为缆绳添加硬度约束。默认值为 true

---

Moderate

SetForces

设置应用到缆绳上的外力（仅限视觉效果）

my_cable:SetForces(force, gravity_scale?)

Parameters

Type	Parameter	Default	Description
Vector	force	Required parameter	应用到缆绳中所有粒子的力向量（世界空间）。默认值为 Vector(0, 0, 0)
float	gravity_scale?	1	应用到影响此缆绳的世界重力上的缩放系数。默认值为 1

---

Optimal

SetLinearLimits

设置此缆绳的物理线性限制。如果启用了 use_soft_constraint，则会使用劲度和阻尼，否则将使用弹性系数（restitution）。

注：此方法必须在附加任何缆绳端点之前调用。

my_cable:SetLinearLimits(x_motion, y_motion, z_motion, limit?, restitution?, use_soft_constraint?, stiffness?, damping?)

Parameters

Type	Parameter	Default	Description
ConstraintMotion	x_motion	Required parameter	指示沿 X 轴应用的线性约束。Free 表示完全没有约束。Locked 表示不允许沿 X 轴运动。Limited 表示所有激活轴上关节内的距离必须小于提供的距离
ConstraintMotion	y_motion	Required parameter	指示沿 Y 轴应用的线性约束。Free 表示完全没有约束。Locked 表示不允许沿 Y 轴运动。Limited 表示所有激活轴上关节内的距离必须小于提供的距离
ConstraintMotion	z_motion	Required parameter	指示沿 Z 轴应用的线性约束。Free 表示完全没有约束。Locked 表示不允许沿 Z 轴运动。Limited 表示所有激活轴上关节内的距离必须小于提供的距离
float	limit?	0	两个关节参考系之间允许的距离。距离限制适用于所有启用的轴（启用一个轴意味着线，两个轴意味着圆，三个轴意味着球）
float	restitution?	0	控制违反约束时的反弹量。弹性系数为 1 时，将以撞击限制时的相同速度反弹回来。值为 0 时则会完全静止停止
boolean	use_soft_constraint?	false	是否要使用柔性约束（弹簧）
float	stiffness?	0	柔性约束的刚度。仅在开启柔性约束时使用
float	damping?	0	柔性约束的阻尼。仅在开启柔性约束时使用

---

Optimal

SetLinearMotorPositionSettings

设置启用哪些线性位置驱动以及目标位置

my_cable:SetLinearMotorPositionSettings(enable_drive_x?, enable_drive_y?, enable_drive_z?, strength?, target?)

Parameters

Type	Parameter	Default	Description
boolean	enable_drive_x?	false	启用 X 轴上的线性位置驱动
boolean	enable_drive_y?	false	启用 Y 轴上的线性位置驱动
boolean	enable_drive_z?	false	启用 Z 轴上的线性位置驱动
float	strength?	0	驱动的位置强度（刚度）
Vector	target?	Vector(0, 0, 0)	目标位置

---

Optimal

SetLinearMotorVelocitySettings

设置启用哪些线性速度驱动以及目标速度

my_cable:SetLinearMotorVelocitySettings(enable_drive_x?, enable_drive_y?, enable_drive_z?, strength?, target?)

Parameters

Type	Parameter	Default	Description
boolean	enable_drive_x?	false	启用 X 轴上的线性速度驱动
boolean	enable_drive_y?	false	启用 Y 轴上的线性速度驱动
boolean	enable_drive_z?	false	启用 Z 轴上的线性速度驱动
float	strength?	0	驱动的速度强度（阻尼）
Vector	target?	Vector(0, 0, 0)	目标速度

---

Optimal

SetPhysicsConstraintSettings

设置此缆绳与物理约束相关的设置

my_cable:SetPhysicsConstraintSettings(disable_collision)

Parameters

Type	Parameter	Default	Description
boolean	disable_collision	Required parameter	如果为 true，将禁用该约束的两个刚体之间的碰撞

---

Optimal

SetRenderingSettings

设置此缆绳的渲染设置（仅限视觉效果）

my_cable:SetRenderingSettings(width, num_sides, tile_material)

Parameters

Type	Parameter	Default	Description
float	width	Required parameter	缆绳几何体的宽度。默认值为 6
integer	num_sides	Required parameter	缆绳几何体的侧面数量。默认值为 4
integer	tile_material	Required parameter	材质沿缆绳长度方向重复平铺的次数。默认值为 1

🚀 事件

Inherited Entity Events

Cable inherits from Base Entity Class, sharing it's events:
Base Entityscripting-reference/classes/base-classes/entity

	Name	Description
	ClassRegister	当使用 继承系统 注册一个新类时触发
	Destroy	当实体被销毁时触发
	Spawn	当实体被生成/创建时触发
	ValueChange	当实体通过 :SetValue() 改变了值时触发

Inherited Actor Events

Cable inherits from Base Actor Class, sharing it's events:
Base Actorscripting-reference/classes/base-classes/actor

	Name	Description
	DimensionChange	当 Actor 改变其维度时触发
	EnterWater	当 Actor 进入水体时触发
	LeaveWater	当 Actor 离开水体时触发
	NetworkAuthorityChange	当 Actor 更改其网络主控玩家时触发
	NetworkAuthorityChange	当本地玩家获得或失去对此 Actor 的网络主控时触发

This class doesn't have own events.