基础 Actor

Actor 是一个可以通过 Lua 生成和销毁的对象。
Actor 支持 3D 变换，例如平移（位置）、旋转和缩放。

Actor 是多个实体的基础母版，所有这些实体都共享本页面中所描述的方法和事件。

👪Base Class🧑‍💻API Source

👪Base Class

This is a Base Class, an abstract definition that shares common methods and events with it's child classes. You cannot spawn it, and you cannot call anything on the Base Class name itself. Use any class that inherits it.

Classes that share methods and events from this Base Class: Billboard, Blueprint, Cable, Character, CharacterSimple, Decal, Gizmo, Grenade, InstancedStaticMesh, Light, Melee, Particle, Prop, SceneCapture, StaticMesh, Sound, TextRender, Text3D, Trigger, VehicleWheeled, VehicleWater, Weapon, Widget3D.

---

🦠 函数

注意

以下部分方法可能不适用于某些 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 最近是否在屏幕上被渲染过

---

Optimal

AddActorTag

向该 Actor 添加一个虚幻 Actor 标签

my_actor:AddActorTag(tag)

Parameters

Type	Parameter	Default	Description
string	tag	Required parameter	要添加的标签

See also RemoveActorTag, GetActorTags.

---

Optimal

AddAngularImpulse

向该 Actor 添加角冲量。适用于单次瞬间爆发

my_actor:AddAngularImpulse(angular_impulse, velocity_change?)

Parameters

Type	Parameter	Default	Description
Vector	angular_impulse	Required parameter	要施加的冲量大小和方向。方向为旋转轴。单位为弧度
boolean	velocity_change?	false	是否忽略质量

---

Optimal

AddImpulse

向该 Actor 添加冲量。适用于单次瞬间爆发

my_actor:AddImpulse(impulse, velocity_change?)

Parameters

Type	Parameter	Default	Description
Vector	impulse	Required parameter	要施加的冲量大小和方向
boolean	velocity_change?	false	是否忽略质量

---

Moderate

AttachTo

将该 Actor 附加到任何其他 Actor 上，可选择附加在特定骨骼处

local attached_successfully = my_actor:AttachTo(other, attachment_rule?, bone_name?, lifespan_when_detached?, use_absolute_rotation?)

Parameters

Type	Parameter	Default	Description
Base Actor	other	Required parameter	要附加的其他 Actor
AttachmentRule	attachment_rule?	AttachmentRule.SnapToTarget	如何附加
string	bone_name?		要附加到哪根骨骼。如果为空，它将附加到 Actor 本身，否则将附加到网格体对应的骨骼/插槽上
float	lifespan_when_detached?	-1	分离时销毁该 Actor 之前的秒数，设为 0 将在分离时自动销毁该 Actor，设为 10 将在分离 10 秒后销毁
boolean	use_absolute_rotation?	false	是否强制被附加的对象使用绝对旋转（不会跟随父级移动）

Returns

Type	Description
boolean	是否成功附加

---

Optimal

Detach

将该 Actor 从其附加的 Actor 上分离

my_actor:Detach()

---

Moderate

GetActorTags

获取该 Actor 上的所有虚幻 Actor 标签

local ret = my_actor:GetActorTags()

Returns

Type	Description
table of string	此 Actor 上的所有虚幻 Actor 标签

See also AddActorTag, RemoveActorTag.

---

Optimal

GetAngularForce

获取该 Actor 的角外力（由 SetAngularForce() 设置）

local angular_force = my_actor:GetAngularForce()

Returns

Type	Description
Vector	此 Actor 的角作用力

See also SetAngularForce.

---

Optimal

GetAngularVelocity

返回此 Actor 的角速度

local angular_velocity = my_actor:GetAngularVelocity()

Returns

Type	Description
float	此 Actor 的角速度

---

Moderate

GetAttachedEntities

获取附加到该 Actor 的所有 Actor

local ret = my_actor:GetAttachedEntities(recursively?)

Parameters

Type	Parameter	Default	Description
boolean	recursively?	false	同时也返回附加到已附加 Actor 上的 Actor

