📽️ SceneCapture

场景捕获是一个将场景的完全动态图像捕获到纹理中的 Actor。它从其视锥体中捕获场景，将该视图存储为图像，然后该图像将在材质中使用。

Client Only🧑‍💻API Source

👪Inheritance

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

---

🎒 示例

Client/Index.lua

local scene_capture = SceneCapture(
  Vector(0, 0, 200),
  Rotator(-15, 0, 0),
  256,
  256,
  0,
  5000,
  100
)

-- 使用 SceneCapture 的输出在 Prop 上进行绘制
local my_prop = Prop(Vector(200, 200, 100), Rotator(), "nanos-world::SM_Cube")
my_prop:SetMaterialFromSceneCapture(scene_capture)

Client/Index.lua

local scene_capture = SceneCapture(
  Vector(0, 0, 200),
  Rotator(-15, 0, 0),
  256,
  256,
  0,
  5000,
  100
)

-- 使 SceneCapture 仅渲染特定 Actor
local my_prop = Prop(Vector(200, 200, 100), Rotator(), "nanos-world::SM_Cube")
scene_capture:AddRenderActor(my_prop)
scene_capture:SetShowFlag("Atmosphere", false)

提示

你可以通过 :SetMaterialFromSceneCapture() 方法使用 SceneCapture 输出的纹理！

🛠 构造函数

Default Constructor

No description provided

local my_scenecapture = SceneCapture(location?, rotation?, width?, height?, render_rate?, view_distance?, fov_angle?, enable_distance_optimization?)

Parameters

Type	Name	Default	Description
Vector	location	Vector(0, 0, 0)	位置
Rotator	rotation	Rotator(0, 0, 0)	旋转
integer	width	128	生成的纹理宽度（最大为 4096）
integer	height	128	生成的纹理高度（最大为 4096）
float	render_rate	0.033	渲染率（捕获的频率）- 传入 -1 禁用自动渲染，传入 0 逐帧捕获
float	view_distance	5000	最大捕获距离
float	fov_angle	90	视场角
boolean	enable_distance_optimization	true	如果带有此材质的实体过远或不可见，则降低渲染频率。禁用此项将始终按 render_rate 进行渲染

备注

Scene Capture 是实时捕获场景的，这意味着每个刻它都会从头开始重新渲染场景。请考虑调低 width/height 甚至 render_rate 以提升性能。

我们一直在努力使 SceneCapture 尽可能保持高效！我们应用了一些优化技术，当玩家距离较远或生成的纹理超出屏幕范围时，会自动降低 render_rate。

🗿 静态函数

Inherited Entity Static Functions

SceneCapture 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

SceneCapture 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

SceneCapture 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	IsImpulseOnDamage	Returns true if taking damage pushes this Actor's physics body
	boolean	IsInWater	如果该 Actor 处于水中，则返回 true
	boolean	IsNetworkDistributed	如果该 Actor 当前处于网络分配状态，则返回 true
	boolean	IsVisible	如果该 Actor 可见，则返回 true
		RemoveActorTag	从该 Actor 中移除一个虚幻 Actor 标签
		RotateRelativeTo	Smoothly rotates this attached actor to an angle relative to its parent over a certain time
		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 是否启用高亮显示，以及使用哪个高亮索引值
		SetImpulseOnDamage	Sets whether taking damage (shots, melee, explosions) pushes this Actor's physics body
		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 是否可见
		TranslateRelativeTo	Smoothly moves this attached actor to a location relative to its parent over a certain time
		TranslateTo	在一定时间内平滑地将该 Actor 移动到某个位置
	boolean	WasRecentlyRendered	获取该 Actor 最近是否在屏幕上被渲染过

	Returns	Name	Description
		AddRenderActor	将一个 Actor 添加到仅渲染列表中
		CaptureScene	捕获场景。如果 deferred 为 true，则执行延迟捕获并记录该帧；否则立即捕获并触发 Capture 事件
		ClearRenderActors	清空仅渲染列表
	string	EncodeToBase64	获取场景捕获的快照并返回其 Base64
		EncodeToBase64Async	获取场景捕获的快照并返回其 Base64 字符串（异步）
		RemoveRenderActor	从仅渲染列表中移除一个 Actor
		Resize	更改输出纹理的分辨率 注：分辨率过高会导致捕获变慢并影响游戏性能
		SetDistanceOptimizationEnabled	启用或禁用当带有此材质的实体过远时的渲染频率优化
		SetFOVAngle	设置视场角
		SetFreeze	停止或恢复捕获
		SetRenderRate	设置捕获频率 注：设为 0 以逐帧捕获，或设为 -1 以禁用自动捕获
		SetShowFlag	启用/禁用渲染特性以决定其是否被捕获

