wyvern.lib.properties
Class MovableSoundSource

java.lang.Object
  wyvern.lib.properties.SimpleSound
      wyvern.lib.properties.MovableSoundSource

All Implemented Interfaces:

AddRemoveNotify, Alert, ContainerChangeListener, java.util.EventListener, HookCallback, MapChangeListener, MapMotionListener, MethodHookCallback, Music, MutableProperty, ObjectTracker, Sound, Subscriber

public final class MovableSoundSource

extends SimpleSound

implements Sound, Subscriber, HookCallback, MethodHookCallback, ObjectTracker, AddRemoveNotify, MutableProperty

An object responsible for managing a single instance of a sound. It keeps track of who can currently hear it, and if they get out of range, it makes sure they stop hearing it.

Every sound is logically attached to an owner, which must be a GameObject. If you want your map to have sounds, you need to create (possibly invisible) objects in the map that emit and manage the sounds, each of which has a MovableSoundSource property.

Version:

1.0, Jul 21, 2003

Author:

Steve Yegge

Field Summary

protected java.util.List	listeners_ The list of players who can currently hear the sound.
protected GameObject	owner_ The thing that's emitting the sound: a player, a harp, a music box, or anything else.
protected int	repeatDelay_ Number of milliseconds to pause between repeats.
protected int	repeats_ Number of times to repeat the sound before stopping. 0 = only play once.
protected java.lang.String	subject_ The pubsub subject we listen for, to get a notification that the endsound came in from a client.

Fields inherited from class wyvern.lib.properties.SimpleSound

gain_, path_

Fields inherited from interface wyvern.lib.Music

DEFAULT_COMBAT_MUSIC, DEFAULT_FUNERAL_MUSIC, DEFAULT_GAIN, DEFAULT_LEVELUP_MUSIC, DEFAULT_LOW_HP_COMBAT_MUSIC, DEFAULT_REPEAT_DELAY, DEFAULT_REPEATS, LOOP_FOREVER, PRIORITY_HIGH, PRIORITY_NORMAL

Constructor Summary

MovableSoundSource()
Constructs a new MovableSoundSource.

MovableSoundSource(java.lang.String path, GameObject owner)
Constructs a new MovableSoundSource.

Method Summary

protected void	addHooks(GameObject agent) Registers hooks for a particular player, or the owner object.
void	addListener(Player player) Adds a player to the set of players who can hear this sound.
void	broadcast() Broadcasts this sound to all the players within earshot of the owner.
java.lang.Object	createClone() Creates a clone of this object.
java.lang.String	getID() Returns the unique ID for this sound.
GameObject	getOwner() Returns the object that's emitting this sound.
java.lang.String	getPath() Returns the path to the sound file for this MovableSoundSource.
java.lang.String	getPropName() Returns the name of the property we store ourselves under automatically.
int	getRepeatDelay() Returns delay in millis between repeats
int	getRepeats() Returns number of times to repeat before stopping and sending a notification to the server that we're done.
java.lang.String	getStopSubject() Pubsub subject for notification from the client when the sound has finished playing.
void	hookEvent(java.lang.String hookName, CommandEvent event) Hooks move and teleport for listeners, so we can adjust the sound volume.
void	methodCalled(java.lang.String hookName, MethodHookable target, java.lang.Object data) Owner was added to or removed from its map.
void	notifyAdd(PropertyList list) This sound has been added to a GameObject.
void	notifyRemove(PropertyList list) We've been removed from the owner's property list.
void	playerLeft(Player p) Removes a player from the set of people who can hear this sound.
void	pubsubMessage(Message m) We got an #endsound message from the client, with our track ID in it.
protected void	removeHooks(GameObject agent) Removes hooks for a particular player, or the owner object.
void	removeListener(java.lang.String name) Removes a player from our list of people who can hear the sound.
void	setCleanupOnStop() Tells the sound source that as soon as it stops, it should unlink itself from its owner.
void	setOwner(GameObject owner) Sets the owner for this sound.
void	setPath(java.lang.String path) Sets the path on this sound source.
void	setRepeatDelay(int repeatDelay) Sets delay in millis between repeats
void	setRepeats(int repeats) Sets number of times to repeat the music before stopping.
void	stop() Stops the sound.
void	targetEnteredContainer(ContainerChangeEvent event) Target object was added to a bag or inventory.
void	targetEnteredMap(MapChangeEvent event) Notification that the target object has entered a map.
void	targetLeftContainer(ContainerChangeEvent event) Target object was removed from a bag or inventory.
void	targetLeftMap(MapChangeEvent event) Notification that the target object has left its map.
void	targetMoved(MapMotionEvent event) Notification that the target object has moved in its map.
java.lang.String	toString() Returns a debugging string.
void	unlinkFromOwner() Removes ourself from the owner's property list, and removes our hooks from the owner.

