meta data for this page
  •  

📚 差别

这里会显示出您选择的修订版和当前版本之间的差别。

到此差别页面的链接

两侧同时换到之前的修订记录前一修订版
后一修订版		前一修订版
scripting:client:camera [2023/08/07 16:17] – bibiboxsscripting:client:camera [2025/07/18 09:45] (当前版本) – bibiboxs
行 1: 行 1:
 <markdown> <markdown>
 # Client/Camera # Client/Camera
 +
 +在`Camera`类操作中，开发者可修改**玩家本地状态**下的相机属性。
 +
 +[note2]
 +
 +**注意：控制==非玩家自身角色==外的其他对象或相机功能，均属于“观察模式”，在观察模式下无法操作玩家自身角色。**
 +
 +（例如：观察对象非玩家自身角色、其他相机观察模式等）
 +
 +[/note]
 +
 +
  
 ## Property ## Property
 +
 +### Camera.Mode
 +
 +> 设置本地玩家游戏视角模式（默认2.5D、第三人称）。
 +>
 +> 开发者可根据游戏需求，随时在代码中动态切换模式及配套的属性，需要注意的是，**不同视角模式可能有不同的属性控制，此文档中的属性并非完全适用于全部模式==（有些属性在特定模式下修改可能不会有效果）==。**
 +>
 +> **不同游戏视角会衍生不同的游戏效果，例如2.5D视角主要是平面射击，第三人称视角则是根据准星自由射击、交互等。**
 +
 +```javascript
 +Camera.Mode = 0;
 +```
 +
 +| ID   | 视角模式                                                     | 主要改动                                                  |
 +| ---- | ------------------------------------------------------------ | --------------------------------------------------------- |
 +| 0    | 默认视角，2.5D鸟瞰视角<br />示例：孤胆枪手、Moba类游戏、视角相对固定（可调） | `FocusPos`基于世界地面<br />（扩展属性：`Camera.D2Mode`） |
 +| 1    | 第一人称视角<br />示例：未转变者、我的世界                   | 此视角因效果比较特殊，所以许多属性修改并不会起作用        |
 +| 2    | 第三人称视角<br />示例：绝地求生、GTA系列、视角相对自由      | `FocusPos`基于屏幕中心（准星）                            |
 +
 +[note2]
 +**==注意：第一人称、第三人称视角仅在【鼠标隐藏】情况下正常镜头转向，以避免此视角下【激活或移动鼠标+操作UI】时晃动。==**
 +
 +**反之亦然，通常鸟瞰视角也应在【鼠标可见】情况下正常操作角色。**
 +（相关API：`GUI.SetCursorActive()`）
 +[/note]
 +
 +[note2]
 +**==注意：此属性的修改会改变`Camera`其他属性，已达到最终的视角预制效果（例如`Distance\Sway\Offset`等属性），如果开发者有多个自定义视角的修改需求，建议将修改视角封装成多个方法（如下代码示例）。==**
 +[/note]
 +
 +```javascript
 +//FPS
 +function ChangeCameraMode0()
 +{
 +    Camera.Mode = 1;
 +    Camera.Sway = 0;
 +}
 +
 +//TPS
 +function ChangeCameraMode1()
 +{
 +    Camera.Mode = 2;
 +    Camera.Sway = 1.0; //恢复漫游抖动
 +    Camera.Offset = Vector(0.2, 0.8, 0);
 +}
 +```
 +
 +
 +
 +### Camera.Pos
 +
 +> 获取（只读）相机焦点（游戏的眼睛）世界空间位置。
 +> 
 +> 游戏视角位置的控制应该使用`Camera.Mode | LookAt | RoamPoint`等方法进行引擎自动跟随，而不需要手动每帧编写跟随。
 +
 +```javascript
 +Camera.Pos: Vector
 +```
 +
 +
 +
 +### Camera.EulerAngle
 +
 +> 获取（只读）相机焦点（游戏的眼睛）世界空间角度。
 +
 +```javascript
 +Camera.EulerAngle: Vector
 +```
 +
 +
  
 ### Camera.Target ### Camera.Target
  
-> 设置一个相机跟随对象（Entity），通常用于跟随`Character\Vehicle`。+> 设置一个相机跟随对象（仅限`Character`对象），**多数情况下应该优先使用此属性**。
 > >