---

Optimal

AddRenderActor

将一个 Actor 添加到仅渲染列表中

注：向该列表添加一个 Actor 后，场景捕获将仅渲染这些 Actor。

my_scenecapture:AddRenderActor(actor)

Parameters

Type	Parameter	Default	Description
Base Actor	actor	Required parameter	要渲染的 Actor

See also RemoveRenderActor, ClearRenderActors.

---

Slow

CaptureScene

捕获场景。如果 deferred 为 true，则执行延迟捕获并记录该帧；否则立即捕获并触发 Capture 事件

my_scenecapture:CaptureScene(deferred?)

Parameters

Type	Parameter	Default	Description
boolean	deferred?	false	如果为 true，则执行延迟捕获（将在稍后捕获并触发 Capture 事件）

---

Optimal

ClearRenderActors

清空仅渲染列表

my_scenecapture:ClearRenderActors()

See also AddRenderActor, RemoveRenderActor.

---

Slow

EncodeToBase64

获取场景捕获的快照并返回其 Base64

local ret = my_scenecapture:EncodeToBase64(image_format?)

Parameters

Type	Parameter	Default	Description
ImageFormat	image_format?	ImageFormat.JPEG	生成的图像格式 - JPEG 最快，但会丢弃 Alpha 通道

Returns

Type	Description
string	作为 Base64 字符串的快照

See also EncodeToBase64Async.

---

Optimal

EncodeToBase64Async

获取场景捕获的快照并返回其 Base64 字符串（异步）

my_scenecapture:EncodeToBase64Async(image_format?, callback)

Parameters

Type	Parameter	Default	Description
ImageFormat	image_format?	ImageFormat.JPEG	生成的图像格式 - JPEG 最快，但会丢弃 Alpha 通道
function	callback	Required parameter	回调函数 with this format

See also EncodeToBase64.

---

Optimal

RemoveRenderActor

从仅渲染列表中移除一个 Actor

my_scenecapture:RemoveRenderActor(actor)

Parameters

Type	Parameter	Default	Description
Base Actor	actor	Required parameter	停止渲染的 Actor

See also AddRenderActor, ClearRenderActors.

---

Moderate

Resize

更改输出纹理的分辨率 注：分辨率过高会导致捕获变慢并影响游戏性能

my_scenecapture:Resize(width, height)

Parameters

Type	Parameter	Default	Description
integer	width	Required parameter	宽度（像素）
integer	height	Required parameter	高度（像素）

---

Optimal

SetDistanceOptimizationEnabled

启用或禁用当带有此材质的实体过远时的渲染频率优化

my_scenecapture:SetDistanceOptimizationEnabled(enabled)

Parameters

Type	Parameter	Default	Description
boolean	enabled	Required parameter	当带有此材质的实体距离过远时，是否启用渲染频率优化

---

Optimal

SetFOVAngle

设置视场角

my_scenecapture:SetFOVAngle(angle)

Parameters

Type	Parameter	Default	Description
float	angle	Required parameter	新的视场角

---

Optimal

SetFreeze

停止或恢复捕获

my_scenecapture:SetFreeze(freeze)

Parameters

Type	Parameter	Default	Description
boolean	freeze	Required parameter	是否停止捕获

---

Optimal

SetRenderRate

设置捕获频率 注：设为 0 以逐帧捕获，或设为 -1 以禁用自动捕获

my_scenecapture:SetRenderRate(render_rate)

Parameters

Type	Parameter	Default	Description
float	render_rate	Required parameter	两次捕获之间的间隔秒数，0 代表每帧捕获，-1 代表禁用自动捕获

---

Optimal

SetShowFlag

启用/禁用渲染功能的捕获
可用标志的完整列表可在 虚幻引擎官方文档 中找到

my_scenecapture:SetShowFlag(flag, enable)

Parameters

Type	Parameter	Default	Description
string	flag	Required parameter	虚幻引擎显示标志的名称，例如 Fog
boolean	enable	Required parameter	是否渲染

🚀 事件

Inherited Entity Events

SceneCapture 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

SceneCapture 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 的网络主控时触发

	Name	Description
	Capture	当此场景捕获进行更新/渲染帧时触发

---

Capture

当此场景捕获进行更新/渲染帧时触发

SceneCapture.Subscribe("Capture", function(self)
	-- Capture was called
end)

Arguments

Type	Argument	Description
SceneCapture	self	触发该事件的场景捕获对象