Methods inherited from class wyvern.lib.properties.SimpleSound

get, getGain, setGain

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface wyvern.lib.Alert

getGain, setGain

Field Detail

owner_

protected GameObject owner_

The thing that's emitting the sound: a player, a harp, a music box, or anything else.

listeners_

protected java.util.List listeners_

The list of players who can currently hear the sound.

subject_

protected java.lang.String subject_

The pubsub subject we listen for, to get a notification that the endsound came in from a client.

repeats_

protected int repeats_

Number of times to repeat the sound before stopping. 0 = only play once.

repeatDelay_

protected int repeatDelay_

Number of milliseconds to pause between repeats.

Constructor Detail

MovableSoundSource

public MovableSoundSource()

Constructs a new MovableSoundSource. Required for using it as a Bean property. The Properties system will initialize it by calling this constructor, then setting its properties from the XML.

MovableSoundSource

public MovableSoundSource(java.lang.String path,
                          GameObject owner)

Constructs a new MovableSoundSource.

Parameters:

owner - the owner of the sound, so if people move away from it, the sound volume decreases, and if the owner moves, the sound moves as well.

path - the relative path to the file to play, such as "music/midi/riff-harp.mid", or "wiz/foo/music/foo.wav". The file extension is required. If filename is null, the method just returns silently.

Method Detail

setCleanupOnStop

public void setCleanupOnStop()

Tells the sound source that as soon as it stops, it should unlink itself from its owner.

getPropName

public java.lang.String getPropName()

Returns the name of the property we store ourselves under automatically.

setOwner

public void setOwner(GameObject owner)

Sets the owner for this sound. Should only be called once, after instantiating the object, and not if you passed the owner into the constructor.

Parameters:

owner - the new owner of the sound

Throws:

java.lang.IllegalStateException - if the owner has already been initialized.

setPath

public void setPath(java.lang.String path)

Sets the path on this sound source.

Specified by:

setPath in interface Alert

Overrides:

setPath in class SimpleSound

Parameters:

path - the relative path to the sound file to play.

getPath

public java.lang.String getPath()

Returns the path to the sound file for this MovableSoundSource.

Specified by:

getPath in interface Alert

Overrides:

getPath in class SimpleSound

Returns:

the relative path to the sound file to play.

getID

public final java.lang.String getID()

Returns the unique ID for this sound. By default, it's the hashcode of the owner object.

Specified by:

getID in interface Sound

getOwner

public GameObject getOwner()

Returns the object that's emitting this sound.

getStopSubject

public java.lang.String getStopSubject()

Pubsub subject for notification from the client when the sound has finished playing. If you want to know when a particular player has finished listening to a sound, use Kernel.subscribe() with this subject string to receive the notification.

Specified by:

getStopSubject in interface Sound

Returns:

a subject to listen for, via wyvern.lib.Kernel.subscribe(), that says that this particular instance of a Sound has finished playing Message body is the name of the player that notified us that the sound has stopped.

Returns null if this is not a stoppable sound, i.e. the ID is "-1".

getRepeats

public int getRepeats()

Returns number of times to repeat before stopping and sending a notification to the server that we're done. (Any repeats are counted as part of the track, so the client doesn't notify the server until all the repeats have finished playing.)

Specified by:

getRepeats in interface Music

Returns:

number of times to repeat. 0 means don't repeat - just play one time and stop. For a repeat value of 1, the music will play a total of 2 times. A value of -1 means "repeat forever": the client will loop the music until it's stopped or changed.

setRepeats

public void setRepeats(int repeats)

Sets number of times to repeat the music before stopping.

Specified by:

setRepeats in interface Music

Parameters:

repeats - number of times to repeat. A value of zero (0) means to play the piece once and stop, with no repeats. A value of -1 means to loop continuously.

getRepeatDelay

public int getRepeatDelay()

Returns delay in millis between repeats

Specified by:

getRepeatDelay in interface Music

Returns:

delay in millis between repeats

setRepeatDelay

public void setRepeatDelay(int repeatDelay)

Sets delay in millis between repeats

Specified by:

setRepeatDelay in interface Music

Parameters:

