Node API

Contents

Node API#

FmodAudioStreamPlayer#

Inherits: Node

used for 2D spatialization audio stream node.

Description#

FmodAudioStreamPlayer plays FmodAudioStream resources. It is suitable for background music, UI sounds, and audio that does not need spatial positioning.

When node will FmodServer gets specified bus FmodChannelGroup. if to specified bus, to Master bus.

Properties#

Type

Name

Default

Description

FmodAudioStream

stream

null

Audio stream.

bool

playing

false

Sets as true, sets as false stop.

bool

stream_paused

false

Pause current.

float

volume_db

0.0

Volume, unit as.

float

pitch_scale

1.0

Velocity and pitch.

bool

auto_play

false

Scene tree after.

bool

preload_on_set_stream

false

Sets stream when load internal FmodSound.

StringName

bus

“Master”

Output to audio bus name.

Signals#

Signals

Description

finished()

Emitted when playback ends naturally.

Methods#

void set_stream(stream: FmodAudioStream)#

Sets audio stream.

If current in, will stop current channel and state.

FmodAudioStream get_stream() const#

Returns current sets audio stream.

void play(from_position: float = 0.0)#

Specified position, unit as.

If internal channel, will channel and to specified position; otherwise will current stream creates FMOD channel.

bool preload_stream()#

Preloads the current stream by creating the internal FmodSound ahead of time to reduce first-play latency. Returns true if creation succeeds.

void seek(to_position: float)#

To specified playback position, unit as.

void stop()#

Stop and pause state.

void set_playing(playing: bool)#

Sets state.

true play(), false stop()

bool is_playing() const#

Returns true if internal channel in.

void set_stream_paused(paused: bool)#

Pause or resume current.

bool get_stream_paused() const#

Returns current pause state.

float get_playback_position() const#

Returns current playback position, unit as.

If internal channel, returns 0.0

void set_volume_db(volume_db: float)#

Sets volume, unit as.

If in, will synchronizes to underlying channel.

float get_volume_db() const#

Returns current volume, unit as.

void set_pitch_scale(pitch_scale: float)#

Sets velocity and pitch.

1.0 represents velocity, 2.0 represents velocity, 0.5 represents.

float get_pitch_scale() const#

Returns current velocity and pitch.

void set_auto_play(enable: bool)#

Sets in scene tree after.

State will.

bool is_autoplay_enabled() const#

Returns true if .

void set_preload_on_set_stream(enable: bool)#

Sets in stream when load.

bool is_preload_on_set_stream_enabled() const#

Returns true if when load.

void set_bus(bus: StringName)#

Sets output bus name.

StringName get_bus() const#

Returns current output bus name.

If sets bus in, returns "Master"

Example#

@onready var music: FmodAudioStreamPlayer = $FmodAudioStreamPlayer

func _ready() -> void:
    music.stream = FmodAudioStream.load_from_file("res://music/bgm.ogg", FmodAudioStream.MODE_STREAM)
    music.bus = "Music"
    music.volume_db = -6.0
    music.play()

func fade_out() -> void:
    var tween = create_tween()
    tween.tween_property(music, "volume_db", -40.0, 1.5)
    tween.tween_callback(music.stop)

FmodAudioStreamPlayer2D#

Inherits: Node2D

Audio stream node for 2D scenes with distance attenuation and panning.

Description#

FmodAudioStreamPlayer2D node in 2D position calculates volume attenuation and. will audio stream as 2D, distance attenuation node controls.

Position FmodServer 2D; if, current Camera2D

Properties#

Type

Name

Default

Description

FmodAudioStream

stream

null

Audio stream.

bool

playing

false

Sets as true, sets as false stop.

bool

stream_paused

false

Pause current.

float

volume_db

0.0

Volume, unit as.

float

pitch_scale

1.0

Velocity and pitch.

bool

autoplay

false

Scene tree after.

bool

preload_on_set_stream

false

Sets stream when load internal FmodSound.

float

max_distance

2000.0

Pixels distance after mute.

float

attenuation

1.0

Distance attenuation.

float

panning_strength

1.0

Left/right pan strength

StringName

bus

“Master”

Output to audio bus name.

int

area_mask

1

2D physics area mask.

int

max_polyphony

1

Maximum polyphony

Signals#

Signals

Description

finished()

Emitted when playback ends naturally.

Methods#

void set_stream(stream: FmodAudioStream)#

Sets audio stream.

If current in, will stop current channel and state.

FmodAudioStream get_stream() const#

Returns current sets audio stream.

void play(from_position: float = 0.0)#

Specified position, unit as.

Before will as audio stream adds FmodMode FMOD_MODE_2D and creates cache sound.

bool preload_stream()#

Preloads the current stream by creating the internal FmodSound ahead of time. Returns true if creation succeeds.

void seek(to_position: float)#