Returns

Type	Description
table of Base Actor	附加到此 Actor 的所有 Actor

---

Optimal

GetAttachedTo

获取该 Actor 所附加到的父级 Actor

local ret = my_actor:GetAttachedTo()

Returns

Type	Description
Base Actor or nil	此 Actor 附加到的父级 Actor

---

Optimal

GetAttachedToSocket

获取此 Actor 所附加到的骨骼或插槽名称

local ret = my_actor:GetAttachedToSocket()

Returns

Type	Description
string	骨骼或插槽名称；若未附加到骨骼则返回空字符串

---

Moderate

GetBounds

获取此 Actor 的包围盒，便于计算其在世界中的尺寸

local ret = my_actor:GetBounds()

Returns

Type	Description
table	此 Actor 的包围盒 with this format

---

Optimal

GetCollision

获取该 Actor 的碰撞类型

local collision_type = my_actor:GetCollision()

Returns

Type	Description
CollisionType	此 Actor 的碰撞类型

See also SetCollision.

---

Optimal

GetDimension

获取该 Actor 的维度

local dimension = my_actor:GetDimension()

Returns

Type	Description
integer	此 Actor 的维度

See also SetDimension, DimensionChange.

---

Optimal

GetDistanceFromCamera

获取该 Actor 距离相机的距离

local ret = my_actor:GetDistanceFromCamera()

Returns

Type	Description
float	此 Actor 距离相机的距离

---

Optimal

GetForce

获取该 Actor 的持续外力（由 SetForce() 设置）

local force = my_actor:GetForce()

Returns

Type	Description
Vector	此 Actor 的作用力

See also SetForce.

---

Optimal

GetLifeSpan

获取此 Actor 被销毁前剩余的时间（秒）

local ret = my_actor:GetLifeSpan()

Returns

Type	Description
float	销毁前的秒数

See also SetLifeSpan.

---

Optimal

GetLocation

获取该 Actor 在游戏世界中的位置

local location = my_actor:GetLocation()

Returns

Type	Description
Vector	此 Actor 在游戏世界中的位置

See also SetLocation.

---

Optimal

GetMass

返回此 Actor 的质量

local mass = my_actor:GetMass()

Returns

Type	Description
float	此 Actor 的质量

---

Optimal

GetNetworkAuthority

获取该 Actor 的网络主控玩家

local ret = my_actor:GetNetworkAuthority()

Returns

Type	Description
Player or nil	对此 Actor 拥有网络主控的玩家

See also SetNetworkAuthority.

---

Optimal

GetRelativeLocation

如果该 Actor 已附加，获取其相对位置

local relative_location = my_actor:GetRelativeLocation()

Returns

Type	Description
Vector	若处于附加状态，则为此 Actor 的相对位置

See also SetRelativeLocation.

---

Optimal

GetRelativeRotation

如果该 Actor 已附加，获取其相对旋转

local relative_rotation = my_actor:GetRelativeRotation()

Returns

Type	Description
Rotator	若处于附加状态，则为此 Actor 的相对旋转

See also SetRelativeRotation.

---

Optimal

GetRotation

获取该 Actor 在游戏世界中的角度值

local rotation = my_actor:GetRotation()

Returns

Type	Description
Rotator	此 Actor 在游戏世界中的角度

See also SetRotation.

---

Optimal

GetScale

获取该 Actor 的缩放比例

local scale = my_actor:GetScale()

Returns

Type	Description
Vector	此 Actor 的缩放比例

See also SetScale.

---

Optimal

GetScreenPercentage

获取该 Actor 在屏幕中所占尺寸的百分比

local ret = my_actor:GetScreenPercentage()

Returns

Type	Description
float	此 Actor 在屏幕中所占尺寸的百分比

---

Moderate

GetSocketTransform

在给定骨骼或插槽名称的情况下，获取世界空间中的插槽变换

local ret = my_actor:GetSocketTransform(socket_name, attachable_id?)

Parameters