-> 设置为`null`时则不跟随任何对象。+> **设置非玩家自身角色对象可用于观察（观战），此模式下会跟随目标对象的角度，因此`VAngle | HAngle`修改可能不会生效。** 
 +> 
 +> 设置为`null`时则不跟随任何对象，转而尝试跟随`Camera.TargetPos`坐标。 
 + 
 +[note2] 
 + 
 +**注意：控制==非玩家自身角色==的其他对象，将切换至“观察模式”（`Camera.IsObserver == true`）。** 
 + 
 +[/note]
  
 ```javascript ```javascript
行 14: 行 104:
 if(target != null) Camera.Target = target; if(target != null) Camera.Target = target;
 ``` ```
 +
 +
 +
 +### Camera.TargetPos
 +
 +> 设置一个相机目标位置坐标（Entity），如果`TargetPos`被激活设置，`Camera.Target`将会被自动置空（两个属性无法同时兼容）。
 +>
 +> 如果`Camera.Target`存在对象（优先），即使`TargetPos`属性不为空，也仍然只会跟随`Camera.Target`而不是`Camera.TargetPos`。
 +
 +```javascript
 +Camera.TargetPos = Vector(0, 0, 0);
 +```
 +
 +
 +
 +### Camera.IsObserver
 +
 +> 获取当前相机是否为**观察模式**。
 +>
 +> **注意：控制==非玩家自身角色==外的**其他对象**或相机功能，均属于“观察模式”**
 +
 +```javascript
 +Camera.IsObserver: bool //Camera.Target isn't Owner Character
 +```
 +
 +
 +
 +### Camera.IsIndoors
 +
 +> 获取当前相机是否为**处于室内**（相机上方被物体遮挡）。
 +
 +```javascript
 +Camera.IsIndoors: bool
 +```
 +
  
  
