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

AudioStreamPlayer3D

节点继承关系

继承链：Node -> AudioStreamPlayer3D

Node

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

定义

AudioStreamPlayer3D 是带有 3D 空间定位功能的音频播放节点。声音会根据它在 3D 世界中的位置和监听器（通常是摄像机）之间的距离、方向甚至运动速度发生变化，营造出真实的 3D 空间感。

一句话理解：它就像你在现实生活中听声音——你能判断声音从哪里来、离你多远、是在靠近还是在远离。

想象你在玩一个 3D 射击游戏，前面有个敌人在开枪。你戴着耳机，能清楚地听到枪声来自前方偏右的位置。如果你转身背对敌人，枪声就到了背后；如果敌人向你跑来，枪声会越来越大。这种逼真的声音效果就是 AudioStreamPlayer3D 做到的——它甚至还能模拟"多普勒效应"（就像救护车从你身边开过时，靠近时声音尖锐、远离时声音低沉）。

使用频率：★★★★ 常用（3D 游戏中经常用到）

节点用途

• 播放与 3D 位置相关的声音（脚步声、枪声、环境音）
• 根据距离自动衰减音量
• 实现真正的 3D 立体声效果（上下左右前后都能分辨）
• 模拟多普勒效应（声源快速移动时声音变调）
• 营造 3D 游戏中的沉浸感

使用场景

典型场景

• 3D 枪声/爆炸声：声音来自枪口/爆炸点的位置，随距离衰减。
• 角色脚步声：能通过声音判断敌人是从前方还是后方接近。
• NPC 对话：靠近 NPC 时声音清晰，走远了就模糊不清。
• 环境音效：远处的鸟叫声、流水声、风声，都有真实的距离感。
• 车辆/飞行器：配合多普勒效应，当物体高速经过时声音会变调。

不适用场景

• 背景音乐、UI 音效等不需要空间定位的声音 → 使用 AudioStreamPlayer
• 2D 游戏中的空间音效 → 使用 AudioStreamPlayer2D

常用节点搭配

搭配节点	用途	必需？
AudioListener3D	接收声音的"耳朵"	是（Camera3D 自带）
Camera3D	自带 AudioListener3D，是默认的监听位置	通常已有
CharacterBody3D / RigidBody3D	将播放器作为子节点跟随物体移动	视需求
Area3D	配合区域实现室内外音效切换	视需求

生效必备素材/资源

资源类型	格式	说明
音频文件	.ogg、.wav、.mp3	需要加载为 AudioStream 资源
AudioListener3D	—	场景中必须有至少一个激活的监听器，否则 3D 空间音效不会生效

提示

如果你已经用了 Camera3D，它默认就带了 AudioListener3D，不需要额外添加。只有在需要自定义监听位置时才需要手动添加 AudioListener3D。

节点属性与信号

音频属性

属性	类型	默认值	继承自	说明
Stream	AudioStream?	null	—	要播放的音频资源
VolumeDb	float	0.0	—	音量（分贝），0 是原始音量
PitchScale	float	1.0	—	播放速度和音调的缩放
Autoplay	bool	false	—	是否在场景加载后自动播放
Bus	StringName	"Master"	—	音频总线名称
MaxPolyphony	int	1	—	同时播放的最大声音数量
Playing	bool	false	—	是否正在播放（只读）
StreamPaused	bool	false	—	是否暂停

空间音频属性（3D 特有）

属性	类型	默认值	继承自	说明
UnitSize	float	10.0	—	声音响度的基准单位（米）。值越大，同样距离下声音衰减得越慢
MaxDistance	float	0.0	—	超过这个距离后声音完全听不到。0 表示不限制（由衰减模型决定）
AttenuationModel	AttenuationModelEnum	InverseDistance	—	衰减模型，决定声音如何随距离变小（见下表）
DopplerTracking	DopplerTrackingEnum	Disabled	—	多普勒效应追踪模式
AreaMask	uint	1	—	区域遮罩，只对匹配该遮罩的 AudioListener3D 产生空间效果

衰减模型说明

模型	说明	适用场景
InverseDistance	反距离衰减（默认）	大多数游戏场景，声音随距离自然变小
InverseSquareDistance	反平方距离衰减	模拟真实物理世界，声音衰减更快
Logarithmic	对数衰减	更柔和的衰减曲线，远距离声音仍然可闻
Linear	线性衰减	声音匀速变小，适合卡通风格游戏
Disabled	不衰减	声音在任何距离都一样大（此时相当于 AudioStreamPlayer）

多普勒效应说明

模式	说明
Disabled	不追踪，无多普勒效应
PhysicsStep	每个物理帧追踪位置变化（推荐）
IdleStep	每个空闲帧追踪位置变化

相关信息