Type	Parameter	Default	Description
string	socket_name	Required parameter	插槽名称
string	attachable_id?		要从中读取插槽的附加 ID（通过 AddSkeletalMeshAttached 或 AddStaticMeshAttached 设置）。传入字符串为空则仅从主网格体读取

Returns

Type	Description
table	根据给定的骨骼或插槽名称获取世界空间中的插槽变换 with this format

---

Optimal

GetVelocity

获取该 Actor 当前的速度

local velocity = my_actor:GetVelocity()

Returns

Type	Description
Vector	此 Actor 当前的速度

---

Optimal

HasNetworkAuthority

如果本地玩家当前是该 Actor 的网络主控（Network Authority），则返回 true

local has_network_authority = my_actor:HasNetworkAuthority()

Returns

Type	Description
boolean	本地玩家当前是否为此 Actor 的网络主控

---

Optimal

IsGravityEnabled

如果该 Actor 启用了重力，则返回 true

local gravity_enabled = my_actor:IsGravityEnabled()

Returns

Type	Description
boolean	此 Actor 是否已启用重力

See also SetGravityEnabled.

---

Optimal

IsInWater

如果此 Actor 在水中，则返回 true。此函数仅适用于模拟物理的 Actor，例如 Prop、Vehicle、Pickables 和 Character。

local in_water = my_actor:IsInWater()

Returns

Type	Description
boolean	此 Actor 是否在水中

---

Optimal

IsNetworkDistributed

如果该 Actor 当前处于网络分配状态，则返回 true。只有处于网络分配状态的 Actor 才能手动设置其网络主控
实体在以下情况时会自动禁用 NetworkDistributed：被附加、被控制、被抓取、被拾取或驾驶中

local ret = my_actor:IsNetworkDistributed()

Returns

Type	Description
boolean	此 Actor 当前是否处于网络分布式状态

See also SetNetworkAuthorityAutoDistributed, SetNetworkAuthority.

---

Optimal

IsVisible

如果该 Actor 可见，则返回 true

local is_visible = my_actor:IsVisible()

Returns

Type	Description
boolean	此 Actor 是否可见

---

Optimal

RemoveActorTag

从该 Actor 中移除一个虚幻 Actor 标签

my_actor:RemoveActorTag(tag)

Parameters

Type	Parameter	Default	Description
string	tag	Required parameter	要移除的标签

See also AddActorTag, GetActorTags.

---

Optimal

RotateTo

在一定时间内平滑旋转该 Actor 到指定角度

my_actor:RotateTo(rotation, time, exp?)

Parameters

Type	Parameter	Default	Description
Rotator	rotation	Required parameter	目标旋转
float	time	Required parameter	从当前位置插值到目标位置所需的时间
float	exp?	0	用于平滑插值的指数。使用 0 表示线性运动

---

Optimal

SetAngularForce

向该 Actor 添加一个永久的角外力，设为 Vector(0, 0, 0) 可以取消

my_actor:SetAngularForce(angular_force)

Parameters

Type	Parameter	Default	Description
Vector	angular_force	Required parameter	每帧施加的角作用力

See also GetAngularForce.

---

Moderate

SetCastShadow

设置该 Actor 是否投射阴影

my_actor:SetCastShadow(cast_shadow)

Parameters

Type	Parameter	Default	Description
boolean	cast_shadow	Required parameter	是否投射新的阴影

---

Optimal

SetCollision

设置该 Actor 的碰撞类型

my_actor:SetCollision(collision_type)

Parameters

Type	Parameter	Default	Description
CollisionType	collision_type	Required parameter	新的碰撞类型

See also GetCollision.

---

Moderate

SetDimension

设置此 Actor 的维度。Actor 仅能看见并与处于同一维度中的实体进行交互

my_actor:SetDimension(dimension)

Parameters

Type	Parameter	Default	Description
integer	dimension	Required parameter	新的维度

See also GetDimension, DimensionChange.

---

Optimal

SetDistanceOptimizationMultiplier