行 20: 行 145:
 > 设置相机跟随对象的**本地坐标偏移**，默认为`Vector(0, 0, 0)`，可用于调整相机方向偏移。 > 设置相机跟随对象的**本地坐标偏移**，默认为`Vector(0, 0, 0)`，可用于调整相机方向偏移。
 > >
 +> **注意：由于第一人称视角的特殊性，此属性将被忽略。**
  
 ```javascript ```javascript
 Camera.Offset = Vector(0, 2, 0); //相机高度偏上2.0 Camera.Offset = Vector(0, 2, 0); //相机高度偏上2.0
 +```
 +
 +
 +
 +### Camera.D2Mode
 +
 +![](asset:1718665560544.webp)
 +
 +> 设置相机**2D渲染方式**开关，激活后相机将以正交视角渲染。
 +>
 +> **注意：此模式更适合搭配用于`Camera.Mode = 0`鸟瞰2.5D视角。**
 +
 +[note3]
 +
 +当2D渲染开启后，部分有关Camera的属性将会发生变化，可能需要手动将`Fov | Distance...`等属性调整为**更适合2D渲染**的数值。
 +
 +[/note]
 +
 +```javascript
 +Camera.D2Mode = false; //bool
 +```
 +
 +```javascript
 +//2DMode example
 +Camera.Mode = 0;
 +Camera.Offset = Vector(0, 1, 0);
 +Camera.Distance = 3; //3 = 30(fixed)
 +Camera.Sway = 0;
 +Camera.SmoothTime = 0.3;
 +Camera.DistanceSpeed = 2;
 +Camera.AutoFix = false; //Disable Rotate
 +Camera.ForwardMode = false; //Disable Rotate
 +Camera.VAngle = 55; //2.5D
 +Camera.FOV = 0.8; //2D Mode(Distance)
 +Camera.D2Mode = true; //Wake
 +GUI.SetCursorActive(true);
 +```
 +
 +
 +
 +### Camera.SlowMode
 +
 +> 设置相机**慢动作模式（半速插值）**开关（不支持**常规跟随视角**），激活后相机将以慢速延迟移动视角。
 +>
 +> **注意：此模式更适合搭配`FreeMode`自由视角模式，在漫游模式下鼠标将会差值慢速移动，适合拍摄视频、漫游浏览。**
 +
 +```javascript
 +Camera.SlowMode = false; //bool
 +```
 +
 +
 +
 +### Camera.FreeMode
 +
 +> 设置相机**自由漫游模式**开关，激活后相机将允许玩家自由移动视角（移动、旋转速度同步受到`Camera`属性影响）。
 +>
 +> **注意：此模式优先级最高，启用后将暂时屏蔽其他相机模式，同时开启模式并不会屏蔽控制角色移动（如果存在操纵角色\载具，仍然可进行移动等行为，如果不希望这样，可以自行编写相关冻结逻辑（Frozen），以达到漫游模式时停止控制）。**
 +
 +[note2]
 +**提示：此模式不会修改鼠标可见状态，因此通常应该手动关闭鼠标可见，已达到随鼠标自由旋转。**
 +
 +此模式下移动、旋转速度受到`SmoothTime`、`RotateSpeed`影响。
 +
 +[/note]
 +
 +```javascript
 +Camera.FreeMode = false; //bool
 +```
 +
 +
 +
 +### Camera.ForwardMode
 +
 +> 设置相机**向前跟随模式**开关，激活后相机将始终向`Target`正前角度靠近。
 +>
 +> **注意：此选项需要`Camera.Target`存在目标才有意义。此功能只在`RoamPoint`或`BirdView`模式下生效。**
 +>
 +> **（如果希望在第一人称\第三人称使用类似功能，你可能找的是`Camera.AutoFix`）**
 +
 +```javascript
 +Camera.ForwardMode = false; //bool
 +```
 +
 +
 +
 +### Camera.AutoDistance
 +
 +> 设置相机**自动遮挡距离**开关，激活后相机在遮挡时保持可见距离（但不会调整实际`Distance`变量）。
 +
 +```javascript
 +Camera.AutoDistance = true; //bool
 +```
 +
 +
 +
 +### Camera.AutoFix
 +
 +> 设置相机**自动修正功能**开关，此功能可以修正有关相机的便捷化效果。
 +>
 +> **例如：玩家操作空闲超过X秒后，相机自动旋转至角色或载具的正前方。**
 +
 +```javascript
 +Camera.AutoFix = true; //bool
 +```
 +
 +
 +
 +### Camera.RotateSpeed
 +
 +> 设置相机**旋转角度**的插值速度（非鼠标灵敏度），默认为`2.0`。
 +>
 +> 此类属性仅对**鸟瞰视角、激活受支持的`SlowMode`视角、相机观察行为**等生效。
 +
 +```javascript
 +Camera.RotateSpeed = 2;
 +```
 +
 +
 +
 +### Camera.VAngle
 +
 +> 设置相机跟随的**上下角度**，默认为`0.0`（举例：设置`45.0`则为向下45度看，反之`-45.0`表示向上看）。
 +> 
 +> **注意：此方法更偏向于修改`Camera`自身的角度，如果玩家正在控制自身角色，实际上可能修改的是`player.FocusVAngle`（映射）。**
 +
 +```javascript
 +Camera.VAngle = 0.0;
 +```
 +
 +
 +
 +### Camera.HAngle
 +
 +> 设置相机跟随的**横向角度**，默认为`0.0`。
 +> 
 +> **注意：此方法更偏向于修改`Camera`自身的角度，如果玩家正在控制自身角色，实际上可能修改的是`player.FocusHAngle`（映射）。**
 +
 +```javascript
 +Camera.HAngle = 0.0;
 ``` ```
  
行 30: 行 295:
  
 > 设置相机跟随对象的距离，默认为`10.0`。 > 设置相机跟随对象的距离，默认为`10.0`。
 +>
 +> **注意：在开启`AutoDistance`属性后，因为其自动距离机制，可能不会完全按照`Distance`所设定的距离执行。**
  
 ```javascript ```javascript
-Camera.Distance = 10;+Camera.Distance = 10.0;
 ``` ```
  
行 39: 行 306:
 ### Camera.DistanceSpeed ### Camera.DistanceSpeed
  
-> 设置相机跟随对象距离的差值速度，默认为`1.0`。+> 设置相机跟随**对象距离**的差值速度，默认为`1.0`。
 > >
-> （设置新的`Distance`值后多久到达新距离）+> （设置新的`Distance`值后多久到达新距离）。
  
 ```javascript ```javascript
 Camera.DistanceSpeed = 1; Camera.DistanceSpeed = 1;
 +```
 +
 +
 +
 +### Camera.FOV
 +
 +> 设置相机FOV（默认`70.0`）。
 +>
 +
 +```javascript
 +Camera.FOV = 70.0;
 +```
 +
 +
 +
 +### Camera.FOVSpeed
 +
 +> 设置相机FOV变换速度（默认`3.0`）。
 +>
 +
 +```javascript
 +Camera.FOVSpeed = 3.0;
 ``` ```
  
行 51: 行 340:
 ### Camera.SmoothTime ### Camera.SmoothTime
  