repeatDelay - delay in millis between repeats

notifyAdd

public void notifyAdd(PropertyList list)

This sound has been added to a GameObject. Sets the list as the owner of the object.

Specified by:

notifyAdd in interface AddRemoveNotify

Parameters:

list - the PropertyList whose property list we're being added to

notifyRemove

public void notifyRemove(PropertyList list)

We've been removed from the owner's property list. Stops the sound and removes all the hooks.

Specified by:

notifyRemove in interface AddRemoveNotify

Parameters:

list - the PropertyList we're being removed from

pubsubMessage

public void pubsubMessage(Message m)

We got an #endsound message from the client, with our track ID in it. Remove the Player from our list of listeners. We get one of these for each player who successfully finishes playing the sound.

Specified by:

pubsubMessage in interface Subscriber

Parameters:

m - the message whose body is the player name

broadcast

public void broadcast()

Broadcasts this sound to all the players within earshot of the owner. If this sound instance was already playing, it starts over again, for everyone who could hear it. For those who can't hear it anymore, it shuts off. Keeps track of those players, and if they move out of range, or the sound moves out of range, it updates the sound for all affected players.

Configurable via properties (TBD).

Specified by:

broadcast in interface Sound

stop

public void stop()

Stops the sound. Shuts off the sound for all the clients that can currently hear it.

Specified by:

stop in interface Sound

unlinkFromOwner

public void unlinkFromOwner()

Removes ourself from the owner's property list, and removes our hooks from the owner. Sets owner_ field to null.

addListener

public void addListener(Player player)

Adds a player to the set of players who can hear this sound. Adds hooks to the player, so we know when they quit. Starts listening for "endsound" pubsub messages so we know when clients have stopped playing the sound.

playerLeft

public void playerLeft(Player p)

Removes a player from the set of people who can hear this sound.

removeListener

public void removeListener(java.lang.String name)

Removes a player from our list of people who can hear the sound.

Parameters:

name - the name of the player

addHooks

protected void addHooks(GameObject agent)

Registers hooks for a particular player, or the owner object.

removeHooks

protected void removeHooks(GameObject agent)

Removes hooks for a particular player, or the owner object.

hookEvent

public void hookEvent(java.lang.String hookName,
                      CommandEvent event)

Hooks move and teleport for listeners, so we can adjust the sound volume.

Specified by:

hookEvent in interface HookCallback

Parameters:

hookName - the name of the hook, such as "movePreHook".

event - the CommandEvent encapsulating the event parameters

methodCalled

public void methodCalled(java.lang.String hookName,
                         MethodHookable target,
                         java.lang.Object data)

Owner was added to or removed from its map.

Specified by:

methodCalled in interface MethodHookCallback

Parameters:

hookName - the name of the hook being run

target - the object on which the method was invoked: a GameMap or GameObject.

data - a method-specific data object; can be null. Check the documentation for the method hook to see if any data is passed to the callbacks.

targetEnteredMap

public void targetEnteredMap(MapChangeEvent event)

Description copied from interface: MapChangeListener

Notification that the target object has entered a map. Called at the end of the object's setMap() function.

Specified by:

targetEnteredMap in interface MapChangeListener

targetLeftMap

public void targetLeftMap(MapChangeEvent event)

Description copied from interface: MapChangeListener

Notification that the target object has left its map. Called at the end of the object's remove() function.

Specified by:

targetLeftMap in interface MapChangeListener

targetMoved

public void targetMoved(MapMotionEvent event)

Description copied from interface: MapMotionListener

Notification that the target object has moved in its map.

Specified by:

targetMoved in interface MapMotionListener

targetEnteredContainer

public void targetEnteredContainer(ContainerChangeEvent event)

Description copied from interface: ContainerChangeListener

Target object was added to a bag or inventory.

Specified by:

targetEnteredContainer in interface ContainerChangeListener

targetLeftContainer

public void targetLeftContainer(ContainerChangeEvent event)

Description copied from interface: ContainerChangeListener

Target object was removed from a bag or inventory.

Specified by:

targetLeftContainer in interface ContainerChangeListener

createClone

public java.lang.Object createClone()

Creates a clone of this object. Used by the Archetype system while creating the owner. Makes a copy of the MovableSoundSource bean from the parent archetype, and sticks it on our owner, at which point notifyAdd() is called and we get initialized.

Specified by:

createClone in interface MutableProperty

toString

public java.lang.String toString()

Returns a debugging string.

Overrides:

toString in class SimpleSound