Class: sound_object

Play an engine sound resource from scripts.

Source

C++ class sound_object

Custom Constructor

sound_object

Remarks

Most playback and parameter APIs require the sound resource to exist, unless the engine is running with sound disabled. Missing files are logged at construction and fail later when playback starts.

Constructors

Constructor

new sound_object(sound_path: string): sound_object;

Create a sound from $game_sounds$/<sound_path>.ogg.

Parameters

Parameter	Type	Description
sound_path	string	Sound resource path without extension.

Returns

sound_object

Remarks

Missing sound files are logged during construction. Playback methods will throw later if the sound handle was not created.

Constructor

new sound_object(sound_path: string, type: TXR_snd_type): sound_object;

Create a typed sound from $game_sounds$/<sound_path>.ogg.

Parameters

Parameter	Type	Description
sound_path	string	Sound resource path without extension.
type	TXR_snd_type	Sound category used by AI sound memory.

Returns

sound_object

Remarks

Missing sound files are logged during construction. Playback methods will throw later if the sound handle was not created.

Methods

attach_tail()

attach_tail(sound_path: string): void;

Append a tail sound played after this sound ends.

Parameters

Parameter	Type	Description
sound_path	string	Sound resource path without extension.

Returns

void

Remarks

The tail path is passed to the engine sound handle as-is. Use a game sound resource path without extension.

---

get_position()

get_position(): vector;

Get the current playback position.

Returns

vector

Current sound position.

Remarks

Logs an engine script error and returns a zero vector if the sound was not launched.

---

length()

length(): number;

Get sound length in milliseconds.

Returns

number

Sound duration.

Remarks

Reads the engine sound handle. Do not use it as a file-existence check after construction logged a missing file.

---

play()

Call Signature

play(object: Nillable<game_object>): void;

Play the sound attached to an object, or globally when object is null.

Parameters

Parameter	Type	Description
object	Nillable<game_object>	Object used as sound owner.

Returns

void

Throws

If the sound handle was not created.

Call Signature

play(object: Nillable<game_object>, delay: number): void;

Play the sound after a delay.

Parameters

Parameter	Type	Description
object	Nillable<game_object>	Object used as sound owner.
delay	number	Delay in seconds.

Returns

void

Throws

If the sound handle was not created.

Call Signature

play(
   object: Nillable<game_object>, 
   delay: number, 
   flags: number): void;

Play the sound with engine sound flags.

Parameters

Parameter	Type	Description
object	Nillable<game_object>	Object used as sound owner.
delay	number	Delay in seconds.
flags	number	Playback flags such as sound_object.looped or sound_object.s2d.

Returns

void

Throws

If the sound handle was not created.

---

play_at_pos()

Call Signature

play_at_pos(object: Nillable<game_object>, position: vector): void;

Play the sound at a fixed world position.

Parameters

Parameter	Type	Description
object	Nillable<game_object>	Optional object used as sound owner.
position	vector	World position for playback.

Returns

void

Throws

If the sound handle was not created.

Call Signature

play_at_pos(
   object: Nillable<game_object>, 
   position: vector, 
   delay: number): void;

Play the sound at a fixed world position after a delay.

Parameters

Parameter	Type	Description
object	Nillable<game_object>	Optional object used as sound owner.
position	vector	World position for playback.
delay	number	Delay in seconds.

Returns

void

Throws

If the sound handle was not created.

Call Signature

play_at_pos(
   object: Nillable<game_object>, 
   position: vector, 
   delay: number, 
   flags: number): void;

Play the sound at a fixed world position with engine sound flags.

Parameters

Parameter	Type	Description
object	Nillable<game_object>	Optional object used as sound owner.
position	vector	World position for playback.
delay	number	Delay in seconds.
flags	number	Playback flags such as sound_object.looped or sound_object.s2d.

Returns

void

Throws

If the sound handle was not created.

---

play_no_feedback()

play_no_feedback(
   object: Nillable<game_object>, 
   flags: number, 
   delay: number, 
   position: vector, 
   volume: number): void;

Play without tracking feedback.

Parameters

Parameter	Type	Description
object	Nillable<game_object>	Optional object used as sound owner.
flags	number	Playback flags.
delay	number	Delay in seconds.
position	vector	Optional playback position.
volume	number	Optional playback volume.

Returns

void

Remarks

This starts playback without storing feedback on the sound_object, so playing() will not describe this playback instance.

Throws

If the sound handle was not created.

---

playing()

playing(): boolean;

Check whether the sound has active playback feedback.

Returns

boolean

Whether the sound is currently playing.

Remarks

Sounds started with play_no_feedback are intentionally not tracked by feedback.

---

set_position()

set_position(position: vector): void;

Move the sound emitter.

Parameters

Parameter	Type	Description
position	vector	New world position.

Returns

void

Throws

If the sound handle was not created.

---

stop()

stop(): void;

Stop playback immediately.

Returns

void

Throws

If the sound handle was not created.

---

stop_deferred()

stop_deferred(): void;

Stop playback through the engine deferred-stop path.

Returns

void

Remarks

Preferred spelling. stop_deffered is kept for script compatibility.

Throws

If the sound handle was not created.

---

stop_deffered()

stop_deffered(): void;

Stop playback through the engine deferred-stop path.

Returns

void

Remarks

Legacy misspelled alias for stop_deferred.

Throws

If the sound handle was not created.

Properties

frequency

frequency: number;

Playback frequency multiplier.

---

max_distance

max_distance: number;

Maximum audible distance in meters.

---

min_distance

min_distance: number;

Minimum distance before attenuation starts.

---

volume

volume: number;

Playback volume.

---

looped

readonly static looped: 1;

Keep playing until stopped.

---

s2d

readonly static s2d: 2;

Screen-space 2D playback.

---

s3d

readonly static s3d: 0;

Spatial 3D playback.