Difference between revisions of "Lib Music"

From Elite Wiki
(Documentation)
 
m (Example overhaul)
 
(3 intermediate revisions by the same user not shown)
Line 1: Line 1:
 
[[Image:IconLib.png|100px|right]]
  
[[Image:IconLib.png|100px|right]]
 
==Overview==
  
==Overview==
−
Lib_Music (part of [[Library]]) is an expandable event driven music player, but also the successor to [[Hyperradio]].
 +
Lib_Music (part of [[Library]]) is an expandable event driven music player, but also the successor to [[Hyperradio]]. If 'Radio'-AddOns are used the radio-channels are configurable through [[Lib_Config]].
   
   
 
==Events==
  
==Events==
 
Events are handled through Oolites handler (e.g. shipExitedWitchspace). Lib_Music uses handlers which are not fired repeatedly and selects one of the music entries randomly for the specified event. Event music is particulary interesting for mission related things.
  
Events are handled through Oolites handler (e.g. shipExitedWitchspace). Lib_Music uses handlers which are not fired repeatedly and selects one of the music entries randomly for the specified event. Event music is particulary interesting for mission related things.
  +
  +
Used handlers:
  +
* alertConditionChanged
  +
* playerStartedAutoPilot
  +
* playerRescuedEscapePod
  +
* shipDockedWithStation
  +
* shipEnteredPlanetaryVicinity
  +
* shipEnteredStationAegis
  +
* shipExitedStationAegis
  +
* shipExitedPlanetaryVicinity
  +
* shipExitedWitchspace
  +
* shipKilledOther
  +
* shipScoopedFuel
  +
* shipScoopedOther
  +
* shipTargetDestroyed
  +
* shipWillDockWithStation
  +
* shipWillLaunchFromStation
  +
  +