-> 设置相机跟随对象的平滑速度，默认为`0.2`。+> 设置相机**部分模式**的平滑（移动）间隔速度，默认`0.2`（数值越小，速度越快）。 
 +>  
 +> **注意：常规视角（第一人称\第三人称）跟随方式，**不会收到此数值的影响**，此数值适用于相机其他观察模式。**
  
 ```javascript ```javascript
 Camera.SmoothTime = 0.2; Camera.SmoothTime = 0.2;
 +```
 +
 +
 +
 +### Camera.Flip
 +
 +> 设置相机临时反转模式，默认为`false`，此功能仅在**第一人称、第三人称**生效，并且可通过玩家【鼠标中键】**优先**开关。
 +
 +```javascript
 +Camera.Flip = false;
 +```
 +
 +
 +
 +### Camera.Sway
 +
 +> 设置相机漫游摇晃幅度，默认为`1.0`。
 +
 +```javascript
 +Camera.Sway = 1.0;
 +```
 +
 +
 +
 +### Camera.SwaySpeed
 +
 +> 设置相机漫游摇晃速度，默认为`0.1`。
 +
 +```javascript
 +Camera.SwaySpeed = 0.1;
 +```
 +
 +
 +
 +### Camera.TiltShift
 +
 +> 设置相机镜头边缘虚化（移轴），范围`0.0~25.0`。
 +
 +```javascript
 +Camera.TiltShift = 0;
 ``` ```
  
行 61: 行 392:
 ### Camera.Vignette ### Camera.Vignette
  
-> 设置相机镜头边缘阴影（强度），默认范围`0.0~1.0`。+> 设置相机镜头边缘阴影（强度），范围`0.0~2.0`。
  
 ```javascript ```javascript
行 81: 行 412:
 ### Camera.LensLUT ### Camera.LensLUT
  
-> 设置相机镜头调色主题，默认范围`0~10`，设置为`0`则表示默认主题。+> 设置**相机镜头色彩滤镜**，设置为`0`表示原生滤镜，设置为`-1`表示地图默认滤镜。
  
 ```javascript ```javascript
 Camera.LensLUT = 0; Camera.LensLUT = 0;
 ``` ```
 +
 +
 +
 +### Camera.DefaultLensLUT
 +
 +> 获取地图默认**相机镜头色彩滤镜**（由地图作者设置的LUT）。
 +
 +```javascript
 +Camera.DefaultLensLUT: int
 +```
 +
 +
 +
 +### Camera.IsInWater
 +
 +> 获取相机是否在水中（水底状态）。
 +
 +```javascript
 +Camera.IsInWater: bool
 +```
 +
 +
 +
 +### Camera.LookAtMode
 +
 +> 获取相机是否正在`LookAt`焦点模式（使用`StartLookAt()`激活）。
 +
 +```javascript
 +Camera.LookAtMode: bool
 +```
 +
  
  
  
 ## Static Function ## Static Function
 +
 +### Camera.Focus()
 +
 +> 立即将相机定位到追踪目标位置，适用于希望立即到相机目标位置（不需要平移效果）时调用。
 +
 +```javascript
 +function Camera.Focus()
 +```
 +
 +
 +
 +### Camera.AddRoamPoint()
 +
 +> 增加一个相机漫游点**（相机优先级更高，但相比`FreeMode`低）**。
 +>
 +> 如果相机漫游点数量>0，相机将进入漫游模式，将按照漫游点坐标池循环移动相机（循环自动前往下一个点），通常至少添加2个点以上来使用。
 +>
 +> **注意：相机漫游运动仍然使用`Target`焦点跟随的方式，==因此漫游坐标并非实际相机本地位置，而是相机看向的【焦点位置】，`Distance`等属性仍然是有效的。==**
 +
 +```javascript
 +function Camera.AddRoamPoint( point: Vector )
 +```
 +
 +
 +
 +### Camera.RemoveRoamPoint()
 +
 +> 移除指定索引的相机漫游点（如果相机漫游点数量<=0，漫游模式将自动关闭）。
 +
 +```javascript
 +function Camera.RemoveRoamPoint( index: int )
 +```
 +
 +
 +
 +### Camera.GetRoamPoint()
 +
 +> 根据指定索引获取相机的漫游点坐标。
 +
 +```javascript
 +function Camera.GetRoamPoint( index: int ): Vector
 +```
 +
 +
 +
 +### Camera.GetCurrentRoamIndex()
 +
 +> 获取相机当前漫游点目标索引。
 +
 +```javascript
 +function Camera.GetCurrentRoamIndex(): int
 +```
 +
 +
 +
 +### Camera.GetRoamPointCount()
 +
 +> 获取当前相机漫游点的数量（如果相机漫游点数量<=0，表示漫游模式关闭）。
 +
 +```javascript
 +function Camera.GetRoamPointCount(): int
 +```
 +
 +
 +
 +### Camera.ClearAllRoamPoint()
 +
 +> 清空当前相机全部漫游点（自动关闭漫游模式）。
 +
 +```javascript
 +function Camera.ClearAllRoamPoint()
 +```
 +
 +
  
 ### Camera.SetImageEffectActive() ### Camera.SetImageEffectActive()