设置此 Actor 的距离优化系数。
值为 0 时禁用优化。小于 1 的值会减弱优化效果，而大于 1 的值会增强优化效果

my_actor:SetDistanceOptimizationMultiplier(multiplier)

Parameters

Type	Parameter	Default	Description
float	multiplier	Required parameter	新的距离优化系数

---

Optimal

SetForce

向该 Actor 添加一个永久的外力，设为 Vector(0, 0, 0) 可以取消

my_actor:SetForce(force, is_local?)

Parameters

Type	Parameter	Default	Description
Vector	force	Required parameter	每帧施加的作用力
boolean	is_local?	true	是否在局部空间中施加该外力

See also GetForce.

---

Optimal

SetGravityEnabled

设置该 Actor 是否启用重力

my_actor:SetGravityEnabled(gravity_enabled)

Parameters

Type	Parameter	Default	Description
boolean	gravity_enabled	Required parameter	此 Actor 是否已启用重力

See also IsGravityEnabled.

---

Optimal

SetHighlightEnabled

设置该 Actor 是否启用高亮显示，以及使用哪个高亮索引值。这也会同时应用到每一个附加的实体上

my_actor:SetHighlightEnabled(is_enabled, index?)

Parameters

Type	Parameter	Default	Description
boolean	is_enabled	Required parameter	是否启用高亮
integer	index?	0	要使用的索引（应为 0、1 或 2）

See also Client.SetHighlightColor().

---

Optimal

SetLifeSpan

设置该 Actor 被销毁前的生存时间（秒）。经过这段时间后，Actor 将被自动销毁。

my_actor:SetLifeSpan(seconds)

Parameters

Type	Parameter	Default	Description
float	seconds	Required parameter	销毁前的秒数

See also GetLifeSpan.

---

Moderate

SetLocation

设置该 Actor 在游戏世界中的位置

my_actor:SetLocation(location)

Parameters

Type	Parameter	Default	Description
Vector	location	Required parameter	游戏世界中的新位置

See also GetLocation.

---

Moderate

SetNetworkAuthority

设置某个玩家拥有此 Actor 的网络主控。该玩家将被手动分配来处理该 Actor 的物理效果，并与其他客户端同步其位置。游戏依然会自动覆盖此主控分配

请参考 网络主控 进一步了解

my_actor:SetNetworkAuthority(player?)

Parameters

Type	Parameter	Default	Description
Player	player?	nil	将承担此 Actor 网络主控的新玩家

See also SetNetworkAuthorityAutoDistributed, IsNetworkDistributed, GetNetworkAuthority, NetworkAuthorityChange.

---

Optimal

SetNetworkAuthorityAutoDistributed

设置该 Actor 在空闲时是否在玩家之间自动分配网络主控

请参考 网络主控 进一步了解

my_actor:SetNetworkAuthorityAutoDistributed(auto_distribute)

Parameters

Type	Parameter	Default	Description
boolean	auto_distribute	Required parameter	该 Actor 是否会自动网络分配

See also SetNetworkAuthority, IsNetworkDistributed.

---

Optimal

SetOutlineEnabled

设置该 Actor 是否启用描边，以及使用哪个描边索引值。这也会同时应用到每一个附加的实体上

my_actor:SetOutlineEnabled(is_enabled, index?)

Parameters

Type	Parameter	Default	Description
boolean	is_enabled	Required parameter	是否启用轮廓
integer	index?	0	要使用的索引（应为 0、1 或 2）

See also Client.SetOutlineColor().

---

Moderate

SetRelativeLocation

在局部空间中设置该 Actor 的相对位置（仅在此 Actor 已附加时生效）

my_actor:SetRelativeLocation(relative_location)

Parameters

Type	Parameter	Default	Description
Vector	relative_location	Required parameter	局部空间中的新相对位置

See also GetRelativeLocation.

---

Moderate

SetRelativeRotation

在局部空间中设置该 Actor 的相对旋转（仅在此 Actor 已附加时生效）

my_actor:SetRelativeRotation(relative_rotation)

Parameters

