GFGravityProbe3D¶
API Reference / Physics / 类索引
- 路径：
addons/gf/extensions/physics/nodes/gf_gravity_probe_3d.gd - 模块：
Physics - 继承：
Node3D - API：
public - 类别：运行时服务 (
runtime_service) - 首次版本：
3.17.0
通用 3D 重力采样器。 从场景树分组中采样 GFGravityField3D 或任何暴露 get_acceleration_at() 方法的对象，并按组合策略计算当前位置处的加速度、上下方向。
成员概览¶
| 类型 | 名称 | 签名 |
|---|---|---|
| 枚举 | CombinationMode |
enum CombinationMode |
| 属性 | field_group |
var field_group: StringName = &"gf_gravity_field_3d" |
| 属性 | combination_mode |
var combination_mode: CombinationMode = CombinationMode.SUM |
| 属性 | use_fallback_when_empty |
var use_fallback_when_empty: bool = true |
| 属性 | fallback_acceleration |
var fallback_acceleration: Vector3 = Vector3.DOWN * 9.8 |
| 属性 | cache_samples_per_frame |
var cache_samples_per_frame: bool = true |
| 属性 | last_acceleration |
var last_acceleration: Vector3 = Vector3.ZERO |
| 方法 | sample |
func sample() -> Vector3: |
| 方法 | sample_fields |
func sample_fields(fields: Array) -> Vector3: |
| 方法 | sample_field_provider |
func sample_field_provider(candidate_provider: Object, options: Dictionary = {}) -> Vector3: |
| 方法 | get_down_direction |
func get_down_direction() -> Vector3: |
| 方法 | get_up_direction |
func get_up_direction() -> Vector3: |
| 方法 | invalidate_cache |
func invalidate_cache() -> void: |
枚举¶
CombinationMode¶
- API：
public - 首次版本：
3.17.0
enum CombinationMode {
## 汇总所有有效力场的加速度。
SUM,
## 只使用当前点加速度长度最大的力场。
STRONGEST,
## 只汇总当前点非零加速度中最高优先级的力场。
HIGHEST_PRIORITY,
}
多个力场重叠时的采样组合策略。
属性¶
field_group¶
- API：
public - 首次版本：
3.17.0
要采样的力场分组。
combination_mode¶
- API：
public - 首次版本：
3.17.0
多个力场重叠时的组合策略。
use_fallback_when_empty¶
- API：
public - 首次版本：
3.17.0
找不到力场时是否返回 fallback_acceleration。
fallback_acceleration¶
- API：
public - 首次版本：
3.17.0
找不到力场时使用的默认加速度。
cache_samples_per_frame¶
- API：
public - 首次版本：
3.17.0
同一帧、同一位置重复 sample() 时是否复用上次结果。
last_acceleration¶
- API：
public - 首次版本：
3.17.0
最近一次 sample() 得到的加速度。
方法¶
sample¶
- API：
public - 首次版本：
3.17.0
采样场景树分组中的所有力场。
返回：按 combination_mode 组合后的加速度。
sample_fields¶
- API：
public - 首次版本：
3.17.0
采样指定力场列表。
参数：
| 名称 | 说明 |
|---|---|
fields |
力场对象列表。 |
返回：按 combination_mode 组合后的加速度。
结构：
fields: Array，包含 GFGravityField3D 或任何暴露 get_acceleration_at(Vector3) 的 Object。
sample_field_provider¶
- API：
public - 首次版本：
8.0.0
从候选 provider 采样力场。
参数：
| 名称 | 说明 |
|---|---|
candidate_provider |
暴露 get_candidate_objects(options) 的候选 provider。 |
options |
候选查询选项；未设置 method_name 时默认筛选 get_acceleration_at。 |
返回：按 combination_mode 组合后的加速度。
结构：
options: Dictionary passed to candidate_provider.get_candidate_objects(); method_name defaults to get_acceleration_at.
get_down_direction¶
- API：
public - 首次版本：
3.17.0
获取当前位置的向下方向。
返回：向下方向。
get_up_direction¶
- API：
public - 首次版本：
3.17.0
获取当前位置的向上方向。
返回：向上方向。
invalidate_cache¶
- API：
public - 首次版本：
7.0.0
清空当前帧采样缓存。