利用者:AnOrdinaryKitten/Doc:2.6/Manual/Game Engine/Logic/Actuators/Sound/

Sound Actuator

The Sound actuator allows you to play sound files in the game engine.

The Sound Actuator

See Actuator Common Options for common options.

Actuator Settings

Sound File

Load a new sound file or select one from the list.

Play Mode

How the sound effect is played.

Play Stop

The sound effect is played when activated. Stops instantly when deactivated.

Play End

The sound effect is played when activated. When deactivated, stops after finishing playing the sound. The sound is not replayed if activated while still playing.

Loop Stop

The sound is played as infinite loop when activated. Stops instantly when deactivated.

Loop End

The sound is played as infinite loop when activated. When deactivated, stops after finishing playing the sound.

Loop Bidirectional

The sound is played as infinite ping-pong loop. When deactivated, stops after finishing playing the sound.

Loop Bidirectional Stop

The sound is played as infinite ping-pong loop. Stops instantly when deactivated.

Volume

The volume at which the sound effect is played.

Pitch

The pitch at which the sound effect is played. 0 is default, 12 is one octave.

3D Sound

If enabled, the sound is affected by distance, speed of the emitting object and various other things. The options below are only available if 3d Sound is enabled.

Minimum Gain

The minimum gain of the sound, no matter how far it is away.

Maximum Gain

The maximum gain of the sound, no matter how near it is.

Reference Distance

The cones point in the direction of the objects negative Z axis.

The distance at which the sound has a gain of 1.0.

Maximum Distance

The maximum distance at which the sound can be heard.

Rolloff

The influence factor on volume depending on distance. The higher, the more the sound will fade with distance.

Cone Outer Gain

The gain outside the outer cone. The gain inside the outer cone will be interpolated between this value and the normal gain inside the inner cone (Volume). Note that the cones always point in the direction of the objects local -Z axis (Figure right).

Cone Outer Angle

The angle of the outer cone.

Cone Inner Angle

The angle of the inner cone.

	Sound options
	3d sound is influenced by the Sound options in Render. A brief description of the different distance models can be found here.

Python Access

All settings of the Sound actuator can be retrieved and manipulated via Python.

# Import GameLogic module so we can access controller and its owner.
import GameLogic
controller = GameLogic.getCurrentController()
owner = controller.owner

# Accessing the sound actuator with the name "Sound".
owner.actuators["Sound"].startSound()

owner.actuators["Sound"].startSound()

Plays the sound. It has no effect if the sound is already being played. All settings but Volume, Pitch and Play Mode are ignored.

owner.actuators["Sound"].stopSound()

Instantly stops the sound that is currently being played. Does not work if the sound actuator has been activated via the controller. The play mode has no effect on this.

controller.activate(owner.actuators["Sound"])

The controller activates the actuator.

controller.deactivate(owner.actuators["Sound"])

The controller deactivates the actuator.

owner.actuators["Sound"].volume

Float, gets/sets the actuators Volume. Using negative values does not produce errors but have no effect (Sound is played with default volume).

owner.actuators["Sound"].pitch

Float, gets/sets the actuators Pitch. Here the pitch is handled in a different way from the Pitch setting in the actuator itself. The default value is 1.0 which is equal to 0.0 in the Pitch setting. 2.0 here is equal to 12.0 in Pitch, 0.5 is equal to -12.0 in Pitch and so on. Using negative values does not produce errors but have no effect (Sound is played with default pitch).

owner.actuators["Sound"].mode

Integer, gets/sets the actuators Play Mode.

1 = Play Stop

2 = Play End

3 = Loop Stop

4 = Loop End

5 = Loop Bidirectional

6 = Loop Bidirectional Stop

Other values are not accepted and cause errors.

owner.actuators["Sound"].is3D

Boolean, gets/sets the actuators 3D Sound.

owner.actuators["Sound"].volume_minimum

Float, gets/sets the actuators Minimum Gain.

owner.actuators["Sound"].volume_maximum

Float, gets/sets the actuators Maximum Gain.

owner.actuators["Sound"].distance_reference

Float, gets/sets the actuators Reference Distance.

owner.actuators["Sound"].distance_maximum

Float, gets/sets the actuators Maximum Distance.

owner.actuators["Sound"].cone_volume_outer

Float, gets/sets the actuators Cone Outer Gain.

owner.actuators["Sound"].cone_angle_outer

Float, gets/sets the actuators Cone Outer Angle.

owner.actuators["Sound"].cone_angle_inner

Float, gets/sets the actuators Cone Inner Angle.

owner.actuators["Sound"].time

Returns unidentified value.

owner.actuators["Sound"].sound

Returns a pointer to the sound file in aud.Factory.

owner.actuators["Sound"].attenuation

Returns unidentified value.