Type	Parameter	Default	Description
Rotator	relative_rotation	Required parameter	局部空间中的新相对旋转

See also GetRelativeRotation.

---

Moderate

SetRenderCullDistance

设置该 Actor 的渲染剔除距离。注：这只会影响渲染距离，无论此距离如何，该实体仍会正常生成并同步

my_actor:SetRenderCullDistance(max_distance)

Parameters

Type	Parameter	Default	Description
integer	max_distance	Required parameter	新的渲染剔除距离

---

Moderate

SetRotation

设置该 Actor 在游戏世界中的旋转

my_actor:SetRotation(rotation)

Parameters

Type	Parameter	Default	Description
Rotator	rotation	Required parameter	游戏世界中的新旋转

See also GetRotation.

---

Slow

SetScale

设置该 Actor 的缩放比例

my_actor:SetScale(scale)

Parameters

Type	Parameter	Default	Description
Vector	scale	Required parameter	新的缩放比例

See also GetScale.

---

Optimal

SetVisibility

设置该 Actor 是否可见

my_actor:SetVisibility(is_visible)

Parameters

Type	Parameter	Default	Description
boolean	is_visible	Required parameter	Actor 是否可见

---

Optimal

TranslateTo

在一定时间内平滑地将该 Actor 移动到某个位置

my_actor:TranslateTo(location, time, exp?)

Parameters

Type	Parameter	Default	Description
Vector	location	Required parameter	目标位置
float	time	Required parameter	从当前位置插值到目标位置所需的时间
float	exp?	0	用于平滑插值的指数。使用 0 表示线性运动

---

Moderate

WasRecentlyRendered

获取该 Actor 最近是否在屏幕上被渲染过

local ret = my_actor:WasRecentlyRendered()

Returns

Type	Description
boolean	此 Actor 近期是否已在屏幕上被渲染

🚀 事件

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

---

DimensionChange

当 Actor 改变其维度时触发

<AnyActorClass>.Subscribe("DimensionChange", function(self, old_dimension, new_dimension)
	-- DimensionChange was called
end)

Arguments

Type	Argument	Description
Base Actor	self	触发该事件的 Actor
integer	old_dimension	上一个维度
integer	new_dimension	新的维度

See also SetDimension, GetDimension.

---

EnterWater

当 Actor 进入水体时触发。仅模拟物理的 Actor 会触发此事件，例如 Prop、Vehicle、Pickables 和 Character。

<AnyActorClass>.Subscribe("EnterWater", function(self)
	-- EnterWater was called
end)

Arguments

Type	Argument	Description
Base Actor	self	触发该事件的 Actor

See also IsInWater.

---

LeaveWater

当 Actor 离开水体时触发。仅模拟物理的 Actor 会触发此事件，例如 Prop、Vehicle、Pickables 和 Character。

<AnyActorClass>.Subscribe("LeaveWater", function(self)
	-- LeaveWater was called
end)

Arguments

Type	Argument	Description
Base Actor	self	触发该事件的 Actor

See also IsInWater.

---

NetworkAuthorityChange

当 Actor 更改其网络主控玩家时触发

<AnyActorClass>.Subscribe("NetworkAuthorityChange", function(self, old_network_authority, new_network_authority)
	-- NetworkAuthorityChange was called
end)

Arguments

Type	Argument	Description
Base Actor	self	触发该事件的 Actor
Player or nil	old_network_authority	原网络主控玩家（若有）
Player or nil	new_network_authority	新网络主控玩家（若有）

See also SetNetworkAuthority, GetNetworkAuthority.

---

NetworkAuthorityChange

当本地玩家获得或失去对此 Actor 的网络主控时触发

<AnyActorClass>.Subscribe("NetworkAuthorityChange", function(self, is_network_authority)
	-- NetworkAuthorityChange was called
end)

Arguments

Type	Argument	Description
Base Actor	self	触发该事件的 Actor
boolean	is_network_authority	本地玩家现在是否拥有此 Actor 的网络主控

See also SetNetworkAuthority, GetNetworkAuthority.