行 143: 行 579:
  
  
-### Camera.ScreenFade()+### Camera.SetCinematicBorder()
  
-> 执行一次相机全屏转场（`Alpha: 0 -> 1 -> 0`）。+> 设置屏幕电影模式边框开关，**在场景切换时不会重置**。
  
 ```javascript ```javascript
-function Camera.ScreenFade( time: float, middleTime = 0, color: Color = Color(0, 0, 0), onMiddle = null, ignoreHit: bool = true ) +function Camera.SetCinematicBorder( active: bool, time: float = 1.0 )
-/* +
- time：渐变时间（渐入>不透明>渐出），例如设置为2，则表示0~1秒变不透明，1~2秒变透明 +
- middleTime：不透明延迟时间，默认为0，否则将等待X秒后再进行透明渐变 +
- color：颜色，默认为黑色 +
- onMiddle：可选委托事件，当颜色完成不透明时调用 +
- ignoreHit：转场是否屏蔽点击，默认为true +
-*/+
 ``` ```
  
  
  
-### Camera.ScreenFadeIn()+### Camera.GetCinematicBorder()
  
-> 执行一次相机全屏渐入转场（`Alpha: 0 -> 1`）。+> 获取屏幕电影模式边框开关。
  
 ```javascript ```javascript
-function Camera.ScreenFadeIn( time: float, color: Color = Color(0, 0, 0), onComplete = null, ignoreHit: bool = true ) +function Camera.GetCinematicBorder(): bool
-/* +
- time：整体时间（渐入>不透明） +
- color：颜色，默认为黑色 +
- onComplete：可选委托事件，当颜色完成不透明时调用 +
- ignoreHit：转场是否屏蔽点击，默认为true +
-*/+
 ``` ```
  
  
  
-### Camera.ScreenFadeOut()+### Camera.Shake()
  
-> 执行一次相机全屏渐出转场（`Alpha: 1 -> 0`）。+> 激活一次相机Shake抖动效果。
  
 ```javascript ```javascript
-function Camera.ScreenFadeOut( time: float, color: Color = Color(0, 0, 0), onComplete = null, ignoreHit: bool = true ) +function Camera.Shake( strength: float = 1.0, time: float = 1.0 )
-/* +
- time：整体时间（不透明>渐出） +
- color：颜色，默认为黑色 +
- onComplete：可选委托事件，当颜色完成透明时调用 +
- ignoreHit：转场是否屏蔽点击，默认为true +
-*/+
 ``` ```
 +
 +
 +
 +### Camera.Punch()
 +
 +> 激活一次相机Punch力量抖动效果。
 +
 +```javascript
 +function Camera.Punch( strength: float = 1.0, time: float = 1.0 )
 +```
 +
 +
 +
 +### Camera.Shock()
 +
 +> 激活一次相机Shock冲击抖动效果。
 +
 +```javascript
 +function Camera.Shock( strength: float = 1.0, time: float = 1.0 )
 +```
 +
 +
 +
 +### Camera.StartLookAt()
 +
 +> 激活相机`LookAt`观察焦点模式，可用于让相机从A点看向B点。
 +>
 +> 注意：此方法改变的是相机本身，而不是传统的跟随焦点。
 +
 +```javascript
 +function Camera.StartLookAt( start: Vector, end: Vector, time: float = 1.0 )
 +```
 +
 +
 +
 +### Camera.StopLookAt()
 +
 +> 取消相机`LookAt`观察焦点模式。
 +
 +```javascript
 +function Camera.StopLookAt()
 +```
 +
 +
 +
 +### Camera.TestVisiblePoint()
 +
 +> 测试某坐标是否在相机可视范围内。
 +
 +```javascript
 +function Camera.TestVisiblePoint( pos: Vector ): bool
 +```
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
 +
  
  
 </markdown> </markdown>