roblox-camera

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

When to Load

加载时机

Load when scripting custom camera behavior (cutscenes, third-person follow, custom rotation), manipulating

CFrame

for placement/rotation, raycasting from the screen, or building a non-default player view. Client-only.

在编写自定义相机行为（过场动画、第三人称跟随、自定义旋转）、操控

CFrame

进行位置/旋转调整、从屏幕发射射线，或构建非默认玩家视角时加载。仅客户端可用。

Quick Reference

快速参考

The Camera:

workspace.CurrentCamera

— one per client. Set

CameraType = Scriptable

to disable defaults and take full control. Without it, defaults overwrite your CFrame every frame.

CameraType:

Fixed

Attach

Watch

Track

Follow

(subject-following),

Custom

(default),

Scriptable

(no default),

Orbital

(fixed Y, rotates around player).

CameraSubject

cannot be

nil

— setting it reverts.

Key properties:

CFrame

CameraSubject

FieldOfView

(deg),

FieldOfViewMode

(

Vertical

Diagonal

NearPlaneZ

ViewportSize

HeadLocked

HeadScale

Focus

CFrame essentials:

luau

CFrame.new(pos)
CFrame.lookAt(at, lookAt, up?)                 -- preferred over deprecated CFrame.new(pos, lookAt)
CFrame.Angles(rx, ry, rz)                      -- XYZ Euler (radians)
cf * Vector3.new(0, 0, 10)                     -- local offset → world
cf:Lerp(goal, alpha)                           -- 0..1 linear interp
cf.LookVector / RightVector / UpVector         -- world-space unit axes

Custom camera loop — always

RenderStepped

, never

Heartbeat

luau

camera.CameraType = Enum.CameraType.Scriptable
RunService.RenderStepped:Connect(function(dt)
    local desired = CFrame.lookAt(head.Position - offset, head.Position)
    camera.CFrame = camera.CFrame:Lerp(desired, math.min(dt * 10, 1))
end)

Raycasting from camera:

camera:ScreenPointToRay(mx, my)

(accounts for GUI inset) vs

camera:ViewportPointToRay(mx, my)

(raw, NO inset).

ScreenPointToRay

returns a unit Ray (1 stud) — multiply

Direction

by length for actual raycast.

Pitfalls:

Client-only. Server sets silently dropped.
Without
```
Scriptable
```
, defaults overwrite your CFrame every frame.
```
RenderStepped
```
for camera (visual sync).
```
Heartbeat
```
adds 1-frame lag.
```
Camera.CFrame
```
lacks VR head rotation — use
```
GetRenderCFrame()
```
for true view.
```
SetRoll
```
is outdated — apply roll via
```
CFrame.Angles(0, 0, roll)
```
on CFrame.
```
CameraSubject = nil
```
reverts to previous.
```
CFrame.new(pos, lookAt)
```
is legacy (back-compat only) — use
```
CFrame.lookAt(at, lookAt)
```
for new code.

ScreenPointToRay

≠

ViewportPointToRay

(GUI inset). Use

ScreenPointToRay

for mouse input.

See

references/full.md

for first/third-person recipes, cutscenes, screen shake, mouse-look, full API.

相机：

workspace.CurrentCamera

— 每个客户端一个实例。将

CameraType

设置为

Scriptable

可禁用默认行为，获得完全控制权。若不设置，默认行为会每帧覆盖你的CFrame设置。

CameraType枚举：

Fixed

、

Attach

Watch

Track

Follow

（跟随目标）、

Custom

（默认）、

Scriptable

（无默认行为）、

Orbital

（Y轴固定，围绕玩家旋转）。

CameraSubject

不能设为

nil

— 设置为

nil

会恢复之前的设置。

关键属性：

CFrame

、

CameraSubject

、

FieldOfView

（度数）、

FieldOfViewMode

（

Vertical

Diagonal

）、

NearPlaneZ

、

ViewportSize

、

HeadLocked

、

HeadScale

、

Focus

。

CFrame核心用法：

luau

CFrame.new(pos)
CFrame.lookAt(at, lookAt, up?)                 -- 优先使用此方法，替代已弃用的CFrame.new(pos, lookAt)
CFrame.Angles(rx, ry, rz)                      -- XYZ欧拉角（弧度）
cf * Vector3.new(0, 0, 10)                     -- 本地偏移 → 世界坐标
cf:Lerp(goal, alpha)                           -- 0到1之间的线性插值
cf.LookVector / RightVector / UpVector         -- 世界空间单位轴向量

自定义相机循环 — 务必使用

RenderStepped

，绝不要用

Heartbeat

：

luau

camera.CameraType = Enum.CameraType.Scriptable
RunService.RenderStepped:Connect(function(dt)
    local desired = CFrame.lookAt(head.Position - offset, head.Position)
    camera.CFrame = camera.CFrame:Lerp(desired, math.min(dt * 10, 1))
end)

从相机发射射线：

camera:ScreenPointToRay(mx, my)

（考虑GUI内边距） vs

camera:ViewportPointToRay(mx, my)

（原始坐标，不考虑内边距）。

ScreenPointToRay

返回单位射线（1 studs）—— 需将

Direction

乘以长度以获得实际射线。

注意事项：

仅客户端可用。服务器端设置会被静默丢弃。
若未设置
```
Scriptable
```
，默认行为会每帧覆盖你的CFrame设置。
相机需使用
```
RenderStepped
```
（视觉同步）。使用
```
Heartbeat
```
会增加1帧延迟。
```
Camera.CFrame
```
不包含VR头部旋转 — 需使用
```
GetRenderCFrame()
```
获取真实视角。
```
SetRoll
```
已过时 — 需通过在CFrame上应用
```
CFrame.Angles(0, 0, roll)
```
来设置旋转。
```
CameraSubject = nil
```
会恢复之前的设置。
```
CFrame.new(pos, lookAt)
```
为旧版方法（仅用于向后兼容）—— 新代码请使用
```
CFrame.lookAt(at, lookAt)
```
。
```
ScreenPointToRay
```
≠
```
ViewportPointToRay
```
（区别在于是否考虑GUI内边距）。鼠标输入请使用
```
ScreenPointToRay
```
。

更多第一/第三人称实现方案、过场动画、屏幕震动、鼠标视角控制及完整API，请查看

references/full.md

。