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

AudioListener3D

节点继承关系

继承链：Node -> AudioListener3D

Node

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

定义

AudioListener3D 是 3D 世界中的"耳朵"。它定义了"听声音的人"在 3D 空间中的位置和朝向。AudioStreamPlayer3D 播放的声音，就是根据声源（播放器）和这只"耳朵"之间的距离、方向来计算音量和立体声效果的。

一句话理解：如果 AudioStreamPlayer3D 是 3D 世界里的"喇叭"，那 AudioListener3D 就是"你的耳朵"——声音的大小、方向甚至高度感都取决于喇叭和耳朵之间的相对位置。

想象你戴着 VR 头盔在虚拟世界里走动。你的耳朵所在的位置就是 AudioListener3D。当你面前有个篝火，你会听到篝火声来自前方；当你转身 180 度，篝火声就到了背后；当你抬头看天上的鸟，鸟叫声就从上方传来。这一切的空间感都是 AudioListener3D 配合 AudioStreamPlayer3D 共同实现的。

使用频率：★★ 偶尔使用（大多数情况不需要手动添加）

节点用途

• 定义 3D 空间中"听声音的人"的位置和朝向
• 让 AudioStreamPlayer3D 的空间音效生效
• 在需要自定义监听位置时使用（比如跟随非摄像机物体）

使用场景

典型场景

• Camera3D 默认自带：绝大多数情况下你不需要手动添加 AudioListener3D，因为 Camera3D 默认就带了一个。你能看到什么视角，"耳朵"就在那个位置。
• 分屏游戏：两个玩家各有一个 Camera3D，各自带着自己的 AudioListener3D，这样每个玩家听到的声音都是基于自己视角的空间音效。
• VR 游戏：VR 头盔的位置就是监听器位置，需要确保 AudioListener3D 跟随头盔移动和旋转。
• 自定义监听位置：比如声音不跟随摄像机，而是跟随玩家角色的头部。

不适用场景

• 如果你只需要默认的监听行为（声音跟着摄像机走），不需要手动添加。
• 2D 游戏请使用 AudioListener2D。

常用节点搭配

搭配节点	用途	必需？
Camera3D	自带 AudioListener3D，通常不需要额外添加	通常已有
AudioStreamPlayer3D	空间音效需要至少一个监听器才能生效	是（配对使用）
XRNode3D（VR）	VR 游戏中监听器跟随头部位置	视需求

生效必备素材/资源

AudioListener3D 本身不需要任何外部资源。但要让它的空间音效功能有意义，场景中需要有 AudioStreamPlayer3D 节点。

节点属性与信号

监听器属性

属性	类型	默认值	继承自	说明
Current	bool	true	—	是否是当前激活的监听器。场景中同一时间只能有一个激活的 AudioListener3D

注意

一个场景中同一时间只应该有一个 Current = true 的 AudioListener3D。如果有多个，Godot 会使用最后一个激活的监听器，结果可能不符合预期。

信号

AudioListener3D 没有自定义信号。

常用方法

AudioListener3D 没有自定义方法，它只有继承自 Node 的通用方法。

代码示例

VR 游戏中的监听器跟随

C

using Godot;

public partial class VRPlayer : Node3D
{
    private AudioListener3D _headListener;

    public override void _Ready()
    {
        // 在 XR 摄像机（头部）上添加监听器
        // 这样声音会跟随玩家的头部朝向变化
        var xrCamera = GetNode<XRCamera3D>("XROrigin3D/XRCamera3D");

        _headListener = new AudioListener3D();
        _headListener.Current = true;
        xrCamera.AddChild(_headListener);
    }
}

GDScript

extends Node3D

var _head_listener: AudioListener3D

func _ready():
    # 在 XR 摄像机（头部）上添加监听器
    # 这样声音会跟随玩家的头部朝向变化
    var xr_camera = $XROrigin3D/XRCamera3D

    _head_listener = AudioListener3D.new()
    _head_listener.current = true
    xr_camera.add_child(_head_listener)

切换监听器（多角色视角）

C

using Godot;

public partial class ViewSwitcher : Node
{
    [Export] public AudioListener3D[] AllListeners;

    private int _activeIndex;

    /// <summary>
    /// 切换到下一个角色的视角和监听器
    /// </summary>
    public void SwitchToNextView()
    {
        // 关闭当前监听器
        AllListeners[_activeIndex].Current = false;

        // 切换到下一个
        _activeIndex = (_activeIndex + 1) % AllListeners.Length;

        // 激活新监听器
        AllListeners[_activeIndex].Current = true;
        GD.Print($"切换到监听器 {_activeIndex}");
    }
}

GDScript

extends Node

@export var all_listeners: Array[AudioListener3D] = []

var _active_index: int = 0

## 切换到下一个角色的视角和监听器
func switch_to_next_view():
    # 关闭当前监听器
    all_listeners[_active_index].current = false

    # 切换到下一个
    _active_index = (_active_index + 1) % all_listeners.size()

    # 激活新监听器
    all_listeners[_active_index].current = true
    print("切换到监听器 ", _active_index)

在角色头部添加自定义监听器

C

using Godot;

public partial class Player3DWithListener : CharacterBody3D
{
    private AudioListener3D _listener;

    public override void _Ready()
    {
        // 在角色身体上添加监听器
        // 适合第三人称视角，声音跟随角色而非摄像机
        _listener = new AudioListener3D();
        _listener.Current = true;
        AddChild(_listener);

        // 把监听器位置稍微抬高（模拟耳朵高度）
        _listener.Position = new Vector3(0, 1.7f, 0);
    }
}

GDScript

extends CharacterBody3D

var _listener: AudioListener3D

func _ready():
    # 在角色身体上添加监听器
    # 适合第三人称视角，声音跟随角色而非摄像机
    _listener = AudioListener3D.new()
    _listener.current = true
    add_child(_listener)

    # 把监听器位置稍微抬高（模拟耳朵高度）
    _listener.position = Vector3(0, 1.7, 0)