GFCameraOrbitInput3D¶
API Reference / Camera / 类索引
- 路径：
addons/gf/extensions/camera/nodes/gf_camera_orbit_input_3d.gd - 模块：
Camera - 继承：
Node - API：
public - 类别：运行时服务 (
runtime_service) - 首次版本：
3.23.0
通用 3D 环绕相机输入桥接节点。 将 GFInputMappingUtility 的可配置动作值或鼠标拖拽转换为 GFCameraOrbitRig3D 的角度和距离增量。 它不创建输入上下文，也不定义项目动作绑定。
成员概览¶
| 类型 | 名称 | 签名 |
|---|---|---|
| 枚举 | UpdateMode |
enum UpdateMode |
| 属性 | enabled |
var enabled: bool = true |
| 属性 | orbit_rig_path |
var orbit_rig_path: NodePath = NodePath("") |
| 属性 | update_mode |
var update_mode: UpdateMode = UpdateMode.IDLE |
| 属性 | use_input_mapping |
var use_input_mapping: bool = false |
| 属性 | node_context_path |
var node_context_path: NodePath = NodePath("") |
| 属性 | orbit_action_id |
var orbit_action_id: StringName = &"camera_orbit" |
| 属性 | zoom_action_id |
var zoom_action_id: StringName = &"camera_zoom" |
| 属性 | orbit_degrees_per_second |
var orbit_degrees_per_second: float = 120.0 |
| 属性 | zoom_units_per_second |
var zoom_units_per_second: float = 8.0 |
| 属性 | invert_y |
var invert_y: bool = false |
| 属性 | mouse_orbit_enabled |
var mouse_orbit_enabled: bool = false |
| 属性 | mouse_button |
var mouse_button: MouseButton = MOUSE_BUTTON_RIGHT |
| 属性 | mouse_degrees_per_pixel |
var mouse_degrees_per_pixel: float = 0.15 |
| 属性 | mouse_zoom_enabled |
var mouse_zoom_enabled: bool = false |
| 属性 | mouse_wheel_step |
var mouse_wheel_step: float = 1.0 |
| 属性 | consume_mouse_input |
var consume_mouse_input: bool = true |
| 属性 | input_mapping_utility |
var input_mapping_utility: GFInputMappingUtility = null |
| 方法 | get_orbit_rig |
func get_orbit_rig() -> GFCameraOrbitRig3D: |
| 方法 | set_input_mapping_utility |
func set_input_mapping_utility(utility: GFInputMappingUtility) -> void: |
| 方法 | process_input |
func process_input(delta: float) -> bool: |
| 方法 | apply_orbit_vector |
func apply_orbit_vector(value: Vector2, scale: float = 1.0) -> bool: |
| 方法 | apply_zoom_value |
func apply_zoom_value(value: float, scale: float = 1.0) -> bool: |
| 方法 | get_debug_snapshot |
func get_debug_snapshot() -> Dictionary: |
枚举¶
UpdateMode¶
- API：
public
enum UpdateMode { ## 在 _process 中读取输入。 IDLE, ## 在 _physics_process 中读取输入。 PHYSICS, ## 只在 process_input() 被显式调用时读取输入。 MANUAL, }
输入自动处理模式。
属性¶
enabled¶
- API：
public
是否启用输入桥接。
orbit_rig_path¶
- API：
public
要控制的环绕 Rig。为空时使用父节点中的 GFCameraOrbitRig3D。
update_mode¶
- API：
public
自动处理模式。
use_input_mapping¶
- API：
public
是否从 GFInputMappingUtility 读取动作值。默认关闭，项目应显式启用并配置动作 ID。
node_context_path¶
- API：
public
可选 GFNodeContext 路径。设置后会从该上下文获取 GFInputMappingUtility。
orbit_action_id¶
- API：
public
环绕输入动作 ID。动作值应为 Vector2。
zoom_action_id¶
- API：
public
缩放输入动作 ID。动作值应为 float 或 bool。
orbit_degrees_per_second¶
- API：
public
每秒环绕角速度，单位度。
zoom_units_per_second¶
- API：
public
每秒缩放速度，单位距离。
invert_y¶
- API：
public
是否反转垂直环绕输入。
mouse_orbit_enabled¶
- API：
public
是否启用鼠标拖拽环绕。默认关闭，避免框架节点隐式接管项目输入。
mouse_button¶
- API：
public
鼠标拖拽环绕使用的按键。
mouse_degrees_per_pixel¶
- API：
public
鼠标每像素对应的角度。
mouse_zoom_enabled¶
- API：
public
是否启用鼠标滚轮缩放。默认关闭，避免框架节点隐式接管项目输入。
mouse_wheel_step¶
- API：
public
鼠标滚轮每格缩放距离。
consume_mouse_input¶
- API：
public
鼠标输入被应用后是否标记为已处理。
input_mapping_utility¶
- API：
public
显式注入的输入映射工具。为空时尝试从 node_context_path 或父级 GFNodeContext 获取。
方法¶
get_orbit_rig¶
- API：
public
获取当前控制的环绕 Rig。
返回：环绕 Rig；不存在时返回 null。
set_input_mapping_utility¶
- API：
public
显式设置输入映射工具。
参数：
| 名称 | 说明 |
|---|---|
utility |
输入映射工具；传 null 表示回退到上下文查找。 |
process_input¶
- API：
public
读取输入映射并推进环绕 Rig。
参数：
| 名称 | 说明 |
|---|---|
delta |
本帧时间增量（秒）。 |
返回：应用了任意输入时返回 true。
apply_orbit_vector¶
- API：
public
应用二维环绕输入。
参数：
| 名称 | 说明 |
|---|---|
value |
x 为 yaw 输入，y 为 pitch 输入。 |
scale |
输入缩放量，通常是每秒速度乘以 delta。 |
返回：成功应用时返回 true。
apply_zoom_value¶
- API：
public
应用一维缩放输入。
参数：
| 名称 | 说明 |
|---|---|
value |
缩放输入；正数拉远，负数拉近。 |
scale |
输入缩放量，通常是每秒速度乘以 delta。 |
返回：成功应用时返回 true。
get_debug_snapshot¶
- API：
public
获取输入桥接调试快照。
返回：调试快照。
结构：
return: Dictionary，包含 enabled、update_mode、use_input_mapping、orbit_action_id、zoom_action_id、has_rig 和 has_input_mapping。