CameraUnit

概览

字段	值
Kind	Unit · 单位 Unit
Realm	common

继承关系

• Unit（4 属性 / 25 函数 / 6 事件）
  • SpaceUnit（2 属性 / 9 函数）
    • [CameraUnit]（22 属性 / 2 函数 / 1 事件）

继承成员

2 个来源 / 6 属性 / 34 函数 / 6 事件

• 来自 SpaceUnit（2 属性 / 9 函数）
  • 属性：Tags、EcaPath
  • 函数：HasTag、AddTag、RemoveTag、GetPivot、PivotTo、ApplyPivotDelta、TranslateBy、IsTopLevel、FindTopLevel
• 来自 Unit（4 属性 / 25 函数 / 6 事件）
  • 属性：AssetId、Name、Desc、Parent
  • 函数：ClearAllChildren、GetChildren、GetDescendants、IsAncestorOf、IsDescendantOf、FindFirstAncestor、FindFirstAncestorWhichIsA、FindFirstAncestorOfClass、FindFirstChild、FindFirstChildWhichIsA、FindFirstChildOfClass、HasChildren、GetChildCount、GetChildAtIndex、SetAttribute、GetAttribute、GetAllProps、Clone、IsA、Destroy、GetPropertyChangedSignal、GetAttributeChangedSignal、FindFromPath、GetFullPath、GetDebugId
  • 事件：ChildAdded、ChildRemoved、DescendantAdded、DescendantRemoving、AncestryChanged、Destroying

CameraUnit 描述渲染视角自身的状态，涵盖位置与四元数朝向、俯仰偏航滚转角度、视场角与视场角模式、近裁剪面与裁剪范围、跟随目标与额外关注目标等属性。它通过 Priority 与 IsActive 参与活跃相机的选择，通过 Mode 与 CameraType 决定行为方式，并可借助 GetPartsObscuringTarget 查出挡在目标前方的场景单位、用 ResetMovement 复位相机移动状态。

适用场景

需要临时接管玩家视角时，例如角色被快速挪动后对齐镜头、脚本化运镜或跟随指定单位，作者会先取得当前相机实例，把 Mode 切换为 Enums.CameraMode.SCRIPTABLE，调整完 CFrame 后再切回 Enums.CameraMode.EGGY。排查视角异常时则查看 CameraService.LiveCamera，确认真正参与渲染的相机是哪一个。

使用要点

通过 game:GetService('World').CurrentCamera 获取当前活跃相机。设置 Mode、Position、Rotation、Focus 等公开属性控制视角，调用 GetPartsObscuringTarget 检查目标点之间的遮挡。

注意事项

CameraUnit 是 World 自带的相机实例，必须通过 game:GetService('World').CurrentCamera 获取，不能用 World:CreateUnit('CameraUnit', {}) 创建（运行时会失败）。要切换活跃相机：1) 设置 Priority 大于当前活跃相机（数值越大优先级越高）；2) 确保 CameraService.MainCamera 已指向该实例或依赖自动选择逻辑。CameraService.LiveCamera（只读）始终指向当前实际渲染的相机，调试视角问题时优先看 LiveCamera 而非 MainCamera。Focus 的公开类型为 Vector3。2026-08-11 当前编辑器运行时的 CurrentCamera 未提供 Meta 声明的 AfterUpdateState 信号，使用前必须判空。

代码示例

获取当前相机并检查遮挡

-- @runtime client
local World = game:GetService('World')
local camera = World.CurrentCamera
if camera == nil then return end

local ok, obscuringParts = pcall(function()
    return camera:GetPartsObscuringTarget({ Vector3.New(0, 5, 20) }, {})
end)
obscuringParts = ok and obscuringParts or {}
for _, part in ipairs(obscuringParts) do
    print('遮挡单位:', part.Name)
end

属性 (22)

