Difference between revisions of "Lib Music"

From Elite Wiki
m (Added volume parameter)
m (Example overhaul)
Line 36: Line 36:
 
:::;dur: duration seconds <integer>
 
:::;dur: duration seconds <integer>
 
:::;vol: volume 0...1 <float> (Optional) {{AV|1.1}}
 
:::;vol: volume 0...1 <float> (Optional) {{AV|1.1}}
 +
:;ID:String. Group name.
  
 
'''Returns:'''
 
'''Returns:'''
Line 43: Line 44:
 
   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 53: Line 57:
  
 
'''Parameters:'''
 
'''Parameters:'''
:;ID:String.
+
:;ID:String. Group name.
  
 
'''Returns:'''
 
'''Returns:'''

Revision as of 17: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.