Cabal Common Library Doc Music

Overview

This is the main class for the event driven inflight music for missions and part of the Cabal_Common_Library.

The script handles incoming data from worldScripts to play music in specific situations. OXPs can place or remove their sets fairly simple and a few parameters are handled. The inserted data is associated to the inserting worldScript by ID and the whole group of events can be easily de/activated at every time via .changeStatus(). Additionally a property can be assigned to a specific event, means that different entries can be de/activated by using different properties.

Note: Length, volume and fadeIn/fadeOut in the audio itself are important factors for a smooth transition between musicfiles. For the volume it is adviced to use at least -9 db (peak) to avoid conflicts with spoken inflight messages and digital clipping.

Properties

requestHandlerSet

On startUp created set of handlers (Array) for Cabal_Common_Music.

 var a = worldScripts.Cabal_Common_Music.requestHandlerSet;
 a -> [ [aegis, enter, exit], [alert, red, ... ] ... ]

Functions

addMedia()

	worldScripts.Cabal_Common_Music.addMedia( obj )

Profiler
Native	0.000097s
Extension	0.000032s
JS	0.000455s

Adds incoming object to the list and associates the entries to the sending worldScript. Internally every entry gets a group ID, so make sure that the object is extensible and not sealed or frozen.

Properties:

who

String. Required. Name of the sending worldScript.

start

Boolean. Required. Starting state for the group after insertion.

aegis

Object. Allowed members: enter³, exit³.

alert

Object. Allowed members: red, yellow¹, green¹.

destroyed

Object. Allowed members: ent.

exitWS

Object. Allowed members: inter, goneNova, doNova, standard, any.

launch

Object. Allowed members: ent, inter, goneNova, doNova, main, any.

planet

Object. Allowed members: ent³, enterMain³, enterSun³, exitMain³, exitSun³.

scooped

Object. Allowed members: ent², fuel⁴ Added in v1.6.1.

track

Object. Allowed members: byName.

Returns

Boolean

True on success, false on failure.

¹ If other handlers have fired blocked for 10 seconds.
² The handler is only fired for scripted pods. (Changed in Oolite v1.77)
³ Can collide, because aegis and planet vicinities can be close together.
⁴ Blocked for 10 seconds when fired.

The above mentioned members are all of type Array and are holding the music related objects. See Structure for a overview.

removeMedia()

	worldScripts.Cabal_Common_Music.removeMedia( who )

Profiler
Native	0.000040s
Extension	0.000012s
JS	0.000346s

Removes all entries of a group from the stored list.

Properties:

who

String. Name of the worldScript.

Returns

Boolean

True on success, false on failure.

changeStatus()

	worldScripts.Cabal_Common_Music.changeStatus( who, status )

Profiler
Native	0.000040s
Extension	0.000017s
JS	0.000104s

Changes the group state for a specific group.

Properties:

who

String. Name of the worldScript.

status

Boolean. Sets the group flag for all inserted files of a specific worldScript group.

Returns

Boolean

True on success, false on failure.

Structure

A short overview about the expected structure:

 var eventMusic = {
   who:this.name,
   start:true,
   aegis:{
     exit:[
       {prop:"myProperty",music:"myMusic.ogg"}
     ]
   }
 };
 worldScripts.Cabal_Common_Music.addMedia(eventMusic);

The objects that are holding the music itself have a set of available properties as well.

dist

Number. Min. distance to entity. Required in track.byName.

ent

String/Number. Either entity.name (String) or entity.radius (Number). Required in destroyed.ent, launch.ent, planet.ent (radius), scooped.ent and track.byName.

fadeQ

Number. Optional. Sound as transition between musicfiles. If used must be 1 (will be expanded).

music

String. Required. Filename with fileextension.

prop

String. Optional. Name of worldScript property to be checked.

---