最后同步日期：2026-04-15 | Godot 官方原文 — VisibleOnScreenEnabler3D

VisibleOnScreenEnabler3D

节点继承关系

继承链：Node -> Node3D -> VisibleOnScreenEnabler3D

Node

类型	名称	说明
属性	Name	节点名称
属性	ProcessMode	处理模式（始终 / 暂停时 / 仅编辑器）
属性	ProcessPriority	处理优先级，数字越小越先执行
信号	ready	节点进入场景树并准备就绪
信号	tree_entered	节点进入场景树
信号	tree_exited	节点完全离开场景树
方法	GetNode<T>()	按路径获取子节点
方法	AddChild()	添加子节点
方法	RemoveChild()	移除子节点
方法	QueueFree()	帧结束后释放节点
方法	GetParent()	获取父节点

定义

VisibleOnScreenEnabler3D 是 VisibleOnScreenEnabler2D 的3D版本。它会自动检测自己是否在3D摄像机的视野内，并根据结果自动开启或关闭目标节点。

简单说：3D版本的自动视野控制器。

使用频率：★★ 偶尔使用

节点用途

• 3D性能优化：屏幕外的3D物体自动停止计算
• 自动动画控制：屏幕外角色自动暂停动画
• 批量性能管理：给所有NPC加上此节点，自动管理性能

使用场景

场景	说明
开放世界	远处的NPC自动停止AI计算
大型场景	屏幕外的装饰物自动停止动画
性能优化	无需写代码，直接挂上即可

常用节点搭配

搭配节点	搭配方式
任意 Node3D	通过 enable_node_path 属性指向目标节点

生效必备素材/资源

需要设置 enable_node_path 属性。

节点属性与信号

属性

属性	类型	默认值	继承自	说明
enable_node_path	NodePath	NodePath("..")	VisibleOnScreenEnabler3D	要控制的目标节点路径
physics_process	bool	true	VisibleOnScreenEnabler3D	是否自动控制物理处理
process	bool	true	VisibleOnScreenEnabler3D	是否自动控制帧处理
input	bool	false	VisibleOnScreenEnabler3D	是否自动控制输入处理

信号

信号	参数	说明
screen_entered	无	节点进入屏幕时触发
screen_exited	无	节点离开屏幕时触发

常用方法

方法	返回值	说明
IsOnScreen()	bool	当前是否在屏幕上可见

代码示例

C

// C# - 3D自动性能优化
// 场景树组织方式：
// NPC (CharacterBody3D)
//   └── VisibleOnScreenEnabler3D
//        enable_node_path = ".."
//        physics_process = true
//        process = true
using Godot;

public partial class NPC : CharacterBody3D
{
    private VisibleOnScreenEnabler3D _enabler;

    public override void _Ready()
    {
        _enabler = GetNode<VisibleOnScreenEnabler3D>("VisibleOnScreenEnabler3D");
    }
}

GDScript

# GDScript - 3D自动性能优化
# 场景树组织方式：
# NPC (CharacterBody3D)
#   └── VisibleOnScreenEnabler3D
#        enable_node_path = ".."
extends CharacterBody3D

@onready var enabler: VisibleOnScreenEnabler3D = $VisibleOnScreenEnabler3D