To specified playback position, unit as.

void stop()#

Stop and pause state.

void set_playing(playing: bool)#

Sets state.

bool is_playing() const#

Returns true if internal channel in.

void set_stream_paused(paused: bool)#

Pause or resume current.

bool get_stream_paused() const#

Returns current pause state.

float get_playback_position() const#

Returns current playback position, unit as.

void set_volume_db(volume_db: float)#

Sets volume, unit as.

Volume will to distance attenuation.

float get_volume_db() const#

Returns volume, unit as.

void set_volume_linear(volume_linear: float)#

Volume sets volume.

float get_volume_linear() const#

Volume returns volume.

void set_pitch_scale(pitch_scale: float)#

Sets velocity and pitch.

float get_pitch_scale() const#

Returns current velocity and pitch.

void set_autoplay(enable: bool)#

Sets in scene tree after.

bool is_autoplay_enabled() const#

Returns true if .

void set_preload_on_set_stream(enable: bool)#

Sets in stream when load.

bool is_preload_on_set_stream_enabled() const#

Returns true if when load.

void set_max_distance(pixels: float)#

Sets the maximum audible distance, in pixels.

0.0 will as 1.0

float get_max_distance() const#

Returns the maximum audible distance, in pixels.

void set_attenuation(curve: float)#

Sets distance attenuation.

Distance attenuation.

float get_attenuation() const#

Returns distance attenuation.

void set_panning_strength(panning_strength: float)#

Sets .

0.0 will as 0.0

float get_panning_strength() const#

Returns .

void set_bus(bus: StringName)#

Sets output bus name.

StringName get_bus() const#

Returns current output bus name.

If sets, returns "Master"

void set_area_mask(mask: int)#

Sets 2D.

int get_area_mask() const#

Returns 2D.

void set_max_polyphony(max_polyphony: int)#

Sets .

1 will as 1

int get_max_polyphony() const#

Returns .

bool has_stream_playback() const#

Returns true if internal channel object.

FmodChannel get_stream_playback() const#

Returns the internal playback channel for advanced control.

Example#

@onready var ambience: FmodAudioStreamPlayer2D = $FmodAudioStreamPlayer2D

func _ready() -> void:
    ambience.stream = FmodAudioStream.load_from_file("res://audio/river.ogg", FmodAudioStream.MODE_STREAM)
    ambience.bus = "Ambience"
    ambience.max_distance = 1200.0
    ambience.attenuation = 1.5
    ambience.panning_strength = 1.0
    ambience.play()

FmodAudioStreamPlayer3D#

Inherits: Node3D

Node for playing audio streams in 3D space.

Description#

FmodAudioStreamPlayer3D will sound as FMOD 3D channel, and synchronizes node global position, velocity, distance attenuation, distance filter and sets.

Suitable for spatialized audio such as ambient emitters, character voices, machinery, and moving sound sources.

Properties#

Type

Name

Default

Description

FmodAudioStream

stream

null

Audio stream.

int

attenuation_model

2

3D distance attenuation.

float

volume_db

0.0

Volume, unit as.

float

unit_size

1.0

FMOD attenuation distance.

float

pitch_scale

1.0

Velocity and pitch.

bool

playing

false

Sets as true, sets as false stop.

bool

auto_play

false

Scene tree after.

bool

preload_on_set_stream

false

Sets stream when load internal FmodSound.

bool

stream_paused

false

Pause current.

float

max_distance

10.0

Attenuation distance, distance as max_distance * unit_size

StringName

bus

“Master”

Output to audio bus name.

int

area_mask

1

Physics area mask.

bool

emission_angle_enabled

false

Whether the directional emission cone is enabled.

float

emission_angle

45.0

Inner emission cone angle, in degrees.

float

emission_angle_filter_attenuation_db

-12.0

Volume attenuation, unit as.

float

attenuation_filter_cutoff_hz

5000.0

Distance filter, unit as Hz.

float

attenuation_filter_db

0.0

Distance filter attenuation, unit as.

int

doppler_tracking

0

Doppler velocity.

Signals#

Signals

Description

finished()

Emitted when playback ends naturally.

Methods#

void set_stream(stream: FmodAudioStream)#

Sets audio stream.

If current in, will stop current channel and state.

FmodAudioStream get_stream() const#

Returns current sets audio stream.

void play(from_position: float = 0.0)#

Specified position, unit as.

Creates an FMOD 3D channel when playback starts, and applies the current 3D attenuation, filtering, emission angle, and Doppler settings.

bool preload_stream()#

Preloads the current stream by creating the internal FmodSound ahead of time. Returns true if creation succeeds.

void seek(to_position: float)#

To specified playback position, unit as.

void stop()#

Stop and pause state.

void set_playing(playing: bool)#

Sets state.

bool is_playing() const#