多普勒效应是什么？想象救护车鸣着笛从你身边开过——靠近你时笛声变尖锐（频率变高），远离你时笛声变低沉（频率变低）。这就是多普勒效应，AudioStreamPlayer3D 可以自动模拟这种效果。

信号

信号	触发时机	说明
Finished	音频播放完毕时	非循环音频播完会触发

常用方法

方法	返回值	说明
Play(double fromPosition = 0.0)	void	从指定位置开始播放
Stop()	void	停止播放
Seek(double position)	void	跳到指定时间点
GetPlaybackPosition()	double	获取当前播放进度（秒）
SetStreamPaused(bool paused)	void	暂停或恢复播放

代码示例

3D 角色脚步声

C

using Godot;

public partial class Player3D : CharacterBody3D
{
    [Export] public AudioStream FootstepSound { get; set; }
    [Export] public float StepInterval { get; set; } = 0.45f;

    private AudioStreamPlayer3D _footstepPlayer;
    private double _stepTimer;

    public override void _Ready()
    {
        // 创建 3D 脚步声播放器，放在角色脚底位置
        _footstepPlayer = new AudioStreamPlayer3D();
        _footstepPlayer.Stream = FootstepSound;
        _footstepPlayer.UnitSize = 10.0f;      // 10 米为一个单位距离
        _footstepPlayer.MaxDistance = 50.0f;     // 50 米外听不到脚步声
        _footstepPlayer.AttenuationModel = AttenuationModel.InverseSquareDistance;
        _footstepPlayer.DopplerTracking = DopplerTracking.PhysicsStep;
        AddChild(_footstepPlayer);
    }

    public override void _PhysicsProcess(double delta)
    {
        Vector2 inputDir = Input.GetVector("ui_left", "ui_right", "ui_up", "ui_down");
        Vector3 velocity = Velocity;

        if (inputDir.LengthSquared() > 0.01f)
        {
            _stepTimer += delta;
            if (_stepTimer >= StepInterval)
            {
                _footstepPlayer.Play();
                _stepTimer = 0.0;
            }
        }
        else
        {
            _stepTimer = StepInterval;
        }
    }
}

GDScript

extends CharacterBody3D

@export var footstep_sound: AudioStream
@export var step_interval: float = 0.45

var _footstep_player: AudioStreamPlayer3D
var _step_timer: float

func _ready():
    # 创建 3D 脚步声播放器，放在角色脚底位置
    _footstep_player = AudioStreamPlayer3D.new()
    _footstep_player.stream = footstep_sound
    _footstep_player.unit_size = 10.0       # 10 米为一个单位距离
    _footstep_player.max_distance = 50.0    # 50 米外听不到脚步声
    _footstep_player.attenuation_model = AudioStreamPlayer3D.AttenuationModel.INVERSE_SQUARE_DISTANCE
    _footstep_player.doppler_tracking = AudioStreamPlayer3D.DopplerTracking.PHYSICS_STEP
    add_child(_footstep_player)

func _physics_process(delta):
    var input_dir = Input.get_vector("ui_left", "ui_right", "ui_up", "ui_down")

    if input_dir.length_squared() > 0.01:
        _step_timer += delta
        if _step_timer >= step_interval:
            _footstep_player.play()
            _step_timer = 0.0
    else:
        _step_timer = step_interval

3D 环境音效（篝火）

C

using Godot;

public partial class Campfire : Node3D
{
    private AudioStreamPlayer3D _cracklePlayer;

    public override void _Ready()
    {
        _cracklePlayer = new AudioStreamPlayer3D();
        _cracklePlayer.Stream = GD.Load<AudioStream>("res://assets/audio/campfire_crackle.ogg");
        _cracklePlayer.UnitSize = 5.0f;      // 篝火声传播范围小
        _cracklePlayer.MaxDistance = 30.0f;   // 30 米外听不到
        _cracklePlayer.VolumeDb = -5.0f;      // 稍微调低一点
        _cracklePlayer.AttenuationModel = AttenuationModel.Logarithmic;
        AddChild(_cracklePlayer);
        _cracklePlayer.Play();
    }
}

GDScript

extends Node3D

var _crackle_player: AudioStreamPlayer3D

func _ready():
    _crackle_player = AudioStreamPlayer3D.new()
    _crackle_player.stream = load("res://assets/audio/campfire_crackle.ogg")
    _crackle_player.unit_size = 5.0       # 篝火声传播范围小
    _crackle_player.max_distance = 30.0   # 30 米外听不到
    _crackle_player.volume_db = -5.0      # 稍微调低一点
    _crackle_player.attenuation_model = AudioStreamPlayer3D.AttenuationModel.LOGARITHMIC
    add_child(_crackle_player)
    _crackle_player.play()