Name	类型	默认值	说明
Position	Vector3	-	相机当前位置，类型为 Vector3。在预设行为下，相机会按参照更新此状态。
Rotation	Quaternion	-	相机当前朝向，类型为 Quaternion。在预设行为下，相机会按参照更新此状态。
Pitch	Float	-	相机的俯仰角（单位：度），用于改变视角的上下角度，参考世界上方向。
Yaw	Float	-	相机的偏航角（单位：度），用于改变视角的左右方向。
Roll	Float	-	相机的滚转角（单位：度），沿前后方向旋转，用于倾斜画面。
TrackingUnit	Unit	-	标记当前相机跟随目标，类型为 Unit，供相机行为参考。
ExtraSubject	Unit	-	相机额外的关注目标，类型为 Unit，默认为空。当该属性非空时，在预设行为下相机的朝向状态会参考此目标。
FieldOfView	Float	-	相机的垂直视场角，类型为 Float。
FieldOfViewMode	Int	-	相机视场角模式，使用 Enums.FieldOfViewMode.Vertical、Enums.FieldOfViewMode.Diagonal 或 Enums.FieldOfViewMode.MaxAxis。
ProjectionType	CameraProjection	-	相机的投影模式，类型为 CameraProjection，可取 Enums.CameraProjection.PERSPECTIVE、Enums.CameraProjection.ORTHOGRAPHIC 等取值。
NearPlaneZ	Float	-	近裁剪平面距离，类型为 Float。
ViewportSize	Vector2	-	视口尺寸（像素），类型为 Vector2。
Focus	Vector3	-	相机聚焦点的 Vector3 坐标，用于确定相机朝向。
CFrame	CFrame	-	相机坐标矩阵（Position + Rotation 的组合），类型为 CFrame。
Priority	Float	-	相机的展示优先级，类型为 Float；全局展示优先级最高的相机会操作实际的渲染相机。
IsActive	Bool	-	相机是否处于激活状态，类型为 Bool。
ClippingRange	Vector2	-	相机裁剪平面范围，类型为 Vector2，默认值为 [0.5, 15000]，其中 X 分量表示近裁剪面，Y 分量表示远裁剪面。
Distance	Float	-	相机与跟随目标之间的距离，类型为 Float。
ScriptableBehaviour	Table	-	相机的脚本行为，类型为 Table，用于以表格形式描述脚本控制下的相机行为参数。
Mode	CameraMode	-	相机的行为模式，类型为 CameraMode，使用 Eggy 原生模式，可取 Enums.CameraMode 中的 NONE、EGGY、SCRIPTABLE、FOLLOW、BIND、SCREEN_ZONE、ORBIT 等取值。
CameraType	CameraType	-	相机类型，类型为 CameraType，会按类型自动映射到 Mode；可取 Enums.CameraType 中的 Fixed、Attach、Watch、Track、Follow、Custom、Scriptable、Orbital 等取值。
DevCameraOcclusionMode	DevCameraOcclusionMode	-	相机遮挡处理模式，使用 Enums.DevCameraOcclusionMode.Zoom、Enums.DevCameraOcclusionMode.Invisicam 或 Enums.DevCameraOcclusionMode.EggyHybrid。

关联类型

• SpaceUnit
• CFrame
• CameraMode
• CameraProjection
• CameraType
• DevCameraOcclusionMode
• Quaternion
• Vector2
• Vector3

事件 (1)

AfterUpdateState

签名：AfterUpdateState(delta: Float) 触发：local

相机在每次更新状态之后触发的事件，回调参数 delta 为 Float，表示本次更新的时间增量。

⚙ 公开 Meta 声明该事件，但当前编辑器运行时的 CurrentCamera 上该信号为 nil；运行包补齐前只能做兼容性判空。

回调参数	类型	说明
delta	Float	帧间隔时间

示例代码

兼容性监听相机更新事件

-- @runtime client
local camera = game:GetService('World').CurrentCamera
if camera == nil then return end
local signal = camera.AfterUpdateState
if signal == nil then
    print('当前运行时暂未提供 CameraUnit.AfterUpdateState')
    return
end
signal:Once(function(delta)
    print('相机更新完成，帧间隔:', delta)
end)

函数 (2)

GetPartsObscuringTarget

签名：GetPartsObscuringTarget(castPoints: Array, ignoreList: Array) -> Array<Unit> (遮挡视线的单位列表)

获取遮挡相机视线的单位列表。该函数接收 castPoints 与 ignoreList 两个数组参数，返回遮挡视线的单位列表（元素类型为 Unit）。

参数	类型	说明
castPoints	Array	射线检测目标点列表
ignoreList	Array	忽略的单位列表

返回值 Array<Unit> (遮挡视线的单位列表)

示例代码

读取目标点前的遮挡单位

-- @runtime client
local camera = game:GetService('World').CurrentCamera
if camera == nil then return end
local ok, obscuringParts = pcall(function()
    return camera:GetPartsObscuringTarget({ Vector3.New(0, 5, 20) }, {})
end)
obscuringParts = ok and obscuringParts or {}
for _, part in ipairs(obscuringParts) do
    print('遮挡单位:', part.Name)
end

ResetMovement

签名：ResetMovement() -> void

重置相机的移动状态。

返回值 void

示例代码

重置相机移动状态

-- @runtime client
local world = game:GetService("World")
-- 通过 World 获取当前使用的相机实例
local camera = world.CurrentCamera
if camera == nil then return end

-- 记录调用前的位置，便于对比调用结果
local beforePos = camera.Position
print("重置前相机位置:", beforePos)

-- 清空相机当前累积的移动状态，例如角色被传送到新位置后调用
camera:ResetMovement()

local afterPos = camera.Position
print("重置后相机位置:", afterPos)