Returns true if internal channel in.

void set_stream_paused(paused: bool)#

Pause or resume current.

bool get_stream_paused() const#

Returns current pause state.

float get_playback_position() const#

Returns current playback position, unit as.

void set_volume_db(volume_db: float)#

Sets volume, unit as.

float get_volume_db() const#

Returns volume, unit as.

void set_pitch_scale(pitch_scale: float)#

Sets velocity and pitch.

float get_pitch_scale() const#

Returns current velocity and pitch.

void set_auto_play(enable: bool)#

Sets in scene tree after.

bool is_autoplay_enabled() const#

Returns true if .

void set_preload_on_set_stream(enable: bool)#

Sets in stream when load.

bool is_preload_on_set_stream_enabled() const#

Returns true if when load.

void set_bus(bus: StringName)#

Sets output bus name.

StringName get_bus() const#

Returns current output bus name.

If sets, returns "Master"

void set_max_distance(distance: float)#

Sets attenuation distance.

FMOD distance as max_distance * unit_size, 0.01 will as 0.01

float get_max_distance() const#

Returns attenuation distance.

void set_unit_size(size: float)#

Sets FMOD attenuation distance.

0.001 will as 0.001

float get_unit_size() const#

Returns FMOD attenuation distance.

void set_attenuation_model(model: AttenuationModel)#

Sets distance attenuation.

If current channel, will 3D attenuation sets.

AttenuationModel get_attenuation_model() const#

Returns current distance attenuation.

void set_emission_angle_enabled(enabled: bool)#

Or direction.

bool is_emission_angle_enabled() const#

Returns true if direction.

void set_emission_angle(angle: float)#

Sets unit as.

Will in 0.0 to 90.0

float get_emission_angle() const#

Returns unit as.

void set_emission_angle_filter_attenuation_db(db: float)#

Sets volume attenuation, unit as.

Will in -80.0 to 0.0

float get_emission_angle_filter_attenuation_db() const#

Returns volume attenuation, unit as.

void set_attenuation_filter_cutoff_hz(freq: float)#

Sets distance filter, unit as Hz.

Will in 10.0 to 22050.0

float get_attenuation_filter_cutoff_hz() const#

Returns distance filter, unit as Hz.

void set_attenuation_filter_db(db: float)#

Sets distance filter attenuation, unit as.

Will in -80.0 to 0.0

float get_attenuation_filter_db() const#

Returns distance filter attenuation, unit as.

void set_doppler_tracking(tracking: DopplerTracking)#

Sets Doppler velocity.

When underlying channel Doppler as 0.0; when node calculates velocity.

DopplerTracking get_doppler_tracking() const#

Returns current Doppler velocity.

void set_area_mask(mask: int)#

Sets .

int get_area_mask() const#

Returns .

Enumerations#

AttenuationModel#

Member

Value

Description

ATTENUATION_INVERSE_DISTANCE

0

Distance attenuation.

ATTENUATION_INVERSE_SQUARE_DISTANCE

1

Distance attenuation.

ATTENUATION_LOGARITHMIC

2

Distance mute.

ATTENUATION_DISABLED

3

Distance attenuation.

DopplerTracking#

Member

Value

Description

DOPPLER_TRACKING_DISABLED

0

Doppler.

DOPPLER_TRACKING_IDLE_STEP

1

In calculates velocity.

DOPPLER_TRACKING_PHYSICS_STEP

2

In calculates velocity.

Example#

@onready var engine_sound: FmodAudioStreamPlayer3D = $FmodAudioStreamPlayer3D

func _ready() -> void:
    engine_sound.stream = FmodAudioStream.load_from_file("res://audio/engine.ogg", FmodAudioStream.MODE_STREAM)
    engine_sound.bus = "SFX"
    engine_sound.max_distance = 40.0
    engine_sound.unit_size = 1.5
    engine_sound.attenuation_model = FmodAudioStreamPlayer3D.ATTENUATION_INVERSE_SQUARE_DISTANCE
    engine_sound.doppler_tracking = FmodAudioStreamPlayer3D.DOPPLER_TRACKING_PHYSICS_STEP
    engine_sound.play()

@onready var speaker: FmodAudioStreamPlayer3D = $Speaker

func _ready() -> void:
    speaker.emission_angle_enabled = true
    speaker.emission_angle = 30.0
    speaker.emission_angle_filter_attenuation_db = -18.0

FmodGeometryInstance3D#

: StaticBody3D

3D FMOD occlusion geometry node.

Description#

FmodGeometryInstance3D used for geometry to FMOD Geometry, 3D sound can occlusion and reverb occlusion.

Node can or specified node, can mesh creates FMOD geometry. StaticBody3D, as occlusion.

Properties#

Type

Name

Default

Description

SourceMode

source_mode

SOURCE_AUTO

Geometry.