Any of the following methods should be used on [[Oolite_JavaScript_Reference:_World_script_event_handlers#startUpComplete|.startUpComplete]] or later.
   
   
Line 13: Line 32:
   
 
'''Parameters:'''
  
'''Parameters:'''
−
:;obj:Object. See [[#$media|$media]] for its members. The entries must contain snd: <filename> and dur: duration seconds <integer>.
 +
:;obj:Object. See [[#$media|$media]] for its members. The entries must contain
  +
:::;snd: <filename>
  +
:::;dur: duration seconds <integer>
  +
:::;vol: volume 0...1 <float> (Optional) {{AV|1.1}}
  +
:;ID:String. Group name.
   
 
'''Returns:'''
  
'''Returns:'''
Line 21: Line 40:
 
worldScripts.Lib_Music._addEventMusic({
  
worldScripts.Lib_Music._addEventMusic({
 
aegis:{
  
aegis:{
−
enter:[ {snd:"MyOXP_AegisFile.ogg",dur:98} ]
 +
enter:[
  +
{snd:"MyOXP_AegisFile.ogg",dur:98},
  +
{snd:"MyOXP_OtherAegisFile.ogg",dur:98,vol:0.7}
  +
]
 
}
  
}
 
},"MyGroupID");
  
},"MyGroupID");
Line 31: Line 50:
   
 
'''Parameters:'''
  
'''Parameters:'''
−
:;ID:String.
 +
:;ID:String. Group name.
   
 
'''Returns:'''
  
'''Returns:'''
 
:;n:Number. 0 or 1. The current status.
  
:;n:Number. 0 or 1. The current status.
  +
  +
Example:
  +
worldScripts.Lib_Music._toggleGroup("MyGroupID");
   
   
 
===_setPriorityGroup===
  
===_setPriorityGroup===
−
Take priority for specified GroupID. Resets and stores the current status, disables all other GroupIDs and enables this GroupID. This method is particulary interesting for mission related things.
  
  +
{{CodeEx|codeex= _setPriorityGroup: function( ID )}}
  +
Take priority for specified GroupID. Stores the current status, disables all other GroupIDs and enables this GroupID. This method is particulary interesting for mission related things.
  +
  +
'''Parameters:'''
  +
:;ID:String.
  +
  +
'''Returns:'''
  +
:;true or false.
  +
  +
Example:
  +
worldScripts.Lib_Music._setPriorityGroup("MyGroupID");
   
   
 
===_clrPriorityGroup===
  
===_clrPriorityGroup===
  +
{{CodeEx|codeex= _clrPriorityGroup: function( )}}
 
Clear priority mode. Resets the status of all GroupIDs.
  
Clear priority mode. Resets the status of all GroupIDs.
  +
  +
'''Parameters:'''
  +
:;none.
  +
  +
'''Returns:'''
  +
:;nothing.
  +
  +
Example
  +
worldScripts.Lib_Music._clrPriorityGroup();
   
   
 
====$media====
  
====$media====
−
$media = {
  
  +
The structure.
  +
{
 
aegis:{enter:[], exit:[]},
  
aegis:{enter:[], exit:[]},
 
alert:{red:[]},
  
alert:{red:[]},
Line 63: Line 106:
   
 
==Channels==
  
==Channels==
−
Channels are used as playlists. As long as no other event gets triggered and the status doesn't change Lib_Music will continue to pick another one from the currently active radio channel. If a channel is explicitely set via _setChannel() it will use this channel until it gets unset (both docked and inflight). Otherwise - If docked it will use either a channel that is equal to the name of the station or the "generic" channel. Inflight it uses either the "docking" channel for the autopilot, "fight" for dangerous situations or "generic".
 +
Channels are used as playlists. As long as no other event gets triggered and the status doesn't change Lib_Music will continue to pick another one from the currently active radio channel. If a channel is explicitely set via _setChannel() it will use this channel until it gets unset (both docked and inflight). Otherwise - if docked it will use either a channel that is equal to the name of the station or the "generic" channel. Inflight it uses either the "docking" channel for the autopilot, "fight" for dangerous situations or "generic".
  +
  +
Any of the following methods should be used on [[Oolite_JavaScript_Reference:_World_script_event_handlers#startUpComplete|.startUpComplete]] or later.
   
   
 
===_addChannel===
  
===_addChannel===
  +
{{CodeEx|codeex= _addChannel: function( obj )}}
  +
Clones the passed Object and adds or merges the channel to the queued music lists.
  +
  +
'''Parameters:'''
  +
:;obj:Object with members:
  +
::;name:String.
  +
::;sounds:Array. The entries must contain
  +
:::;snd: <filename>
  +
:::;dur: duration seconds <integer>
  +
:::;vol: volume 0...1 <float> (Optional) {{AV|1.1}}
  +
::;radio:Boolean. Optional.
  +
  +
'''Returns:'''
  +
:;true or false.
  +
  +
Example:
  +
worldScripts.Lib_Music._addChannel({name:"docking",sounds:[ {snd:"MyOXP_Docking.ogg",dur:180} ]});
  +
   
 
===_setChannel===
  
===_setChannel===
  +
{{CodeEx|codeex= _setChannel: function( str )}}
  +
Sets or clears custom radio channel.
  +
  +
'''Parameters:'''
  +
:;str:String or null. Channel name.
  +
  +
'''Returns:'''
  +
:;String or null:Channel name.
  +
  +
  +
==Execution order==
  +
The priority is as follows:
  +
* Event with active priority mode (GroupID).
  +
* Event standard (e.g. .main).
  +
* Event for specified entity.
  +
* Event .any.
  +
* Radio channel set through _setChannel().
  +
* Radio channel.
   
   

Latest revision as of 18:23, 6 October 2018

IconLib.png

Overview

Lib_Music (part of Library) is an expandable event driven music player, but also the successor to Hyperradio. If 'Radio'-AddOns are used the radio-channels are configurable through Lib_Config.


Events

Events are handled through Oolites handler (e.g. shipExitedWitchspace). Lib_Music uses handlers which are not fired repeatedly and selects one of the music entries randomly for the specified event. Event music is particulary interesting for mission related things.

Used handlers:

  • alertConditionChanged
  • playerStartedAutoPilot
  • playerRescuedEscapePod
  • shipDockedWithStation
  • shipEnteredPlanetaryVicinity
  • shipEnteredStationAegis
  • shipExitedStationAegis
  • shipExitedPlanetaryVicinity
  • shipExitedWitchspace
  • shipKilledOther
  • shipScoopedFuel
  • shipScoopedOther
  • shipTargetDestroyed
  • shipWillDockWithStation
  • shipWillLaunchFromStation

Any of the following methods should be used on .startUpComplete or later.


_addEventMusic

_addEventMusic: function( obj, ID )

Clones the passed Object and adds entries silently to the event Arrays. Without activating the GroupID via _toggleGroup none of them will be played. The passed Object can use any of the members of $media, except radio (which is reserved for queued music)!

Parameters:

obj
Object. See $media for its members. The entries must contain
snd
<filename>
dur
duration seconds <integer>
vol
volume 0...1 <float> (Optional) Added in v1.1
ID
String. Group name.

Returns:

true or false.

Example: 

 worldScripts.Lib_Music._addEventMusic({
   aegis:{
     enter:[
       {snd:"MyOXP_AegisFile.ogg",dur:98},
       {snd:"MyOXP_OtherAegisFile.ogg",dur:98,vol:0.7}
     ]
   }
 },"MyGroupID");


_toggleGroup

_toggleGroup: function( ID )

Toggles the status for GroupID if it exists. If priority mode is active the change is inactive until priority mode is cleared.

Parameters:

ID
String. Group name.

Returns:

n
Number. 0 or 1. The current status.

Example: 

 worldScripts.Lib_Music._toggleGroup("MyGroupID");


_setPriorityGroup

_setPriorityGroup: function( ID )

Take priority for specified GroupID. Stores the current status, disables all other GroupIDs and enables this GroupID. This method is particulary interesting for mission related things.

Parameters:

ID
String.

Returns:

true or false.

Example: 

 worldScripts.Lib_Music._setPriorityGroup("MyGroupID");


_clrPriorityGroup

_clrPriorityGroup: function( )

Clear priority mode. Resets the status of all GroupIDs.

Parameters:

none.

Returns:

nothing.

Example 

 worldScripts.Lib_Music._clrPriorityGroup();


$media

The structure. 

 {
   aegis:{enter:[], exit:[]},
   alert:{red:[]},
   docked:{main:[], any:[]},
   exitWS:{inter:[], goneNova:[], doNova:[], standard:[]},
   killed:{any:[]},
   launch:{inter:[], goneNova:[], doNova:[], main:[], any:[]},
   planetIn:{enterMain:[], enterSun:[], any:[]},
   planetOut:{exitMain:[], exitSun:[], any:[]},
   radio:{generic:[]},
   rescued:{any:[]},
   scooped:{any:[]},
   scoopFuel:{fuel:[]}
 };


Channels

Channels are used as playlists. As long as no other event gets triggered and the status doesn't change Lib_Music will continue to pick another one from the currently active radio channel. If a channel is explicitely set via _setChannel() it will use this channel until it gets unset (both docked and inflight). Otherwise - if docked it will use either a channel that is equal to the name of the station or the "generic" channel. Inflight it uses either the "docking" channel for the autopilot, "fight" for dangerous situations or "generic".

Any of the following methods should be used on .startUpComplete or later.


_addChannel

_addChannel: function( obj )

Clones the passed Object and adds or merges the channel to the queued music lists.

Parameters:

obj
Object with members:
name
String.
sounds
Array. The entries must contain
snd
<filename>
dur
duration seconds <integer>
vol
volume 0...1 <float> (Optional) Added in v1.1
radio
Boolean. Optional.

Returns:

true or false.

Example: 

 worldScripts.Lib_Music._addChannel({name:"docking",sounds:[ {snd:"MyOXP_Docking.ogg",dur:180} ]});


_setChannel

_setChannel: function( str )

Sets or clears custom radio channel.

Parameters:

str
String or null. Channel name.

Returns:

String or null
Channel name.


Execution order

The priority is as follows:

  • Event with active priority mode (GroupID).
  • Event standard (e.g. .main).
  • Event for specified entity.
  • Event .any.
  • Radio channel set through _setChannel().
  • Radio channel.
Retrieved from "http://backup.witchspacewiki.org/index.php?title=Lib_Music&oldid=57616"