NodePath

source_node_path

NodePath()

Specified node path.

Mesh

mesh

null

Used for occlusion geometry.

float

direct_occlusion

0.5

Direct occlusion.

float

reverb_occlusion

0.5

Reverb occlusion.

bool

double_sided

true

Polygon occlusion.

bool

active

true

Geometry and occlusion calculates.

bool

auto_rebuild

true

Or when geometry.

bool

sync_transform

true

Synchronizes node transform to underlying FmodGeometry

bool

recursive_source_scan

true

Whether automatic mode recursively scans child nodes.

int

primitive_segments

16

Geometry when.

bool

show_debug_gizmo

true

Whether to show the editor debug gizmo.

Signals#

Signals

Description

geometry_created()

Emitted after the geometry is created successfully.

geometry_cleared()

Geometry clears after.

geometry_rebuilt()

Geometry successfully after.

Methods#

void set_source_mode(mode: SourceMode)#

Sets the geometry source mode. It can scan automatically, use collision shapes, use MeshInstance3D nodes, or use the mesh resource directly.

SourceMode get_source_mode() const#

Returns current geometry.

void set_source_node_path(path: NodePath)#

Sets node path.

NodePath get_source_node_path() const#

Returns current node path.

void set_mesh(mesh: Mesh)#

Sets used for occlusion geometry Mesh.

Mesh get_mesh() const#

Returns current Mesh.

void set_direct_occlusion(value: float)#

Sets direct occlusion.

Will in 0.0 to 1.0. auto_rebuild geometry when will geometry.

float get_direct_occlusion() const#

Returns direct occlusion.

void set_reverb_occlusion(value: float)#

Sets reverb occlusion.

Will in 0.0 to 1.0. auto_rebuild geometry when will geometry.

float get_reverb_occlusion() const#

Returns reverb occlusion.

void set_double_sided(value: bool)#

Sets polygon occlusion.

bool get_double_sided() const#

Returns true if polygon as occlusion.

void set_active(value: bool)#

Sets geometry and occlusion calculates.

If geometry creates, will synchronizes to underlying FmodGeometry

bool get_active() const#

Returns true if geometry state.

void set_auto_rebuild(value: bool)#

Sets geometry.

After node will, used for.

bool get_auto_rebuild() const#

Returns true if .

void set_sync_transform(value: bool)#

Sets synchronizes node transform to underlying geometry.

bool get_sync_transform() const#

Returns true if transform synchronizes.

void set_recursive_source_scan(value: bool)#

Sets node when node.

bool get_recursive_source_scan() const#

Returns true if .

void set_primitive_segments(segments: int)#

Sets geometry when.

int get_primitive_segments() const#

Returns .

void set_show_debug_gizmo(value: bool)#

Sets Gizmo.

bool get_show_debug_gizmo() const#

Returns true if Gizmo.

void rebuild_geometry()#

Node and FMOD geometry.

Successfully after will geometry_rebuilt and geometry_created

void sync_geometry_transform()#

Node current transform synchronizes to underlying FmodGeometry.

void clear_geometry()#

Releases current FMOD geometry and clears reference.

Successfully clears when will geometry_cleared

bool has_valid_geometry() const#

Returns true if internal geometry in.

FmodGeometry get_geometry() const#

Returns internal FmodGeometry object.

int get_polygon_count() const#

Returns current occlusion polygon.

int get_vertex_count() const#

Returns current.

Enumerations#

SourceMode#

Member

Value

Description

SOURCE_AUTO

0

Can.

SOURCE_COLLISION_SHAPES

1

CollisionShape3D

SOURCE_MESH_INSTANCE

2

MeshInstance3D

SOURCE_MESH_RESOURCE

3

Mesh

Example#

# Node hierarchy:
# WallMesh (MeshInstance3D)
#   FmodGeometryInstance3D

@onready var occluder: FmodGeometryInstance3D = $WallMesh/FmodGeometryInstance3D

func _ready() -> void:
    occluder.direct_occlusion = 0.8
    occluder.reverb_occlusion = 0.4
    occluder.double_sided = true
    occluder.rebuild_geometry()

Node.#

Feature

FmodAudioStreamPlayer

FmodAudioStreamPlayer2D

FmodAudioStreamPlayer3D

FmodGeometryInstance3D

Inherits

Node

Node2D

Node3D

Node3D

Primary Use

Spatialization.

2D spatial playback

3D spatial playback

3D occlusion geometry.

Audio.

Yes

Yes

Yes

No

Distance attenuation.

No

Yes

Yes

Not applicable

Panning / spatial positioning

No

2D panning

3D positioning

Not applicable

Doppler.

No

No

Yes

Not applicable

Suitable for.

Background music and UI sounds.

2D ambience and map sound sources.

3D sound source.

Walls, obstacles, and occluders.
Contents